App structure
When you use SHOPLINE CLI to create an app, a standard directory structure is generated. This app structure enables you to develop and configure apps more efficiently and conveniently.
Directory structure
After initiating the app with CLI, you will get the following project directory 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
The following table demonstrates and explains the main project directories and files.
| File/Directory | Description |
|---|---|
| shopline.app.toml | Contains app-related configurations. Refer to shopline.app.toml for configuration instructions. |
| shopline.web.toml | Contains configurations for the app development. Refer to shopline.web.toml for configuration instructions. |
| package.json | Contains dependencies for app development and various development commands. |
| app/** | Contains the app's backend development files. |
| web/** | Contains the app's frontend development files. |
Main configuration files
shopline.app.toml
The shopline.app.toml file contains app-related configurations. After you start the app with the CLI, the CLI will update the configuration from the project to the Partner Portal.
The following table demonstrates the file configuration properties.
| Property | Type | Required or not | Description |
|---|---|---|---|
| appName | string | No | The app name. |
| appKey | string | No | The unique identifier for the app, obtained from the Partner Portal. |
| appUrl | string | No | The URL used to preview the app. |
| appCallbackUrlList | string[] | No | A list of app callback URLs, used for redirection after app authorization is complete. |
| scopes | string | Yes | The scope of access to store resources, represented by permission points. If you apply for multiple permissions, use commas to separate permission points, such as read_products, read_orders. |
The following example shows a sample configuration for the shopline.app.toml file.
appName = "shopline-app-template"
appKey = "b54f8adfeee2722203bb462a1045b773f3d51510d86"
appUrl = "https://volkswagen-quantitative-continuous-timing.trycloudflare.com"
appCallbackUrlList = [
"https://volkswagen-quantitative-continuous-timing.trycloudflare.com/api/auth/callback"
]
[access_scopes]
scopes = "write_products"
shopline.web.toml
The shopline.web.toml file contains app development configurations. When you start the app, the CLI will read all shopline.web.toml files in the project and execute the script commands specified under the commands configuration.
For example, if you are a Node.js developer and have set the command yarn run dev under commands.dev, the CLI will execute yarn run dev via the shell to start the process when you start the app, and add the process variables to the process. For more information about processes and process variables, refer to Process conventions.
The following table demonstrates the file configuration properties.
| Property | Type | Required or not | Description |
|---|---|---|---|
| type | backend| frontend | Yes | The type of the server |
| commands.dev | string | Yes | The startup command |
| command.build | string | No | The command to build the app |
The following example shows the frontend configuration sample from the shopline.web.toml file.
type="frontend"
[commands]
dev = "npm run dev"
build = "npm run build"
The app directory structure includes two shopline.web.toml configuration files: one for the Node.js backend and another for the React frontend. The CLI will scan these two files and simultaneously start two processes, assigning BACKEND_PORT and FRONTEND_PORT to them. The frontend uses Vite to proxy traffic to the backend process.
Process conventions
When starting the app, the CLI retrieves the app configuration information stored in the Partner Portal and passes some of the information as environment variables to the startup process.
The CLI identifies the process type as either backend or frontend by recognizing the type property in the shopline.web.toml configuration file, and then build the service accordingly.
Frontend process
To configure the frontend service, ensure to set the type property to frontend in a shopline.web.toml configuration file. It is recommended to place the configuration file in the <App Name>/web/ directory.
When starting the service, the CLI will read the frontend port number based on the type configuration and use it to establish an external access URL. Additionally, the CLI will generate the necessary environment variables to start the frontend process.
Environment variables
SHOPLINE_APP_KEY: The unique identifier for the app, obtained from the Partner Portal.SHOPLINE_APP_SECRET: The app secret used to generate and verify request signatures, obtained from the Partner Portal.SCOPES: The scope of access to store resources, represented by permission points.SHOPLINE_APP_URL: The URL used to preview the app.BACKEND_PORT: The backend service port number.
Backend process
To configure the backend service, ensure to set the type property to backend in a shopline.web.toml configuration file. It is recommended to place the configuration file in the <App Name>/app/ directory.
Environment variables
SHOPLINE_APP_KEY: The unique identifier for the app, obtained from the Partner Portal.SHOPLINE_APP_SECRET: The app secret used to generate and verify request signatures, obtained from the Partner Portal.SCOPES: The scope of access to store resources, represented by permission points.SHOPLINE_APP_URL: The URL used to preview the app.FRONTEND_PORT: The frontend service port number.
