How to run the frontend

Start the Next.js web console (frontend/apps/console/) for local development. The console provides the dashboard UI for test runs, bug reports, and project configuration.

Prerequisites

• Node.js 22+ and pnpm 9+ (setup guide)
• Backend running on port 8080 (for API calls) — see run the backend

Steps

Step 1: Install dependencies

From the repository root:

pnpm install

Step 2: Set environment variables

# Create a local env file (not committed)
cp frontend/apps/console/.env.example frontend/apps/console/.env.local

Key variables in .env.local:

# API proxy target (defaults to localhost:8080)
NEXT_PUBLIC_API_URL=http://localhost:8080

# Auth (local dev — bypass OAuth for convenience)
NEXT_PUBLIC_AUTH_ENABLED=false

Step 3: Start dev server

cd frontend/apps/console
pnpm dev

Expected output:

  ▲ Next.js 15.x
  - Local:   http://localhost:3000
  - Ready in 2.1s

Step 4: Verify

1. Open http://localhost:3000 in your browser
2. You should see the Aucert dashboard (or login page if auth is enabled)
3. Check the browser console for API errors — if the backend isn't running, you'll see fetch failed errors

API proxy

The Next.js dev server proxies API calls to the backend. This is configured in next.config.ts:

// frontend/apps/console/next.config.ts
async rewrites() {
  return [
    {
      source: '/api/:path*',
      destination: 'http://localhost:8080/api/:path*',
    },
  ];
}

Requests to http://localhost:3000/api/... are transparently forwarded to http://localhost:8080/api/.... This avoids CORS issues during development.

Common tasks

Task	Command
Start dev server	pnpm dev
Build production	pnpm build
Run tests	pnpm test
Run tests in watch mode	pnpm test:watch
Lint	pnpm lint
Type check	pnpm typecheck
Format code	pnpm format

Troubleshooting

API calls fail with "fetch failed" or CORS errors

1. Verify the backend is running: curl http://localhost:8080/health
2. Check that the proxy config in next.config.ts points to the correct port
3. If you changed NEXT_PUBLIC_API_URL, restart the dev server (env changes require restart)

Port 3000 already in use

Kill the existing process or use a different port:

# Find what's using port 3000
lsof -i :3000

# Use a different port
PORT=3001 pnpm dev

"Module not found" or stale cache

Clear Next.js cache and node modules cache:

rm -rf .next node_modules/.cache
pnpm install
pnpm dev

Tailwind styles not applying

Verify Tailwind is watching the right content paths in tailwind.config.ts. The content array should include:

content: [
  './src/**/*.{ts,tsx}',
  './app/**/*.{ts,tsx}',
]

If newly added component directories aren't covered, add them to the content array and restart the dev server.

What's next

• How to run tests — Frontend test suite
• How to run the backend — Backend dev server
• How to add an API endpoint — Full-stack development