CLItheme
theme dev
Preview a StoreOS theme from your folder with live reload, and connect it to the console customizer.
Serves the theme from your folder with the same engine stores use, so what you see is what a store renders. Nothing is zipped or uploaded.
There is no built-in sample catalog. Until dev has store data, the preview shows a waiting page. Give it data one of three ways:
- Connect local theme in the console. No flags needed
--storefront <url>to load a real shop and catalog from a running storefront API--data <file>to use your own JSON
Usage
storeos theme dev [dir] [flags]Flags
| Flag | Description |
|---|---|
--port <n> | Port to listen on. Default 9292; the next free port is used if it's taken |
--host <host> | Host to bind. Default localhost. Use 0.0.0.0 to open the preview from a phone on the same network |
--storefront <url> | Load the shop, catalog and SEO from storefront-api, such as http://127.0.0.1:4001 |
--store <store> | The store's tenant uid. Needed with --storefront when the address has no tenant subdomain. Also prints a direct console link |
--data <file> | A store data JSON file |
--document <file> | A theme document to use instead of config/document.json, such as one copied from a store's customizer |
--console <url> | Allow a console on a custom domain. Any *.storeos.dev and localhost console is allowed without it |
--open | Open the preview in your browser |
--data and --document files are watched too.
Examples
storeos theme dev --storefront http://127.0.0.1:4001 --store demo-grocery
storeos theme dev --data store.json --open
storeos theme dev # then use Connect local theme in the consoleStop it with Ctrl+C.
When it starts, dev prints:
> storeos theme dev
storeos theme dev · my-theme
Preview http://localhost:9292
Widgets http://localhost:9292/__theme/widgets
Data waiting for storefront (Connect local theme or --storefront)
Console Online store → Themes → Uploaded themes → Connect local theme
Watching for changes. Ctrl+C to stop.Pages
| URL | Description |
|---|---|
/, /products/:handle, /collections/:handle, /collections/all, /pages/:slug, /blog, /blog/:handle, /search?q= | Your theme's pages, with the same routes as a store |
/__theme/widgets | Every widget in your theme on its own, with its default settings |
/__theme/widgets/<type> | One widget |
Pages the app renders, such as the cart and checkout, show a notice.
When you save a file
| You save | What happens |
|---|---|
A .css file in assets/ | The stylesheet is swapped in place. No reload, so scroll and state are kept |
| Any other theme file | The theme is re-read and checked, then the page reloads |
| A file with an error | The page shows the error with file and line, and the terminal prints it. The next good save recovers |
A widget reading a props.<name> its schema doesn't list | It gets a guessed setting, and the terminal lists it as a warning |
Tailwind stylesheets are recompiled on every save.
To open the theme in the console customizer, see Console connection.
Troubleshooting
| Problem | Fix |
|---|---|
doesn't look like a theme | Run the command inside the theme folder, or pass it: storeos theme dev my-theme |
| The preview shows a waiting page | Give dev store data: --storefront, --data, or Connect local theme in the console |
| The console can't connect | Check the port dev printed, use Chrome, Edge or Firefox, and allow local network access if asked |