@zalify/theme-templates

Template carrier for Zalify storefronts. This package is not a CLI — it ships the standalone app templates, their checksum manifests, and framework metadata. The front door is the Zalify CLI (@zalify/cli):

npx zalify theme create my-store -t nextjs   # scaffold
zalify theme status                          # which theme files have you edited?
zalify theme upgrade                         # pull in a newer theme version

(The old create-zalify-theme scaffolder is retired and deprecated on npm in favor of zalify theme create.)

What's in the tarball

templates.json                    # framework metadata (env vars, editor overlay, next steps)
templates/<framework>/…           # the app template, ready to copy
templates/<framework>/.zalify/theme.json   # checksum manifest (the upgrade contract)

• .zalify/theme.json records {template, version, kitVersion, files: {path: sha256}} over every theme-owned file, plus editorFiles for the __editor__ overlay (resolved into files at scaffold time along with a recorded variant). zalify theme upgrade uses old + new manifests to overwrite untouched files, 3-way-merge edited ones, and never touch merchant-owned paths (theme/, .env, public/ additions, package.json is merged structurally).
• Merchant-owned theme/ folder — settings_data.json, templates/.json, locales/.json — is how a scaffolded store customizes the theme without editing shipped source; it survives every upgrade untouched.
• .gitignore files are stashed as gitignore inside the tarball (npm pack strips the real name); the CLI restores them.

Every template runs against mock.shop demo data out of the box; connect a Shopify store by filling in .env.

Frameworks

| Name | What you get | | ---------- | --------------------------------------------------------- | | liquid | Shopify Online Store 2.0 theme (Liquid + Vite JS islands) | | hydrogen | Shopify Hydrogen on the React Router framework | | nextjs | Next.js App Router storefront (single or multi-tenant) |

Generated projects are plain single-package apps depending on the published @zalify/storefront-kit SDK — the SDK is versioned, your theme data and customizations live in your project.

Optional editor (both React runtimes)

Hydrogen and Next.js always include the same lazy editor bridge. There is no separate editor starter and no --editor flag is necessary. Legacy --editor remains harmless; old CLI releases may print an informational "no editor overlay" notice. Existing editor projects upgrade through the same framework template and retain three-way merge protection.

Set exact trusted origins in config/editor.ts to connect an editor. The empty default disables the bridge. See docs/optional-editor.md in both starters for preview setup and the persistence boundary.

Development (inside the zalify-storefronts monorepo)

Templates are snapshots of apps/*, built by:

pnpm --filter @zalify/theme-templates build:templates

prepack runs the same script, so pnpm publish from this package always ships templates (+ manifests + templates.json) matching the current source tree. Publishing must happen from inside the monorepo checkout. The release gate is test:smoke (scaffolds every variant via scripts/scaffold.mjs — the reference implementation of zalify theme create; keep it in sync with zalify-cli/src/theme.ts).

Release ordering: templates depend on @zalify/storefront-kit@^<version in the source tree>, so publish the kit first (its prepack compiles dist/), then this package.

License

Source-available under the Zalify Source Available License: build, modify, and operate the storefronts you scaffold freely (including for clients); don't republish the templates or SDK as your own developer product.