Build, Validation, and Deployment

Crane validates theme projects during crane build. Treat a clean build as the minimum bar before previewing in the Instant Site Editor or deploying to merchants.

The deployment workflow also needs discipline. A deployed blueprint update can affect every live site using the theme, so validation should happen in a test app before anything is published through the app merchants use.

Pin the Crane Version

Avoid npx @lightspeed/crane@latest in CI and long-lived theme projects. Pin the Crane packages in package.json and run them through npm scripts so builds are repeatable and do not change when a new release is published.

Use release notes to decide when to upgrade. Upgrade deliberately, run the full validation flow, and commit the package changes with the theme changes that require them.

{
  "scripts": {
    "build": "crane build",
    "preview": "crane preview",
    "deploy": "crane build && crane deploy",
    "lint": "eslint ."
  },
  "dependencies": {
    "@lightspeed/crane": "3.5.0",
    "@lightspeed/crane-api": "2.5.0",
    "@lightspeed/eslint-config-crane": "1.1.3",
    "vue": "^3.5.21"
  },
  "devDependencies": {
    "eslint": "9.33.0"
  }
}

Use npx @lightspeed/crane@latest init for creating a new project if needed. For existing projects, prefer the pinned local dependency through npm scripts, or use an explicitly pinned command such as npx @lightspeed/crane@3.5.0 preview when you need to run Crane outside the project scripts.

Keep Credentials Out of Git

crane.config.json contains app credentials:

{
  "app_client_id": "your-client-id",
  "app_secret_key": "your-secret-key"
}

Never commit real values. The generated Crane project includes crane.config.json in .gitignore; keep that entry in place:

# .gitignore
crane.config.json

Use different local crane.config.json values for test and publishing apps. Credentials should be distributed through a secure internal channel, not through source control, pull requests, or documentation examples with real IDs.

Keep Build Validation Clean

Run crane build and fix every validation failure before deployment:

npm run build

Do not work around validation by removing showcases, leaving unused content keys, or ignoring schema errors. Build-time validation exists to catch problems before they become broken editor states or broken storefront sections.

At minimum, check that:

• Every showcase builds and renders.
• Showcase content keys match settings/content.ts.
• Showcase design keys match settings/design.ts.
• Selectbox defaults use valid option values.
• Deck card settings match the deck configuration.
• layoutId values exist when sections define settings/layout.ts.
• Preview and content image files exist in the expected assets/ directory.
• Template page, header, footer, layout, and slot configuration pass validation without warnings.

Lint Without Silencing Rules

Use @lightspeed/eslint-config-crane and keep lint passing:

// eslint.config.js
export { default } from '@lightspeed/eslint-config-crane';

npm run lint

Do not silence accessibility or framework rules to get a deployment out. Those rules protect merchant editing flows, keyboard users, screen readers, and SSR-safe Vue code. If a rule looks wrong for a specific case, isolate the reason and keep any exception as narrow as possible.

Preview Every Page Type

Local preview is useful for fast iteration, but it should cover the whole theme surface, not just the home page.

Preview:

• Home page.
• Every custom page.
• Product page layouts.
• Catalog page layouts.
• Category page layouts.
• Headers and footers.
• Empty, loading, and fallback states where the section depends on store data.

Run:

npm run build
npm run preview

See Local Preview for the local server workflow.

Test in the Instant Site Editor

Local preview does not exercise the full merchant experience. It does not fully cover editor panels, merchant changes, platform-rendered storefront content, or the way the section behaves after a merchant adds it to a real site.

Use Crane DevTools by Lightspeed to preview local sections in the Instant Site Editor, then test the same workflows a merchant would use:

• Add each section from the editor.
• Switch between showcases.
• Edit content and design settings.
• Reorder deck cards.
• Change global theme colors, fonts, and text sizes.
• Check storefront pages after saving changes.

The local preview page links to the Chrome Web Store extension when you run crane preview.

Use Separate Test and Publishing Apps

Maintain two Lightspeed apps:

• A test app for development and validation.
• A publishing app for the version merchants use.

This separation matters because blueprint changes can propagate to every live site using the theme. If a deployed update breaks a header, product layout, or global section, merchants using that theme can be affected immediately.

Use the test app first:

// crane.config.json for the test app
{
  "app_client_id": "test-app-client-id",
  "app_secret_key": "test-app-secret"
}

After validation passes, switch to the publishing app credentials and deploy:

// crane.config.json for the publishing app
{
  "app_client_id": "publish-app-client-id",
  "app_secret_key": "publish-app-secret"
}

Keep both config files out of Git. If your team stores examples, commit only placeholders such as crane.config.example.json.

Understand Package Version Scope

Crane uses the version field in package.json during deployment. The CLI reports the deployed app version and increments the patch version after a successful deploy.

This is not a merchant-facing version selector. Merchants do not choose a Crane theme version at install time, and the platform does not provide a formal merchant-level versioning mechanism for these blueprint updates.

Use the package version as an internal deployment marker, not as a promise that merchants can pin or roll back to a specific version.

Use Git for Every Theme

Keep the theme in Git from the beginning. Build and deployment hygiene depends on being able to review changes, compare releases, and recover from bad deployments.

Commit:

• Source files.
• package.json and lockfile changes.
• Preview and cover assets.
• Documentation needed to run and validate the theme.

Do not commit:

• crane.config.json.
• dist/.
• preview/.
• node_modules/.
• Local editor files.

Pre-Deployment Checklist

• Crane packages are pinned in package.json.
• Dependencies and lockfile are committed.
• crane.config.json is ignored and contains the intended app credentials locally.
• npm run lint passes.
• npm run build passes without validation errors.
• Every showcase renders in local preview.
• Home, custom, product, catalog, and category pages are checked.
• The theme is tested in the Instant Site Editor with Crane DevTools.
• Test app deployment is validated before publishing app deployment.
• package.json.version is understood as an internal deployment marker.