Migrate your app to SHOPLINE CLI​

To enhance development efficiency and experience, we recommend using the SHOPLINE CLI to develop your app. The SHOPLINE CLI allows you to quickly log in to the Partner Portal, synchronize app-related settings in the Partner Portal, and easily manage app configurations within your local project.

If this is your first time developing a SHOPLINE app, follow the Build apps using SHOPLINE CLI guide directly, without needing to read the content below.

For apps that are already live or under development, we strongly encourage you to migrate to the SHOPLINE CLI as described in this guide to benefit from a more streamlined development process.

CLI advantages​

Using the SHOPLINE CLI to build your app offers the following advantages:

• Unified configuration file management: Utilizes the simple and clear TOML format for configuration files, making it easier to manage app settings.
• Standardized app structure: Constructs a clear, standard app structure, simplifying integration and development.
• Local preview and debugging: Supports commands for local preview and debugging, allowing you to observe real-time effects and quickly identify issues, accelerating development iterations.

How to migrate​

Step 1: Standardize app structure​

- <App Name>
  |-- app			         # Backend development directory
      └──shopline.web.toml	 # Backend development configuration file
  |-- web                    # Frontend development directory
      |-- src
      └── shopline.web.toml	 # Frontend development configuration file
  |-- package.json           # Project metadata and dependencies 
  |-- shopline.app.toml      # App configuration file

Develop your app using the standard directory structure above to maintain project scalability. Key directories:

• app: Contains backend files.
• web: Contains frontend files.

If your project does not yet have the shopline.app.toml or shopline.web.toml files, you can create them as follows:

• In the <App Name> directory, create a shopline.app.toml file to store app-related configurations.
• In the <App Name>/app/ and <App Name>/web/ directories, create shopline.web.toml files to configure development-related startup and build commands. For more understanding about different shopline.web.toml files, refer to App structure.

Step 2: Create configuration files​

Configuration files are an essential part of app development. They define key configurations such as startup commands, dependencies, and environment variables.

This section explains how to create and configure the necessary TOML files to ensure that the CLI reads the configurations correctly and starts the app smoothly.

App configuration​

The shopline.app.toml file contains app-related configurations. Create this file in the root directory of your app and configure it as follows. The scopes property is required for this configuration file. If you apply for multiple permissions, use commas to separate permission points, such as read_products, read_orders.

[access_scopes]
scopes = "write_products"

Startup configuration​

The shopline.web.toml file is a configuration file required for starting an app. Set configurations for backend and frontend processes in the following directories:

• Backend: Create a shopline.web.toml file in the <App Name>/app/ directory.
• Frontend: Create a shopline.web.toml file in the <App Name>/web/ directory.

The CLI executes the startup commands based on the following logic:

Frontend configuration​

Node.js handles the configuration for starting the web frontend. Regardless of whether you choose Webpack, Vite, Rspack, or any other build tool, you can run the run start or run dev command through npm. The CLI will determine the startup command based on the scripts configured in your package.json file. Refer to the following for the frontend configuration.

type="frontend"
[commands]
dev = "npm run dev"
build = "npm run build"

Backend configuration​

Since the backend language can vary, you need to tailor the shopline.web.toml configuration file based on the language you use. The following examples show how to configure the file for both Node.js and Golang.

• Node.js

type="backend"
[commands]
dev = "npm run dev"
build = "npm run build"

• Golang

type="backend"
[commands]
dev = "go run main.go"
build = "go build"

Step 3: Install dependencies​

After migrating the configuration files, create a new package.json file in the root directory. The package.json file includes the dependencies for app development and various development commands.

Configure the file according to the sample provided below.

{
  "name": "shopline-app-template",
  "version": "1.0.0",
  "scripts": {
    "shopline": "shopline",
    "build": "shopline app build",
    "dev": "shopline app dev",
    "dev:reset": "shopline app dev --reset",
  },
  "dependencies": {},
  "author": "SHOPLINE",
  "devDependencies": {
    "@shoplinedev/app": "2.1.0",
    "@shoplinedev/cli": "2.1.0"
  }
}

Then, run the following command in the root directory to install the dependency.

npm install

In addition to installing dependencies in the root directory, you will typically need to install necessary dependencies for respective development languages in <App Name>/app/ and <App Name>/web/. You can refer to the official documentation for yarn, pnpm, and other dependency managers for configuration guidance.

Step 4: Start your app​

After installing dependencies, start your app by running the following command:

npm run dev

The CLI will create a tunnel URL, which will be automatically updated to the Partner Portal as the app's preview URL.

If no errors occur, you will see the preview URL as shown in the above picture, indicating that you have successfully completed the migration. You can click the link to preview whether the app meets your expectations.