Build apps using SHOPLINE CLI
The SHOPLINE CLI is a command-line tool tailored for SHOPLINE developers, streamlining project initialization, local development, and deployment workflows. It encompasses functionalities such as local app configuration, development store association, local project preview, and app debugging.
This document will guide you on how to use the SHOPLINE CLI to build apps.
App creation
Step 1: Set up the environment
Before you begin, ensure that your development environment meets the following requirements to facilitate smooth app development:
- A partner account and a development store have been created.
- Node.js is installed, with version 18.0 or higher.
- A package manager, such as npm, is installed.
- Git version control tool is installed.
- A browser is downloaded. We recommend using the latest version of Chrome.
Step 2: Initialize the app
When initializing your app, choose one of the following package managers: npm, yarn, or pnpm, and follow these steps:
- Navigate to the target directory where you want to install the app.
- Run the following command to initialize the app:
npm create @shoplinedev/app@next
- Enter the name of your app development project. For example, if you enter
Shopline App, it will be converted toshopline-app.
The initialization process may take some time because necessary project dependencies need to be downloaded. To accelerate initialization, you can use the dev --skip-dependencies-installation command to skip downloading dependencies. However, you need to manually download the dependencies later.
After the app project is successfully initialized, a standard app structure is generated in your project directory. Develop your app based on this app structure.
Step 3: Start the local server
The SHOPLINE CLI uses cloudflared to proxy your local development services, allowing you to debug and preview your app in the development store. Start your app's local development server by the following steps:
- Navigate to the target app directory.
cd shopline-app
- Execute the local start command.
npm run dev
After completing the above commands, follow the SHOPLINE CLI's instructions to proceed with the following steps:
- Log in to the Partner Portal.
- Select a partner account.
- Choose the app you want to manage.
- If the app is not found, the CLI will assist you in creating a new one.
- Select and associate the target development store.
If your app is already published on the SHOPLINE App Store, you cannot start it locally. This is because SHOPLINE CLI prevents developers from directly updating published apps in a production environment to avoid potential negative impacts. To continue local development, you can use the dev --reset command to reset the app's local cache data and create a new local development instance.
Step 4: Install the app
After starting the development service, the SHOPLINE CLI will generate a preview link for the app and guide you to install the app in the associated development store. If the app is already installed in the development store, the installation step will be skipped and you can directly preview your app.
Click the preview link or copy and paste it into your browser, and then you will see the following authorization and installation interface. Click Authorize and install to install and preview your app.
When you see the following interface, it means the app has been successfully created and installed. You can click Create Product to verify whether the app can properly invoke the SDK functions integrated with the app. If everything works correctly, you can continue local development in the current environment.
CLI commands for building apps
By following the above steps, you can successfully create and start a local app development service. Additionally, you can use the following SHOPLINE CLI commands for further app development.
| Command | Description |
|---|---|
| dev | Used to start app-related services |
| build | Used to compile and package app development resources |
| config | Used to manage app configuration information |
dev
Use the dev command to start local development services, including both frontend and backend. This command will start the services and generate a link for previewing the app locally.
When you run the dev command, the following steps are performed by default:
cloudflaredproxies local services and creates a tunnel URL for external access.- Update the app URL, callback URL, and other information for the remote app.
- Update the local TOML configuration file synchronously.
| Command | Flag | Description |
|---|---|---|
| dev | --reset | Reset the app's configuration. For example, reselect the partner, app, and associated development store. |
| --tunnel-url | Set the app address for the proxy. By default, the CLI automatically generates the tunnel URL. If you need to use a custom local address for the proxy, you can specify it using this command. | |
| --skip-dependencies-installation | When running npm create @shoplinedev/app, all necessary libraries are installed locally by default. You can use this command to skip the installation of app dependencies. npm install to install dependencies.package.json, run npm install again to install these new libraries. |
Command example
The following command shows an example of setting an app address for proxy.
npm run dev --tunnelUrl=https://{handle}.myshopline.com
config
The config command is used to update local and remote app configurations, and to switch between configurations as needed locally. When you execute this command, it generates corresponding TOML files locally.
For example, when you use the link command to associate a local app with a remote app, a shopline.app.{appName}.toml file is generated.
| Command | Flag | Description |
|---|---|---|
| config | link | Retrieve the full list of apps from the Partner Portal, connect to the target app, and generate the corresponding configuration files. Existing files will be overwritten. |
| push | Push the local TOML configuration to the remote server. | |
| use | Choose the TOML configuration file to use. |
Command example
The following command shows an example of choosing the TOML configuration file to use.
shopline app config use
# All available TOML configuration files are listed for selection.
# ·shopline.app.appOne.toml
# ·shopline.app.appTwo.toml
# ·shopline.app.appThree.toml
# ·shopline.app.appFour.toml
- When you use the
linkcommand to associate a remote app namedappOnewith a local app namedappTwo, the SHOPLINE CLI will handle the configuration file as follows:- If a configuration file named
shopline.app.appTwo.tomlalready exists locally, it will be overwritten with the new configuration. - If the file does not exist, a new configuration file named
shopline.app.appTwo.tomlwill be created.
- If a configuration file named
- When executing the
push,link, orusecommands, if you encounter a permissions issue with your current partner account, ensure you are using the correct partner account. Switch to the partner account that matches the current developing app and try executing the command again.
build
The build command is used to compile the app's frontend and backend resources. After executing this command, it will automatically perform packaging and create a dist folder in a specified directory to store the compiled static files. Subsequently, this compiled version is ready for immediate deployment to the production environment.
Command example
npm run build
