---
title: "App structure"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/docs/apps/development-tool/shopline-cli/app-structure'
  md: 'https://developer.shopline.com/docs/apps/development-tool/shopline-cli/app-structure.md'
---
# App structure

When you use [SHOPLINE CLI to create an app](https://developer.shopline.com/docs/apps/development-tool/shopline-cli/build-apps-using-shopline-cli.md), a standard directory structure is generated. This app structure enables you to develop and configure apps more efficiently and conveniently. 


## Directory structure 

Execute the following command to initialize the project   
```shell
npm create @shoplinedev/app
```

After [initiating the app with CLI](https://developer.shopline.com/docs/apps/development-tool/shopline-cli/build-apps-using-shopline-cli.md?lang=en), you will get the following project directory structure. 

```bash
 - <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](#app) for configuration instructions.  |
| shopline.web.toml | Contains configurations for the app development. Refer to [shopline.web.toml](#web) 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{#app}
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](https://developer.myshopline.com/home/index). 

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](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). 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. 

```toml
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{#web}
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](#process). 

The following table demonstrates the file configuration properties. 

| **Property** | **Type** | **Required or not** | **Description** |
| --- | --- | --- | --- |
| type | `backend`&#124; `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. 

```bash
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{#process}
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](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). 
- `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](https://developer.shopline.com/docs/apps/api-instructions-for-use/access-scope.md). 
- `SHOPLINE_APP_URL`: The URL used to preview the app. 
- `FRONTEND_PORT`: The frontend service port number.