CLI Usage

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

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

Initialize a New Application

Create a new Crane application:

npx @lightspeed/crane@latest init --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:

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

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 <name>

ℹ️ Interactive Prompt

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

Creates section files in sections/<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

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}"
}

🚨 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 necessary permissions

Preview Not Working

Cause: Build artifacts missing or outdated

Solution:

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

Project Structure

A typical Crane application structure:

my-app/
├── crane.config.json      # Application credentials
├── package.json           # Node.js dependencies
├── sections/              # Custom sections
│   ├── example-section/   # Default example section
│   └── my-section/        # Your custom sections
├── headers/               # Custom header components
│   └── example-header/    # Your custom header
├── footers/               # Custom footer components
│   └── example-footer/    # Your custom footer
├── preview/               # Local development preview server
│   ├── sections/          # Section preview setup
│   ├── shared/            # Shared preview utilities
│   ├── ssr-server.ts      # SSR server for local testing
│   └── vite.config.js     # Vite configuration for preview
├── shared/                # Shared components and utilities
├── dist/                  # Built output (generated)
└── node_modules/          # Dependencies (generated)

Glossary

• Custom Application: Project defining boundaries of custom building blocks for a specific topic
• Custom Section: Essential building block for custom functionality
• Default Section: Existing building block in Lightspeed E-Commerce
• Content Settings: Section configuration for content (titles, buttons, texts)
• Design Settings: Section configuration for design (colors, font sizes)
• Showcase: Section highlight with specific configuration values
• Section layout: Configuration for section placement and arrangement
• Storefront: The storefront is the public-facing part of your e-commerce website where customers can browse products, add them to their cart, and complete transactions.
• Slot: A slot is a placeholder for a custom section in a storefront layout
• Storefront layout: The layout of a storefront page

Next Steps

• Learn about UI Composables
• Getting Started Guide

Version Information

• Check the npm package for latest version and changelog
• CHANGELOG and UPGRADE guides are included in the npm package