Ahora con creación de páginas por IA vía el servidor MCP
Documentation
Empieza con un ejemplo funcional

¿Prefieres un punto de partida ejecutable? Clona el starter de código abierto cmssy-io/cmssy-next-starter - una aplicación Next.js con tres bloques de ejemplo (hero, prose, blog-index) - o despliégalo en Vercel con un clic. Para ver contenido real de inmediato, usa el slug del workspace de demostración público cmssy-demo.

Instalación

Pon Cmssy en marcha en menos de 5 minutos.

Last updated: 29 de junio de 2026

Requisitos previos

Un sitio Cmssy es un proyecto Next.js (App Router) estándar que renderiza tu contenido publicado con el SDK de Cmssy. Necesitarás:

  • Node.js 20+ - recomendamos nvm
  • pnpm - nuestro gestor de paquetes recomendado (npm y yarn también funcionan)
  • Una aplicación Next.js App Router - nueva o existente
  • Un workspace de Cmssy - para el slug del workspace y los ajustes de borrador/editor

Instala el SDK

Añade los dos paquetes del SDK a tu proyecto Next.js:

Crea una aplicación Next.js

¿Empiezas desde cero? Genera un proyecto App Router y luego añade el SDK. (O sáltate este paso y usa tu aplicación existente.)

Configura

Crea cmssy/config.ts exportando una CmssyNextConfig y luego añade las claves de abajo a tu .env. Copia los valores desde la página Settings → Headless de tu workspace en el panel de Cmssy. En cmssy cloud solo defines dos valores - apiUrl y editorOrigin tienen valores por defecto automáticos:

VariableQué esObligatoria
CMSSY_WORKSPACE_SLUGEl slug de tu workspace (resuelve el id del workspace)Sí
CMSSY_DRAFT_SECRETSecreto que desbloquea el modo borrador / vista previaSí
CMSSY_REVALIDATE_SECRETSecreto para el webhook de revalidación ISR al publicarSí
CMSSY_API_URLEndpoint GraphQL de entrega. Por defecto https://api.cmssy.io/graphqlSolo self-host / staging
CMSSY_EDITOR_ORIGINOrigen del admin que enmarca tu sitio. Por defecto https://www.cmssy.ioSolo self-host

Mantén estos valores en secreto - nunca subas .env al control de versiones. En producción, define las mismas variables en tu proveedor de hosting (p. ej. los ajustes de tu proyecto en Vercel).

Estructura del proyecto

Un sitio Cmssy típico tiene este aspecto:

my-site/
├── app/
│   ├── layout.tsx            # CmssyServerLayout (header/footer)
│   ├── [[...path]]/page.tsx  # createCmssyPage - the catch-all page
│   └── api/draft/route.ts    # createDraftRoute - editor preview
├── blocks/
│   └── hero/
│       ├── block.ts          # defineBlock(...) + fields
│       └── src/index.tsx     # the React component
├── cmssy/
│   ├── config.ts             # CmssyNextConfig + resolveLocale
│   └── blocks.ts             # registry: exports the `blocks` array
└── proxy.ts                  # locale + edit-mode + CSP

Cada bloque vive en su propia carpeta dentro de blocks/ y se registra en cmssy/blocks.ts.

Inicia el desarrollo

Ejecuta el servidor de desarrollo de Next.js:

Abre http://localhost:3000 - tu sitio renderiza el contenido publicado de Cmssy.

Vista previa del editor

Para editar contenido visualmente con vista previa en vivo, el editor de Cmssy enmarca tu sitio desplegado (o local) en un iframe. Para que tu proyecto aparezca en el editor, necesitas:

  • La Preview URL de tu workspace (Settings → Headless) apuntando a tu sitio - p. ej. https://your-site.com, o http://localhost:3000 mientras desarrollas.
  • La ruta de borrador app/api/draft/route.ts = createDraftRoute(cmssy) para que el editor pueda entrar en modo vista previa / borrador.
  • proxy.ts aplicando la CSP mediante applyCmssyCsp en modo edición.

En cmssy cloud el origen del editor ya está configurado. Si autoalojas el admin, define CMSSY_EDITOR_ORIGIN con el origen de tu admin - el SDK lo usa para el puente postMessage y la CSP frame-ancestors que permite al admin enmarcar tu sitio. Después abre el editor de páginas en el admin - tu sitio se carga en el lienzo y los cambios aparecen al instante.

Despliega

Despliega como cualquier aplicación Next.js (p. ej. Vercel). Define las mismas variables de entorno en tu proveedor de hosting y luego apunta la Preview URL de tu workspace al sitio desplegado para que el editor pueda enmarcarlo.

Actualiza el SDK

Actualiza ambos paquetes juntos para obtener las correcciones del SDK y luego vuelve a desplegar:

Solución de problemas

Problemas comunes

  • "Preview didn't connect" - comprueba que la Preview URL del workspace apunta a tu sitio. Si autoalojas el admin, CMSSY_EDITOR_ORIGIN debe ser el origen de tu admin.
  • Página en blanco - comprueba que CMSSY_WORKSPACE_SLUG coincide con tu workspace (y, si autoalojas, que CMSSY_API_URL es el endpoint GraphQL completo).
  • "Port 3000 already in use" - detén otros servidores de desarrollo o ejecuta next dev -p 3001.
  • Error de versión de Node.js - actualiza a Node.js 20+ con nvm install 20.

Próximos pasos

Ahora que ya está todo listo, explora las siguientes guías:

Terminal
pnpm add @cmssy/next @cmssy/react

# or with npm
npm install @cmssy/next @cmssy/react
Inicio más rápido

El camino más rápido: ejecuta pnpm add @cmssy/next @cmssy/react, añade cmssy/config.ts con el slug de tu workspace y el secreto de borrador, una página catch-all app/[[...path]]/page.tsx usando createCmssyPage, y la ruta de borrador - luego pnpm dev. Los pasos de abajo repasan cada archivo.

Terminal
pnpm create next-app@latest my-site
# App Router: Yes

cd my-site
pnpm add @cmssy/next @cmssy/react
cmssy/config.ts
import type { CmssyNextConfig } from "@cmssy/next";

export const cmssy: CmssyNextConfig = {
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG ?? "",
  draftSecret: process.env.CMSSY_DRAFT_SECRET ?? "",
  defaultLocale: "en",
  // apiUrl + editorOrigin default to cmssy cloud; set only for self-host/staging.
};
Copia tu .env desde Settings → Headless

Abre Settings → Headless en el panel de Cmssy y copia cada valor en el .env de tu proyecto:

CMSSY_WORKSPACE_SLUG=your-workspace
CMSSY_DRAFT_SECRET=your-draft-secret
CMSSY_REVALIDATE_SECRET=your-revalidate-secret

apiUrl y editorOrigin tienen cmssy cloud por defecto, así que no los defines - añade CMSSY_API_URL / CMSSY_EDITOR_ORIGIN solo para desarrollo local o autoalojamiento. Mantén los secretos fuera del control de versiones; en producción define las mismas variables en tu host (p. ej. ajustes del proyecto en Vercel).

Terminal
pnpm dev

# Next.js dev server -> http://localhost:3000
Terminal
# Deploy to Vercel
vercel

# or just push to your connected Git repo
git push
Versionado del SDK

Actualiza @cmssy/react y @cmssy/next juntos - @cmssy/next tiene una peer dependency de un @cmssy/react compatible. Tras actualizar, ejecuta pnpm install y vuelve a desplegar.

Terminal
pnpm up @cmssy/next @cmssy/react

# check the installed version
pnpm why @cmssy/react