> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt
> - To build a Wix site agentically, follow https://www.wix.com/headless/skill.md

## Resource: Migrate a Legacy CLI App to the New Wix CLI

## Article: Migrate a Legacy CLI App to the New Wix CLI

## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-legacy-cli-app-to-the-new-wix-cli.md

## Article Content:

# Migrate a Legacy CLI App to the New Wix CLI

Migrate an app from the legacy [Wix CLI for Apps](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/about-the-legacy-wix-cli-for-apps.md) to the new [Wix CLI](https://dev.wix.com/docs/wix-cli/cli-for-apps/about-the-wix-cli-for-apps.md). 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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/about-extensions-in-the-wix-cli.md) 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](https://nodejs.org/en/) 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:

    ```bash
    npm create @wix/new@latest app
    ```

    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:

    ```js
    customExtensions({
      appId,
      projectId: '<your-legacy-project-id>',
    }),
    ```

<blockquote class="important">

__Important:__
The new project must have the same `appId` and `projectId` as your legacy project. The CLI sets `appId` to the app you selected. To confirm that you selected the right app, compare the `appId` value in `wix.config.mjs` with the one in your legacy project's `wix.config.json`.

</blockquote>

## 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:

    ```ts
    import { app } from '@wix/custom-extensions';
    import myPage from './extensions/dashboard/pages/my-page/my-page.extension.ts';

    export default app().use(myPage);
    ```

    After the change, the file contains the following:

    ```ts
    import { app } from '@wix/custom-extensions';

    export default app();
    ```

## Step 3 | Migrate the backend

If your legacy project has [web methods](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/apis/web-methods/about-web-method-extensions.md) or [HTTP functions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/apis/http-functions/about-http-function-extensions.md), 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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-from-web-methods-to-http-endpoints.md) guide.
2. If your project uses HTTP functions, follow the [Migrate from HTTP Functions to HTTP Endpoints](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-from-http-functions-to-http-endpoints.md) 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`:

    ```ts
    export default app({ apiDir: './<your-endpoints-folder>' })
      .use(myExtension);
    ```

    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](#install-the-extensions-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.

<blockquote class="important">

__Important:__ Don't release until all your extensions are in the new project. The new project has the same project ID as your legacy project, so a release from it contains only the extensions that are in it.

</blockquote>

### Add the extension to the new project

In the new project, add the extension by following the migration guide for [your extension type](#extension-types).

If the extension calls web methods or HTTP functions, also update those call sites. See [Migrate from Web Methods to HTTP Endpoints](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-from-web-methods-to-http-endpoints.md#update-your-frontend-call-sites-as-you-migrate-each-extension) or [Migrate from HTTP Functions to HTTP Endpoints](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-from-http-functions-to-http-endpoints.md#update-your-frontend-call-sites-as-you-migrate-each-extension).

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:

```ts
import { app } from '@wix/custom-extensions';
import myFirstExtension from './extensions/.../first.extension';
import mySecondExtension from './extensions/.../second.extension';
import myThirdExtension from './extensions/.../third.extension';

export default app()
  .use(myFirstExtension)
  .use(mySecondExtension)
  .use(myThirdExtension);
```

### 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`:

    ```bash
    npm install "<package>@<version-range>"
    ```

    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:

    ```bash
    npm run typecheck
    ```

    > **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:

```bash
wix app build
```

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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-legacy-cli-app-to-the-new-wix-cli.md#the-build-fails-with-there-is-a-new-version-of-the-pre-bundle).

You can also check each extension on a development site as you go, the same way [Test the project](#test-the-project) describes for the whole project.

### Extension types

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

| Extension type | Migrate |
|---|---|
| Dashboard page | [Migrate a Dashboard Page Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-dashboard-page-extension.md) |
| Dashboard modal | [Migrate a Dashboard Modal Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-dashboard-modal-extension.md) |
| Dashboard plugin | [Migrate a Dashboard Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-dashboard-plugin-extension.md) |
| Dashboard menu plugin | [Migrate a Dashboard Menu Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-dashboard-menu-plugin-extension.md) |
| Custom element | [Migrate a Custom Element Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-custom-element-extension.md) |
| Site plugin | [Migrate a Site Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-site-plugin-extension.md) |
| Embedded script | [Migrate an Embedded Script Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-an-embedded-script-extension.md) |
| Service plugin | [Migrate a Service Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-a-service-plugin-extension.md) |
| Event | [Migrate an Event Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/migrate-an-app-to-the-new-cli/migrate-an-app-from-the-legacy-cli/migrate-an-event-extension.md) |

## Step 5 | Test, build, and release

Once all your extensions are in the new project, [test the project](#test-the-project), [release it](#release-the-project), and check the new version on a site. [Delete the legacy project](#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:

::::tabs

:::Your-app-already-works-on-a-development-site

Choose that site, usually your legacy project's development site. It already has the business solutions, apps, permissions, and data your extensions depend on, so they run under the same conditions as before the migration.

:::

:::No-site-has-what-your-app-needs

Create a development site, or choose one your app isn't set up on yet, and prepare it for your extensions:

- Install the Wix apps and business solutions your extensions depend on, such as Wix Stores for a site plugin that sits on a store page.
- Add the data your code reads, such as products or collection items.
- Match what your app expects of the site, such as its editor.

Otherwise your extensions fail there for reasons unrelated to the migration.

:::

::::

#### 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:

::::tabs

:::In-an-interactive-terminal

Run [`wix app dev`](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/dev.md) from the new project. Because no site is set, the CLI asks you to install your app on one, and you select the site in your browser. For the steps, see [Install your app on a development site](https://dev.wix.com/docs/build-apps/develop-your-app/development-sites/work-with-development-sites.md#install-your-app-on-a-development-site).

:::

:::Without-an-interactive-terminal

Before you run `wix app dev`, set the site with [`wix app dev-site select <site-id>`](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/dev-site.md). An AI agent or a CI job can't use the browser window, and `wix app dev` stops with an error until the project has a development site. For your legacy project's site, the ID is the `siteId` value in the legacy project's `.wix/app.config.json` file. For the steps, see [Switch your Wix CLI project's development site](https://dev.wix.com/docs/build-apps/develop-your-app/development-sites/work-with-development-sites.md#switch-your-wix-cli-projects-development-site).

:::

::::

#### 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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/about-extensions-in-the-wix-cli.md).

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.

<blockquote class="warning">

__Warning:__
A released version of your app can hide a broken migration. Where Wix serves your app rather than your dev session, you see the released version instead of your local code, and the extension looks correct while your migrated code never runs. Two cases to watch:

- A dashboard URL opened directly, rather than from the running dev session, serves your released app.
- A service plugin is called by Wix from its own servers, so that call reaches the released version installed on the site. A migrated handler that fails shows up as your feature silently missing rather than as an error.

Open every extension from the running dev session, and treat a service plugin as verified only after you release.

</blockquote>

### Release the project

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

<blockquote class="warning">

__Warning:__ A `wix app release` can't be undone. A broken release stays broken for Wix users whose sites received it until you release a fix. Verifying on a development site beforehand catches most issues.

For details on how Wix users receive new versions, see [About App Versioning](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning.md).

</blockquote>

1. [Build](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/build.md) the project:

    ```bash
    wix app build
    ```

2. [Preview](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/preview.md) the project, install the preview on your development site from one of the links the CLI prints, and check your extensions there:

    ```bash
    wix app preview
    ```

    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](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/release.md):

    ```bash
    wix app release
    ```

    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](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning.md) 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](#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.

<blockquote class="warning">

__Warning:__
If you release from the legacy project, which has the same project ID as the new project, the new version of your app contains only what's in the legacy project. Your migrated extensions return to their legacy versions, and anything you added in the new project, such as new extensions, is removed. This applies to any release from the legacy project, however long after the migration.

</blockquote>

## 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:

    ```bash
    rm -rf node_modules package-lock.json && npm install
    ```

### 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](#extension-types).
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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/project-development/environment-variables/about-environment-variables-in-the-cli.md). 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`](https://dev.wix.com/docs/wix-cli/cli-for-apps/command-reference/project-commands/env.md#pull).