> 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`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Migrate an App from the Legacy Wix CLI to the New Wix CLI

## Article: Migrate an App from the Legacy Wix CLI 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-from-legacy-cli/migrate-an-app-from-the-legacy-wix-cli-to-the-new-wix-cli.md

## Article Content:

# 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](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps.md) to the new [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). The two CLIs use different project structures and toolchains. The migration converts your app to use the [new project structure](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md), so it can use the new CLI's commands, generators, and supported [extensions](https://dev.wix.com/docs/wix-cli/guides/extensions/about-extensions.md).

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:

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

> **Note:** If the default folder name is already in use on your filesystem, the CLI prompts you to enter a different one.

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

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](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/backend/http-endpoints/migrate/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/supported-extensions/backend/http-endpoints/migrate/migrate-from-http-functions-to-http-endpoints.md) 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](#extension-types).

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/astro/builders';
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);
```

### Test, build, and release

To finish migrating the extension:

<blockquote class="warning">

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

For details on how 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. From the new project, run [`wix dev`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/dev.md) 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.

    ```bash
    wix dev
    ```

2. [Build](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/build.md) the new project to confirm the extension compiles:

    ```bash
    wix build
    ```

3. In the new project, [release a new version](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md):

    ```bash
    wix release
    ```

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 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](#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).

<blockquote class="important">

__Important:__
When the new project releases an extension that also exists in the legacy project, the new version takes precedence. Still, deletion from the legacy project matters. As long as the extension exists in both projects, a later legacy release for any reason would override the new project's version.

</blockquote>

### Extension types

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

| Extension type | Migrate | Delete |
|---|---|---|
| Dashboard page | [Migrate a Dashboard Page Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/dashboard/dashboard-pages/add-dashboard-page-extensions-with-the-wix-cli.md) | [Delete a dashboard page](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/dashboard-extensions/dashboard-pages/add-dashboard-page-extensions-with-the-cli.md#delete-a-dashboard-page) |
| Dashboard modal | [Migrate a Dashboard Modal Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/dashboard/dashboard-modals/add-dashboard-modal-extensions-with-the-wix-cli.md) | [Delete a dashboard modal](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/dashboard-extensions/dashboard-modals/add-dashboard-modal-extensions-with-the-cli.md#delete-a-dashboard-modal) |
| Dashboard plugin | [Migrate a Dashboard Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/dashboard/dashboard-plugins/add-dashboard-plugin-extensions-with-the-wix-cli.md) | [Delete a dashboard plugin](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/dashboard-extensions/dashboard-plugins/add-dashboard-plugin-extension-with-the-cli.md#delete-a-dashboard-plugin) |
| 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/supported-extensions/dashboard/dashboard-menu-plugin/add-dashboard-menu-plugin-extensions-with-the-wix-cli.md) | [Delete a dashboard menu plugin](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/dashboard-extensions/dashboard-menu-plugins/add-dashboard-menu-plugin-extensions-with-the-cli.md#delete-a-dashboard-menu-plugin) |
| Custom element | [Migrate a Custom Element Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/site/custom-elements/add-a-custom-element-extension-with-the-wix-cli.md) | [Delete a site widget extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/custom-element-site-widgets/add-a-site-widget-extension-in-the-cli.md#delete-a-site-widget-extension) (custom elements were a kind of site widget in the legacy CLI) |
| Site plugin | [Migrate a Site Plugin Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/site/site-plugins/add-a-site-plugin-extension-with-the-wix-cli.md) | [Delete a site plugin extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/site-plugins/add-a-site-plugin-extension-in-the-cli.md#delete-a-site-plugin-extension) |
| Embedded script | [Migrate an Embedded Script Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/site/embedded-scripts/add-an-embedded-script-extension-with-the-wix-cli.md) | [Delete an embedded script extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/embedded-scripts/add-embedded-script-extensions-with-the-cli.md#delete-an-embedded-script-extension) |
| Service plugin | [Migrate Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/backend/service-plugins/add-service-plugin-extensions-with-the-wix-cli.md) | [Delete a service plugin extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md#delete-a-service-plugin-extension) |
| Event | [Migrate an Event Extension](https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/backend/events/add-event-extensions-with-the-wix-cli.md) | [Delete an event extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/events/add-event-extensions-with-the-cli.md#delete-an-event-extension) |


## Step 5 | Distribute the migrated app

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

::::tabs

:::App-already-distributed

The migrated version is already live for existing users via the final `wix release`. To confirm the release was created, open the **Versions** page in the **Distribute** tab of your app's dashboard. For details on how users receive new versions, see [About App Versioning](https://dev.wix.com/docs/build-apps/manage-your-app/versioning/about-app-versioning.md).

:::

:::App-not-distributed

The migrated version is ready to distribute. When you're ready to share the app with users, see [About App Distribution](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/about-app-distribution.md) for the available paths: Wix App Market submission, install link, or direct install on a site. Until then, you can keep developing on your development site.

:::

::::


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

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

### 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](#extension-types).
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](https://dev.wix.com/docs/wix-cli/guides/development/environment-variables/about-environment-variables.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 env pull`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/env-pull.md).