Instalacja

Wymagania

• Node.js 20+ - polecamy nvm
• pnpm - npm, yarn i bun też działają; CLI wypisuje komendę instalacji pasującą do twojego lockfile'a
• Workspace cmssy i token API - token tworzysz w Settings → API Tokens; to on łączy aplikację z workspace'em
• Aplikacja Next.js (App Router), nowa albo istniejąca. CLI podłącza też Astro i React Router 7 - pliki są inne, kroki poniżej te same.

Utwórz aplikację i podłącz cmssy

Wygeneruj aplikację Next.js (albo wejdź cd do tej, którą masz) i pozwól CLI ją okablować. cmssy init wykrywa framework, kopiuje pliki okablowania do twojego repo, dodaje @cmssy/next, @cmssy/react i @cmssy/core do package.json i wypisuje każdy zapisany plik z jedną linią o tym, po co jest.

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

Co zapisuje init

Każdy plik to zwykły kod w twoim repozytorium - otwórz, zmień, nie ma za nim ukrytego runtime'u:

Pliki, które już istnieją, są pomijane i wypisywane; --force je nadpisuje. Pod src/, gdy aplikacja go używa. Gdy aplikacja lintuje i nie ma własnej konfiguracji, init dokłada też eslint.config.mjs z pluginem cmssy. Pełny opis każdego pliku jest na stronie CLI.

Połącz aplikację z workspace'em

cmssy link zapisuje CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG i CMSSY_DRAFT_SECRET do .env.local i weryfikuje je z API, więc literówka wychodzi tutaj, a nie przy pierwszym renderze.

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

Bez --token CLI czyta CMSSY_API_TOKEN. Token użytkownika z kilkoma workspace'ami dostaje pytanie, o który chodzi; --workspace <slug> pomija pytanie.

Środowisko w jednym miejscu

cmssy.config.ts przekazuje je do defineCmssyConfig bez obróbki. Walidacja przy starcie wskazuje brakującą zmienną po nazwie - fallback ?? "" by to ukrył, a błąd wyszedłby później, w niezwiązanym miejscu.

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

Trzymaj .env.local poza kontrolą wersji. Na produkcji ustaw te same zmienne u hostingodawcy (np. w ustawieniach projektu Vercel).

Uruchom development

pnpm dev   # http://localhost:3000

Otwórz http://localhost:3000 - aplikacja renderuje opublikowane strony twojego workspace'u blokami z cmssy/blocks.ts.

Podgląd w edytorze

Edytor osadza twoją stronę w iframe i edytuje ją na żywo. Trasa draft i CSP w proxy.ts są już na miejscu po init; to, co wskazujesz na swoją stronę, to jedno ustawienie:

• W trakcie developmentu włącz w edytorze Dev host z http://localhost:3000. Ten cel jest tylko twój i nie dotyka niczego wspólnego.
• Dla wdrożonej strony ustaw Preview URL workspace'u (Settings → Headless) - np. https://twoja-strona.com.

W chmurze cmssy origin edytora jest skonfigurowany za ciebie. Jeśli hostujesz admina samodzielnie, ustaw CMSSY_EDITOR_ORIGIN na jego origin - SDK używa go w mostku postMessage i w CSP frame-ancestors, które pozwala adminowi osadzić twoją stronę.

Wdrożenie

Wdrażasz jak każdą aplikację Next.js. Ustaw u hosta te same zmienne środowiskowe, w tym CMSSY_WEBHOOK_SECRET, wyceluj webhook content.changed w https://twoja-strona.com/api/revalidate, żeby publikacja pojawiała się bez redeployu, i ustaw Preview URL workspace'u na wdrożoną stronę.

vercel        # albo push do repo Git, które obserwuje twój host

Aktualizacja SDK

Podbijaj pakiety @cmssy/* razem - @cmssy/next ma peer dependency na pasujące @cmssy/react i @cmssy/core. CLI nie jest instalowane; npx @cmssy/cli@latest zawsze uruchamia aktualne.

pnpm up @cmssy/next @cmssy/react @cmssy/core
pnpm why @cmssy/react   # sprawdź zainstalowaną wersję

Okablowanie ręczne

init to kopiarka plików, nic więcej. Jeśli wolisz dodać pliki samodzielnie albo chcesz przeczytać, co robi każdy z nich, zanim mu zaufasz - układ per framework opisuje Rendering, a strona CLI wymienia każdy plik, który zapisuje init, dla Next.js, Astro i React Routera.

Rozwiązywanie problemów

• init mówi: plik istnieje, pominięto - aplikacja już go miała (zwykle proxy.ts albo layout root). init nigdy nie nadpisuje bez --force; porównaj swój plik z tym, który zapisałby init, i scal ręcznie.
• link: "no API token given" - podaj --token cs_... albo ustaw CMSSY_API_TOKEN. Token bierzesz z Settings → API Tokens.
• "Preview didn't connect" - Dev host albo Preview URL workspace'u musi wskazywać działającą stronę. Przy self-hostowanym adminie CMSSY_EDITOR_ORIGIN musi być jego originem.
• Pusta strona - CMSSY_WORKSPACE_SLUG musi zgadzać się z workspace'em (a przy self-hoście CMSSY_API_URL musi być pełnym endpointem GraphQL).
• "Port 3000 already in use" - zatrzymaj inne serwery dev albo odpal next dev -p 3001 i wskaż ten port w Dev host.
• Błąd wersji Node.js - zaktualizuj do Node.js 20+ przez nvm install 20.

Następne kroki

• Twój pierwszy blok, na żywo - od tej konfiguracji do bloku, który napisałeś, edytowałeś w edytorze i opublikowałeś
• Tworzenie bloków - anatomia bloku, schematy i typy pól
• Page Builder - edycja treści w edytorze wizualnym