Migrate an App from the Legacy Wix CLI to the New Wix CLI

This guide walks through migrating an app from the legacy Wix CLI for Apps to the new Wix CLI. The two CLIs use different project structures and toolchains. The migration converts your app to use the new project structure, so it can use the new CLI's commands, generators, and supported extensions.

The migration involves creating a new Wix CLI project linked to the same app and migrating extensions to it one at a time. Both projects share a single version history.

Step 1 | Create a new project linked to your existing app

To create a new project linked to your existing app:

1. In the terminal, navigate to the folder where you want to create the new project.

2. Run the following command:

   Copy

   If prompted to install the package, confirm it.

3. Select Add new extensions for an existing Wix app.

4. Select the existing Wix CLI app you want to migrate from the list.

5. Enter a name for the project folder or accept the default. The CLI generates the new project and shows a Results summary when it's done.

Step 2 | Remove the default extension

The new project comes with a default my-page dashboard extension that's not part of the migration. To remove it:

1. Delete the src/extensions/dashboard/pages/my-page/ folder.
2. In src/extensions.ts, remove the myPage import and the .use(myPage) call.

Step 3 | Migrate the backend

If your legacy project has web methods or HTTP functions, migrate them to the new project before migrating extensions. Extensions may reference backend code, so migrating the backend first keeps your extension migrations working.

To migrate the backend, complete each step that applies to your project:

1. If your project uses web methods, follow the Migrate from Web Methods to HTTP Endpoints guide.
2. If your project uses HTTP functions, follow the Migrate from HTTP Functions to HTTP Endpoints guide.

Step 4 | Migrate extensions one at a time

For each extension in your legacy project, follow the steps below. Repeat until all extensions are migrated.

Add the extension to the new project

In the new project, add the extension by following the migration guide for your extension type.

As you migrate extensions, src/extensions.ts accumulates one import per extension and one chained .use() call per extension. For example, after migrating three extensions:

Test, build, and release

To finish migrating the extension:

1. From the new project, run wix dev and verify the extension works on the development site. The dev site reflects your local code, so issues found here can be fixed before release.

   Copy

2. Build the new project to confirm the extension compiles:

   Copy

3. In the new project, release a new version:

   Copy

4. On a site where your app is installed, check the release as follows:

   1. Make sure the site uses the new version. See About App Versioning for details on how updates are delivered.
   2. Verify that the migrated extension works as expected.
   3. If the extension is missing from the dashboard or broken, fix it before continuing. See Extension missing in dashboard after release for troubleshooting.

5. In the legacy project, delete the extension's files by following the delete instructions for your extension type.

Extension types

For each extension type, follow the migration guide and the delete instructions:

Step 5 | Distribute the migrated app

What to do next depends on whether your app is already distributed:

Troubleshooting

This section lists common issues you might run into during the migration, with instructions to resolve each.

ERESOLVE errors during npm install

When npm install fails with peer-dependency conflicts (ERESOLVE), you need to allow legacy peer dependencies and reset the install.

1. At the top of your project's folder, create a .npmrc file containing legacy-peer-deps=true.

2. In the terminal, navigate to your project's folder and run the following command:

   Copy

Extension missing in dashboard after release

If you released a new version but the extension doesn't appear in the dashboard, a value that should have been preserved from the legacy config most likely wasn't carried over.

1. Open the migration sub-guide for your extension type.
2. Re-verify the field table and make sure all required values match those in the legacy config.

Build fails with missing WIX_CLIENT_ID

The build needs the WIX_CLIENT_ID environment variable. If it isn't set, the build fails.

Set it in one of these ways:

• At the top of your project's folder, create a .env.local file containing WIX_CLIENT_ID=<your-app-id>.
• In the terminal, navigate to your project's folder and run wix env pull.