Go Headless
Changelog
Wix CLI
Guides
About The Wix CLI
Get Started
Development
Extensions
Command Reference
Introduction
Project Creation
create app
create headless
create headless link
Project Commands
Global Commands
Legacy CLIs
Legacy Wix CLI for Apps
In This Article
  1. Before you begin
  2. Usage
  3. Flags
  4. Examples
  5. After the command runs
  6. See also

npm create @wix/new headless link

Links an existing Astro project to Wix.

Use this command when you have an existing Astro project that wasn't created through create headless, and you want to connect it to Wix. This command creates a Wix-managed headless project.

Run this command at the root folder of your Astro project. The command provisions a Wix business and site for the project.

Important: Your project must use Astro 5. Astro 6 isn't supported.

Learn more about linking an existing Astro project to Wix.

Running the command without flags starts interactive mode, prompting you for a business name and project name. To run non-interactively, pass the --business-name and --project-name flags.

Note: This command is provided by the @wix/create-new package, which is invoked through npm create. It's a separate package from @wix/cli and operates on the project in the current working directory.

Before you begin

The link command verifies that 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.
  • 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.

In addition, the project you want to link must be an Astro 5 project. Astro 6 isn't supported.

Usage

Copy

The -- separator tells npm to forward everything after it to the @wix/create-new package, instead of treating the flags as options for npm create itself.

Flags

The following flags are available for the link command:

FlagDescription
--business-name <business-name>The name of your business as it appears in the Wix dashboard.

Required if running non-interactively; otherwise the CLI prompts you for it.
--project-name <project-name>The name of your project, used as the project identifier. Must be 3 to 20 characters long and contain only lowercase letters and numbers. Don't use hyphens, underscores, uppercase letters, or other characters.

Required if running non-interactively; otherwise the CLI prompts you for it.
-h, --helpDisplay help for the command.

Examples

Link the Astro project in the current folder to a new Wix business non-interactively:

Copy

After the command runs

The npm create @wix/new -- headless link command modifies your existing Astro project in place. It doesn't create a new project folder. Rather, the command:

  • Provisions a new Wix business and site for the project. The site appears on the Sites page of your Wix account.
  • Adds a wix.config.json file to the project root, populated with a siteId for the new site and an appId for the project's private app.
  • Updates your existing Astro configuration by:
    • Adding the @wix/astro and @astrojs/react integrations.
    • Setting output: 'server'.
    • Adding static.wixstatic.com to the allowed image domains.
    • Adding the @wix/cloud-provider-fetch-adapter for production builds.
  • Replaces your package.json scripts with CLI equivalents that route dev, build, preview, and release through the wix command. Also adds Wix and React dependencies.
  • Installs dependencies automatically.

To start a local development environment, run wix dev.

Learn more about the architecture and project structure of a Wix-managed headless project.

See also

  • About Wix-Managed Headless
  • create headless
Did this help?