Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
Prerequisites: Node.js 20.x, npm 10+, Git. See Prerequisites for full setup.
This guide walks through setting up the WWAI Web App for local development. The application is a Next.js 16.0.10 project using React 19.2.3, TypeScript 5.7.2, Redux Toolkit 2.5.0, Tailwind CSS 3.4.17, and NextAuth 4.24.11. It runs on Node.js 20.x (production uses 20.9.0) and uses Turbopack for fast local development.
| Item | Value |
|---|---|
| Runtime | Node.js 20.x (production: 20.9.0) |
| Package Manager | npm 10.x |
| Default Port | 3000 |
| Dev Server | npm run dev (Turbopack) |
| Key Config | .env.local |
| Framework | Next.js 16.0.10, React 19.2.3 |
| Requirement | Version | Notes |
|---|---|---|
| Node.js | 20.x (LTS) | Recommended: use nvm to manage versions. Production uses 20.9.0. |
| npm | 10.x+ | Bundled with Node.js 20 |
| Git | 2.x+ | For repository access |
| IDE | VS Code (recommended) | With ESLint, Prettier, Tailwind CSS IntelliSense extensions |
git clone <repository-url> app-main
cd app-main
Ensure you are on the correct branch:
git checkout main
git pull origin main
npm install
This installs all dependencies defined in package.json, including Next.js, React, Redux Toolkit, NextAuth.js, TipTap (rich text editor), NextUI v2 (UI components), and all other libraries.
Note: The
preparescript automatically runshuskyduring install, which sets up Git hooks (e.g., pre-commit linting). This is expected behavior -- you will see Husky output during install.
Note: If you encounter peer dependency warnings, they are generally safe to ignore. Do not use
--forceor--legacy-peer-depsunless explicitly told to.
Create a .env.local file in the project root (the same directory as package.json):
cp .env.example .env.local # If .env.example exists
# Otherwise, create manually:
touch .env.local # macOS/Linux
# On Windows: New-Item .env.local -ItemType File
Important: The
.env.localfile must be in the same directory aspackage.json. If it is placed in a subdirectory or parent directory, Next.js will not load it.
Populate the file with the required environment variables. See Environment Variables for the complete reference (all 36 variables).
These five variables are the minimum needed to start the dev server:
# Backend API connection
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
# Environment identifier
NEXT_PUBLIC_ENVIRONMENT=local
# NextAuth session encryption
NEXTAUTH_SECRET=any-random-string-for-dev
# NextAuth base URL (must match your dev server URL)
NEXTAUTH_URL=http://localhost:3000
# Internal API key (server-only -- no NEXT_PUBLIC_ prefix)
WALTER_INTERNAL_KEY=your-internal-key
| Variable | Scope | Purpose |
|---|---|---|
NEXT_PUBLIC_BACKEND_URL |
Browser + Server | Base URL for all Django backend API calls. Used 40+ times in the codebase via utils/api.ts. |
NEXT_PUBLIC_ENVIRONMENT |
Browser + Server | Controls environment-specific behavior (analytics, feature flags, error reporting). Set to local for development. |
NEXTAUTH_SECRET |
Server only | Encrypts JWT session tokens. Any random string works for local development. |
NEXTAUTH_URL |
Server only | Tells NextAuth the canonical URL of the app. Must be http://localhost:3000 for local dev. |
WALTER_INTERNAL_KEY |
Server only | Sent as X-Walter-Internal-Key header on server-side API requests in utils/api.ts. Not prefixed with NEXT_PUBLIC_ -- this is a secret that must never reach the browser. |
For local dev, any string works. For production-like setups:
openssl rand -base64 32
# OAuth (needed for Google/Facebook login)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
FACEBOOK_CLIENT_ID=your-facebook-client-id
FACEBOOK_CLIENT_SECRET=your-facebook-client-secret
# Captcha (needed for registration)
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-turnstile-key
# Stripe (needed for payment flows)
NEXT_PUBLIC_STRIPE_KEY=your-stripe-publishable-key
| Variable type | When loaded | What to do after changes |
|---|---|---|
NEXT_PUBLIC_* variables |
Build time -- baked into the client JS bundle | Restart the dev server (Ctrl+C, then npm run dev) |
| Server-only variables (no prefix) | Runtime -- read on each request | Changes take effect on next server-side request (no restart needed in dev) |
Common mistake: Changing a
NEXT_PUBLIC_*variable and expecting it to update without restarting the dev server. These values are inlined at build/compile time. Always restart after changing them.
npm run dev
This runs next dev --turbopack, starting the Next.js development server with Turbopack for fast HMR (Hot Module Replacement).
Default URL: http://localhost:3000
Next.js uses port 3000 by default. No custom port is configured in
next.config.js. If port 3000 is occupied, Next.js will automatically try the next available port (3001, 3002, etc.) and display the actual URL in the terminal.
| Command | Script | Purpose |
|---|---|---|
npm run dev |
next dev --turbopack |
Start dev server with Turbopack for fast HMR |
npm run build |
next build |
Create optimized production build |
npm run start |
next start |
Start production server (requires npm run build first) |
npm run lint |
next lint |
Run ESLint on the codebase |
npm run prepare |
husky |
Install Git hooks (runs automatically on npm install) |
After the dev server starts, verify everything is working:
Navigate to http://localhost:3000. You should see the WWAI landing page.
Navigate to http://localhost:3000/en/humanizer. You should see the humanizer page. The next-intl middleware handles locale routing -- URLs follow the pattern /{locale}/{page}.
Open browser DevTools > Network tab. Refresh the page and look for requests to the NEXT_PUBLIC_BACKEND_URL host. Verify:
Open browser DevTools > Console. There should be no critical errors. Warnings about missing optional environment variables are expected if you have not configured all 36 variables.
If you have configured Google/Facebook OAuth credentials:
The app uses a middleware chain that runs on every request:
/en/, /de/, /es/, etc.)The following routes are accessible without authentication:
| Route | Description |
|---|---|
/ |
Landing page |
/login |
Login page |
/register |
Registration page |
/checkout |
Checkout flow |
/pricing |
Pricing page |
/forgot-password |
Password reset request |
/reset-password |
Password reset form |
/verify |
Email verification |
/account-deleted |
Account deletion confirmation |
/embed, /embed-2 through /embed-6 |
Embeddable widget variants |
/embed-register |
Embed registration flow |
/trial-started-email-signup |
Trial email signup |
/register-verification |
Registration verification |
/payment-failed-redirect/.+ |
Payment failure redirects (dynamic) |
/wp-plugin-callback |
WordPress plugin callback |
/sentry-example-page |
Sentry test page |
/account-setup |
Initial account setup |
All other routes require authentication. Unauthenticated users are redirected to the login page.
When configuring OAuth providers for local development, use these callback URLs:
| Provider | Callback URL |
|---|---|
http://localhost:3000/api/auth/callback/google |
|
http://localhost:3000/api/auth/callback/facebook |
Configure these in the respective developer consoles:
These URLs must match exactly, including the protocol (
http, nothttps) and port (3000).
Module not found errors after installCause: Incomplete or corrupted node_modules.
Fix:
rm -rf node_modules
rm -f package-lock.json
npm install
On Windows (PowerShell):
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install
Cause: Another process is using port 3000.
Fix:
# Find the process (macOS/Linux)
lsof -i :3000
# Find the process (Windows)
netstat -ano | findstr :3000
# Kill it, or use a different port:
PORT=3001 npm run dev
Note: If you change the port, you must also update
NEXTAUTH_URLin.env.localto match (e.g.,http://localhost:3001) and update your OAuth callback URLs in the provider consoles.
Cause: Variables in .env.local not configured correctly.
Fix checklist:
.env.local is in the same directory as package.json (not a subdirectory)NEXT_PUBLIC_WALTER_INTERNAL_KEY) do not get the NEXT_PUBLIC_ prefixNEXT_PUBLIC_* variable (they are baked at build time)Cause: NEXTAUTH_URL does not match the OAuth provider's configured redirect URI.
Fix:
NEXTAUTH_URL=http://localhost:3000 in .env.localhttp://localhost:3000/api/auth/callback/google as an authorized redirect URIhttp://localhost:3000/api/auth/callback/facebook as a valid OAuth redirect URICause: The backend does not allow requests from localhost:3000.
Fix:
http://localhost:3000Cause: Server-side rendering (SSR) hydration mismatch or missing CSS.
Fix:
"use client" directive -- they cannot be rendered as Server Componentstailwind.config.js includes TipTap component paths).next cache and restart:rm -rf .next && npm run dev
On Windows (PowerShell):
Remove-Item -Recurse -Force .next; npm run dev
Cause: Type mismatches introduced by recent changes.
Fix:
npx tsc --noEmit # Check for type errors without building
Fix reported type errors before attempting the build again. The project uses TypeScript 5.7.2 with strict mode.
Cause: Large node_modules or resource constraints.
Fix:
--turbopack in the terminal output when starting. The dev script explicitly uses it: next dev --turbopack.NODE_OPTIONS="--max-old-space-size=4096" npm run dev
Cause: Git hooks installed by Husky are failing on commit.
Fix:
prepare script during npm install.husky/ directory exists in the project rootnpx huskygit commit --no-verifyNEXT_PUBLIC_* variable shows as undefined in the browserCause: The dev server was not restarted after adding or changing the variable.
Fix:
NEXT_PUBLIC_* variables are inlined at build/compile time, not read at runtimeCtrl+C), then restart with npm run devNEXT_PUBLIC_ (case-sensitive)After setup, familiarize yourself with:
| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Initial creation |
| 2026-01-30 | Docs team | Rewritten with verified source code facts: corrected port from 3001 to 3000 (Next.js default), fixed WALTER_INTERNAL_KEY (removed incorrect NEXT_PUBLIC_ prefix), added "What Each Variable Does" quick reference, documented all package.json scripts including Husky, added middleware behavior and public pages list, added OAuth callback URLs, added build-time vs runtime variable explanation, expanded troubleshooting with Windows commands, added Husky and NEXT_PUBLIC_ undefined issues |
Prev: Web App Overview | Next: Folder Structure | Up: WalterWrites