# Crane

### Preface

Crane is a command line interface that aids the creation, build and deployment of fully customisable website components (so-called sections)
within the Lightspeed E-Commerce ecosystem.

### Glossary

- Custom application: a small project that defines the boundaries of custom building-blocks that belong to one particular topic.
- Custom section: smallest building block to define a particular custom functionality.
- Default section: existing building block within the Lightspeed E-Commerce product.
- Settings
    - Content: configuration regarding the content of a custom section, e.g.: titles, buttons and texts.
    - Design: similarly, the design aspects of a custom section configuration, e.g.: colours and font size.
- Showcase: the highlight of a custom section with very specific configuration values.

### Prerequisites

In order to use this utility, first a Lightspeed specific application needs to be created containing the necessary
permissions granted, as well as an optional test site in order to verify the changes made in a custom application.

```For both the test site and the permission, please contact your Partner Manager!```

### Recommended Node.js Version

For the best compatibility and performance, it is recommended to use **Node.js 22.x**

### Installation

The following commands need to be performed to install the required dependencies and Crane utility, along with our linter:
```
npm install vite
npm install vue
npm install @lightspeed/crane@latest
npm install @lightspeed/eslint-config-crane@latest
```

### Commands

```
npx @lightspeed/crane@latest init --app <name>
```
Creates an application folder inside the current directory with default resources (configuration, assets and JS files).
By default, there is one custom section located in the folder "sections" named "example-section".

```
npx @lightspeed/crane@latest init --section <name>
```
Creates an additional custom section. The command will create files necessary for this section and locate them in
folder "sections" under the directory with the given name.

```
npx @lightspeed/crane@latest build
``` 
Builds the application. Upon a successful build, the following directories can be located inside the application folder: ```dist``` and ```node_modules```.
A prompt describing the next steps will be shown.

```
npx @lightspeed/crane@latest preview
``` 
Builds the application and starts a development server for local preview. A prompt pointing to the preview URL will be shown in the terminal, which can be accessed in a browser.
This command needs to be run only once, after a consecutive build and refresh of the preview browser window, the changes will be visible without the need to run this command again.

```
npx @lightspeed/crane@latest deploy
```
Deploys the application to the Lightspeed E-Commerce platform.

```
npx @lightspeed/crane@latest --help
```
Displays list of available commands, resource descriptions and actions.

### Example

The following example will demonstrate how to create a custom application with 2 sections and to deploy it to
Lightspeed E-Series, provided the necessary prerequisites are fulfilled.

1. Initialization of the application with the name: 'my-app'
```
npx @lightspeed/crane@latest init --app my-app
```
2. Switching the directory
```
cd my-app
```
3. Creation of additional custom sections, in case it is necessary. **Optional**
```
npx @lightspeed/crane@latest init --section my-section
```
4. Editing ```crane.config.json```

In order to successfully deploy a custom application, its credentials are need to be specified.
This can be done by specifying the proper ```client_id``` and ```client_secret``` in ```crane.config.json```, located in the root of the custom application.
```json
{
  "app_client_id": "{client_id}",
  "app_secret_key": "{client_secret}"
}
```
5. Building the application
```
npx @lightspeed/crane@latest build
```
6. Deploying the application
```
npx @lightspeed/crane@latest deploy
```

### Common issues and remedies

1. In case of a failed build command execution, the following action needs to be
   performed, followed by a repeat execution of said command:
```
npm install
```

2. HTTP 401 during deployment:
   Invalid credentials provided, please verify that the ```crane.config.json``` file is correct.

3. HTTP 403 during deployment:
   Insufficient permissions, please contact your Partner Manager regarding the necessary permissions.

### More information

For more information regarding the notable changes for each versioned release and the upgrade guide, please refer to the following files:

- [CHANGELOG](CHANGELOG.md)
- [UPGRADE](UPGRADE.md)

Note: for visitors through the `npmjs.com` site, please refer to the individual files in the `Code` tab of the package repository, as the links above will not work.
