Crane

$3

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.

$3

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

$3

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!`

$3

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

$3

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
`

$3

`
npx @lightspeed/crane@latest init --app
`
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
`
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.

$3

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
`

$3

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.

$3

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

- CHANGELOG
- UPGRADE

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.