@lightspeed/crane

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!

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

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