CLI

You changed a block's props and the site editor still shows the old form: the schema needs regenerating. This page lists every deco command and its flags.

The Deco CLI is the deco command. It ships inside @decocms/blocks, so there's nothing extra to install, and it always matches your runtime version. Run it once with npx (bunx works the same):

npx @decocms/blocks schema

Once @decocms/blocks is installed, your package.json scripts call it by its short name, deco (for example deco schema). To call it from your own code, import it from @decocms/blocks/cli.

Every command works on one folder, .deco/, in your app root (the folder with your app's package.json). Which file in it is which, and which to commit, is in The .deco folder.

It has four commands, and each does one job:

• deco schema turns the types in .deco/index.ts into .deco/schema.gen.json. Commit this file. See Forms from types.
• deco content turns the files in .deco/blocks into the content module, .deco/blocks.gen.ts. It's generated, so gitignore it. See The content module.
• deco check makes sure your saved blocks fit your code, and fails if one doesn't. It writes nothing. See Checking content.
• deco serve is the local server the site editor uses to edit the files on your machine. See Edit on your machine.

There's no deco publish: publishing is committing. Running it prints that and exits with code 1 (see Design decisions).

Run it before dev and build

There's no separate dev command: run deco schema and deco content before your dev server and your build. The build also runs deco check, so content that doesn't fit the code fails the deploy instead of shipping; dev skips it, so a content error doesn't stop your dev server.

{
  "scripts": {
    "predev": "deco schema && deco content",
    "prebuild": "deco schema && deco content && deco check"
  }
}

Finding the .deco folder

Every command takes --root <dir>: the folder that contains .deco/, relative to the current folder. You rarely pass it. By default, the command walks up from the current folder to the first folder with a .deco/, so it works from any subfolder of your app.

If no folder on the way up has a .deco/, the command stops with an error:

no .deco/ found from /path/you/ran/it/in; run inside your app or pass --root

In a monorepo, walking up from the repository root never reaches apps/storefront/.deco, so the command fails there (or, if the root has a stray .deco/, it uses that one). Run the commands inside the app instead, for example as scripts in apps/storefront/package.json. Then @decocms/blocks must be a dependency of that app, so its scripts can find deco. Or pass the app from the repository root:

deco schema --root apps/storefront
deco content --root apps/storefront

The site editor's "app root" setting points at that same folder, both on your machine and when the site editor reads your repository on GitHub in the hosted version.

deco schema and deco content

deco schema  [--root <dir>] [--watch]
deco content [--root <dir>] [--watch]

deco content only bundles the JSON files in .deco/blocks. It never reads your block map.

The options:

• --root <dir>: the folder that contains .deco/ (see above).
• --watch: regenerate as files change.

deco check

deco check [--root <dir>]

deco check reads .deco/schema.gen.json and .deco/blocks as they are, writes nothing, and validates every saved block against that schema. It doesn't generate the schema or load your TypeScript, so run deco schema first: deco schema && deco check. It exits with 0 when everything fits, and with 1 otherwise, listing the problems per file. Warnings are listed but don't change the exit code. What it checks, and how to run it on every pull request, is in Checking content.

deco serve

deco serve [--root <dir>] [--port <n>] [--host <addr>] [--preview <host:port|url>] [--assets <dir>] [--read-only]

deco serve is the local server the site editor uses to edit the files on your machine, over the content protocol: it reads and writes .deco/blocks, reads .deco/schema.gen.json, and accepts uploads into public/assets/ (or --assets). It tells the site editor which root it serves through the content protocol's describe. The flow is in Edit on your machine. It takes:

• --root <dir>: the folder that contains .deco/, such as apps/storefront in a monorepo. By default, it walks up from the current folder to the first folder with a .deco/, like every command.
• --port <n>: the port to listen on (default 4545).
• --host <addr>: the address to listen on. By default the server listens on loopback, both 127.0.0.1 and ::1 on the same port, so http://localhost:<port> reaches it whichever address your system gives localhost; it prints its address as localhost. With --host it listens on that one address only. An address beyond loopback prints a warning: the server has no authentication, so other machines on your network can then read and write your content. The site editor still connects only through localhost: with 0.0.0.0 the printed link uses localhost, and with a specific network address the link doesn't work. How the server is protected is in The local server.
• --preview <host:port|url>: your running dev app, which the site editor shows in its Preview tab, as localhost:8001 or a full URL such as http://127.0.0.1:3000/en/. It must be on your machine (localhost, 127.0.0.1 or ::1). By default, the server.port from your Vite config (read as text, never run), else http://localhost:5173. The server prints it as Preview and reports it in describe (see The four methods).
• --assets <dir>: the folder the site editor's uploads are written to, relative to the folder that contains .deco (default public/assets). The field always stores /assets/<name>, whatever this folder is, so a folder you pass must be served at /assets/; see Images and other uploads.
• --read-only: serve the content without accepting writes or uploads.