@gonzoblasco/create-stack

Scaffolder opinado multi-stack. Un solo comando y tenés un proyecto moderno, testeado, lintado y listo para que un AI agent lo habite.

Instalación

# Stack Next.js full (app + API routes + tests + AI agent)
npx @gonzoblasco/create-stack next my-app

# Stack Next.js API-only (Drizzle ORM + SQLite + middleware)
npx @gonzoblasco/create-stack api my-api

Eso es todo. El comando genera un proyecto listo para empezar a desarrollar.

Stacks disponibles

| Stack | Descripción | |-------|-------------| | next | Next.js 15 + React 19 + TypeScript estricto + Biome + Vitest + Playwright + Zod + OpenSpec + AI agent config | | api | Next.js 15 App Router (API-only) + Drizzle ORM + SQLite + middleware Bearer + tests con node-mocks-http |

Stack Next.js Full (next)

El proyecto generado viene con todo preconfigurado:

• Next.js 15 + React 19 + TypeScript estricto
• Biome (lint + format en un solo comando)
• Vitest (tests unitarios) + Playwright (tests e2e)
• Zod para validación runtime
• GitHub Actions (CI + e2e)
• OpenSpec — Spec-Driven Development integrado (specs + slash commands para IA)
• AGENTS.md + workflow de IA inyectado para desarrollo asistido
• docs/ con arquitectura, decisiones y guía de contribución

Stack API-only (api)

Si preferís generar un backend puramente funcional sin React components:

• Next.js 15 App Router (Rutas de API).
• Drizzle ORM + SQLite pre-configurado para base de datos.
• Utilidades estandarizadas de Error Handling y Respuestas API.
• Middleware base con validación de Bearer Token.
• node-mocks-http + Vitest para probar endpoints velozmente.

¿Por qué este y no create-next-app?

| Aspecto | create-next-app | @gonzoblasco/create-stack | |---------|-----------------|---------------------------| | Testing | Ninguno | Vitest + Playwright configurados | | Linter | ESLint + Prettier | Biome (un solo binario) | | TypeScript | Básico | Estricto + noUncheckedIndexedAccess | | AI agents | Ninguno | AGENTS.md + prompts listos para usar | | Spec-Driven Development | Ninguno | OpenSpec integrado (specs + slash commands) | | CI | Ninguno | GitHub Actions incluido | | Filosofía | Mínimo | Opinado con defaults 2026 | | Multi-stack | Solo Next.js | next, api, y más por venir |

Ideal si: arrancás proyectos con frecuencia y no querés repetir las mismas 40 decisiones cada vez.

Opciones

npx @gonzoblasco/create-stack <stack> [nombre] [opciones]

Opciones:
  --no-git          No inicializa git ni hace commit inicial
  --no-install      No corre npm install después de generar
  --no-openspec     No inicializa OpenSpec (Spec-Driven Development)
  --pm <nombre>     Package manager: npm, pnpm, yarn, bun (default: npm)

Ejemplos:
  npx @gonzoblasco/create-stack next my-app
  npx @gonzoblasco/create-stack api my-api
  npx @gonzoblasco/create-stack next my-app --pm pnpm --no-git

Compatibilidad hacia atrás

El formato legacy npx create-stack-next my-app sigue funcionando (asume stack next). El flag --template api también funciona, mapeado al stack api.

AI agents integrados

El proyecto incluye:

• AGENTS.md — instrucciones agnósticas (funciona con OpenClaw, Claude Code, Cursor, etc.)
• .openclaw/ — config y prompts específicos de OpenClaw
• .agents/ — config genérica + prompts compartidos
• openspec/ — Spec-Driven Development con OpenSpec (specs, changes, slash commands)
• npm run agent — abre sesión con el agente ya contextualizado

Spec-Driven Development con OpenSpec

Todos los proyectos generados incluyen OpenSpec pre-configurado. Esto significa que tu IA trabaja con especificaciones en vez de prompts vagos:

/opsx:propose "agregar autenticación"   # la IA crea propuesta + specs + tasks
/opsx:apply                              # la IA implementa
/opsx:archive                            # specs actualizadas, cambio archivado

Durante el scaffolding, el CLI te pregunta qué herramientas de IA usás (Claude Code, Cursor, etc.) e instala los skills y slash commands correspondientes.

Comandos del proyecto generado

npm run dev          # servidor de desarrollo
npm run build        # build de producción
npm run lint         # Biome (check)
npm run lint:fix     # Biome con --write
npm run typecheck    # verificación de tipos
npm run test:run     # tests unitarios
npm run test:e2e     # tests e2e
npm run agent        # sesión con OpenClaw

Arquitectura del CLI

src/
├── index.ts              # Entrypoint
├── cli.ts                # Lógica principal del CLI
├── parse-args.ts         # Parser de argumentos
├── copy-template.ts      # Copia y personaliza templates
├── openspec-init.ts      # Inicialización de OpenSpec
├── workspace.ts          # Detección de workspaces
└── stacks/
    ├── types.ts          # Tipos de StackConfig
    ├── index.ts          # Registry de stacks
    ├── next/
    │   ├── index.ts      # Config del stack next
    │   └── template/     # Template Next.js full
    └── api/
        ├── index.ts      # Config del stack api
        └── template/     # Template Next.js API-only

Cada stack es un módulo independiente. Para agregar uno nuevo, creá src/stacks/<id>/ con su index.ts y template/, y registralo en src/stacks/index.ts.

Roadmap

Ver ROADMAP.md y FUTURE.md.

Licencia

MIT

Creado con ❤️ por Gonzo y Kanam (OpenClaw)