aegis-nextjs-frontend

What this skill does

# Next.js Frontend with ByteForge Aegis Authentication

This skill scaffolds a complete Next.js 16 frontend with ByteForge Aegis authentication, internationalization (next-intl), Tailwind CSS v4, and Docker deployment. The generated project includes login, email verification, password reset, and protected dashboard pages out of the box.

## When to Use This Skill

- Starting a new web application that needs user authentication
- Creating a frontend for an existing ByteForge Aegis-powered backend
- Spinning up a new site with login, signup, i18n, and Docker support
- Needing a production-ready Next.js template with auth already wired up

## What This Skill Creates

1. **Next.js 16 project** with App Router and `[locale]` dynamic segments
2. **Full auth flow** - Login, email verification, password reset, email change confirmation, welcome page
3. **Protected dashboard** - Auth-gated page with redirect to login
4. **Internationalization** - next-intl with English translations (extensible to any language)
5. **Auth utilities** - Singleton `browserClient` with token refresh, `useAuth` hook with proactive refresh, `AuthCTA` component
6. **Language switcher** - Scalable dropdown component in header
7. **Design system** - CSS variables, light/dark mode, animations, card/button/input components
8. **Docker deployment** - Multi-stage Dockerfile with standalone output
9. **Health check endpoint** - `/api/health` for container orchestration
10. **Loki logging** - Structured server-side logging with Grafana Loki (production) and console fallback (local dev)
11. **Webhook provisioning docs** - Aegis user.verified webhook contract and reference implementation for tenant-side user provisioning

## Step 1: Gather Project Information

**IMPORTANT**: Before creating any files, ask the user these questions:

1. **"What is your project name?"** (e.g., "DevNotes", "TaskFlow", "ReleasePad")
   - Derive:
     - `{ProjectName}` - Display name (e.g., "DevNotes")
     - `{project-name}` - Kebab case for package.json, Docker, URLs (e.g., "devnotes")
     - `{project_name}` - Snake case for internal use (e.g., "dev_notes")

2. **"What is the site domain?"** (e.g., "devnotes.ai", "taskflow.reallybadapps.com")
   - Used for `NEXT_PUBLIC_SITE_DOMAIN`

3. **"What is the Aegis API URL?"** (default: `https://aegis.reallybadapps.com`)
   - Used for `NEXT_PUBLIC_AEGIS_API_URL` (browser bootstrap) and `AEGIS_API_URL` (server-side proxy)

3a. **"What is the tenant API key for this site? (Get it from the Aegis admin dashboard → Site → Settings → Tenant API Key)"**
   - Used for `AEGIS_TENANT_API_KEY` (server-side only). REQUIRED for the gated public auth endpoints. See Step 5b and `references/tenant-api-key-templates.md`.

3b. **"What is the site_id for this site in Aegis?"** (visible in the admin dashboard)
   - Used for `AEGIS_SITE_ID` (server-side, used by proxy routes for verify-email/etc.).

4. **"What is the container registry URL?"** (e.g., `ghcr.io/org/project-frontend`)
   - Used in docker-compose and build scripts

5. **"What is a one-line description of the project?"** (e.g., "AI-powered release notes platform")
   - Used in metadata, home page subtitle, health check

6. **"Does your backend need to provision users when they verify on Aegis? If yes, what backend handles it?"** (e.g., "Yes, Flask backend" / "Yes, Next.js API routes" / "No")
   - Determines whether to include webhook setup instructions in Step 14

## Step 2: Create Directory Structure

```
{project-name}-frontend/
├── app/
│   ├── layout.tsx
│   ├── globals.css
│   ├── [locale]/
│   │   ├── layout.tsx
│   │   ├── page.tsx                    # Home page (customize per project)
│   │   ├── login/page.tsx
│   │   ├── verify-email/page.tsx
│   │   ├── forgot-password/page.tsx
│   │   ├── reset-password/page.tsx
│   │   ├── confirm-email-change/page.tsx
│   │   ├── welcome/page.tsx
│   │   └── dashboard/page.tsx
│   └── api/health/route.ts
├── i18n/
│   ├── routing.ts
│   ├── request.ts
│   └── navigation.ts
├── lib/
│   ├── browserClient.ts
│   ├── logger.ts
│   └── useAuth.ts
├── components/
│   ├── AuthCTA.tsx
│   └── LanguageSwitcher.tsx
├── messages/
│   └── en.json
├── public/
│   └── .gitkeep                        # required so Dockerfile COPY /app/public succeeds
├── proxy.ts                            # next-intl middleware
├── package.json
├── next.config.ts
├── tsconfig.json
├── tailwind.config.ts
├── postcss.config.mjs
├── global.d.ts
├── .env.example
├── .gitignore                          # includes VERSION (and build-publish.sh if Tier 2)
├── Dockerfile
├── docker-compose.example.yaml
└── build-publish.sh                    # chmod +x, see Step 12
```

## Step 3: Create Configuration Files

Generate each configuration file using the templates in `references/config-templates.md`. These files are mostly boilerplate with placeholder substitutions:

- `package.json` - Dependencies including `byteforge-aegis-client-js`, `byteforge-loki-logging-ts`, `next-intl`, Tailwind v4
- `next.config.ts` - next-intl plugin, transpilePackages for aegis client and loki logging, standalone output
- `tsconfig.json` - ES2017 target, strict mode, `@/*` path alias
- `tailwind.config.ts` - Content paths for app/ and components/
- `postcss.config.mjs` - `@tailwindcss/postcss` plugin
- `global.d.ts` - IntlMessages type declaration
- `.env.example` - `NEXT_PUBLIC_AEGIS_API_URL`, `NEXT_PUBLIC_SITE_DOMAIN`, and Loki logging variables

**CRITICAL**: Replace all instances of `{project-name}`, `{ProjectName}`, `{site_domain}`, `{aegis_api_url}`, and `{project_description}` in every file.

## Step 4: Create i18n Infrastructure

Generate files from `references/i18n-templates.md`:

- `i18n/routing.ts` - Locale definitions (start with `['en']`, add more as needed)
- `i18n/request.ts` - Server-side message loading
- `i18n/navigation.ts` - Locale-aware `Link`, `useRouter`, `usePathname`
- `proxy.ts` - next-intl middleware wrapped with a defensive Host-header fallback that fixes redirect URLs when the upstream proxy doesn't forward `X-Forwarded-Host` / `X-Forwarded-Port`. Matches all paths except `/api`, `/_next`, static files. See `docker-templates.md` for the upstream proxy header contract.

These files are identical across projects. No placeholder substitution needed.

## Step 5: Create Auth Utilities

Generate files from `references/auth-templates.md`:

- `lib/browserClient.ts` - Singleton AuthClient that persists tokens in memory and syncs to localStorage. Includes `initAuthClientFromLogin()`, `refreshAuthTokens()`, `isTokenExpired()`, `clearAuthClient()`, and the `browserAuthProxy` shim that posts to the local `/api/frontend/auth/*` proxy routes (used by auth pages for the six tenant-key-gated endpoints).
- `lib/useAuth.ts` - React hook that reads auth state from localStorage, proactively refreshes tokens (5-minute buffer, 60-second check interval), and auto-logs out on refresh failure.

These files are identical across projects except for the default env variable values (`{aegis_api_url}`, `{site_domain}`).

### Step 5b: Tenant API Key Proxy Routes (Required)

After backend image v40+, six public auth endpoints (`register`, `login`, `request-password-reset`, `reset-password`, `verify-email`, `check-verification-token`) require an `X-Tenant-Api-Key` header that **must live server-side**. This means scaffolded apps need backend proxy routes for these flows — the browser cannot call Aegis directly for them.

Generate from `references/tenant-api-key-templates.md`:

- `lib/serverAuthClient.ts` — server-side `AuthClient` factory configured with `AEGIS_TENANT_API_KEY` and `AEGIS_SITE_ID` from env.
- `app/api/frontend/auth/register/route.ts`
- `app/api/frontend/auth/login/route.ts`
- `app/api/frontend/auth/request-password-reset/route.ts`
- `app/api/frontend/auth/reset-password/route.ts`
- `app/api/frontend/auth/verify-email/route.ts`
- `app/api/frontend/auth/check-verification-token/route.ts`
- (The `browserAuthProxy` helper is already inli