Désormais avec création de pages par IA via le serveur MCP
Partez d'un exemple exécutable

Envie d'une longueur d'avance ? Clonez cmssy-io/examples - des applications autonomes pour Next.js (simple-blog, next-storefront), Astro et React Router, chacune avec un .env.example pointant vers le workspace de démo public : un clone frais affiche du vrai contenu avant même d'avoir un compte. Pointez-en une vers votre propre workspace avec npx @cmssy/cli link --token cs_....

Installation

Soyez opérationnel avec Cmssy en moins de 5 minutes.

29 juin 2026

Prérequis

Un site Cmssy est un projet Next.js (App Router) standard qui affiche votre contenu publié avec le SDK Cmssy. Vous aurez besoin de :

  • Node.js 20+ - nous recommandons nvm
  • pnpm - notre gestionnaire de paquets recommandé (npm et yarn fonctionnent aussi)
  • Une application Next.js App Router - nouvelle ou existante
  • Un workspace Cmssy - pour le slug du workspace et les réglages draft/éditeur

Installer le SDK

Ajoutez les deux paquets du SDK à votre projet Next.js :

Créer une application Next.js

Vous partez de zéro ? Générez un projet App Router, puis ajoutez le SDK. (Ou sautez cette étape et utilisez votre application existante.)

Configurer

Créez cmssy.config.ts qui appelle defineCmssyConfig, puis ajoutez les clés ci-dessous à votre .env. Copiez les valeurs depuis la page Settings → Headless de votre workspace dans le tableau de bord Cmssy. Sur cmssy cloud, apiUrl et editorOrigin ont des valeurs par défaut automatiques :

VariableDescriptionRequis
CMSSY_ORG_SLUGLe slug de votre organisationOui
CMSSY_WORKSPACE_SLUGLe slug de votre workspace (résout l'id du workspace)Oui
CMSSY_DRAFT_SECRETSecret qui déverrouille le mode draft / aperçuOui
CMSSY_WEBHOOK_SECRETSecret pour le webhook de revalidation ISR à la publicationOui
CMSSY_API_URLEndpoint GraphQL de livraison. Par défaut https://api.cmssy.io/graphqlSelf-host / staging uniquement
CMSSY_EDITOR_ORIGINOrigine de l'admin qui encadre votre site. Par défaut https://www.cmssy.ioSelf-host uniquement

Gardez ces valeurs secrètes - ne commitez jamais .env dans le contrôle de version. En production, définissez les mêmes variables chez votre hébergeur (par ex. les réglages de votre projet Vercel).

Structure du projet

Chaque app cmssy a les mêmes quatre pièces, quel que soit le framework :

your-app/
├── page entry     # rend les blocs cmssy dans vos composants (route catch-all)
├── blocks         # vos composants de bloc + le tableau de registre blocks
├── config         # slug du workspace, secret de brouillon et API de delivery
└── edit route     # monte l'éditeur visuel pour l'aperçu en direct

Les fichiers concrets diffèrent selon le framework - Next.js, Astro et Remix les organisent chacun à leur manière. Voir Rendu pour la configuration par framework.

Lancer le développement

Lancez le serveur de développement Next.js :

Ouvrez http://localhost:3000 - votre site affiche le contenu Cmssy publié.

Aperçu dans l'éditeur

Pour éditer le contenu visuellement avec un aperçu en direct, l'éditeur Cmssy charge votre site déployé (ou local) dans une iframe. Pour que votre projet apparaisse dans l'éditeur, il vous faut :

  • La Preview URL de votre workspace (Settings → Headless) pointant vers votre site - par ex. https://your-site.com. Pendant le développement, ne la touchez pas et activez plutôt le Dev host dans l'éditeur avec http://localhost:3000 - cette cible n'est que la vôtre et ne modifie rien de partagé.
  • La route draft app/api/draft/route.ts = createDraftRoute(cmssy) pour que l'éditeur puisse passer en mode aperçu / draft.
  • proxy.ts appliquant la CSP via applyCmssyCsp en mode édition.

Sur cmssy cloud, l'origine de l'éditeur est configurée pour vous. Si vous hébergez l'admin vous-même, définissez CMSSY_EDITOR_ORIGIN sur l'origine de votre admin - le SDK l'utilise pour le pont postMessage et la CSP frame-ancestors qui permet à l'admin d'encadrer votre site. Ouvrez ensuite l'éditeur de pages dans l'admin - votre site se charge dans le canvas et les modifications apparaissent instantanément.

Déployer

Déployez comme n'importe quelle application Next.js (par ex. Vercel). Définissez les mêmes variables d'environnement chez votre hébergeur, puis pointez la Preview URL de votre workspace vers le site déployé pour que l'éditeur puisse l'encadrer.

Mettre à jour le SDK

Mettez à jour les deux paquets ensemble pour récupérer les correctifs du SDK, puis redéployez :

Dépannage

Problèmes courants

  • « Preview didn't connect » - vérifiez que la Preview URL du workspace pointe vers votre site. Si vous hébergez l'admin vous-même, CMSSY_EDITOR_ORIGIN doit être l'origine de votre admin.
  • Page blanche - vérifiez que CMSSY_WORKSPACE_SLUG correspond à votre workspace (et, en self-host, que CMSSY_API_URL est l'endpoint GraphQL complet).
  • « Port 3000 already in use » - arrêtez les autres serveurs de dev ou lancez next dev -p 3001.
  • Erreur de version Node.js - passez à Node.js 20+ avec nvm install 20.

Étapes suivantes

Maintenant que tout est prêt, explorez les guides suivants :

Terminal
pnpm add @cmssy/next @cmssy/react

# or with npm
npm install @cmssy/next @cmssy/react
Démarrage le plus rapide

Le chemin le plus rapide : exécutez pnpm add @cmssy/next @cmssy/react, ajoutez cmssy.config.ts avec le slug de votre workspace et le secret draft, une page catch-all app/[[...path]]/page.tsx utilisant createCmssyPage, et la route draft - puis pnpm dev. Les étapes ci-dessous détaillent chaque fichier.

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,
});
Copiez votre .env depuis Settings → Headless

Ouvrez Settings → Headless dans le tableau de bord Cmssy et copiez chaque valeur dans le .env de votre projet :

CMSSY_ORG_SLUG=your-org
CMSSY_WORKSPACE_SLUG=your-workspace
CMSSY_DRAFT_SECRET=your-draft-secret
CMSSY_WEBHOOK_SECRET=your-webhook-secret

npx @cmssy/cli link --token cs_... écrit les slugs et le secret draft pour vous et les vérifie - voir CLI.

apiUrl et editorOrigin ont cmssy cloud par défaut, vous ne les définissez donc pas - ajoutez CMSSY_API_URL / CMSSY_EDITOR_ORIGIN uniquement pour le dev local ou le self-hosting. Gardez les secrets hors du contrôle de version ; en production, définissez les mêmes variables chez votre hébergeur (par ex. réglages du projet 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
Versionnage du SDK

Mettez à jour vos paquets @cmssy/* ensemble - votre paquet framework (@cmssy/next, @cmssy/astro ou @cmssy/remix) a une peer dependency sur un @cmssy/react correspondant. Après la mise à jour, exécutez pnpm install et redéployez.

Terminal
pnpm up @cmssy/next @cmssy/react

# check the installed version
pnpm why @cmssy/react