# Make your first section

With **Crane** framework, you can build and deploy [**custom sections**](/site-themes/develop-site-themes/getting-started/crane-overview.md#glossary) within the Lightspeed E-Commerce ecosystem.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

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 <a href="#installation" id="installation"></a>

Install Crane and its dependencies in your project:

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

### Commands <a href="#commands" id="commands"></a>

#### Initialize a New Application <a href="#initialize-a-new-application" id="initialize-a-new-application"></a>

Create a new Crane application:

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

{% hint style="info" icon="keyboard" %}
If you omit the `app-name`, you'll be prompted to enter it interactively.
{% endhint %}

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:**

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

**Example with no specified app name:**

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

#### Create a New Section <a href="#create-a-new-section" id="create-a-new-section"></a>

Add a custom section to your application:

{% hint style="info" icon="folder" %}
Run this command from your application folder (created with `init --app`).
{% endhint %}

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

{% hint style="info" icon="keyboard" %}
If you omit the `section-name`, you'll be prompted to enter it interactively.
{% endhint %}

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

**Example:**

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

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

#### Build the Application <a href="#build-the-application" id="build-the-application"></a>

Build your application for deployment:

```bash
npx @lightspeed/crane@latest build
```

Creates `dist` and `node_modules` directories with compiled output.

#### Preview Locally <a href="#preview-locally" id="preview-locally"></a>

Start a local development server:

```bash
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 <a href="#deploy-to-lightspeed" id="deploy-to-lightspeed"></a>

Deploy your application to production:

```bash
npx @lightspeed/crane@latest deploy
```

{% hint style="warning" icon="sliders" %}
Ensure `crane.config.json` is properly configured before deploying.
{% endhint %}

#### Get Help <a href="#get-help" id="get-help"></a>

Display available commands and options:

```bash
npx @lightspeed/crane@latest --help
```

### Configuration <a href="#configuration" id="configuration"></a>

#### crane.config.json <a href="#crane-config-json" id="crane-config-json"></a>

Configure your application credentials in `crane.config.json`:

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

{% hint style="danger" %}
**Keep Credentials Safe**

Never commit `crane.config.json` with real credentials to version control. Add it to `.gitignore`.
{% endhint %}

### Complete Workflow Example <a href="#complete-workflow-example" id="complete-workflow-example"></a>

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

#### 1. Create Application <a href="#id-1-create-application" id="id-1-create-application"></a>

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

#### 2. Add Custom Templates <a href="#id-2-add-custom-templates" id="id-2-add-custom-templates"></a>

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

#### 3. Add Custom Sections (Optional) <a href="#id-3-add-custom-sections-optional" id="id-3-add-custom-sections-optional"></a>

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

#### 4. Configure Credentials <a href="#id-4-configure-credentials" id="id-4-configure-credentials"></a>

Edit `crane.config.json`:

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

#### 5. Develop and Preview <a href="#id-5-develop-and-preview" id="id-5-develop-and-preview"></a>

{% hint style="info" icon="book-open" %}
**Want to know more about Crane CLI commands?**

Jump into [Deep dive into Crane CLI](/site-themes/develop-site-themes/getting-started/deep-dive-into-crane-cli.md)
{% endhint %}

```bash
# 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 <a href="#id-6-deploy" id="id-6-deploy"></a>

```bash
npx @lightspeed/crane@latest deploy
```

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Build Failures <a href="#build-failures" id="build-failures"></a>

If the build command fails:

```bash
npm install
npx @lightspeed/crane@latest build
```

#### HTTP 401 Error During Deployment <a href="#http-401-error-during-deployment" id="http-401-error-during-deployment"></a>

**Cause:** Invalid credentials

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

#### HTTP 403 Error During Deployment <a href="#http-403-error-during-deployment" id="http-403-error-during-deployment"></a>

**Cause:** Insufficient permissions

**Solution:** Contact your Partner Manager to grant the necessary permissions

#### Preview Not Working <a href="#preview-not-working" id="preview-not-working"></a>

**Cause:** Build artifacts missing or outdated

**Solution:**

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

### Project Structure <a href="#project-structure" id="project-structure"></a>

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 <a href="#next-steps" id="next-steps"></a>

* [Sections](/site-themes/develop-site-themes/sections.md) — Master your knowledge on section components and configurations
* [Section Collections](/site-themes/develop-site-themes/sections/section-collections.md) — Create redistributable section packages


---

# Agent Instructions: 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:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/getting-started/make-your-first-section.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.