Installation

This page covers system requirements, all supported installation methods, production build configuration, environment variable setup, and the path alias system used throughout the project.

System requirements

Requirement	Minimum	Recommended
Node.js	18.x	20.x LTS
pnpm	9.x	9.15.x (declared in `packageManager`)
npm	9.x	Latest stable
yarn	1.22.x	Latest stable
RAM	4 GB	8 GB
OS	macOS, Linux, Windows (WSL2)	macOS or Linux

Install dependencies

pnpm (recommended)

bash

pnpm install

npm

bash

npm install

yarn

bash

yarn install

Development server

The dev server uses Turbopack for fast builds and hot module replacement.

bash

# pnpm
pnpm dev
 
# npm
npm run dev
 
# yarn
yarn dev

The app starts at http://localhost:3000 by default.

Production build

bash

# pnpm
pnpm build
pnpm start
 
# npm
npm run build
npm start
 
# yarn
yarn build
yarn start

To perform a clean build (removes .next cache first):

bash

# pnpm
pnpm clean-build
 
# npm
npm run clean-build

Environment variables

Copy .env.example to .env.local before starting the app:

bash

cp .env.example .env.local

Never commit .env.local

.env.local contains secrets and is listed in .gitignore. Never commit it to version control. In production, set environment variables through your hosting platform's secrets manager.

Full variable reference

bash

# .env.local
 
# ── Authentication (Auth.js v5) ──────────────────────────
# Required: secret used for JWT signing
# Generate with: openssl rand -base64 32
AUTH_SECRET=your-secret-here
 
# Optional: base URL for OAuth callbacks (auto-detected on most hosts)
AUTH_URL=http://localhost:3000
 
# Optional: trust the X-Forwarded-Host header (required behind a reverse proxy)
AUTH_TRUST_HOST=true
 
# ── Google Maps (optional) ───────────────────────────────
# Obtain from https://console.cloud.google.com
NEXT_PUBLIC_GOOGLE_MAP_API=your-google-maps-api-key
 
# ── Public assets ────────────────────────────────────────
NEXT_PUBLIC_IMAGES_PATH=/assets/images
 
# ── Database (optional, for production auth) ─────────────
# DATABASE_URL=postgresql://user:password@localhost:5432/jumbo

Verification after setup

After running pnpm dev, verify:

The app loads at http://localhost:3000 without console errors
Unauthenticated requests redirect to the login page
After logging in, the misc dashboard renders at /en-US/dashboards/misc

Path aliases

The project uses three TypeScript path aliases configured in tsconfig.json:

json

// tsconfig.json (paths excerpt)
{
  "paths": {
    "@/*":      ["./src/*", "./*"],
    "@jumbo/*": ["./@jumbo/*"],
    "@assets/*": ["./@assets/*"]
  }
}

Alias	Resolves to	Usage
`@/`	`./src/` and `./` (root)	App source files (`@/components`, `@/config`, `@/auth`)
`@jumbo/`	`./@jumbo/`	Jumbo component framework (`@jumbo/components`, `@jumbo/utilities`)
`@assets/`	`./@assets/`	Static assets and fonts (`@assets/fonts/noir-pro/styles.css`)

Vitest aliases

Vitest mirrors these aliases in vitest.config.ts so test files can import using the same @/, @jumbo/, and @assets/ paths without any additional configuration.

Available scripts

Script	Command	Description
`dev`	`next dev --turbopack`	Start dev server with Turbopack
`build`	`next build`	Production build
`clean-build`	`rm -rf .next && next build`	Clean then build
`start`	`next start`	Serve production build
`lint`	`eslint .`	Run ESLint
`format`	`prettier --check .`	Check formatting
`format:fix`	`prettier --write .`	Auto-fix formatting
`test`	`vitest`	Run unit tests
`test:coverage`	`vitest --coverage`	Run tests with coverage report
`test:e2e`	`playwright test`	Run Playwright E2E tests
`test:all`	`npm run test && npm run test:e2e`	Run all tests