Web Frontend Builder

Step 2: Configure Next.js

Edit next.config.ts to set standalone output (required for Docker deployments):

const nextConfig = {
  output: 'standalone',
};

IMPORTANT: Next.js evaluates next.config.ts — including rewrites() — at build time. Any environment variable used in next.config.ts (e.g., BACKEND_URL for API rewrites) must be available during pnpm build. In Docker, this means declaring it as a build argument (ARG) and setting it as an environment variable (ENV) in the Dockerfile before the build step. A runtime-only environment: entry in docker-compose.yml is too late — the rewrite rules are already baked into the build output. See fullstack-architecture.md for the Dockerfile and Docker Compose configuration.

Step 3: Enable Strict TypeScript

Verify tsconfig.json has "strict": true. This is non-negotiable.

Step 4: Initialize shadcn/ui

pnpm dlx shadcn@latest init

When prompted, select the defaults that match the project's design direction. Then install the components needed:

pnpm dlx shadcn@latest add button card input table dialog

Add more components as needed during development.

Step 5: Configure shadcn MCP Server

Add to the project's .mcp.json:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Step 6: Set Up Brand Colors and Semantic Tokens

Configure Open Elements brand colors in tailwind.config.ts so they are available as utility classes. Use the open-elements-brand-guidelines skill to get the exact color values.

IMPORTANT: shadcn/ui components reference semantic CSS custom properties (e.g., --color-background, --color-popover, --color-border). These must be defined in the @theme block of src/app/globals.css, mapped to the project's brand colors. Without them, dialogs, dropdowns, tables, and inputs will render with transparent backgrounds and missing borders.

Required semantic tokens (each with -foreground counterpart where applicable):

See the shadcn/ui Theming docs for details. Never hardcode colors in component files — always use semantic tokens.

Step 7: Verify Setup

pnpm dev

Confirm the dev server starts without errors.

Developing Features

Adding Pages

Create pages in src/app/ following Next.js App Router conventions:

• src/app/page.tsx — home page
• src/app/<route>/page.tsx — additional pages
• src/app/layout.tsx — root layout with consistent header/navigation and footer

IMPORTANT: Pages that fetch data from a backend API must not be statically pre-rendered. Use export const dynamic = 'force-dynamic' to ensure request-time rendering.

Adding Components

Place reusable components in src/components/. Follow these conventions:

• One component per file, named in PascalCase matching the export
• Use shadcn/ui components as building blocks — do not create bare HTML equivalents
• Use shadcn/ui Blocks as starting points for layout structures (sidebar shells, dashboard layouts)
• Apply consistent spacing using Tailwind's spacing scale (p-4, p-6, gap-4, gap-6)
• Constrain content width for readability (max-w-screen-xl mx-auto)
• Ensure responsive design with Tailwind's responsive prefixes (sm:, md:, lg:)

Internationalization

All user-facing text must be i18n-ready from the start:

• Extract all display strings into a central location (constants file or translation file)
• Use consistent key naming (page.section.element)
• Use parameterized messages with placeholders ("Welcome, {name}" not "Welcome, " + name)
• Keep date, number, and currency formatting locale-aware (Intl.DateTimeFormat, Intl.NumberFormat)

Error Handling

• Log detailed errors to the browser console (HTTP status, endpoint URL, error body)
• Never show raw backend error messages to the user — display simplified, user-friendly messages
• Centralize backend error handling in a shared API client layer

Testing

Use the testing framework present in the project (Jest, Vitest, or Node test runner):

pnpm test

• Name tests descriptively: it('should return empty array when no items exist')
• Group related tests with describe blocks
• Avoid excessive mocking — prefer simple stub/dummy implementations

Common Commands

• Install dependencies: pnpm install
• Dev server: pnpm dev
• Build: pnpm build
• Run tests: pnpm test
• Lint: pnpm lint
• Type check: pnpm tsc --noEmit

Quality Checklist

Before considering a feature complete, verify:

• pnpm build succeeds without errors
• pnpm lint passes
• pnpm tsc --noEmit reports no type errors
• All pages are responsive (mobile, tablet, desktop)
• No bare HTML elements where shadcn/ui components exist
• No hardcoded user-facing strings — all are i18n-ready
• No console.log in production code — use console.error, console.warn, console.info
• No sensitive data logged to the browser console
• Standalone output configured in next.config.ts
• Brand colors applied via Tailwind config
• All shadcn/ui semantic CSS tokens defined in globals.css @theme block

Reference

• Next.js docs: https://nextjs.org/docs
• shadcn/ui components: https://ui.shadcn.com/docs/components
• shadcn/ui Blocks: https://ui.shadcn.com/blocks
• Tailwind CSS: https://tailwindcss.com/docs