S13 App Starter — Next.js + Tailwind v4 + Auth0 (Regular Web App)

Production‑quality starter using Next.js App Router, Tailwind v4 utilities, and Auth0 v4 for login/registration.

Prerequisites

• Node 20+ (LTS). On Windows with Git Bash, ensure PATH includes C:\Program Files\nodejs and C:\Users\<you>\AppData\Roaming\npm.
• An Auth0 tenant and a Regular Web Application.

Environment variables

Create .env.local in the project root:

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_SECRET=your-32-byte-hex-secret
APP_BASE_URL=http://localhost:3000

• Generate a strong AUTH0_SECRET locally:
  • macOS/Linux: openssl rand -hex 32
  • Windows (PowerShell): powershell -Command "$b=[byte[]]::new(32); [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); ($b|ForEach-Object ToString X2) -join ''"

Auth0 application setup (critical)

In Auth0 Dashboard → Applications → your app:

• Type: Regular Web Application
• Credentials → Authentication Method: Client Secret (Post)
• Settings → Allowed Callback URLs: http://localhost:3000/auth/callback
• Settings → Allowed Logout URLs: http://localhost:3000
• Settings → Allowed Web Origins: http://localhost:3000
• Settings → Domain: copy the exact domain (e.g., dev-xxxxx.us.auth0.com)
• Optional: Rotate Client Secret; update .env.local if you do

Develop

npm install
npm run dev

Open http://localhost:3000. Click “Sign in / Register”. After authentication you land on /dashboard.

If you change .env.local, restart the dev server.

Build & run production locally

npm run build
npm start

Troubleshooting Auth0

• Discovery fails (404): AUTH0_DOMAIN is mistyped. Visit https://<domain>/.well-known/openid-configuration; it must return JSON.
• AuthorizationCodeGrantError at /error:
  • Verify app type = Regular Web Application
  • Credentials → Authentication Method = Client Secret (Post)
  • Callback/Logout/Web Origins set as above
  • AUTH0_CLIENT_ID/SECRET match the same app
  • Clear site data or use Incognito to avoid stale cookies
• Port in use (EADDRINUSE): free ports 3000/3001 and restart: npx kill-port 3000 3001

Project structure

src/
  app/
    page.tsx            # Landing with CTA
    dashboard/page.tsx  # Protected page (requires login)
    error/page.tsx      # Friendly error surface
  components/nav/Navbar.tsx
  lib/auth0.ts          # Auth0 v4 client + onCallback handling
  middleware.ts         # Mounts /auth/* and guards

Notes

• Styling: Tailwind v4 utilities only (no CLI config needed).
• UI/UX: neutral palette, responsive layout, keyboard accessible links.