App structure
To offer a better and more integrated development experience, apps created using Shopify CLI 3.x follow a conventional directory structure. This structure allows you to serve and deploy your app and its app extensions at the same time, and generate new app extensions easily.
Shopify CLI also manages any Node-based dependencies for you, including your Shopify CLI version. This leads to a consistent app development experience across environments.
Directory structure
Anchor link to section titled "Directory structure"All apps created with Shopify CLI follow the same basic directory structure. Some elements might be included or omitted depending on your app's functionality.
| File/directory | Required? | Description |
|---|---|---|
| shopify.app.toml | Yes | A file containing metadata and configurations for your project. This file represents the root of the app. |
| package.json | Yes | A file containing Node-specific metadata about your project. Includes project dependencies and scripts that let you run Shopify CLI commands using your package manager. Depending on your project structure or template, you might have additional `package.json` files in your project subfolders. |
| Web component directory (default: `web/`) | No | The recommended directory for the web components for your app. Use this directory if you want to build a web interface to display in the Shopify admin or Shopify POS using Shopify App Bridge. These components can be made up of one or more processes. |
extensions/ directory |
No | Any app extensions that you've generated in your app. Each directory under extensions/ represents an extension, where the extension's local identifier is the name of the directory.Each extension's directory must contain the appropriate configuration file for the extension type. |
| env | No | A file containing the UUIDs for your app and each extension in the app. |
Root configuration file
Anchor link to section titled "Root configuration file"shopify.app.toml is a configuration file that contains app-level configurations and metadata. This file also helps Shopify CLI determine whether the directory represents a Shopify app.
| Property | Required? | Description |
|---|---|---|
name |
Yes | The name of your app. |
scopes |
No | Any access scopes that you require for the parts of your app that are embedded in the Shopify admin or Shopify POS. |
extension_directories |
No | A list of glob patterns pointing to directories that contain extensions. |
web_directories |
No | A list of glob patterns pointing to directories that contain web components. Use this property to explicitly specify the directories to check for shopify.web.toml files. |
Web components
Anchor link to section titled "Web components"A directory containing the web components for your app. For new apps created with Shopify CLI 3.x, this directory is called web/. Use this directory if you want to build a web interface to display in the Shopify admin or Shopify POS using Shopify App Bridge.
The web interface can consist of one process or multiple processes. For example, you might have one process if you have a standard Rails app with an asset pipeline, or you might have multiple processes if your web app has independent frontend and backend stacks. To learn more about the conventions for single-process and multiple-process apps, refer to Web component conventions.
shopify.web.toml
Anchor link to section titled "shopify.web.toml"A configuration file where you can define properties for your embedded app. The location of this file identifies your web component directory to the CLI.
When you create an app using a template that contains an embedded app, the shopify.web.toml file is created in the web/ directory. If you choose to store your web components at the project root, or in another subdirectory, you need to include a shopify.web.toml in that directory instead.
If you need to override the build or dev command to build or preview your web app, then you can provide your own command at this level.
In projects where you want to serve the web backend and frontend through two processes, you can create a shopify.web.toml for each process. The CLI can start the two processes, and expects the frontend web HTTP server to forward the traffic to the backend process. To learn more, refer to Web component conventions.
To explicitly specify the folders where Shopify CLI should look for shopify.web.toml files, and to avoid files being loaded twice due to symlinks, use the web_directories variable in the shopify.app.toml file.
| Property | Required? | Description | Values |
|---|---|---|---|
type |
Yes | The role of the process in the directory. If your project uses only one process, then specify frontend. |
frontend, backend |
auth_callback_path |
No | Overrides the allowed redirection URLs set in the Partner Dashboard when you run your app. Use this property if your app uses a custom path to handle OAuth callbacks. You can specify a single path, or multiple paths separated by commas. | |
webhooks_path |
No | The root path for your app's webhook endpoints. If you run the dev command with a --reset flag, then Shopify CLI sends an UNINSTALLED webhook request for the selected store to this endpoint. If this value isn't set, then the default value of /api/webhooks is used. |
|
commands.build |
No | The command to build the app. This command is run when you run the Shopify CLI build command. It's executed from the configuration file's directory. |
|
commands.dev |
Yes | The command to serve the app. This command is run when you run the Shopify CLI dev command. This command is executed from the configuration file's directory. |
Web component conventions
Anchor link to section titled "Web component conventions"Shopify CLI builds and serves the various parts of your app using the following conventions, some of which use information that is defined in configuration files.
Single process or frontend process
Anchor link to section titled "Single process or frontend process"The following conventions apply to apps that run on a single process, such as standard Rails apps, and to the frontend process of apps that have both a frontend and backend process.
Configuration
Anchor link to section titled "Configuration"The CLI expects at least one shopify.web.toml configuration file, with a type of frontend. This file can be at the root of the project, or in a project subdirectory.
To explicitly specify the folders where Shopify CLI should look for shopify.web.toml files, and to avoid files being loaded twice due to symlinks, use the web_directories variable in the shopify.app.toml file.
Provided variables
Anchor link to section titled "Provided variables"The following information is provided to the process as environment variables:
SHOPIFY_API_KEY: The client ID of the app.SHOPIFY_API_SECRET: The client secret of the app.HOST/APP_URL: The URL that stores will load.PORT/FRONTEND_PORT/SERVER_PORT: The port in which the process’ server should run.SCOPES: The app's access scopes.BACKEND_PORT: The port in which the second, or backend, process will run if the app is a two-process app. The frontend uses 'BACKEND_PORT' to proxy traffic to the backend process.
Second process or backend process
Anchor link to section titled "Second process or backend process"The following conventions apply to the backend process of two-process apps.
Configuration
Anchor link to section titled "Configuration"The CLI expects a second shopify.web.toml configuration file in any subdirectory of the project, with a type of backend.
The frontend must proxy backend requests to the backend port defined in the environment variable BACKEND_PORT.
Provided variables
Anchor link to section titled "Provided variables"The following information will be provided as environment variables to the process:
SHOPIFY_API_KEY: The client ID of the app.SHOPIFY_API_SECRET: The client secret of the app.HOST: The URL that stores will load.SERVER_PORT/BACKEND_PORT/PORT: The port in which the process’s server should run.SCOPES: The app's access scopes.
The extensions/ directory contains any app extensions that you've generated onto your app, or that were included in your app template. If your app doesn't contain any app extensions, then you don't need this directory. You can add override the default directories using the extension_directories variable in shopify.app.toml.
Each extension is created in its own directory. The structure of the extension directory depends on the type of extension.
Shopify CLI builds and serves app extensions using information defined in TOML configuration files. Some extension types require specific configurations. To accommodate this, Shopify CLI groups extensions into three main categories, each using a unique TOML config file.
| Type | Supported extensions | TOML config file name |
|---|---|---|
| UI | Post-purchase UI, subscription UI, checkout UI, web pixel | shopify.ui.extension.toml |
| Function | cart and checkout validation, cart transform, delivery customization, fulfillment constraints, order discount, product discount, shipping discount, order routing location rule, payment customization | shopify.function.extension.toml |
| Theme | Theme app extension | shopify.theme.extension.toml |
UI extensions
Anchor link to section titled "UI extensions"Shopify CLI expects a shopify.ui.extension.toml configuration file to exist in the extension's directory.
Some extension types offer additional configuration options. Refer to the documentation for your extension type for more details:
| Property | Required? | Description |
|---|---|---|
type |
Yes | The type of extension.
|
name |
Yes | The name of the extension. |
Build and deploy process
Anchor link to section titled "Build and deploy process"The CLI builds UI extensions using ESBuild.It expects an extension script named index.{ts,js,tsx,jsx} to exist in the extension’s directory or the src/ subdirectory.
The CLI build process outputs the extension in dist/index.js when running build, and inside a temporary directory when running deploy to prevent past build artifacts from leaking into the deploy bundle.
Function extensions
Anchor link to section titled "Function extensions"The CLI expects a shopify.function.extension.toml configuration file to exist in the extension's directory. To learn about this file, refer to Function settings.
Build and deploy process
Anchor link to section titled "Build and deploy process"The CLI runs the command specified in the build.command attribute of the configuration file. It expects the output wasm file to be at dist/index.wasm, unless a different path is set in the build.path attribute.
Functions are only built on deployment.
Theme extensions
Anchor link to section titled "Theme extensions"Shopify CLI expects a shopify.theme.extension.toml configuration file to exist in the extension's directory.
| Property | Required? | Description |
|---|---|---|
type |
Yes | The type of extension. The only valid value is theme. |
name |
Yes | The name of the extension. |
Build and deploy process
Anchor link to section titled "Build and deploy process"When building, the CLI runs Theme Check against the theme app extension.
Extension type values
Anchor link to section titled "Extension type values"The following extension types map to the following extension type values in the extension TOML file:
| Extension type | Category | type value in the TOML file |
|---|---|---|
| Checkout UI | UI | checkout_ui |
| Post-purchase UI | UI | post_purchase_ui |
| Subscription UI | UI | subscription_ui |
| Web pixel | UI | web_pixel |
| Theme app extension | theme | theme_app_extension |
| Cart and checkout validation | function | cart_checkout_validation |
| Cart transform | function | cart_transform |
| Delivery customization | function | delivery_customization |
| Order discount | function | order_discount |
| Product discount | function | product_discount |
| Shipping discount | function | shipping_discount |
| Order routing location rule | function | order_routing_location_rule |
| Payment customization | function | payment_customization |
| Fulfillment constraints | function | fulfillment_constraints |
Dependency management
Anchor link to section titled "Dependency management"Shopify CLI uses a package.json file at the root of the app project to manage all of the dependencies required by Shopify to load, build, and publish your app.
The following dependencies are included in all apps:
@shopify/app: Manages all of the dependencies required to build and run a Shopify app and any CLI-managed app extensions.@shopify/cli: The current version of Shopify CLI.
We recommend including the lock file generated by the package manager (yarn.lock, package-lock.json, or pnpm-lock.yaml) in the repository to ensure the same version of these dependencies is used consistently across environments.
Adding your own dependencies
Anchor link to section titled "Adding your own dependencies"We recommend having a single source of truth for dependencies, in the form of a package.json at the root of your project. Alternatively, you can use your dependency manager’s workspaces functionality to store multiple package.json files at multiple levels of the project. Depending on your project structure or template, you might have additional package.json files in your project subfolders.