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, project name, and site template. 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 |
|---|---|
--project-name <project-name> | The name of your project, used as the local folder name and 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. |
--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. Must be one of: commerce, scheduler, registration, blank. See Site templates for what each template includes.Required 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 to scaffold against the corresponding template non-interactively. 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 --project-name. 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.