Migrate your app to Shopify CLI 3.x
To offer a better and more integrated development experience, apps created Shopify CLI 3.x follow a conventional directory structure, use simplified configuration files, and manage your Node-based dependencies for you.
If you have an app that was created using a previous version of Shopify CLI, or without Shopify CLI, then you can migrate your app so you can use the newest version of Shopify CLI. This process involves updating your app's dependencies, reorganizing your app's folder structure, and adding configurations that tell Shopify CLI how your app is organized.
Requirements
Anchor link to section titled "Requirements"What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn the following:
- How to create CLI-specific configuration files for your project
- How to add Shopify CLI as a project dependency and remove outdated dependencies
- How to migrate your app code
Benefits of migration
Anchor link to section titled "Benefits of migration"When you migrate your app to use Shopify CLI 3.x, you can take advantage of the following improvements to the developer experience:
Conventional directory structure
Anchor link to section titled "Conventional directory structure"To offer a better and more integrated development experience, apps built 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.
Simplified configuration files
Anchor link to section titled "Simplified configuration files"To make reading and editing configuration files easier, apps that use Shopify CLI 3.x use TOML instead of YAML. Only a small set of files and settings are required, so configurations can be made and tracked in fewer files, and fewer manual configurations need to be made.
Node runtime
Anchor link to section titled "Node runtime"The Shopify CLI 3.x is implemented in JavaScript to run in the Node runtime, more closely aligning the Shopify CLI and app development experience.
Project-scoped dependencies
Anchor link to section titled "Project-scoped dependencies"Previous versions of Shopify CLI were installed manually, and the same version was used across all Shopify app projects in an environment. This led to inconsistent results across environments caused by differing versions of the CLI.
Shopify CLI 3.0 is distributed in npm packages (@shopify/cli
and @shopify/app
), which can be listed as dependencies of your project in a package.json
at the project root. Specifying these packages as dependencies leads to a consistent development experience for your app across environments.
Step 1: Migrate your embedded app
Anchor link to section titled "Step 1: Migrate your embedded app"In the Shopify CLI 3.x app directory structure, web/
represents your embedded app:
For your app to work with Shopify CLI, you need to migrate the code for your embedded app to the web/
directory.
The steps that you need to follow depend on your project language:
If your app only contains app extensions, then you can skip this step.
Node.js or Rails
Anchor link to section titled "Node.js or Rails"- In your app project folder, create a
web/
directory. Move your embedded app source code, tests, configuration files, and dependency files into the
web/
directory. This includes yourpackage.json
or yourGemfile
.Files that are scoped to the project should remain at the root of your project. This includes VS Code configuration files or CI pipelines.
Create a
shopify.web.toml
configuration file with content for your project language:
Thedev
command instructs the CLI on how to serve the project in theweb/
directory. The value might differ depending on how the process is invoked in the project. For example, you might need to usebundle exec rails serve
if you don’t have a Rails binstub, orpnpm run dev
if you have a Node project with pnpm as a package manager.
- In your app project folder, create a
web/
directory. Move your embedded app source code, tests, configuration files, and dependency files into the
web/
directory. This includes yourpackage.json
or yourGemfile
.Files that are scoped to the project should remain at the root. This includes VS Code configuration files or CI pipelines.
Create two
shopify.web.toml
configuration files, one for the frontend and one for the backend:
App hosting
Anchor link to section titled "App hosting"At runtime, the CLI will expose the variables that you'll need to set up your application. These include SHOPIFY_API_KEY
, SHOPIFY_API_SECRET
, SCOPES
, and HOST
. Refer to the Shopify starter Node app for an example of the setup in a Node application using the @shopify/shopify-api
npm package.
Step 2: Create a root configuration file
Anchor link to section titled "Step 2: Create a root configuration file"Create a shopify.app.toml
file in your app’s root directory. 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.
The TOML should contain the following information:
name
: The name of your app.scopes
: If you're migrating an embedded app, then enter the value of theSCOPES
attribute of your.env
file. If your app contains only app extensions, then you don't need to include thescopes
in this file.
Step 3: Add Shopify CLI as a project dependency
Anchor link to section titled "Step 3: Add Shopify CLI as a project dependency"In this step, you'll add Shopify CLI as a dependency of your app, and verify that your migrated embedded app is recognized by Shopify CLI.
Create a
package.json
at the root of the project. The content ofpackage.json
should match the content in the code snippet below, wheremy-app
is replaced with the name of your app.After saving the file, run your package manager's
install
command to install the project's dependencies:After the installation has finished, run the root
shopify
command to verify the installation:You should see the help menu for Shopify CLI.
Run the
info
command to verify that theweb/
directory is recognized by Shopify CLI:
Step 4: Connect your app to the Partner Dashboard
Anchor link to section titled "Step 4: Connect your app to the Partner Dashboard"Run the dev
command to log into your Partner account, connect your app to your existing app in the Partner Dashboard, and view the embedded app on a development store using a tunnel:
Step 5: Migrate your app extensions
Anchor link to section titled "Step 5: Migrate your app extensions"In the Shopify CLI 3.x app directory structure, each subdirectory under extensions/
represents a single app extension.
For your app to work with Shopify CLI, you need to migrate the code for each of your app extensions to an extensions/
subdirectory.
If your app doesn’t have app extensions, you can skip this step.
Follow the steps below for each app extension that's included in your app.
Step 4A: Move your files to their new location
Anchor link to section titled "Step 4A: Move your files to their new location"- Navigate to your app directory.
- If you haven't done so already, create an
extensions/
subdirectory. - Under
extensions/
, create a new subdirectory for your extension. - Move the extension files to your new subdirectory.
Step 4B: Update package.json
Anchor link to section titled "Step 4B: Update package.json"You need to remove prerequisites and workflows that have been replaced by Shopify CLI.
Use your package manager to delete the following dependencies:
@shopify/admin-ui-extensions-run
@shopify/checkout-ui-extensions-run
@shopify/shopify-cli-extensions
In your
package.json
, remove the following scripts:build
server
start
Step 4C: Reorganize your dependencies
Anchor link to section titled "Step 4C: Reorganize your dependencies"Shopify CLI enables you to manage your npm dependencies multiple ways. You can store all of your dependencies in the root package.json
file, or you can use your package manager's workspaces functionality. Using workspaces is recommended.
If you decide to use the root package.json
as the source of truth for dependencies, then you need to move the extension’s dependencies
and devDependencies
from your extension's package.json
to the root package.json
.
If the extension’s package.json
has typescript
, eslint
, and prettier
dependencies, then you should also move them to the app’s root package.json
so the same dependency version is shared across all of the extensions in the app. If you decide to make TypeScript, ESLint, or Prettier dependencies of your entire app, then you should also move the following configuration files if they are present:
- Typescript:
tsconfig.json
- ESLint:
.eslintrc.*
, or theeslintConfig
attribute from thepackage.json
- Prettier:
.prettierrc
After you reorganize your dependencies, run your package manager's install
command to install the dependencies, and then make sure that there are no incompatibilities in the dependency graph.
Step 4D: Migrate your configurations to TOML files
Anchor link to section titled "Step 4D: Migrate your configurations to TOML files"Shopify CLI 3.x uses TOML files instead of YAML files and, in some cases, .env
files. The following steps vary depending on the type of extension.
Theme app extensions
Anchor link to section titled "Theme app extensions"If you're migrating a theme app extension, then do the following:
Create a
shopify.theme.extension.toml
in the extension’s directory.The TOML should contain the following information:
name
: The name of your app extension.name
should match theEXTENSION_TITLE
from your extension's.env
file.type
: Entertheme
.
Optional: delete any remaining
.env
,extension.config.yml
, and.shopify-cli.yml
files.
UI extensions (checkout post-purchase)
Anchor link to section titled "UI extensions (checkout post-purchase)"If you're migrating a checkout post-purchase extension, then do the following:
Create a
shopify.ui.extension.toml
in the extension’s directory.The TOML should contain the following information:
name
: The name of your app extension.name
should match theEXTENSION_TITLE
from your extension's.env
file.type
: Entercheckout_post_purchase
.
If the extension’s
extension.config.yml
has additional attributes besidestype
andname
, then convert them to TOML using a YAML to TOML converter, and then add them to theshopify.ui.extension.toml
.If the extension's
.env
file has any user-defined variables, then move them to the root.env
file of the app.Optional: delete any remaining
.env
,extension.config.yml
, and.shopify-cli.yml
files.
Step 4E: Verify the extension
Anchor link to section titled "Step 4E: Verify the extension"Run the
info
command to verify that each extension subdirectory is recognized by Shopify CLI:Run the
dev
command to open the embedded app on a development store. If you haven't logged into your Partner account or connected your app to an app in the Partner Dashboard, then you'll be prompted to do so in this step.Run the
deploy
command to deploy your app extension code to Shopify. From here, you can create a new version and publish your migrated app extension.