Apply for App Market
Instant Site
Join Slack CommunityEmail us

Start building custom sections

Suggest Edits

Custom sections for Instant Site (later referred to as IS) are built locally and then deployed to the Ecwid environment. As a result, you don't need any live servers to host a section's code.

To help with the building process, Ecwid developed the @lightspeed/crane tool. Its main features are:

  • CLI commands for local development of sections and templates.
  • TypeScript support for building user settings UI.
  • Vue support for importing customer settings to the main section file.

Learn more about the section structure

To start working with custom sections:

  • Sign up with Ecwid and get a dev environment: a free store on a premium plan and a dev application.
  • Install Node.js and npm package to your machine.
  • Create a local project with the @lightspeed/crane tool.
  • Open the project folder in any suitable IDE and add your dev app settings to a config file.
  • Build section locally and deploy it to Ecwid.

After that, you'll be able to work on a section template in IDE locally and check it in your dev store with the Editor tools. Now, let's go through these steps in detail.

Step 1. Sign up with Ecwid

You need a store on any paid plan to start working with IS sections. Sign up with Ecwid

We will provide you with a free test store with API access if you:

  • Work on a storefront/Instant Site customization for one of our clients
  • Want to develop a public section or template for our App Market

Email us to get a test store.

If you already have a working store, you can safely build a section in a local environment and check how it works with Instant Site Editor (later referred to as Editor) without applying the changes. Preview mode in the Editor allows it.

Step 2. Set up an application

Building sections require authorization and access. In Ecwid, we have a platform where you can configure permissions called access scopes and authorize in different APIs. We refer to this platform as an application. A private application that gives access to your store API is called a custom application.

Set up a custom application in your Ecwid Control Panel, it only takes a few seconds: #develop-apps

Step 3. Get access scope

Access to building Instant Site sections requires the following scope: add_custom_blocks

Email us with your application name or client_id and a required scope, so we can update the app for you.

Step 4. Install Node.js and npm package

Building sections requires working with CLI (Command Line Interface). On MacOS it's called a Terminal, and on Windows, it's called Command Line.
If your CLI doesn't yet support npm/npx commands, install the required package from the Node.js official website.

Please make sure that your local node version matches the minimum version required by the crane tool. Check the node and npm version by running the following commands:

node -v
npm -v

If you see a response with an npm version like 10.7.0, proceed to the next step.

Step 5. Create a local project with the "@lightspeed/crane" tool

The crane is a CLI module crafted by Lightspeed to make an easy development flow for anyone who wants to build sections for Instant Site. It allows you to get a section template code showcasing recommended practices for setting up section content and design, and deploy section updates with a simple line of code in CLI. It will also help you with importing user settings to the section code.

The first step is to install all required modules, create a project folder, and get section template.

Code example:

'Create project folder'
mkdir {proj_folder}
cd ~/{proj_folder} 

'Install all required modules'
npm install vite
npm install vue
npm install @lightspeed/crane@latest
npm install @lightspeed/eslint-config-crane@latest

'Get section template with using @lightspeed/crane'
npx @lightspeed/crane@latest init --app custom-section

'Install additional dependency for the section template code'
cd custom-section
npm install -D sass

Now you have a project folder with all the required files and modules to start section development.

Step 6. Set up a project in IDE

We recommend using the free VS Code application with Vue and TypeScript extensions. However, you can use any other suitable IDE. Open the project folder there and check the file structure inside. Work with files inside the "sections" folder and set up the crane.config.json file once. All other project files are internal and should not be changed.

Open the crane.config.json file and paste settings from your dev application to the file. To get these settings, go to Ecwid admin > #develop-apps > Details, scroll down, and copy the "client_id" and "client_secret" values.

Code example:

{
    "app_client_id": "client_id",
    "app_secret_key": "client_secret"
}

Step 7. Deploy section template to Ecwid

Now you can start working with the section template. Let's skip the building part for now and deploy the example section to Ecwid as it is.

Make sure your application is installed in the Ecwid admin. To do so, go to Ecwid admin > My apps and check if your custom app is in the list. Then open CLI and run the build and deploy commands.

Code example:

$ cd ~/{proj_folder}/custom-section 'open project folder'
$ npx @lightspeed/crane@latest build 'build section on your local machine'
$ npx @lightspeed/crane@latest deploy 'deploy built section to Ecwid'

You should see a success message in CLI. After that, check the version in the 'package.json' file. You should see something like this:

{
  "name": "custom-section",
  "private": true,
  "version": "0.0.2",
  ...
}

Version value starts with the 0.0.1 and iterates with each successful deployment. Value from the 'package.json' file is the next deployment version. We recommend leaving it as it is.

Now you can go to Ecwid admin > Website > Edit site, and click the "Add section" button in the Editor. You'll find a deployed section at the bottom of the list. Add the section to your Instant Site and change its content and design settings to ensure everything works.

Updated 3 months ago