BIGboss248/nextjs-wordpress

Next.js Development Setup (nextjs-dev-setup)

A structured, end-to-end orchestration runbook for discovering, configuring, and verifying the Next.js App Router development environment, reverse proxy routing (Traefik / Nginx), and single source of truth at docs/project.json.

---

Pre-Conditions & Discovery

• Zero-Interruption Scan: Scan existing repository files (package.json, lockfiles, stylesheets, docs/adr/*.md, docs/plan.md, CONTEXT.md) before asking questions.
• Consult project-json-schema.md for metadata structure and automated deduction rules.

---

Phase 0: Multi-Round Setup Interview (Grilling) & Plan Generation

Conduct the interactive interview in progressive, adaptive rounds (waiting for user response after each round) to tailor the setup:

1. Round 1 (Scope & Tooling): Probe target testing suites (Jest, Playwright, Storybook), MCP servers, and @shadcn/lint enforcement.
2. Round 2 (Reverse Proxy & Production Hosting): Probe domain name, port, and reverse proxy strategy:
   • Traefik via Docker Compose: Automated container discovery using Compose labels reading from environment variables (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) with anti-buffering.
   • Nginx via Host System: Standalone configuration in /etc/nginx/sites-available/<domain> using Certbot SSL certificates.
3. Round 3 (CI/CD, Git Hooks & Registry): Probe Husky pre-push test suites, Commitlint, and GitHub Actions Release Please / GHCR workflows.
4. Consult setup-interview-rounds.md for complete question sets and branching logic.
5. Plan & Execution: Generate and present an implementation_plan.md artifact detailing all planned file creations, configurations, and packages before applying changes, and proceed directly with execution without waiting for manual confirmation.

---

Step-by-Step Execution Flow

Stage 1: Project Metadata & Developer Tooling (docs/project.json)

1. Initialize docs/project.json using project.template.json based on user interview choices.
2. Configure .vscode/launch.json using vscode-launch.json.template.
3. Scaffold app/providers.tsx with <ProgressBarProvider> using providers.tsx.template and composite <Link> using Link.tsx.template.
4. Scaffold .env.example using env.example.template for production and .env.local using env.local.template for local development.
5. App Icons, Apple Icon & PWA Manifest: Deploy manifest.ts.template to app/manifest.ts. Configure the user-provided favicon across root app/favicon.ico, app/icon.png, and app/apple-icon.png (or dynamic ImageResponse icon). Consult app-icons-and-pwa-guide.md.

Stage 2: Testing Suites (Jest, Playwright & Instant Navigation)

[!IMPORTANT] No Dummy Test Files (Rule 3): Do not create placeholder/sample test files in the workspace. Configure framework files and scripts only. Sample patterns are available in sample-component.test.tsx, sample-navigation.spec.ts, and sample-component.stories.tsx.

1. Jest Unit Testing: Configure jest.config.ts.template and jest.setup.ts.template.
2. Playwright E2E & Instant Navigation: Install @playwright/test and @next/playwright (pnpm add -D @playwright/test @next/playwright), configure playwright.config.ts.template, and install browsers.
3. Next.js Instant Config: Configure cacheComponents: true, partialPrefetching: true, and instant insights in next.config.ts.
4. Storybook Workshop: Configure .storybook/main.ts and .storybook/preview.tsx.
5. Review architectures in testing-guide.md and storybook-guide.md.

Stage 3: Dual MCP Server Configuration

[!IMPORTANT] Antigravity Global MCP Loading Rule: AG only loads MCP servers configured globally on the host system (~/.gemini/antigravity/mcp_config.json and ~/.gemini/config/mcp_config.json). Workspace mcp.json is maintained for portability. Both must be configured.

1. Configure next-devtools, playwright, storybook, and codebase-memory-mcp.
2. Stutter Prevention: Set auto_watch = false via codebase-memory-mcp config set auto_watch false and deploy root .cbmignore.
3. Review full specs in mcp-configuration-guide.md.

Stage 4: Agent-First Design System Linting (@shadcn/lint)

1. Install @shadcn/lint and configure ESLint flat config using eslint.config.mjs.template.
2. Review mechanics in styling-and-linting-guide.md.

Stage 5: Standalone Production Docker & Reverse Proxy (Traefik / Nginx)

1. In next.config.ts: resolve Git commit hash (getGitCommitHash() with CI fallbacks) and package version, inject NEXT_PUBLIC_APP_VERSION and NEXT_PUBLIC_GIT_COMMIT_HASH under env, enable output: "standalone", set deploymentId for version skew protection (${pkg.version}-${gitHash}), configure headers with X-Accel-Buffering: no, and set experimental.serverActions.allowedOrigins.
2. Document NEXT_SERVER_ACTIONS_ENCRYPTION_KEY in .env.example and pass it to runtime environments.
3. Deploy Dockerfile.template (with STOPSIGNAL SIGTERM) and docker-compose.yml.template (with stop_grace_period: 30s).
4. Reverse Proxy Configuration:
   • Traefik: Deploy docker-compose.prod.yml.template with dynamic environment variable labels (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) and anti-buffering middleware.
   • Nginx: Deploy or output nginx-site.conf.template for /etc/nginx/sites-available/<domain> with Certbot SSL certificates.
5. Review architecture and multi-container cache drift callout in docker-containerization-guide.md.

Stage 6: Git Hooks & Credit-Optimized CI/CD

1. Install husky, @commitlint/cli, @commitlint/config-conventional.
2. Configure commitlint.config.mjs.template, .husky/commit-msg, and .husky/pre-push (pnpm run test:all).
3. Deploy .github/workflows/release-please.yml with .next/cache build caching and multi-arch matrix publishing.
4. Review caching in cicd-and-release-automation-guide.md.

Stage 7: Final Execution Report & Verification

1. Execute the configuration verification script and ensure all checks pass.
2. Stage all created/modified files in git (git add .) per Rule 36.
3. Mandatory Final Output: Render the complete, structured Next.js Dev Setup Execution Report markdown table summarizing all implemented files, verification check results, and next development steps.

---

Verification & Sanity Check

• Execute configuration verification script:
  • Windows (PowerShell): powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1
  • Linux / macOS (Bash): bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
• Fix any reported errors and re-verify until all checks pass.

---

Edge Cases & Known AI Pitfalls

• Chained Commands: Never chain commands with && or ; on a single line in terminal execution.
• MCP Disabling: In AG global configs, agy.exe ignores "disabled": true inside mcpServers. Move disabled servers outside mcpServers.
• Docker Image Names: Docker OCI naming strictly requires lowercase repository names (IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')).
• Storybook Intl Context: Always wrap Storybook stories rendering Link or useTranslations with NextIntlClientProvider.

---

Mandatory Final Output: Execution Report Template

Always output this report upon completing the skill workflow:

## 🛠️ Next.js Dev Setup Execution Report

| Step / Component                     | Target File(s) / Resource                                                                              | Status                          | Notes / Details                                                                  |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------- |
| **1. Project Metadata**              | `docs/project.json`                                                                                    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured package manager, directories, animation & i18n metadata.              |
| **2. App Icons & PWA Manifest**      | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                             | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured root favicon, Apple touch icon, and Web App Manifest using user favicon. |
| **3. Core Dependencies**             | `package.json`, Lockfile                                                                               | `[IMPLEMENTED]` / `[UNTOUCHED]` | Verified React, Next.js, styling, and motion libraries.                          |
| **4. Next.js Dev Server MCP**        | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Next.js Dev Server (`next-devtools`) globally for AG & in workspace.  |
| **5. Playwright & Instant Testing** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Verified runner, browsers, Playwright MCP & `@next/playwright` instant navigation helper. |
| **6. Codebase Memory & Stutter Fix** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                  | `[IMPLEMENTED]` / `[UNTOUCHED]` | Registered MCP, configured .cbmignore exclusions, and disabled session watcher.  |
| **7. Jest Unit Testing**             | `jest.config.ts`, `jest.setup.ts`                                                                      | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Next.js Jest transformer, jsdom environment & test-dom.               |
| **8. Storybook & Storybook MCP**     | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Storybook Vite, a11y, themes & Storybook AI MCP globally & workspace. |
| **9. Agent-First Tailwind Linter**   | `eslint.config.mjs`, `package.json`                                                                    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured `@shadcn/lint` for agent verification of design tokens and contracts. |
| **10. Docker & Reverse Proxy**       | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                            | `[IMPLEMENTED]` / `[UNTOUCHED]` | Standalone container, Traefik labels / Nginx HTTPS with Certbot SSL.             |
| **11. Husky Git Hooks**              | `.husky/commit-msg`, `.husky/pre-push`                                                                 | `[IMPLEMENTED]` / `[UNTOUCHED]` | Enforces dual pre-push test suite (Jest + Playwright) & commitlint.              |
| **12. Commitlint Config**            | `commitlint.config.mjs`                                                                                | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured `@commitlint/config-conventional`.                                    |
| **13. Release & CI Build Caching**   | `.github/workflows/release-please.yml`                                                                 | `[IMPLEMENTED]` / `[UNTOUCHED]` | Next.js build cache (.next/cache), SemVer release PRs & GHCR multi-arch pkg.     |
| **14. Environment Verification**     | `scripts/verify-project-config.ps1` / `.sh`                                                            | `[PASSED]`                      | Sanity check passed with zero errors.                                            |

#### Status Definitions:
- **`[IMPLEMENTED]`**: Freshly created, installed, or modified during this setup run.
- **`[UNTOUCHED]`**: Already properly configured prior to running the skill; preserved as-is.
- **`[SKIPPED]`**: Intentionally omitted based on user preference.