Theme CLI reference

storeos theme init [dir] [--blank]            Create a theme
storeos theme new widget <name> [--page p]    Add a widget and put it on a page
storeos theme new snippet <name>              Add a snippet
storeos theme dev [dir] [options]             Preview with live reload
storeos theme check [dir]                     Check the theme, the same way upload does
storeos theme package [dir] [--out file.zip]  Check and zip the theme for upload

[dir] is the theme folder. It defaults to the current folder, except for init, which creates ./my-theme. new works in the current folder. Run storeos theme --help for a summary.

The full command reference is at storeos theme. To install the CLI, see the CLI overview.

initCopy Anchor Link

storeos theme init my-theme            # the full starter theme
storeos theme init my-theme --blank    # only the required files
storeos theme init .                   # in the current folder

The folder must not exist yet or must be empty. A .gitignore for zips is added too.

The full starter theme has a header, footer, hero, featured products, and a widget for every page (product, collection, page, blog, article, search), with snippets and translations. Read it to see how a complete theme fits together.

newCopy Anchor Link

storeos theme new widget promo-banner                 # on the home page
storeos theme new widget size-guide --page product    # on the product page
storeos theme new widget button                       # restyle a built-in widget
storeos theme new snippet product-card

new widget writes widgets/<name>.fluid with a heading and a text setting to start from, and adds the widget to a page in config/document.json.

For a built-in widget name such as button or heading, it copies StoreOS's own markup instead, with the props the widget already gets. Change the markup and keep using those props.

Names are lowercase letters, numbers and dashes. An existing file is never overwritten.

devCopy Anchor Link

storeos theme dev
storeos theme dev --port 3000 --open
storeos theme dev --data store.json

Serves the theme from your folder with the same engine stores use, so what you see here is what a store renders. Nothing is zipped or uploaded.

Files given with --data and --document are watched too.

PagesCopy Anchor Link

Other pages, such as the cart and checkout, show a notice: StoreOS renders them, not the theme.

Saving filesCopy Anchor Link

Tailwind stylesheets are recompiled on every save.

Store dataCopy Anchor Link

There is no built-in sample catalog. Until dev has store data, the preview shows a waiting page. Give it data with Connect local theme in the console, with --storefront <url>, or with --data.

To use a JSON file, pass it with --data. It uses the same shapes as the Storefront API. Lists you leave out are empty:

{
  "shop": { "name": "My Shop", "currency": "BDT" },
  "collections": [{ "_id": "c1", "name": "Shoes", "slug": "shoes" }],
  "products": [
    {
      "_id": "p1",
      "title": "Runner",
      "handle": "runner",
      "price": 2500,
      "thumbnail": { "url": "https://example.com/runner.jpg" },
      "collections": [{ "_id": "c1", "name": "Shoes", "slug": "shoes" }]
    }
  ],
  "pages": [],
  "posts": []
}

An image is { "url": "…" }, or { "key": "Some label" } for a placeholder with that label.

To see your real store's data without writing JSON, connect the theme to the console or use --storefront.

Console connectionCopy Anchor Link

While dev runs, the console customizer can load your theme straight from your computer, with your store's real data:

1. In the console: Online store → Themes → Uploaded themes → Connect local theme.
2. http://localhost:9292 is filled in. Change it if dev printed another port, then click Connect.

You can open the console before or after starting dev: it connects when the server is up and reconnects if you restart it. The header shows the connection: updates when you save, connecting or dev server stopped.

• Nothing is saved to the store. Save draft and Publish are replaced by Save to files (⌘S / Ctrl+S), which writes the document to config/document.json in the short form. If you started dev with --document, that file is written instead. Keys the customizer doesn't edit, such as prerender, are kept.
• ⋯ → Save as widget defaults writes the selected widget's settings as the defaults in its {% schema %}, in the short form. This works for your own widgets, not built-in ones.
• ⋯ → Copy JSON copies the document, the selected widget's props or its schema, if you'd rather paste them yourself.
• Reset → Discard changes reloads everything from your config/document.json.
• The terminal prints each file the console writes, e.g. ✎ config/document.json saved from the console.
• New and changed widgets show up in the widget library as soon as you save them.
• Only localhost addresses can be connected.

Which consoles can connectCopy Anchor Link

The dev server only shares your theme with StoreOS consoles, and only they can save to it: https://console.storeos.dev, any other https://*.storeos.dev address, and consoles running on localhost. It checks the address each request comes from, so you don't need any options. Other websites can't read your theme or write to it. The console can only write config/document.json and the schemas of widget files that already exist.

If you use a console on your own domain, allow it with --console:

storeos theme dev --console https://admin.example.com

BrowsersCopy Anchor Link

Use Chrome, Edge or Firefox. Safari blocks an https page from loading http://localhost. Chrome may ask whether the console can access devices on your local network: allow it.

checkCopy Anchor Link

storeos theme check

Runs the same checks as upload and prints every problem it finds. Errors (✗) stop an upload:

• layout/theme.fluid or config/document.json is missing
• A folder or file type that isn't allowed
• A .fluid file that doesn't parse
• A {% schema %} with invalid JSON, a setting without a kind, or an unknown kind
• config/document.json uses a widget the theme can't render
• A Tailwind stylesheet doesn't compile

Warnings (!) are likely mistakes that still render:

• A setting the markup never uses
• Settings guessed from the markup
• An unknown schema key or page name
• A {% schema %} in a built-in widget, which is ignored
• A built-in widget's markup that ignores the settings merchants change

Where it can, it suggests the fix:

  ! widgets/card.fluid: unknown {% schema %} key "lable" (did you mean "label"?)
✗ 1 error(s):
  - config/document.json: uses widget "crad" but the theme has no widgets/crad.fluid (did you mean "card"?)

It exits with code 1 when there are errors, so you can use it in CI. Warnings don't change the exit code. dev prints the same warnings when they change.

packageCopy Anchor Link

storeos theme package
storeos theme package --out dist/my-theme-1.2.zip

Checks the theme, compiles Tailwind stylesheets and writes a zip, by default <folder name>.zip in the current folder. Only the theme folders (layout, widgets, snippets, assets, config, locales) are included. Hidden files are left out.

Upload it in the console: Online store → Themes → Upload theme.

TroubleshootingCopy Anchor Link