Getting started

Four steps from an empty repository to typed content in your application. Nothing here needs a database, a build plugin or a deployment target.

1. Install and connect

The SDK reads content at build time and generates types from your schemas. The CMS itself is hosted — you connect a repository to it rather than running it yourself.

terminal

# in your project root
npm install @commitpress/sdk-node

# then connect the repository at
# https://cms.commitpress.com/

Installing the GitHub App is what grants access. Pick the repositories you want to manage; commitpress can only read and write the ones you select.

2. Add a config file

commitpress.config.json sits at the root of your repository. The CMS can create it when you set up a connected project. Configuration v2 groups content, editor and build settings.

commitpress.config.json

{
  "$schema": "https://cms.commitpress.com/app/schema/config/v2",
  "root": "",
  "branch": "commitpress-content",
  "content": {
    "directory": "__commitpress__",
    "intl": {
      "default_locale": "en",
      "locales": [
        "en"
      ]
    }
  },
  "editor": {
    "preview_urls": [
      "http://localhost:5173/preview/"
    ]
  },
  "build": {
    "sdk": {
      "output": "./src/commitpress.generated.ts"
    }
  }
}

On branch: this is the content branch the CMS uses. Saving content creates commits; it does not itself mean the website is live. Working branches can be reviewed and merged into the content branch. Site releases depend on your publishing configuration.

3. Build a schema, generate types

Schemas are built in the browser — fields, groups, repeatable blocks — and committed as JSON. Once one exists, generate the TypeScript that describes it.

terminal

npx commitpress generate

# Reads every schema under __commitpress__/schema and
# writes typed content shapes to the path declared in
# commitpress.config.json. Re-run it after a schema
# change — or wire it into your build step.

Pages

One file per URL, addressed by slug.

Collections

Many entries sharing one schema, one file each.

Globals

Site-wide content: navigation, footer, SEO defaults.

Page schemas get an seo group whether they declare one or not — browser title, meta description and a noindex switch. It is merged in when a schema is read rather than written into your file, so it appears in the editor and in the generated types without a commit, and a field of the same name in your own schema wins. Collections get the same group, because an entry this CMS serves itself — these documentation pages, for one — has a <head> like any other page.

A site's menus are a navigation field, normally on a global — one field per menu, so a header and a footer are two fields or two globals rather than one list everything has to be filtered out of. The field edits as an indented list and its shape is fixed rather than authored: an item is a label, an optional link and its children. That is what lets the SDK type it the same way in every project, and what makes internal links in a menu checkable — a menu item pointing at a page that no longer exists is reported like any other broken reference.

4. Preview it

Each entry in preview_urls becomes a target the editor can render the page it is editing against, at desktop, tablet or phone width. The preview target is a running instance of your site — point it at localhost while developing and at a staging deploy for everyone else.

The pane renders whatever is at that URL, so it tells you which of those it got: a target that is not running says so, and a target that is running but does not implement the preview handshake says it is showing the last saved version rather than what you are typing. A deployed site is the second of those — a working preview, just not a live one.

A CMS served over https cannot frame a plain http:// target — the browser blocks it. localhost is the exception, which is what makes previewing your local dev server from a deployed CMS work at all.

Repository layout

Everything commitpress owns lives under one folder. It is ordinary JSON — readable in a diff, greppable, and yours whether or not you keep using the product.

repository

__commitpress__/
├─ schema/
│  ├─ pages/          # one file per page type
│  ├─ collections/    # one file per collection type
│  └─ blocks/         # reusable field groups
├─ content/
│  ├─ pages/          # index.json, about.json, …
│  └─ collections/    # posts/1757594289577.json, …
└─ media/
   └─ images/         # the asset, plus its asset.json

Reading those files from your build — typed queries, collections, drafts, and writing content from a script — is the SDK page.

Ready to connect a repository?

The control panel walks through installing the GitHub App and writing your first config.

Open the control panel See what it can do