Installation

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 exportant une CmssyNextConfig, 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, vous ne définissez que deux valeurs - apiUrl et editorOrigin ont des valeurs par défaut automatiques :

Variable	Description	Requis
`CMSSY_WORKSPACE_SLUG`	Le slug de votre workspace (résout l'id du workspace)	Oui
`CMSSY_DRAFT_SECRET`	Secret qui déverrouille le mode draft / aperçu	Oui
`CMSSY_REVALIDATE_SECRET`	Secret pour le webhook de revalidation ISR à la publication	Oui
`CMSSY_API_URL`	Endpoint GraphQL de livraison. Par défaut `https://api.cmssy.io/graphql`	Self-host / staging uniquement
`CMSSY_EDITOR_ORIGIN`	Origine de l'admin qui encadre votre site. Par défaut `https://www.cmssy.io`	Self-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

Un site Cmssy typique ressemble à ceci :

my-site/
├── app/
│   ├── layout.tsx            # CmssyServerLayout (header/footer)
│   ├── [[...path]]/page.tsx  # createCmssyPage - the catch-all page
│   └── api/draft/route.ts    # createDraftRoute - editor preview
├── blocks/
│   └── hero/
│       ├── block.ts          # defineBlock(...) + fields
│       └── src/index.tsx     # the React component
├── cmssy/
│   ├── config.ts             # CmssyNextConfig + resolveLocale
│   └── blocks.ts             # registry: exports the `blocks` array
└── proxy.ts                  # locale + edit-mode + CSP

Chaque bloc vit dans son propre dossier sous blocks/ et est enregistré dans cmssy/blocks.ts.

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 :

Démarrage rapide - créez votre premier bloc de bout en bout
Développement de blocs - anatomie des blocs, schémas et types de champs
Page Builder - édition du contenu dans l'éditeur visuel

Partez d'un exemple fonctionnel