Creates a new Wix-managed Headless project. This is the recommended path for new headless projects, where Wix handles hosting, OAuth, environment variables, and infrastructure.
Run this command in the parent directory where you want the project folder. If you don't include flags, it runs in interactive mode, prompting you for a business name, a site template, and a folder name. To run non-interactively, use the headless command together with the flags below.
For a step-by-step walkthrough, see Quick Start a Headless Project.
To link an existing Astro project to Wix instead, see npm create @wix/new headless link.
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 doesn't require an existing project.
The -- separator tells npm to forward everything after it to the @wix/create-new package, instead of consuming the flags itself.
The following flags are available for the headless command:
| Flag | Description |
|---|---|
--folder-name <folder-name> | The name of the local folder to create for your project. May contain only lowercase letters, numbers, and hyphens. Must start with a letter or number. Required if running non-interactively; otherwise the CLI prompts you for it. |
--business-name <business-name> | The name of your business as it will appear in the Wix dashboard. Required if running non-interactively; otherwise the CLI prompts you for it. |
--site-template [site-template] | The site template to scaffold from. If you provide a value, it must be one of: commerce, scheduler, registration, blank. If you pass --site-template without a value, the CLI scaffolds the blank template. See Site templates for what each template includes.Required as a flag if running non-interactively; otherwise the CLI prompts you to pick a template. |
--skip-install | Skip automatic dependency installation. If you set this flag, run npm install manually before starting the project. |
--skip-git | Skip initializing a Git repository during setup. |
--no-publish | Don't publish your site after creating the project. To publish later, run npm run release. |
-v, --version | Output the version number of @wix/create-new. |
-h, --help | Display help for the command. |
The following Astro-based site templates are supported. Pass the name (the value in the Name column) via --site-template <name> to scaffold against the corresponding template non-interactively. To scaffold the blank starter, you can either pass --site-template blank or pass bare --site-template. For descriptions of each template's features and links to the source repositories, see Wix-Managed Headless Templates.
| Name | Template | Description |
|---|---|---|
commerce | Commerce (Wix Stores) | Product catalog, checkout, and more. |
scheduler | Scheduler (Wix Bookings) | Appointment booking and calendar. |
registration | Registration (Wix Forms) | Inputs, dropdowns, and field validations. |
blank | Blank | Basic Astro project with no business solution preconfigured. |
Scaffold an ecommerce project built on Astro non-interactively, without auto-publishing:
Scaffold a blank Astro project and skip dependency installation, with auto-publishing:
The command creates a new folder named after --folder-name. In interactive mode, if you don't pass this flag, the CLI prompts you for a folder name and suggests a slug derived from your business name by default. The folder follows the standard project structure for Wix CLI projects.
In addition to scaffolding the standard layout, this command:
wix.config.json with the appId and siteId provisioned for the new project.--skip-git.To start a local development environment, run wix dev.
create headless vs. initBoth commands provision the same Wix headless project and write a local wix.config.json file that connects it to your code. A Wix headless project consists of:
siteId in wix.config.json. It's the same entity as your business — the workspace in your Wix account with a dashboard, billing, and business solutions, listed on the Sites page.appId in wix.config.json.create headless scaffolds a complete, opinionated Astro project for you. It generates project files from a site template, installs dependencies, initializes a Git repository, and publishes your site. Use it when you want Wix to set up the project structure for you.init connects project code you already have, whether you wrote it yourself or generated it. It only provisions the Wix headless project and writes wix.config.json, leaving the rest of your folder untouched — it doesn't generate a template, install dependencies, initialize Git, or publish your site. Use it when you just want to connect existing code to Wix.