create-limitedrun-theme

Modern toolchain for building Limited Run storefront themes — a scaffolder plus a local dev/build CLI, in the spirit of create-react-app.

It supersedes the 2014 limitedrun-themekit Ruby gem. Like the gem, it renders themes locally against a mock store.json; unlike the gem it also scaffolds new themes, live-reloads on save, and packages an upload-ready zip. There is no theme API, so deploys are still a manual zip upload in the Limited Run admin.

Quick start

npm create limitedrun-theme@latest my-theme
cd my-theme
npm run dev      # preview at http://localhost:4567

The scaffolder prompts for a starter theme (or pass --template <id>): skeleton (default), telescope, hyde, binoculars, winter, winter-peak — ported from Limited Run's own themes. Every starter ships the same store.json mock, a .gitignore, and an AGENTS.md / CLAUDE.md that orient an AI agent on editing and running the theme.

Packages

Package	What it does
create-limitedrun-theme	npm create scaffolder — picks a starter theme, wires package.json
@limitedrun/cli	limitedrun dev (preview + live reload) and limitedrun build (validate + zip)

CLI

limitedrun dev [--path DIR] [--port N] [--strict]
limitedrun build [--path DIR] [--out DIR]

• dev — Hono server rendering the theme with liquidjs, routes matching the platform, stylesheets processed through Liquid, JS served verbatim, and a chokidar watcher that live-reloads the browser over SSE. --strict fails on undefined Liquid variables/filters.
• build — validates configs/default.json and store.json, runs stylesheets/ and javascripts/ through the asset-transform registry (identity today — the seam where SCSS / TypeScript / minification plug in later), and writes dist/<name>.zip in the platform's export layout. Upload that zip in the admin under Storefront → Themes.

Theme layout

The authored source is exactly what the platform ingests:

configs/default.json      theme settings schema
layouts/default.html      wrapper layout ({{ content }})
templates/*.html          page templates
snippets/*                Liquid partials for {% include %}
stylesheets/*.css         run through Liquid on serve/build
javascripts/*.js          served verbatim
store.json                mock data for local preview (not shipped in the zip)
store.schema.json         JSON Schema for store.json

store.json is validated on dev startup and build; a bad file gives a readable error instead of a stack trace.

Development

nvm use           # Node 24, per .nvmrc
npm install
npm test          # vitest, all packages
npm run build     # tsup, all packages
npm run lint      # prettier --check + per-package typecheck

Requires Node 22+; development and CI run on the version pinned in .nvmrc (Node 24, the active LTS). Versioning and publishing via Changesets.

License

MIT — see LICENSE. Retains the original copyright of the limitedrun-themekit gem by Howard Wilson.