Ctrlk
Contact API support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

keyboard

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:

Example with no specified app name:

Create a New Section

Add a custom section to your application:

Working Directory

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

keyboard

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:

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

Create a new template

Working Directory

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

keyboard

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:

Build the Application

Build your application for deployment:

Creates dist and node_modules directories with compiled output.

Preview Locally

Start a local development server:

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:

Prerequisites

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

Get Help

Display available commands and options:

Configuration

crane.config.json

Configure your application credentials in crane.config.json:

sliders

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

2. Add Custom Templates

3. Add Custom Sections (Optional)

4. Configure Credentials

Edit crane.config.json:

5. Develop and Preview

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

6. Deploy

Troubleshooting

Build Failures

If the build command fails:

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:

Use Crane CLI in your project

PreviousMake your first template
NextDev recommendations

Last updated

Was this helpful?