Deep dive into Crane CLI

Crane is a command line interface for creating, building, and deploying custom sections within the Lightspeed E-Commerce ecosystem.

Follow this article to learn all CLI features provided by this tool.

Prerequisites

Before using Crane CLI, you need:

1. Node.js 22.x - Recommended for best compatibility

2. Lightspeed Application - Contact your Partner Manager for:

   • Application credentials (client ID and secret)

   • Test site access for verification

   • Required permissions

Installation

Install Crane and its dependencies in your project:

npm install vite vue @lightspeed/crane@latest @lightspeed/eslint-config-crane@latest

Commands

Find a list of available Crane CLI commands below.

To push changes to Ecwid:

Call build and deploy commands every time you need to push some changes into your Crane app.

Initialize a New Application

Create a new Crane application:

npx @lightspeed/crane@latest init --app app-name

Interactive Prompt

If you omit the app-name, you'll be prompted to enter it interactively.

This creates:

• Application folder with default resources

• Configuration files

• Assets and TypeScript files

• One example section in sections/example-section

Example with specified app name:

npx @lightspeed/crane@latest init --app my-app
cd my-app

Example with no specified app name:

npx @lightspeed/crane@latest init --app
## Please specify a name for your app: ›

Create a New Section

Add a custom section to your application:

Working Directory

Run this command from your application folder (created with init --app).

npx @lightspeed/crane@latest init --section section-name

Interactive Prompt

If you omit the section-name name, you'll be prompted to enter it interactively.

Creates section files in sections/<section-name> directory.

Example:

npx @lightspeed/crane@latest init --section my-custom-section

By providing the --blank flag, you can create a section with the minimum required files for the section to work.

npx @lightspeed/crane@latest init --section my-custom-section --blank

Create a new template

Working Directory

Run this command from your application folder (created with init --app).

npx @lightspeed/crane@latest init --template template-name

Interactive Prompt

If you omit the template-name name, you'll be prompted to enter it interactively.

Creates section files in sections/<template-name> directory.

Example:

npx @lightspeed/crane@latest init --section my-custom-template

Build the Application

Build your application for deployment:

npx @lightspeed/crane@latest build

Creates dist and node_modules directories with compiled output.

Preview Locally

Start a local development server:

npx @lightspeed/crane@latest preview

Features:

• Opens preview URL in your terminal

• Hot reload - build once, refresh browser to see changes

• No need to restart after subsequent builds

Deploy to Lightspeed

Deploy your application to production:

npx @lightspeed/crane@latest deploy

Prerequisites

Ensure crane.config.json is properly configured before deploying.

Get Help

Display available commands and options:

npx @lightspeed/crane@latest --help

Configuration

crane.config.json

Configure your application credentials in crane.config.json:

{
  "app_client_id": "{your_client_id}",
  "app_secret_key": "{your_client_secret}"
}

Find the client_id and client_secret values for your custom application to the file. Find these values at the bottom of the Ecwid admin > #develop-apps > Details page.

Keep Credentials Safe

Never commit crane.config.json with real credentials to version control. Add it to .gitignore.

Complete Workflow Example

Here's a typical workflow for creating and deploying a Crane application:

1. Create Application

npx @lightspeed/crane@latest init --app my-store-app
cd my-store-app

2. Add Custom Templates

npx @lightspeed/crane@latest init --template custom-template

3. Add Custom Sections (Optional)

npx @lightspeed/crane@latest init --section product-showcase
npx @lightspeed/crane@latest init --section custom-cart

4. Configure Credentials

Edit crane.config.json:

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

5. Develop and Preview

# Build your application
npx @lightspeed/crane@latest build

# Start preview server
npx @lightspeed/crane@latest preview

Open the preview URL in your browser and test your sections.

6. Deploy

npx @lightspeed/crane@latest deploy

Troubleshooting

Build Failures

If the build command fails:

npm install
npx @lightspeed/crane@latest build

HTTP 401 Error During Deployment

Cause: Invalid credentials

Solution: Verify crane.config.json has correct app_client_id and app_secret_key

HTTP 403 Error During Deployment

Cause: Insufficient permissions

Solution: Contact your Partner Manager to grant the necessary permissions

Preview Not Working

Cause: Build artifacts are missing or outdated

Solution:

npx @lightspeed/crane@latest build
npx @lightspeed/crane@latest preview

Use Crane CLI in your project

• Install Crane to your system

• Start with Crane app