About Migrating an App to the New Wix CLI

App projects in the Wix CLI use the new Wix CLI project structure, built on the @wix/custom-extensions package, which replaces the two structures that came before it:

• The Astro-based CLI app project structure
• The legacy Wix CLI for Apps project structure

Migrating changes your project, and your app stays the same app: same ID, same Wix users who installed it, and its version history continues rather than starting over. You release a new version when the migration is done, because your code reaches Wix users only after you release it.

Why migrate

The new Wix CLI is part of a broader move to streamline how you develop apps on Wix:

• Faster development: A streamlined project setup gets you building sooner.
• Built for what's next: The new Wix CLI is aligned with where the Wix platform is heading, including Studio Two.
• Full support and new features: The legacy Wix CLIs for apps are deprecated. Projects built with them keep working, but new features and full support come only to the new Wix CLI.

Which migration applies to you

The migration to follow depends on the structure your project uses. To identify it, see Determine Which CLI Your Project Uses.

Project structure	Migration
Astro-based CLI app	Migrate an Astro-based CLI App to the New Wix CLI
Legacy CLI app	Migrate a Legacy CLI App to the New Wix CLI

What each migration involves

The two paths differ in scope, because they start from different distances away. Each guide covers what to change, and what to check before you release.

From an Astro-based CLI app

The migration replaces the toolchain your project uses and updates the code that depends on it, such as import paths. Your extensions keep their IDs, and nothing is added to or removed from your app.

To migrate, follow Migrate an Astro-based CLI App to the New Wix CLI, which takes you through the conversion step by step.

From a legacy CLI app

The migration reaches your extensions themselves. Each one is declared a different way in the new structure, so you recreate its configuration, and your backend moves to a different shape. The guide works through your extensions one at a time as you move them into a new project, then has you test the whole project and release it in one version. Until that release, your app keeps running the legacy project's last release. After you confirm that the release works, you delete the legacy project.

How you work after the migration

A migration also changes part of your routine for good, beyond the conversion itself.

If you migrated from the Astro-based CLI

• Your wix commands don't change.
• A build doesn't typecheck the project. In the Astro-based structure, astro check did. Run npm run typecheck yourself, or chain it into your build script.
• There's no astro.config.mjs. Any build setting you customized there has nowhere to go, so check what you had before you rely on it.
• Your endpoints move, and their routes change. They live in src/api/ in the new structure, and a route doesn't carry the /api prefix that src/pages/api/ supplied.

If you migrated from the legacy CLI

• Your commands are a different set. Compare the legacy command reference with the Wix CLI for Apps command reference.
• Your backend is reached over HTTP. Where a web method was a function your frontend imported and called, an endpoint is a route your frontend requests. Every backend function you add after the migration works that way.
• Your extensions are configured in code. Each one is declared in a TypeScript file rather than a JSON file, so adding an extension later means writing a declaration, which wix app generate scaffolds for you.