Create a theme with theme init

theme init creates a named theme inside an Upstorr theme workspace. It always starts from Upstorr's basic bespoke retail starter.

Before you start

  • Install Node.js 20.9 or newer.
  • Install @upstorr/cli globally.
  • Choose an empty directory for the workspace.

Command

mkdir my-upstorr-themes
cd my-upstorr-themes
upstorr theme init "My Brand Theme"

If you leave out the name, the CLI asks for one. To choose another workspace directory:

upstorr theme init "My Brand Theme" --workspace ./client-themes

The destination must be empty. There is currently one starter, so there is no starter-selection flag.

What the command creates

The workspace receives upstorr-workspace.json and a themes/ directory. The example above creates themes/my-brand-theme/.

Inside the theme checkout:

  • theme/ is the storefront source you edit.
  • .upstorr-theme/ contains generated local state and SDK autocomplete.
  • docs/ contains the developer guides bundled with this CLI version.
  • tests/, package.json and tsconfig.json support local development.

The CLI also writes the same theme identity into theme.json, theme/storefront.json and the generated lock. Do not rename these pieces independently; use theme rename.

Next step

upstorr theme connect my-brand-theme
upstorr theme dev my-brand-theme

Common problems

  • Workspace is not empty: use a new directory or pass a different --workspace path.
  • Theme name already exists: choose another name. Two themes in one workspace cannot use the same normalized key.
  • Starter files are missing: reinstall the CLI. A valid package includes its starter, documentation and generated SDK types.