Skip to main content
This project is currently a work in progress. There are known issues with consistency, performance, and overall code organization that are being actively addressed.

​
Prerequisites

Before setting up 5Stack locally, ensure you have the following installed:

Node.js

Version 22 or higher (Alpine recommended)

Yarn

Version 4.11.0 (managed by Corepack)

Git

For version control

Code Editor

VS Code or your preferred editor

​
Installation Steps

1

Clone the Repository

Clone the 5Stack repository to your local machine:
git clone https://github.com/your-org/5stack.git
cd 5stack
2

Enable Corepack

5Stack uses Yarn 4.11.0, which is managed by Corepack:
corepack enable
corepack prepare
3

Install Dependencies

Install all project dependencies using Yarn:
yarn install
This will install dependencies in immutable mode, ensuring consistency with the lockfile.
4

Configure Environment Variables

Copy the example environment file and configure it:
cp .env-example .env
See the Environment Variables page for detailed configuration.
5

Prepare Nuxt

Run the postinstall script to prepare Nuxt:
yarn postinstall
This command is automatically run after yarn install and prepares the Nuxt environment.

​
Starting the Development Server

Start the Nuxt development server: 
yarn dev
The development server will start on http://localhost:3000 and will be accessible from your local network (binds to 0.0.0.0).
The development server runs in SSR-disabled mode. See nuxt.config.ts:13 for configuration details.

​
Available Scripts

The following scripts are available in the project:

​
Development Commands

# Start development server
yarn dev

# Build for production
yarn build

# Preview production build
yarn preview

# Generate static site
yarn generate

​
Code Generation

# Generate GraphQL client code from Hasura
yarn codegen
This command:
  • Connects to your Hasura GraphQL endpoint using environment variables
  • Generates TypeScript types and Zeus client code
  • Applies custom patches via scripts/patch-zeus-codegen.sh
The codegen script requires valid NUXT_PUBLIC_API_DOMAIN and HASURA_GRAPHQL_ADMIN_SECRET environment variables.

​
Translations

# Check translation file consistency
yarn check-translations
Validates that all translation keys are present across all supported languages.

​
Cloudflare Workers

# Run Wrangler commands
yarn wrangler [command]
Manage Cloudflare Workers deployments. See Cloudflare Workers Setup for more details.

​
Project Structure

Key directories in the development environment: 
5stack/
├── assets/          # Static assets (CSS, images)
├── components/      # Vue components
├── composables/     # Vue composables
├── pages/           # Nuxt pages (file-based routing)
├── plugins/         # Nuxt plugins
├── public/          # Public static files
├── server/          # Server-side code
├── stores/          # Pinia stores
├── cloudflare-workers/  # Cloudflare Workers code
├── generated/       # Generated GraphQL client code
├── scripts/         # Build and development scripts
└── nuxt.config.ts   # Nuxt configuration

​
Development Features

​
Hot Module Replacement (HMR)

The development server supports HMR, allowing you to see changes instantly without full page reloads.

​
Nuxt DevTools

DevTools are enabled by default in development mode: 
devtools: {
  enabled: true,
  timeline: {
    enabled: true,
  },
}
Access DevTools by pressing Shift + Alt + D in your browser.

​
PWA Development

The PWA (Progressive Web App) features are enabled in development: 
pwa: {
  devOptions: {
    enabled: true,
  },
}
This allows you to test service worker functionality locally.

​
Common Issues

If port 3000 is already in use, you can specify a different port:
PORT=3001 yarn dev
Ensure your .env file has correct values for:
  • NUXT_PUBLIC_API_DOMAIN
  • HASURA_GRAPHQL_ADMIN_SECRET
The GraphQL endpoint should be accessible at https://{API_DOMAIN}/v1/graphql.
Try clearing the Nuxt cache and node_modules:
rm -rf .nuxt node_modules .output
yarn install
If you encounter Corepack errors, ensure you’re using Node.js 16.9.0 or higher:
node --version
corepack enable

​
Next Steps

Environment Variables

Configure your environment variables

Docker Deployment

Deploy using Docker containers

Architecture Overview

Learn about the system architecture

GraphQL API

Explore the GraphQL API

Build docs developers (and LLMs) love

Get started for freeTalk to us