create-easel-theme

create-easel-theme

Scaffold a focused Shopify Liquid theme with Vite and Easel. Choose TypeScript or JavaScript, optional Alpine, React or Vue, and plain CSS or Tailwind CSS through a Clack prompt.

npm create easel-theme@latest my-theme

Or with npx:

npx create-easel-theme@latest my-theme

From a checkout of the Easel repository:

pnpm install
pnpm create:theme ../my-theme

Use the current directory

Pass . as the directory, or enter . at the directory prompt. The theme is created directly in that folder, and its name is derived from the folder name.

npm create easel-theme@latest .

From a repository checkout, build first, then invoke the executable from your desired folder so . refers to that folder rather than the Easel checkout:

pnpm --dir /path/to/Easel/packages/create-easel build
node /path/to/Easel/packages/create-easel/bin/create-easel-theme.mjs .

Existing folders must be empty apart from .git and .DS_Store, which are preserved. Existing project files, including a README or .gitignore, are not overwritten or merged.

Choices

• TypeScript (default) or JavaScript.
• No UI framework (default), Alpine, React, or Vue.
• Plain CSS (default) or Tailwind CSS.
• Optional dependency installation using npm, pnpm, Yarn, or Bun. The manager is detected from the invoking package manager; use --package-manager to override it.

The output is a standalone project using the published vite-plugin-shopify-easel package. It does not depend on this repository or on the scaffolder at runtime. The current templates target Easel 0.2.2 and require Node.js 22.12.0 or newer.

The starter includes a homepage counter, theme settings, translations, generic JSON templates and sections for the standard storefront page types, theme.liquid and password.liquid layouts, and a Liquid gift card template. Customer account templates are intentionally omitted because current customer accounts operate independently of themes. Shopify's default robots and agent-discovery templates are left unchanged. Metaobject templates are definition-specific and should be added when those definitions enable web pages. The generic sections are starting points rather than complete commerce features or a production design. Framework integrations use their official Vite plugins where applicable, and include Theme Editor initialization and cleanup. React includes its development preamble.

Non-interactive use

npm create easel-theme@latest my-theme -- --yes --language ts --framework vue --tailwind --no-install

Flags:

Without an interactive terminal, or in CI, a directory is required, prompts are skipped, and dependencies are installed only when --install is supplied. --yes does not imply installation. Dependency installation can execute package lifecycle scripts; use --no-install to inspect the project first.

Safety and ownership

• New directories and existing empty directories are supported. Git and Finder metadata are preserved; populated directories and symlink targets are rejected. There is no overwrite or force option.
• All questions are answered before writing the theme. Cancelling a prompt exits with code 130 without creating it.
• Templates are rendered in a temporary directory before copying to the target. On failure, rollback removes only unchanged generated files and empty directories it created. Existing directories, metadata, and concurrent edits are preserved. Newly created parent directories can remain.
• Installation failure or Ctrl+C during installation keeps the theme and prints retry instructions. Failures return a nonzero exit code.
• The CLI does not authenticate with Shopify, create stores, push themes, initialize Git, or change global package-manager configuration.
• The CLI invokes the selected package manager directly, without interpolating the destination into a shell command. pnpm installation uses --ignore-workspace to avoid installing into an unrelated ancestor workspace.

After generation, normal Vite commands and Shopify CLI take over. Easel does not wrap either tool. Run npm run check for source and build validation, npm run check:theme for Shopify Theme Check, or npm run check:all for both. The Theme Check scripts require Shopify CLI to be installed separately. Stop development before building and deploy the generated Liquid loader alongside its matching assets.

Development

From the repository root:

pnpm --dir packages/create-easel build
pnpm --dir packages/create-easel check
pnpm test
pnpm build
pnpm test:package

The CLI is TypeScript bundled with tsup. One base theme is composed with small framework overlays; Tailwind changes the generated config and CSS. JavaScript templates are derived from the TypeScript sources at build time rather than maintained as duplicate themes. The Vue component uses runtime props declarations so both script languages share its implementation.

The repository's test/create.test.js covers generation, validation, filesystem safety, automation, and installation outcomes. The package's test/install.test.js also checks signal-handler ordering and cleanup. The package smoke test installs the actual tarball, exercises the npm executable, and installs and checks all 16 language/framework/styling combinations outside the repository. pnpm test:theme-check also validates the generated Liquid variants.

The generator and Vite plugin share a version and trusted-publishing workflow; see the repository's RELEASING.md for the release contract.