Migrate a Legacy CLI App to the New Wix CLI

Migrate 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 moves your app's code into a project with the new Wix CLI project structure, so that you can develop the app with the commands, generators, and supported extensions of the new Wix CLI.

The migration creates a new Wix CLI project for the same app, with the same project ID. Both projects share a single version history. You move your backend and every extension into the new project, test the project on a development site, and release it in one version. Once you've confirmed that the new version of your app works, you delete the legacy project.

Before you begin

The new Wix CLI requires Node.js 24.22.1 or later. If your legacy project pins an older version, for example in an .nvmrc file, switch to a supported version before you run the commands in this guide.

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

To create a project that has the same app ID and project ID as your legacy project:

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. From the list, select the Wix CLI app you want to migrate. If several of your apps have similar names, confirm the selection after the project is created, as described below.

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

6. In the new project's wix.config.mjs, set projectId to the projectId value in your legacy project's wix.config.json. The CLI sets it to the folder name, inside the customExtensions() call:

   Copy

Step 2 | Remove the default extension

The new project comes with a default my-page dashboard page extension that isn't part of your app. To keep it out of the migrated app:

1. Delete the src/extensions/dashboard/pages/my-page/ folder.

2. In src/extensions.ts, remove the myPage import and the .use(myPage) call. The CLI generates the file as follows:

   Copy

   After the change, the file contains the following:

   Copy

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.

Complete each of the following 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.

3. If you keep your endpoints in a folder other than src/api/, name that folder in the apiDir option of app() in src/extensions.ts:

   Copy

   Endpoints are discovered only in that folder. apiDir defaults to api, so a project that keeps its endpoints in src/api/, as the two backend guides do, needs no declaration.

4. Copy any shared code outside src/backend/ that your backend imports, such as src/consts.ts, src/types.ts, or a src/utils/ folder, into the new project at the same path. The new project structure reserves no folder for shared code, so the files keep their paths. Update the import paths in the moved backend files as needed.

5. Install any packages your backend code imports that the new project doesn't already have, the same way you do for an extension in Install the extension's dependencies.

Step 4 | Migrate your extensions

For each extension in your legacy project, add the extension to the new project, install its dependencies, and build the project. Repeat until all your extensions are in the new project.

Add the extension to the new project

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

If the extension calls web methods or HTTP functions, also update those call sites. See Migrate from Web Methods to HTTP Endpoints or Migrate from HTTP Functions to HTTP Endpoints.

If the extension imports code that isn't part of any extension, such as components, hooks, or helpers under src/dashboard/, copy that code into the new project at the same path, and update the relative imports from the extension's new location. The new project structure reserves no folder for shared code, so the files keep their paths.

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:

Install the extension's dependencies

1. Install each package that the extension's code imports, at the version range in your legacy project's package.json:

   Copy

   The new project starts with a small set of dependencies, so packages that your legacy project used, such as @wix/stores or @wix/crm, aren't installed in it. Without a version range, npm install takes the latest version, which can be a newer major version than your code was written for.

2. Typecheck the project:

   Copy

   Note: The typecheck resolves module imports, so it reports a package that isn't installed as Cannot find module '<package>' against the file that imports it. This error is clearer than the build error for the same cause.

Build the project

After the typecheck passes, build the project to confirm that the extension compiles:

The typecheck reports missing packages and type errors, and the build also produces the bundle and the app manifest.

If the first build after you install a package fails with a pre-bundle error, see Troubleshooting.

You can also check each extension on a development site as you go, the same way Test the project describes for the whole project.

Extension types

The following table lists the migration guide for each extension type:

Step 5 | Test, build, and release

Once all your extensions are in the new project, test the project, release it, and check the new version on a site. Delete the legacy project only after the new version of your app works.

Test the project

You test the project on a development site, where your app is installed and your extensions run as they do for Wix users. The project uses one development site at a time and keeps using it until you change it.

Choose a development site

Choose the site based on whether your app already works on one:

Set the site for the project

The new project starts with no development site. Set the site you chose based on how you run the CLI:

Check your extensions

When the site is set for the project:

1. If the development session isn't running, run wix app dev from the new project.

2. Open your site, editor, or dashboard from the links the session prints, and check that each extension works as it did before the migration. For where to check each extension type, see the documentation of that type in About App Extensions in the Wix CLI.

3. If an extension also fails in the legacy project, handle the failure separately from the migration. The migration keeps the behavior of each extension and doesn't fix it.

   If an AI agent runs the migration, have it report such failures instead of changing the extension's code to make them go away.

Release the project

When every extension works on your development site, release the project as a single version of your app.

1. Build the project:

   Copy

2. Preview the project, install the preview on your development site from one of the links the CLI prints, and check your extensions there:

   Copy

   The preview runs the build you just made. A site keeps the preview it was installed with, so after each wix app preview, install the new preview from its link.

3. Release a new version:

   Copy

   Choose a minor version. Your app keeps the same extensions and permissions, so the release doesn't need users to accept an update.

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 your extensions work as expected.
   3. If an extension is missing or misbehaving anywhere it should appear, fix it before continuing. See An extension is missing after release for troubleshooting.

Delete the legacy project

Once the new version of your app works on your site, delete the legacy project.

Troubleshooting

The following problems can occur when you install, build, or release the new project.

ERESOLVE errors during npm install

If npm install fails with ERESOLVE peer-dependency conflicts, 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

The build fails with There is a new version of the pre-bundle

If wix app build fails with There is a new version of the pre-bundle for "<path>" on the first build after you install a package, run the command again. The second build passes.

An extension is missing after release

If an extension doesn't appear where you expect it after you release, the most likely cause is a value from its legacy configuration that wasn't carried over to the new project. This applies wherever the extension surfaces, not only the dashboard.

1. Open the migration sub-guide for your extension type.
2. Re-verify the field tables, and make sure every value matches the legacy config, including any conditional fields your legacy config sets.

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 app env pull.