Instalación

Requisitos

• Node.js 20+ - recomendamos nvm
• pnpm - npm, yarn y bun también funcionan; la CLI imprime el comando de instalación que corresponde a tu lockfile
• Un workspace de cmssy y un token de API - crea el token en Settings → API Tokens; es lo que conecta la app con el workspace
• Una app Next.js (App Router), nueva o existente. La CLI también cablea apps Astro y React Router 7 - los archivos cambian, los pasos de abajo no.

Crear la app y cablear cmssy

Genera una app Next.js (o haz cd a la que ya tienes) y deja que la CLI la cablee. cmssy init detecta el framework, copia los archivos de cableado a tu repositorio, añade @cmssy/next, @cmssy/react y @cmssy/core al package.json e imprime cada archivo escrito con una línea sobre para qué sirve.

npx create-next-app@latest my-site   # App Router: yes
cd my-site
npx @cmssy/cli@latest init
pnpm install

Qué escribe init

Cada archivo es código normal en tu repositorio - ábrelo, cámbialo, no hay ningún runtime oculto detrás:

Los archivos que ya existen se omiten y se listan; --force los sobrescribe. Bajo src/ cuando la app lo usa. Si la app hace lint y no tiene config propia, init también deja un eslint.config.mjs con el plugin de cmssy. La descripción completa de cada archivo está en la página CLI.

Conectar la app con tu workspace

cmssy link escribe CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG y CMSSY_DRAFT_SECRET en .env.local y los verifica contra la API, así que una errata falla aquí y no en el primer render.

npx @cmssy/cli@latest link --token cs_...

Sin --token, la CLI lee CMSSY_API_TOKEN. Con el token de un usuario con varios workspaces, pregunta cuál; --workspace <slug> se salta la pregunta.

El entorno, en un solo sitio

cmssy.config.ts las pasa tal cual a defineCmssyConfig. La validación al arrancar nombra cada variable que falta - un fallback ?? "" lo ocultaría y el error aparecería más tarde, en un sitio sin relación.

import { defineCmssyConfig } from "@cmssy/next";

export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET,
});

Mantén .env.local fuera del control de versiones. En producción, define las mismas variables en tu proveedor de hosting (p. ej. la configuración del proyecto en Vercel).

Arrancar el desarrollo

pnpm dev   # http://localhost:3000

Abre http://localhost:3000 - la app renderiza las páginas publicadas de tu workspace con los bloques de cmssy/blocks.ts.

Vista previa en el editor

El editor enmarca tu sitio en un iframe y lo edita en vivo. La ruta de borrador y la CSP de proxy.ts ya están desde init; lo que apuntas a tu sitio es un solo ajuste:

• Mientras desarrollas, activa el Dev host en el editor con http://localhost:3000. Ese destino es solo tuyo y no toca nada compartido.
• Para el sitio desplegado, define la Preview URL del workspace (Settings → Headless) - p. ej. https://tu-sitio.com.

En la nube de cmssy el origen del editor ya está configurado. Si alojas el admin tú mismo, pon CMSSY_EDITOR_ORIGIN en su origen - el SDK lo usa para el puente postMessage y para la CSP frame-ancestors que permite al admin enmarcar tu sitio.

Desplegar

Despliega como cualquier app Next.js. Define en tu host las mismas variables de entorno, incluida CMSSY_WEBHOOK_SECRET, apunta el webhook content.changed a https://tu-sitio.com/api/revalidate para que una publicación aparezca sin redesplegar, y pon la Preview URL del workspace en el sitio desplegado.

vercel        # o un push al repositorio Git que vigila tu host

Actualizar el SDK

Sube los paquetes @cmssy/* juntos - @cmssy/next tiene peer dependencies de @cmssy/react y @cmssy/core a juego. La CLI no se instala; npx @cmssy/cli@latest ejecuta siempre la versión actual.

pnpm up @cmssy/next @cmssy/react @cmssy/core
pnpm why @cmssy/react   # comprobar la versión instalada

Cablear a mano

init es un copiador de archivos, nada más. Si prefieres añadir los archivos tú mismo, o leer qué hace cada uno antes de fiarte: la disposición por framework está en Rendering, y la página CLI lista cada archivo que escribe init, para Next.js, Astro y React Router.

Solución de problemas

• init dice: el archivo existe, omitido - la app ya lo tenía (normalmente proxy.ts o un layout raíz). init nunca sobrescribe sin --force; compara tu archivo con el que init escribiría y fusiónalos a mano.
• link: "no API token given" - pasa --token cs_... o define CMSSY_API_TOKEN. El token sale de Settings → API Tokens.
• "Preview didn't connect" - el Dev host o la Preview URL del workspace debe apuntar al sitio en ejecución. Con un admin autoalojado, CMSSY_EDITOR_ORIGIN debe ser su origen.
• Página en blanco - CMSSY_WORKSPACE_SLUG debe coincidir con tu workspace (y, si autoalojas, CMSSY_API_URL debe ser el endpoint GraphQL completo).
• "Port 3000 already in use" - para otros servidores de dev o ejecuta next dev -p 3001 y apunta el Dev host a ese puerto.
• Error de versión de Node.js - actualiza a Node.js 20+ con nvm install 20.

Siguientes pasos

• Tu primer bloque, en vivo - desde esta instalación hasta un bloque que escribiste, editaste en el editor y publicaste
• Desarrollo de bloques - anatomía de un bloque, esquemas y tipos de campo
• Page Builder - editar contenido en el editor visual