Teraz z AI - twórz strony przez serwer MCP
Zacznij od gotowego przykładu

Wolisz gotowy punkt startu? Sklonuj otwarty starter cmssy-io/cmssy-next-starter - aplikację Next.js z trzema przykładowymi blokami (hero, prose, blog-index) - lub wdróż na Vercel jednym kliknięciem. Aby od razu zobaczyć prawdziwą treść, użyj publicznego demo workspace o slug cmssy-demo.

Instalacja

Uruchom Cmssy w mniej niż 5 minut.

29 czerwca 2026

Wymagania wstępne

Strona na Cmssy to zwykły projekt Next.js (App Router), który renderuje Twoją opublikowaną treść przy użyciu SDK Cmssy. Potrzebujesz:

  • Node.js 20+ - polecamy nvm
  • pnpm - nasz rekomendowany menedżer pakietów (npm i yarn też działają)
  • Aplikację Next.js App Router - nową albo istniejącą
  • Workspace Cmssy - dla sluga workspace'u i ustawień draftu/edytora

Zainstaluj SDK

Dodaj dwie paczki SDK do projektu Next.js:

Utwórz aplikację Next.js

Zaczynasz od zera? Wygeneruj projekt App Router, a potem dodaj SDK. (Albo pomiń to i użyj istniejącej aplikacji.)

Skonfiguruj

Utwórz cmssy.config.ts, który woła defineCmssyConfig, a potem dodaj poniższe klucze do .env. Wartości skopiuj ze strony Settings → Headless swojego workspace'u w panelu Cmssy. W cmssy cloud apiUrl i editorOrigin mają automatyczne wartości domyślne:

ZmiennaCo to jestWymagana
CMSSY_ORG_SLUGSlug Twojej organizacjiTak
CMSSY_WORKSPACE_SLUGSlug workspace'u (rozwiązuje id workspace'u)Tak
CMSSY_DRAFT_SECRETSekret odblokowujący tryb draft / podgląduTak
CMSSY_REVALIDATE_SECRETSekret webhooka rewalidacji ISR przy publikacjiTak
CMSSY_API_URLEndpoint GraphQL delivery. Domyślnie https://api.cmssy.io/graphqlTylko self-host / staging
CMSSY_EDITOR_ORIGINOrigin panelu, który osadza Twoją stronę. Domyślnie https://www.cmssy.ioTylko self-host

Trzymaj te wartości w tajemnicy - nigdy nie commituj .env do repozytorium. Na produkcji ustaw te same zmienne u swojego hostingu (np. w ustawieniach projektu na Vercel).

Struktura projektu

Każda aplikacja cmssy ma te same cztery elementy, niezależnie od frameworka:

your-app/
├── page entry     # renderuje bloki cmssy w Twoich komponentach (trasa catch-all)
├── blocks         # Twoje komponenty bloków + tablica rejestru blocks
├── config         # slug workspace'u, sekret draftu i API delivery
└── edit route     # montuje edytor wizualny dla podglądu na żywo

Konkretne pliki różnią się per framework - Next.js, Astro i Remix układają je po swojemu. Zobacz Renderowanie po setup dla konkretnego frameworka.

Zacznij pracę

Uruchom serwer deweloperski Next.js:

Otwórz http://localhost:3000 - Twoja strona renderuje opublikowaną treść z Cmssy.

Podgląd w edytorze

Žeby edytować treść wizualnie z podglądem na żywo, edytor Cmssy osadza Twoją wdrożoną (albo lokalną) stronę w iframe. Żeby Twój projekt pojawił się w edytorze, potrzebujesz:

  • Preview URL workspace'u (Settings → Headless) ustawionego na Twoją stronę - np. https://your-site.com albo http://localhost:3000 podczas pracy lokalnej.
  • Trasy draftu app/api/draft/route.ts = createDraftRoute(cmssy), żeby edytor mógł wejść w tryb podglądu / draftu.
  • proxy.ts nakładającego CSP przez applyCmssyCsp w trybie edycji.

W cmssy cloud origin edytora jest skonfigurowany za Ciebie. Jeśli hostujesz panel sam, ustaw CMSSY_EDITOR_ORIGIN na origin swojego panelu - SDK używa go do mostu postMessage i do CSP frame-ancestors, które pozwala panelowi osadzić Twoją stronę. Potem otwórz edytor strony w panelu - Twoja strona ładuje się na kanwie, a zmiany pojawiają się natychmiast.

Wdróż

Wdrażaj jak każdą aplikację Next.js (np. na Vercel). Ustaw te same zmienne środowiskowe u hostingu, a potem wskaż Preview URL workspace'u na wdrożoną stronę, żeby edytor mógł ją osadzić.

Aktualizacja SDK

Podbijaj obie paczki razem, żeby złapać poprawki SDK, a potem wdróż ponownie:

Rozwiązywanie problemów

Częste problemy

  • "Preview didn't connect" - sprawdź, czy Preview URL workspace'u wskazuje na Twoją stronę. Jeśli hostujesz panel sam, CMSSY_EDITOR_ORIGIN musi być originem Twojego panelu.
  • Pusta strona - sprawdź, czy CMSSY_WORKSPACE_SLUG zgadza się z Twoim workspace'em (a przy self-hoście - czy CMSSY_API_URL to pełny endpoint GraphQL).
  • "Port 3000 already in use" - zatrzymaj inne serwery deweloperskie albo odpal next dev -p 3001.
  • Błąd wersji Node.js - przejdź na Node.js 20+ przez nvm install 20.

Następne kroki

Skoro masz już wszystko gotowe, zajrzyj do tych przewodników:

Terminal
pnpm add @cmssy/next @cmssy/react

# or with npm
npm install @cmssy/next @cmssy/react
Najszybszy start

Najkrótsza droga: odpal pnpm add @cmssy/next @cmssy/react, dodaj cmssy.config.ts ze slugiem workspace'u i sekretem draftu, trasę catch-all app/[[...path]]/page.tsx używającą createCmssyPage oraz trasę draftu - potem pnpm dev. Kroki niżej przechodzą przez każdy plik.

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,
});
Skopiuj .env z Settings → Headless

Otwórz Settings → Headless w panelu Cmssy i skopiuj każdą wartość do .env swojego projektu:

CMSSY_ORG_SLUG=your-org
CMSSY_WORKSPACE_SLUG=your-workspace
CMSSY_DRAFT_SECRET=your-draft-secret
CMSSY_REVALIDATE_SECRET=your-revalidate-secret

apiUrl i editorOrigin domyślnie wskazują na cmssy cloud, więc ich nie ustawiasz - CMSSY_API_URL / CMSSY_EDITOR_ORIGIN dodaj tylko przy pracy lokalnej albo self-hoście. Trzymaj sekrety poza repozytorium; na produkcji ustaw te same zmienne u hostingu (np. w ustawieniach projektu na 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
Wersjonowanie SDK

Podbijaj paczki @cmssy/* razem - paczka frameworkowa (@cmssy/next, @cmssy/astro albo @cmssy/remix) ma peer dependency na pasujący @cmssy/react. Po podbiciu odpal pnpm install i wdróż ponownie.

Terminal
pnpm up @cmssy/next @cmssy/react

# check the installed version
pnpm why @cmssy/react