Migrate your app to Shopify CLI 3.x

• Node.js version 14.13.1 or higher
• A Node.js package manager: either npm, Yarn 1.x, or pnpm
• The latest version of Chrome or Firefox

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

When you migrate your app to use Shopify CLI 3.x, you can take advantage of the following improvements to the developer experience:

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.

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.

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.

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.

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:

• Node.js or Rails
• PHP

If your app only contains app extensions, then you can skip this step.

1. In your app project folder, create a web/ directory.

2. Move your embedded app source code, tests, configuration files, and dependency files into the web/ directory. This includes your package.json or your Gemfile.

   Files that are scoped to the project should remain at the root of your project. This includes VS Code configuration files or CI pipelines.

3. Create a shopify.web.toml configuration file with content for your project language:

   
   The dev command instructs the CLI on how to serve the project in the web/ directory. The value might differ depending on how the process is invoked in the project. For example, you might need to use bundle exec rails serve if you don’t have a Rails binstub, or pnpm run dev if you have a Node project with pnpm as a package manager.

1. In your app project folder, create a web/ directory.

2. Move your embedded app source code, tests, configuration files, and dependency files into the web/ directory. This includes your package.json or your Gemfile.

   Files that are scoped to the project should remain at the root. This includes VS Code configuration files or CI pipelines.

3. Create two shopify.web.toml configuration files, one for the frontend and one for the backend:

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.

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 the SCOPES attribute of your .env file. If your app contains only app extensions, then you don't need to include the scopes in this file.

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.

1. Create a package.json at the root of the project. The content of package.json should match the content in the code snippet below, where my-app is replaced with the name of your app.

2. After saving the file, run your package manager's install command to install the project's dependencies:

3. After the installation has finished, run the root shopify command to verify the installation:

   You should see the help menu for Shopify CLI.

4. Run the info command to verify that the web/ directory is recognized by Shopify CLI:

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:

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.

1. Navigate to your app directory.
2. If you haven't done so already, create an extensions/ subdirectory.
3. Under extensions/, create a new subdirectory for your extension.
4. Move the extension files to your new subdirectory.

You need to remove prerequisites and workflows that have been replaced by Shopify CLI.

1. Use your package manager to delete the following dependencies:

   • @shopify/admin-ui-extensions-run
   • @shopify/checkout-ui-extensions-run
   • @shopify/shopify-cli-extensions

2. In your package.json, remove the following scripts:

   • build
   • server
   • start

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 the eslintConfig attribute from the package.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.

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.

If you're migrating a theme app extension, then do the following:

1. 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 the EXTENSION_TITLE from your extension's .env file.
   • type: Enter theme.

2. Optional: delete any remaining .env, extension.config.yml, and .shopify-cli.yml files.

If you're migrating a checkout post-purchase extension, then do the following:

1. 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 the EXTENSION_TITLE from your extension's .env file.
   • type: Enter checkout_post_purchase.

2. If the extension’s extension.config.yml has additional attributes besides type and name, then convert them to TOML using a YAML to TOML converter, and then add them to the shopify.ui.extension.toml.

3. If the extension's .env file has any user-defined variables, then move them to the root .env file of the app.

4. Optional: delete any remaining .env, extension.config.yml, and .shopify-cli.yml files.

1. Run the info command to verify that each extension subdirectory is recognized by Shopify CLI:

2. 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.

3. 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.