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

Vous préférez un point de départ exécutable ? Clonez le starter open source cmssy-io/cmssy-next-starter - une application Next.js avec trois blocs d'exemple (hero, prose, blog-index) - ou déployez-le sur Vercel en un clic. Pour afficher immédiatement du contenu réel, utilisez le slug du workspace de démo public cmssy-demo.

Installation

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

Last updated: 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_REVALIDATE_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, ou http://localhost:3000 pendant le développement.
  • 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_REVALIDATE_SECRET=your-revalidate-secret

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