> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: create headless

## Article: create headless

## Article Link: https://dev.wix.com/docs/wix-cli/command-reference/project-creation/create-headless.md

## Article Content:

# npm create @wix/new headless

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](https://dev.wix.com/docs/wix-cli/guides/get-started/quick-start-a-headless-project.md).

To link an existing Astro project to Wix instead, see [`npm create @wix/new headless link`](https://dev.wix.com/docs/wix-cli/command-reference/project-creation/create-headless-link.md).

> **Note:** This command is provided by the [`@wix/create-new`](https://www.npmjs.com/package/@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.

## Usage

```bash
npm create @wix/new@latest -- headless [flags]
```

The `--` separator tells `npm` to forward everything after it to the `@wix/create-new` package, instead of consuming the flags itself.

## Flags

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.<br /><br />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.<br /><br />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](#site-templates) for what each template includes.<br /><br />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`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/release.md).                                                                                                                                                                          |
| `-v`, `--version`                 | Output the version number of `@wix/create-new`.                                                                                                                                                                                                                                                                                     |
| `-h`, `--help`                    | Display help for the command.                                                                                                                                                                                                                                                                                                       |

## Site templates

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](https://dev.wix.com/docs/go-headless/get-started/templates/astro-templates-for-wix-managed-headless.md).

| Name           | Template                                                                                           | Description                                                  |
| -------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `commerce`     | [Commerce (Wix Stores)](https://github.com/wix/headless-templates/tree/main/astro/commerce)        | Product catalog, checkout, and more.                         |
| `scheduler`    | [Scheduler (Wix Bookings)](https://github.com/wix/headless-templates/tree/main/astro/scheduler)    | Appointment booking and calendar.                            |
| `registration` | [Registration (Wix Forms)](https://github.com/wix/headless-templates/tree/main/astro/registration) | Inputs, dropdowns, and field validations.                    |
| `blank`        | [Blank](https://github.com/wix/headless-templates/tree/main/astro/blank)                           | Basic Astro project with no business solution preconfigured. |

## Examples

Scaffold an ecommerce project built on Astro non-interactively, without auto-publishing:

```bash
npm create @wix/new@latest -- headless \
  --project-name aitest \
  --business-name "AI Test" \
  --site-template commerce \
  --no-publish
```

Scaffold a blank Astro project and skip dependency installation, with auto-publishing:

```bash
npm create @wix/new@latest -- headless \
  --project-name myproject \
  --business-name "My Business" \
  --site-template blank \
  --skip-install
```

## After the command runs

The command creates a new folder named after `--project-name`. The folder follows the standard [project structure](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md) for Wix CLI projects.

In addition to scaffolding the standard layout, this command:

- Provisions a business and site for your project. The site appears on the [Sites page](https://manage.wix.com/account/sites) of your Wix account, where you can manage business settings, billing, and more.
- Populates `wix.config.json` with the `appId` and `siteId` provisioned for the new project.
- Creates a Git repository with an initial commit, unless you pass `--skip-git`.

To start a local development environment, run [`wix dev`](https://dev.wix.com/docs/wix-cli/command-reference/project-commands/dev.md).