Installation

Prérequis

• Node.js 20+ - nous recommandons nvm
• pnpm - npm, yarn et bun fonctionnent aussi ; la CLI affiche la commande d'installation qui correspond à votre lockfile
• Un workspace cmssy et un token API - créez le token dans Settings → API Tokens ; c'est lui qui relie l'app au workspace
• Une app Next.js (App Router), nouvelle ou existante. La CLI branche aussi les apps Astro et React Router 7 - les fichiers diffèrent, pas les étapes ci-dessous.

Créer l'app et brancher cmssy

Générez une app Next.js (ou faites cd dans celle que vous avez), puis laissez la CLI la câbler. cmssy init détecte le framework, copie les fichiers de câblage dans votre dépôt, ajoute @cmssy/next, @cmssy/react et @cmssy/core au package.json et affiche chaque fichier écrit avec une ligne sur son rôle.

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

Ce qu'écrit init

Chaque fichier est du code ordinaire dans votre dépôt - ouvrez-le, modifiez-le, aucun runtime caché derrière :

Les fichiers déjà présents sont ignorés et listés ; --force les écrase. Sous src/ quand l'app en utilise un. Si l'app linte sans config à elle, init dépose aussi un eslint.config.mjs avec le plugin cmssy. La description complète de chaque fichier est sur la page CLI.

Relier l'app à votre workspace

cmssy link écrit CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG et CMSSY_DRAFT_SECRET dans .env.local et les vérifie auprès de l'API : une faute de frappe échoue ici, pas au premier rendu.

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

Sans --token, la CLI lit CMSSY_API_TOKEN. Avec le token d'un utilisateur qui a plusieurs workspaces, elle demande lequel ; --workspace <slug> saute la question.

L'environnement, en un seul endroit

cmssy.config.ts les passe telles quelles à defineCmssyConfig. La validation au démarrage nomme chaque variable manquante - un repli ?? "" la masquerait, et l'erreur surgirait plus tard, à un endroit sans rapport.

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,
});

Gardez .env.local hors du contrôle de version. En production, définissez les mêmes variables chez votre hébergeur (par ex. les réglages du projet Vercel).

Lancer le développement

pnpm dev   # http://localhost:3000

Ouvrez http://localhost:3000 - l'app rend les pages publiées de votre workspace avec les blocs de cmssy/blocks.ts.

Aperçu dans l'éditeur

L'éditeur encadre votre site dans une iframe et le modifie en direct. La route de brouillon et la CSP dans proxy.ts sont déjà en place depuis init ; ce que vous pointez vers votre site tient en un réglage :

• Pendant le développement, activez le Dev host dans l'éditeur avec http://localhost:3000. Cette cible n'appartient qu'à vous et ne touche rien de partagé.
• Pour le site déployé, définissez la Preview URL du workspace (Settings → Headless) - par ex. https://votre-site.com.

Sur le cloud cmssy, l'origine de l'éditeur est configurée pour vous. Si vous hébergez l'admin vous-même, mettez CMSSY_EDITOR_ORIGIN à son origine - le SDK s'en sert pour le pont postMessage et pour la CSP frame-ancestors qui autorise l'admin à encadrer votre site.

Déployer

Déployez comme n'importe quelle app Next.js. Définissez chez l'hébergeur les mêmes variables d'environnement, dont CMSSY_WEBHOOK_SECRET, pointez le webhook content.changed sur https://votre-site.com/api/revalidate pour qu'une publication apparaisse sans redéploiement, et mettez la Preview URL du workspace sur le site déployé.

vercel        # ou un push vers le dépôt Git que suit votre hébergeur

Mettre à jour le SDK

Montez les paquets @cmssy/* ensemble - @cmssy/next a des peer dependencies sur des @cmssy/react et @cmssy/core assortis. La CLI n'est pas installée ; npx @cmssy/cli@latest exécute toujours la version courante.

pnpm up @cmssy/next @cmssy/react @cmssy/core
pnpm why @cmssy/react   # vérifier la version installée

Câbler à la main

init est un copieur de fichiers, rien de plus. Si vous préférez ajouter les fichiers vous-même, ou lire ce que fait chacun avant de lui faire confiance : la disposition par framework est décrite dans Rendering, et la page CLI liste chaque fichier qu'écrit init, pour Next.js, Astro et React Router.

Dépannage

• init dit : fichier existant, ignoré - l'app l'avait déjà (souvent proxy.ts ou un layout racine). init n'écrase jamais sans --force ; comparez votre fichier à celui qu'init écrirait et fusionnez à la main.
• link : "no API token given" - passez --token cs_... ou définissez CMSSY_API_TOKEN. Le token vient de Settings → API Tokens.
• "Preview didn't connect" - le Dev host ou la Preview URL du workspace doit pointer vers le site en cours d'exécution. Avec un admin auto-hébergé, CMSSY_EDITOR_ORIGIN doit être son origine.
• Page blanche - CMSSY_WORKSPACE_SLUG doit correspondre à votre workspace (et, en auto-hébergement, CMSSY_API_URL doit être l'endpoint GraphQL complet).
• "Port 3000 already in use" - arrêtez les autres serveurs de dev ou lancez next dev -p 3001 et pointez le Dev host sur ce port.
• Erreur de version Node.js - passez à Node.js 20+ avec nvm install 20.

Étapes suivantes

• Votre premier bloc, en direct - de cette installation à un bloc que vous avez écrit, modifié dans l'éditeur et publié
• Développement de blocs - anatomie d'un bloc, schémas et types de champs
• Page Builder - éditer le contenu dans l'éditeur visuel