Ahora con creación de páginas por IA vía el servidor MCP
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 que llama a defineCmssyConfig 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 apiUrl y editorOrigin tienen valores por defecto automáticos:

VariableQué esObligatoria
CMSSY_ORG_SLUGEl slug de tu organizaciónSí
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

Cada app de cmssy tiene las mismas cuatro piezas, sea cual sea el framework:

your-app/
├── page entry     # renderiza los bloques cmssy en tus componentes (ruta catch-all)
├── blocks         # tus componentes de bloque + el array de registro blocks
├── config         # slug del workspace, secreto de borrador y API de delivery
└── edit route     # monta el editor visual para la vista previa en vivo

Los archivos concretos difieren según el framework - Next.js, Astro y Remix los organizan a su manera. Consulta Renderizado para la configuración por framework.

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
import { defineCmssyConfig } from "@cmssy/next";

// Pass process.env raw: defineCmssyConfig validates at startup and names any
// variable you are missing. A `?? ""` fallback would hide that, and the error
// would surface later, somewhere unrelated.
//
// This module reads server env. Never import a VALUE from it (or from a module
// that imports it) in a "use client" component - types are erased, values drag
// process.env into the browser bundle.
export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET,
});
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_ORG_SLUG=your-org
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 tus paquetes @cmssy/* juntos - tu paquete de framework (@cmssy/next, @cmssy/astro o @cmssy/remix) 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