Pierwsze kroki z Cmssy CLI

Kompletny przewodnik po instalacji i konfiguracji Cmssy CLI, tworzeniu pierwszego projektu oraz publikowaniu własnych bloków w workspace.

Last updated: April 24, 2026

Instalacja

Zainstaluj Cmssy CLI globalnie używając wybranego menedżera pakietów:

npm install -g @cmssy/cli
# lub
pnpm add -g @cmssy/cli

Wymaganie: Node.js >= 18.0.0

Zweryfikuj instalację:

cmssy --version

Szybki start

Od zera do opublikowanego bloku w 7 krokach:

# 1. Stwórz nowy projekt
cmssy init my-blocks

# 2. Przejdź do katalogu projektu
cd my-blocks

# 3. Zainstaluj zależności
pnpm install

# 4. Połącz się z workspace
cmssy link

# 5. Uruchom serwer deweloperski
cmssy dev

# 6. Stwórz swój pierwszy blok
cmssy create block hero

# 7. Opublikuj swój blok przez pipeline sandbox build
cmssy publish-block hero

Struktura projektu

Po uruchomieniu cmssy init Twój projekt wygląda tak:

my-blocks/
├── cmssy.config.js          # Konfiguracja projektu
├── package.json              # Zależności (React 19, Next.js, Tailwind v4)
├── tsconfig.json             # Konfiguracja TypeScript
├── postcss.config.js         # PostCSS + Tailwind
├── .env                      # Dane dostępowe API (nigdy nie commituj!)
├── .env.example              # Szablon dla .env
├── blocks/                   # Twoje własne bloki
│   └── hero/                 # Przykładowy blok
│       ├── config.ts         # Definicja schematu bloku
│       ├── package.json      # Metadane i wersja bloku
│       ├── preview.json      # Dane podglądu dla serwera dev
│       └── src/
│           ├── Block.tsx     # Komponent React
│           ├── index.tsx     # Wrapper eksportu + import CSS
│           ├── index.css     # Style bloku
│           └── block.d.ts    # Automatycznie generowane typy TypeScript
├── templates/                # Szablony stron
├── components/               # Współdzielone komponenty
├── styles/
│   └── main.css             # Globalne style Tailwind v4
├── public/                   # Wynik budowania
└── .cmssy/                   # Wewnętrzny cache CLI

Konfiguracja

Konfiguracja projektu (cmssy.config.js)

export default {
  framework: "react",
  projectName: "my-blocks",
  author: {
    name: "Twoje Imię",
    email: "ty@example.com"
  },
  build: {
    outDir: "public",
    minify: true,
    sourcemap: true
  }
}

Dane dostępowe API (.env)

Uruchom cmssy link aby skonfigurować interaktywnie, lub stwórz .env ręcznie:

CMSSY_API_URL=https://api.cmssy.io/graphql
CMSSY_API_TOKEN=cs_twoj_token_api
CMSSY_WORKSPACE_ID=twoje_id_workspace
  • Token API: Wygeneruj w Ustawienia Workspace → Tokeny API. Format: cs_xxxxx
  • ID Workspace: Znajdziesz w Ustawienia Workspace → Ogólne → Informacje o Workspace

Struktura bloku

Każdy blok ma spójną strukturę:

blocks/moj-blok/
├── config.ts         # Schemat + metadane (defineBlock)
├── package.json      # Nazwa, wersja, opis
├── preview.json      # Dane podglądu dla serwera dev
└── src/
    ├── Block.tsx     # Twój komponent React
    ├── index.tsx     # Eksportuje komponent + importuje CSS
    ├── index.css     # Style (@import main.css + własne)
    └── block.d.ts    # Automatycznie generowane typy ze schematu

config.ts — Definicja bloku

import { defineBlock } from "@cmssy/cli/config";

export default defineBlock({
  name: "Sekcja Hero",
  description: "Główna sekcja hero z nagłówkiem, CTA i mediami",
  category: "marketing",
  tags: ["hero", "landing", "cta"],

  schema: {
    heading: {
      type: "singleLine",
      label: "Nagłówek",
      required: true,
      defaultValue: "Witamy na naszej stronie"
    },
    description: {
      type: "multiLine",
      label: "Opis",
      defaultValue: "Krótki opis"
    },
    buttonText: {
      type: "singleLine",
      label: "Tekst przycisku",
      defaultValue: "Rozpocznij"
    },
    buttonUrl: {
      type: "link",
      label: "URL przycisku",
      defaultValue: "#"
    },
    image: {
      type: "media",
      label: "Obraz Hero"
    }
  }
});

Block.tsx — Komponent React

import type { PlatformContext } from "@cmssy/cli/config";
import type { BlockContent } from "./block";

export default function Hero({
  content,
  context
}: {
  content: BlockContent;
  context?: PlatformContext;
}) {
  const {
    heading = "Witaj",
    description = "",
    buttonText = "Rozpocznij",
    buttonUrl = "#",
    image
  } = content;

  return (
    <section className="py-20 text-center">
      <h1 className="text-5xl font-bold">{heading}</h1>
      <p className="mt-4 text-lg text-muted-foreground">{description}</p>
      <a href={buttonUrl} className="mt-8 inline-block px-6 py-3 bg-primary text-white rounded-lg">
        {buttonText}
      </a>
      {image && <img src={image} alt="" className="mt-12 mx-auto rounded-xl" />}
    </section>
  );
}

index.tsx — Wrapper eksportu

export { default } from "./Hero";
import "./index.css";

Workflow deweloperski

Serwer deweloperski

cmssy dev

Otwiera się pod http://localhost:3000 z:

  • Podglądem na żywo wszystkich bloków
  • Hot reload przy zmianach plików
  • Danymi podglądu z preview.json

Budowanie

cmssy build

Kompiluje wszystkie bloki za pomocą esbuild, przetwarza Tailwind CSS i generuje wynik do public/.

Publikowanie

cmssy publish-block hero -w <id-workspace>

Wysyła blok przez pipeline sandbox build (CMS-576): CLI archiwizuje drzewo źródeł, backend buduje je w Vercel Sandbox i zapisuje artefakty z powrotem do Vercel Blob.

Opcje:

  • -w, --workspace <id> — nadpisuje workspace z .env
  • --entry <ścieżka> — ścieżka entry bloku (domyślnie: src/index.tsx)
  • --dry-run — zbiera pliki i wypisuje plan bez wysyłania

Stara komenda cmssy publish wraz z flagami --zip / --patch / --minor / --major / --overwrite-content została usunięta w CMS-606. Szablony nadal akceptują --overwrite-content przez cmssy publish-template.

Następne kroki