nextjs-wordpress

Configuración de Desarrollo Next.js (nextjs-dev-setup)

Un runbook de orquestación estructurado de extremo a extremo para descubrir, configurar y verificar el entorno de desarrollo Next.js App Router, enrutamiento de proxy inverso (Traefik / Nginx) y una fuente única de verdad en docs/project.json.

---

Precondiciones y Descubrimiento

• Escaneo sin interrupciones: Escanea los archivos existentes del repositorio (package.json, lockfiles, hojas de estilo, docs/adr/*.md, docs/plan.md, CONTEXT.md) antes de hacer preguntas.
• Consulta project-json-schema.md para la estructura de metadatos y las reglas de deducción automatizadas.

---

Fase 0: Entrevista de Configuración Multironda (Cuestionamiento) y Generación del Plan

Realiza la entrevista interactiva en rondas progresivas y adaptativas (esperando la respuesta del usuario después de cada ronda) para personalizar la configuración:

1. Ronda 1 (Alcance y Herramientas): Indaga sobre las suites de pruebas objetivo (Jest, Playwright, Storybook), servidores MCP y la aplicación de @shadcn/lint.
2. Ronda 2 (Proxy Inverso y Alojamiento en Producción): Indaga sobre el nombre de dominio, puerto y estrategia de proxy inverso:
   • Traefik mediante Docker Compose: Descubrimiento automatizado de contenedores usando etiquetas de Compose que leen variables de entorno (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) con anti-buffering.
   • Nginx mediante Sistema Anfitrión: Configuración independiente en /etc/nginx/sites-available/<dominio> usando certificados SSL de Certbot.
3. Ronda 3 (CI/CD, Hooks de Git y Registro): Indaga sobre las suites de pruebas de pre-push de Husky, Commitlint y los flujos de trabajo de GitHub Actions Release Please / GHCR.
4. Consulta setup-interview-rounds.md para conjuntos completos de preguntas y lógica de ramificación.
5. Plan y Ejecución: Genera y presenta un artefacto implementation_plan.md que detalla todas las creaciones de archivos planificadas, configuraciones y paquetes antes de aplicar los cambios, y procede directamente con la ejecución sin esperar confirmación manual.

---

Flujo de Ejecución Paso a Paso

Etapa 1: Metadatos del Proyecto y Herramientas de Desarrollo (docs/project.json)

1. Inicializa docs/project.json usando project.template.json basado en las elecciones de la entrevista del usuario.
2. Configura .vscode/launch.json usando vscode-launch.json.template.
3. Crea el andamiaje de app/providers.tsx con <ProgressBarProvider> usando providers.tsx.template y un <Link> compuesto usando Link.tsx.template.
4. Crea el andamiaje de .env.example usando env.example.template para producción y .env.local usando env.local.template para desarrollo local.
5. Íconos de la Aplicación, Icono de Apple y Manifiesto PWA: Despliega manifest.ts.template en app/manifest.ts. Configura el favicon proporcionado por el usuario en app/favicon.ico, app/icon.png y app/apple-icon.png (o un icono dinámico ImageResponse). Consulta app-icons-and-pwa-guide.md.

Etapa 2: Suites de Pruebas (Jest, Playwright y Navegación Instantánea)

[!IMPORTANT] Sin Archivos de Prueba de Relleno (Regla 3): No crees archivos de prueba de muestra o marcadores de posición en el espacio de trabajo. Configura únicamente los archivos del framework y los scripts. Los patrones de ejemplo están disponibles en sample-component.test.tsx, sample-navigation.spec.ts y sample-component.stories.tsx.

1. Pruebas Unitarias Jest: Configura jest.config.ts.template y jest.setup.ts.template.
2. Playwright E2E y Navegación Instantánea: Instala @playwright/test y @next/playwright (pnpm add -D @playwright/test @next/playwright), configura playwright.config.ts.template e instala los navegadores.
3. Configuración Instantánea de Next.js: Configura cacheComponents: true, partialPrefetching: true y la información instantánea (instant insights) en next.config.ts.
4. Storybook Workshop: Configura .storybook/main.ts y .storybook/preview.tsx.
5. Revisa las arquitecturas en testing-guide.md y storybook-guide.md.

Etapa 3: Configuración Dual de Servidores MCP

[!IMPORTANT] Regla de Carga Global de MCP de Antigravity: AG solo carga servidores MCP configurados globalmente en el sistema anfitrión (~/.gemini/antigravity/mcp_config.json y ~/.gemini/config/mcp_config.json). El mcp.json del espacio de trabajo se mantiene para portabilidad. Ambos deben estar configurados.

1. Configura next-devtools, playwright, storybook y codebase-memory-mcp.
2. Prevención de Tartamudeo: Establece auto_watch = false mediante codebase-memory-mcp config set auto_watch false y despliega la raíz .cbmignore.
3. Revisa las especificaciones completas en mcp-configuration-guide.md.

Etapa 4: Linting del Sistema de Diseño Centrado en el Agente (@shadcn/lint)

1. Instala @shadcn/lint y configura la configuración plana de ESLint usando eslint.config.mjs.template.
2. Revisa los mecanismos en styling-and-linting-guide.md.

Etapa 5: Docker de Producción Independiente y Proxy Inverso (Traefik / Nginx)

1. En next.config.ts: resuelve el hash del commit de Git (getGitCommitHash() con fallbacks de CI) y la versión del paquete, inyecta NEXT_PUBLIC_APP_VERSION y NEXT_PUBLIC_GIT_COMMIT_HASH bajo env, habilita output: "standalone", establece deploymentId para la protección contra desajustes de versión (${pkg.version}-${gitHash}), configura headers con X-Accel-Buffering: no, y establece experimental.serverActions.allowedOrigins.
2. Documenta NEXT_SERVER_ACTIONS_ENCRYPTION_KEY en .env.example y pásalo a los entornos de ejecución.
3. Despliega Dockerfile.template (con STOPSIGNAL SIGTERM) y docker-compose.yml.template (con stop_grace_period: 30s).
4. Configuración del Proxy Inverso:
   • Traefik: Despliega docker-compose.prod.yml.template con etiquetas dinámicas de variables de entorno (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) y middleware de anti-buffering.
   • Nginx: Despliega o genera nginx-site.conf.template para /etc/nginx/sites-available/<dominio> con certificados SSL de Certbot.
5. Revisa la arquitectura y la advertencia sobre la desviación de la caché en múltiples contenedores en docker-containerization-guide.md.

Etapa 6: Hooks de Git y CI/CD Optimizado para Créditos

1. Instala husky, @commitlint/cli, @commitlint/config-conventional.
2. Configura commitlint.config.mjs.template, .husky/commit-msg y .husky/pre-push (pnpm run test:all).
3. Despliega .github/workflows/release-please.yml con almacenamiento en caché de compilación .next/cache y publicación en matriz multiarquitectura.
4. Revisa el almacenamiento en caché en cicd-and-release-automation-guide.md.

Etapa 7: Informe Final de Ejecución y Verificación

1. Ejecuta el script de verificación de configuración y asegúrate de que todas las comprobaciones se superen.
2. Prepara todos los archivos creados/modificados en git (git add .) según la Regla 36.
3. Salida Final Obligatoria: Renderiza la tabla markdown completa y estructurada del Informe de Ejecución de Configuración de Next.js Dev que resume todos los archivos implementados, los resultados de las comprobaciones de verificación y los siguientes pasos de desarrollo.

---

Verificación y Comprobación de Cordura

• Ejecuta el script de verificación de configuración:
  • 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
• Corrige cualquier error reportado y vuelve a verificar hasta que todas las comprobaciones se superen.

---

Casos Extremos y Errores Conocidos de la IA

• Comandos Encadenados: Nunca encadenes comandos con && o ; en una sola línea en la ejecución del terminal.
• Desactivación de MCP: En las configuraciones globales de AG, agy.exe ignora "disabled": true dentro de mcpServers. Mueve los servidores desactivados fuera de mcpServers.
• Nombres de Imágenes Docker: La nomenclatura OCI de Docker requiere estrictamente nombres de repositorio en minúsculas (IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')).
• Contexto de Internacionalización de Storybook: Siempre envuelve las historias de Storybook que renderizan Link o useTranslations con NextIntlClientProvider.

---

Salida Final Obligatoria: Plantilla del Informe de Ejecución

Genera siempre este informe al completar el flujo de trabajo del skill:

## 🛠️ Informe de Ejecución de Configuración de Next.js Dev

| Paso / Componente                  | Archivo(s) Destino / Recurso                                                                           | Estado                          | Notas / Detalles                                                               |
| :--------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------ | :----------------------------------------------------------------------------- |
| **1. Metadatos del Proyecto**      | `docs/project.json`                                                                                    | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Paquete configurado, directorios, metadatos de animación e i18n.               |
| **2. Íconos de App y Manifiesto PWA** | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                             | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Favicon raíz, icono táctil de Apple y Manifiesto de Aplicación Web configurados usando el favicon del usuario. |
| **3. Dependencias Principales**    | `package.json`, Lockfile                                                                               | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | React, Next.js, estilos y librerías de movimiento verificados.                |
| **4. MCP del Servidor Dev de Next.js** | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json` | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Servidor Dev de Next.js (`next-devtools`) configurado globalmente para AG y en el espacio de trabajo. |
| **5. Playwright y Pruebas Instantáneas** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Runner, navegadores, MCP de Playwright y helper de navegación instantánea `@next/playwright` verificados. |
| **6. Memoria del Codebase y Corrección de Tartamudeo** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                  | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | MCP registrado, exclusiones de .cbmignore configuradas, observador de sesión desactivado. |
| **7. Pruebas Unitarias Jest**      | `jest.config.ts`, `jest.setup.ts`                                                                      | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Transformador Jest de Next.js, entorno jsdom y test-dom configurados.          |
| **8. Storybook y MCP de Storybook** | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`    | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Storybook Vite, a11y, temas y MCP de Storybook AI configurados globalmente y en el espacio de trabajo. |
| **9. Linter de Tailwind Centrado en el Agente** | `eslint.config.mjs`, `package.json`                                                                    | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | `@shadcn/lint` configurado para verificación de tokens de diseño y contratos.  |
| **10. Docker y Proxy Inverso**     | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                            | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Contenedor independiente, etiquetas de Traefik / Nginx HTTPS con Certbot SSL.  |
| **11. Hooks de Git Husky**         | `.husky/commit-msg`, `.husky/pre-push`                                                                 | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Aplica suite dual de pruebas pre-push (Jest + Playwright) y commitlint.        |
| **12. Configuración de Commitlint**| `commitlint.config.mjs`                                                                                | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | `@commitlint/config-conventional` configurado.                                 |
| **13. Almacenamiento en Caché de Compilación y Lanzamiento** | `.github/workflows/release-please.yml`                                                                 | `[IMPLEMENTADO]` / `[NO MODIFICADO]` | Caché de compilación de Next.js (.next/cache), PRs de lanzamiento SemVer y paquete multiarquitectura GHCR. |
| **14. Verificación del Entorno**   | `scripts/verify-project-config.ps1` / `.sh`                                                            | `[PASÓ]`                        | Comprobación de cordura superada con cero errores.                             |

#### Definiciones de Estado:
- **`[IMPLEMENTADO]`**: Creado, instalado o modificado durante esta ejecución de configuración.
- **`[NO MODIFICADO]`**: Ya estaba configurado correctamente antes de ejecutar el skill; se conservó tal cual.
- **`[OMITIDO]`**: Omitido intencionalmente según la preferencia del usuario.