Connect an Existing Astro Project to Wix

If you have an existing Astro project, you can create a Wix-managed headless project and connect your project to it. The create headless link command provisions a Wix business and site for your project, configures your Astro setup for Wix, and installs the necessary dependencies.

This is an alternative to creating a new project with create headless, which scaffolds a new Astro project from a template.

Before you begin

Before getting started, make sure that:

• You are logged in to your Wix account. If you don't already have one, sign up for a Wix account.
• You have Node.js (v20.11.0 or higher).
• You have an existing Astro project using Astro 5. Astro 6 isn't supported.
• Your project contains an Astro configuration file such as astro.config.js, astro.config.cjs, astro.config.mjs, or astro.config.ts. Without one, the command fails with an Only Astro projects can be linked to Wix. error.
• Your project isn't already a Wix-managed headless project and doesn't contain a wix.config.json file. If it does, the command fails with a This project is already connected to Wix, so no changes were made. error.

Step 1 | Link your project to Wix

This creates a new Wix-managed headless project to link your Astro project to:

1. Navigate to the root folder of your Astro project.

2. Run the following command:

   Copy

3. Enter the name of your business. This will be the name of your headless project on Wix. The project is added to your Wix Sites page.

4. Enter the name of your project. This will be the project identifier. It must be 3 to 20 characters long and contain only lowercase letters and numbers.

   The command configures your Astro project for Wix, installs dependencies, and provisions a Wix business and site.

   Note: You can run the command non-interactively by passing the --business-name and --project-name flags. Learn more about flags in the create headless link command.

Step 2 | Test the project

1. Run the dev command to start the local development environment:

   Copy

2. Open the link provided in the terminal to view your site.

The development environment is set up for hot reloading, so any changes you make to your code are immediately reflected in the browser.

Step 3 (Optional) | Call a Wix API

1. Close the local development environment that started when you ran the dev command.

2. Install the @wix/members package:

   Copy

3. Add the following to your index.astro file's front matter:

   Copy

   Your front matter should look something like this:

   Copy

4. Run the dev command to restart the local development environment:

   Copy

5. Click the link to open your site.

6. Return to the terminal. You should see the following log showing that your site has 0 members:

   Copy

   Note: If you added members, you may not see their data in this list due to their status being set to PRIVATE by default. For more information, see List Members.

Next steps

After linking your Astro project, it's connected to Wix and you can develop it locally.

You can now:

• Call Wix APIs with the JavaScript SDK.
• Install the Wix Plugin to set up Wix Skills and the Wix MCP in your IDE for AI-assisted development.
• Learn more about developing your project.

See also

• create headless
• create headless link
• Quick Start a Headless Project
• About the Wix CLI
• About Extensions in the Wix CLI