Make your first section

With Crane framework, you can build and deploy 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 app-name

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:

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

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

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

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

Want to know more about Crane CLI commands?

Jump into Deep dive into Crane CLI

# 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 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)

Learn more

• Sections — Master your knowledge on section components and configurations

• Section Collections — Create redistributable section packages