> 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`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - 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/cli-for-headless/command-reference/project-creation-commands/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.

For a step-by-step walkthrough, see [Create a Headless Project with the Wix CLI for Headless](https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/get-started/create-a-project-with-the-wix-cli.md).

To link an existing Astro project to Wix instead, see [`npm create @wix/new headless link`](https://dev.wix.com/docs/wix-cli/cli-for-headless/command-reference/project-creation-commands/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

Run this command in the parent directory where you want the project folder.

```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.

> **Note:** If you don't include flags, the command 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.

## Flags

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

## Site templates

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 [Astro Templates for Wix-Managed Headless](https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/get-started/astro-templates.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 \
  --folder-name ai-test \
  --business-name "AI Test" \
  --site-template commerce \
  --no-publish
```

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

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

## What the command does

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](https://dev.wix.com/docs/wix-cli/cli-for-headless/project-structure/about-the-headless-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`.

## `create headless` vs. `init`

Both 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:

- **Site**: The Wix site your code targets, identified by the `siteId` in `wix.config.json`. It's the same entity as your [business](https://dev.wix.com/docs/go-headless/wix-managed-headless/about-wix-managed-headless.md#create-a-project): the workspace in your Wix account with a dashboard, billing, and business solutions, listed on the [Sites page](https://manage.wix.com/account/sites).
- **[Private app](https://dev.wix.com/docs/build-apps/get-started/overview/exposing-apps-publicly-and-privately.md)**: Authorizes that code to call the site's APIs and add extensions, identified by the `appId` in `wix.config.json`.

### When to use each

- `create headless` scaffolds a complete, opinionated Astro project for you. It generates project files from a [site template](https://dev.wix.com/docs/wix-cli/cli-for-headless/command-reference/project-creation-commands/create-headless.md#site-templates), 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`](https://dev.wix.com/docs/wix-cli/cli-for-headless/command-reference/project-creation-commands/create-init.md) 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.