LocalStage CLI

LocalStage is the CLI that runs a local theme development server. It renders your theme files with the same engine as production and applies live reload while you edit.

You need Node.js 22.12 or newer, a Basker login, and a theme directory with layouts/, templates/, and blocks/.

Step 1: Install the CLI

npm install -g @baskerhq/localstage

Verify:

basker --version
# @baskerhq/localstage/1.0.x

Step 2: Start the development server

From inside your theme directory:

cd ./my-theme
basker theme dev

Or specify the path explicitly:

basker theme dev --theme ./my-theme

On your first run, LocalStage asks for your Basker email and password. Then it asks for a verification code from an authenticator app, an emailed code, or a recovery code. If your account can access more than one workspace, it then asks which one to use. LocalStage stores the session in its application-data directory. It scopes the session to both the theme path and the Basker origin.

Once authenticated, you should see a summary:

LocalStage  ready

Preview   http://localhost:9292
Theme     my-theme
Theme ID  not set
Basker    https://your-workspace.basker.app
Path      /path/to/my-theme
Reload    on

Actions   o open  c check  p theme ID  r clear cache  a CMS  q quit

LocalStage opens your default browser at http://localhost:9292 automatically. Keep the terminal open while you work.

If you see "No theme files detected in current directory", LocalStage could not find layouts/ or templates/ there. Either cd into the theme directory first, or pass --theme ./my-theme.

Step 3: Confirm the preview is rendering

The browser should show your theme, rendered with live CMS data. If you closed the tab, press o in the terminal to reopen or resync it.

If the page looks unstyled or lacks content, this is normal. A new theme has no content to render yet.

To reset the cached session and sign in as a different user, run basker auth logout. To re-authenticate without restarting the dev server, run basker auth login instead.

Step 4: Set the theme to preview (optional)

If your theme is already uploaded to Basker, link the local server to the remote theme. This lets LocalStage load theme settings from the CMS.

Press p in the dev-server terminal. Enter the theme ID. You can find the ID in the admin, under Design, then Themes.

Or use theme set to find the ID automatically from the theme key (the directory name):

basker theme set --theme ./my-theme

Automatic lookup uses the cached auth session. Run basker auth login first, or start the dev server once. You can also pass an explicit ID with --theme-id <id>.

A theme ID is optional. Without it, LocalStage uses a local fallback theme.

Step 5: Edit a template and see live reload

Open a .liquid file in your editor. Add a paragraph to layouts/default.liquid:

<p>Hello from Basker!</p>

Save the file. Switch to your browser. The page should refresh within a second.

LocalStage watches .liquid, .css, .js, .json, and .html files. When a file changes, it sends a reload signal over a WebSocket one port above the main server (port 9293).

If you prefer manual refreshes, disable live reload with --no-livereload:

basker theme dev --theme ./my-theme --no-livereload

Step 6: Run theme validation

While the dev server runs, press c to run the theme checker against your local files:

Theme check: 0 errors, 2 warnings, 0 info
- [warning] templates/page.liquid: Template is missing a schema tag. (template-missing-schema)
- [warning] blocks/text-section.liquid:12: Unsupported field type 'colourPicker'. (unsupported-field-type)

Or run validation as a standalone command in another terminal:

basker theme check --theme ./my-theme

For CI, use --fail-level to control which severity exits non-zero:

basker theme check --theme ./my-theme --fail-level warning

Exit code 0 means no issues at or above the level. Exit code 1 means at least one matched.

The local checker is intentionally lightweight and can report a different severity than upload validation. After you upload, always review the validation summary too.

Next steps

• Tutorial: if you skipped here.
• Theme directory structure: required and optional directories.
• Uploading themes: package and deploy.

Troubleshooting

"No theme files detected in current directory"

LocalStage looks for layouts/ or templates/ in the current working directory. Either cd into the theme directory first, or pass --theme ./subdirectory-name.

"Theme path does not exist"

The path passed to --theme does not exist. Check for typos. An absolute path can help if relative paths do not resolve.

"Session expired"

LocalStage could not validate your auth token. Run basker auth logout, then basker auth login, to refresh the session. Or restart basker theme dev instead.

Port 9292 is already in use

Another process uses the port. Stop it, or run on a different port: basker theme dev --port 9300.

WebSocket connection refused on port 9293

Live reload uses the port immediately after the main server. If it is in use, the dev server continues to run, but live reload will not fire. Stop whatever process uses port 9293, or change the main port (--port 9300 makes the WebSocket use 9301).