Quickstart: guide to a working Instant Site template

In the following guide, you’ll start by signing up with Ecwid and will end up with a fully working Instant Site template code deployed to your test store.

You need a good knowledge of Typescript and its Vue framework to build templates. Custom templates for Instant Site are built locally and then deployed to the Ecwid environment. After deploying, you can find and install your template in the Instant Site Editor. With any deployed changes, you need to reinstall the template to apply them.

Step 1. Sign up with Ecwid

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

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

• Work on an 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 templates in a local environment and check them with Instant Site Editor without applying any changes. Preview mode in the Editor allows it.

Step 2. Set up an application

Working with Instant Site templates requires authorization and access to Ecwid API. We have a platform called application where you can configure permissions called access scopes and authorize different APIs. A private application that gives access to your store API only is called a custom application.

Set up a custom application for your Ecwid store right from the admin, it only takes a few seconds: #develop-apps

Step 3. Get access scope

With the app, you can access store data with API. However, you need to request additional permissions to build Instant Site templates: add_custom_blocks and add_custom_templates.

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

Step 4. Install Node.js and npm package

Use CLI (Command Line Interface) to deploy the template code to Ecwid. 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

We recommend using at least version 10.7.0 to avoid any npm-related issues.

Step 5. Start a local project with the Crane tool

Crane is a CLI tool for developing Instant Site templates. Learn more about the Crane tool

With Crane, you can get a working template project and control it with CLI. Use the following commands to set up a project folder, install all dependencies, and get the example template code:

'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 full template example using @lightspeed/crane'

npx @lightspeed/crane@latest init --app
npx @lightspeed/crane@latest init --template example-template
npx @lightspeed/crane@latest init --section example-section

'Install additional dependency for the section template code'


cd example-section
npm install -D sass

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

Step 6. Set up a project in IDE

We recommend using the free VS Code application with Vue and TypeScript extensions. Open the project folder there and check the file structure inside. Learn more about the structure

First, you need to set up the crane.config.json file, it will connect the templates you build locally with the application on our side. Open it and copy the client_id and client_secret from your custom application to the file. Find these values at the bottom of the Ecwid admin > #develop-apps > Details page.

After the changes, your file should look like this:

{
    "app_client_id": "custom-app-15695068-1",
    "app_secret_key": "HHLmjx1NQropDPrC5Uzx2BMoUQo4esEmr"
}

Step 7. Deploy section template to Ecwid

From this point, you can start developing custom templates. To start, deploy the example template to Ecwid as it is.

To do so, make sure your application is installed in the Ecwid admin. Go to Ecwid admin > My apps and check if your custom app is listed there. After that, run the build and deploy commands in CLI.

Code example:

'Open project folder'
$ cd ~/{proj_folder}/custom-section

'Build section on your local machine'
$ npx @lightspeed/crane@latest build

'Deploy built section to Ecwid'
$ npx @lightspeed/crane@latest deploy

You should see a success message in CLI. Email us with details about your application and store if you have any errors in this step.

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 0.0.1 and iterates automatically with each successful deployment. Value from the 'package.json' file is the next deployment version. Do not edit it manually.

Now you can find your custom template in the Instant Site Editor in your Ecwid admin. Go to Settings > Templates in the top left Editor menu.