Configuration

Every project has a webstorio.config.ts at its root. Use the defineConfig helper for full type-checking and autocomplete.

Webstorio pages and components are plain React (.tsx) — there is no bespoke framework to learn. You write standard React and call the global window.webstorio SDK on the live site; the server compiles your code against a pinned set of supported libraries.

webstorio.config.ts

import { defineConfig } from "@webstorio/cli/config";

export default defineConfig({
  name: "My Site",
  subdomain: "my-site",
  description: "A short description of your site.",
  components: [
    { file: "components/_header.tsx", slug: "_header", title: "Header" },
    { file: "components/_footer.tsx", slug: "_footer", title: "Footer" },
  ],
  features: {
    header: true,
    footer: true,
    content: true,
    form_and_survey: true,
    online_store: false,
    user_authentication: false,
    app_data: false,
    webstorio_badge: true,
  },
  branding: {
    colors: {
      primary: "#0f766e",
      secondary: "#134e4a",
      background: "#f8fafc",
      text: "#0f172a",
    },
    fonts: { primary: "inter", secondary: "custom:Source Serif 4" },
    brandInfoFile: "brand/brand-info.md",
    designSystemFile: "brand/design-system.md",
    favicon: "favicon.png",
    defaultOgImage: "og-default.png",
  },
  pages: [
    {
      file: "pages/home.tsx",
      slug: "/",
      title: "Home",
      type: "system",
      seo: {
        title: "My Site — Home",
        description: "Welcome to My Site.",
        ogImage: "og-home.png",
      },
    },
    { file: "pages/about.tsx", slug: "about", title: "About" },
    { file: "pages/services.tsx", slug: "services", title: "Services" },
    { file: "pages/contact.tsx", slug: "contact", title: "Contact" },
    {
      file: "pages/blog-detail.tsx",
      slug: "blog/{content_entry_id}",
      title: "Blog post",
    },
  ],
  dev: { dataMode: "dummy" },
});

Fields

string

required

Human-readable project name. Used as the default SEO title on first create.

string

required

Globally-unique subdomain (4–50 chars, lowercase letters/numbers/hyphens). This is how push finds your project — it’s the project’s stable identity, so one working directory maps to exactly one Webstorio project.

string

Optional project description, used as the default SEO description on create.

string

A YYYY-MM-DD date that pins which supported library versions your project targets. webstorio init writes the current date and webstorio update bumps it. The server compiles against the version set effective on or before this date, so existing projects stay stable as the platform adds newer ones.

string

Optional folder (relative to the config file) of feature schema definitions. Expected layout:

content/*.json — CMS content types (content)
forms/*.json — forms (form_and_survey)
data/*.json — App Data tables (app_data)

When present, webstorio push upserts schemas by key. When absent, remote CMS / form / App Data schemas are left unchanged.Each file is JSON config:

{
  "version": 1,
  "kind": "content_type",
  "key": "post",
  "name": "Blog Post",
  "schemaJson": [
    { "key": "title", "type": "text", "label": "Title", "required": true }
  ]
}

Forms may also use the dashboard export shape ({ version: 1, form: { … } }). kind can be omitted when the file lives under the matching folder.

array

Shared header/footer component pages. Each entry is { file, slug, title } where slug is "_header" or "_footer". Pushing a component automatically enables the matching Webstorio feature so it renders on the live site.

object

Optional declarative map of released website features to enable or disable on push.When this field is present, it is the desired state for every released feature: keys set to true are enabled; keys omitted (or set to false) are disabled. Plan limits still apply (for example, Free cannot turn off the Webstorio badge). When the field is absent, push leaves remote feature flags unchanged.Allowed keys: header, footer, content, form_and_survey, online_store, user_authentication, app_data, webstorio_badge.If both components and features are set, features is applied after component auto-enable and wins (e.g. features.header: false disables the header even when _header is listed under components).

object

Optional website branding. When present, authored fields are merged into the remote website config on push. When absent, remote branding is left unchanged.

colors — { primary?, secondary?, background?, text? } as #RRGGBB hex. Exposed in page code as bg-brand-primary, text-brand-text, and related utilities (live site and webstorio dev).
fonts — { primary?, secondary? } curated keys (inter, open_sans, …) or custom:Font Family. Use font-brand-primary / font-brand-secondary in class names.
brandInfo / brandInfoFile — inline markdown or a path relative to the config file (use one, not both).
designSystem / designSystemFile — same pattern for the design-system markdown.
favicon / defaultOgImage — paths under assetsDir (e.g. "favicon.png"). Use null to clear; omit to leave the remote value unchanged.

array

required

Routable pages. Each entry is { file, slug, title, type?, seo? }.

slug — route path. Use "/" for the home page; it is normalized to the canonical empty slug on push. Nested routes use / between segments (e.g. docs/guide). Dynamic segments use {paramName} (e.g. blog/{content_entry_id}). See Routing below and the Routing how-to.
type — "static" (default) or "system". The home page is always "system".
seo — optional { title?, description?, keywords?, ogImage? }. When present, push syncs those SEO fields for the page. When absent, remote SEO is left alone (new pages still get a seed SEO title from title). ogImage should be a path under assetsDir.

object

Local preview options.

dataMode — "empty" | "dummy" | "preview" (default "dummy").
port — local preview port (default 9678).

Routing

Page URLs come only from pages[].slug in this file — not from the filesystem layout under pages/.

Kind	Example slug	Example URL
Home	`"/"`	`/`
Static	`"about"`	`/about`
Nested	`"docs/getting-started"`	`/docs/getting-started`
Dynamic	`"blog/{content_entry_id}"`	`/blog/abc-123`

Wildcards: a segment like {content_entry_id} or {product_slug} matches any single path segment. Exact static routes take priority over patterns. webstorio dev and the published site use the same matching rules. Read captured values in page code:

const { content_entry_id } = window.webstorio.getPathParams();

Feature scaffolds (webstorio generate and dashboard create-page) use conventions such as content/{key}/{content_entry_id}, store/product/{product_slug}, and form/{formKey}. Step-by-step guide: Routing.

Shared components

You do not list inline shared components (like Testimonials) in the config. Import them from your pages with a relative import and the CLI bundles them into whichever page uses them:

pages/about.tsx

import Testimonials from "../components/Testimonials";

export default function Page() {
  return (
    <main>
      <Testimonials />
    </main>
  );
}

Supported libraries

Pages and components may only import from Webstorio’s allowlist of supported libraries; anything else must be inlined as a relative import. Run webstorio update to align your local devDependencies with the exact versions the server compiles against.

Push fails fast if a page imports a non-allowlisted package or has no default export. The server re-validates everything before compiling.

Overview

CLI

Client SDK

MCP Server

Help

Fields

Routing

Shared components

Supported libraries

​Fields

​Routing

​Shared components

​Supported libraries

Fields

Routing

Shared components

Supported libraries