> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/site-themes/develop-site-themes/dev-recommendations/build-validation-and-deployment.md).

# 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 **must 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.

```json
{
  "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:

```json
{
  "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:

```bash
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:

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

```bash
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:

```bash
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:

```jsonc
// 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:

```jsonc
// 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/dev-recommendations/build-validation-and-deployment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.