# Getting started (/docs/getting-started)

> Create your first Stanza project and add modules.

Scaffold a new monorepo, then layer in modules as you go.

## Prerequisites [#prerequisites]

* **Node.js** 22 or newer.
* A package manager — **pnpm** (recommended), **npm**, or **bun**. Stanza writes a workspace-based monorepo, so a workspace-aware package manager is required.

## Create a project [#create-a-project]

The create command launches an interactive wizard that walks you through each category:

```sh
pnpm create stanza my-app
```

The same command works across package managers:

```sh
npm init stanza -- my-app
bun create stanza my-app
```

To run it without the wizard — in CI, for example — see [Non-interactive setup](/docs/getting-started#non-interactive-setup) below.

## What you get [#what-you-get]

Stanza generates a clean monorepo: your app under `apps/web/` (one of potentially many apps as the registry grows), internal packages under `packages/`, and a `stanza.json` manifest at the root. The manifest records the apps in the project, the modules you selected, and which files each one owns — it's how `add` and `remove` know what's installed and what to clean up. You generally don't edit it by hand.

## Install and run [#install-and-run]

```sh
cd my-app
pnpm install
pnpm dev
```

## Add a module [#add-a-module]

Every category is one command away — `framework`, `ui`, `db`, `orm`, `auth`, `tooling`, `testing`, [and more](/docs/registry):

```sh
npx stanza-cli add auth better-auth
```

Stanza resolves peer constraints, picks the adapter that matches your stack, and writes the module's templates, dependencies, and environment variables into the appropriate place.

<Callout type="info">
  Some modules require one or more peer modules to be set up first. Better Auth, for example, peers
  on `framework` and `orm`, so the command above assumes your project already has an ORM like
  Drizzle or Prisma. If it doesn't, Stanza fails with `missing-peer` and directs you to add a module
  from the absent category first.
</Callout>

After adding a module, re-run your package manager's install so the new workspace package(s) are linked:

```sh
pnpm install
```

## Inspect and remove [#inspect-and-remove]

```sh
npx stanza-cli list                  # show installed modules, grouped by category
npx stanza-cli doctor                # check the project still matches its manifest
npx stanza-cli search drizzle        # find modules in the registry by query
npx stanza-cli remove auth           # remove a module and sweep the files it owns
```

`stanza search` prints each module's `category/id` pair — use the **id**, not the display label, when passing it to `add`.

## Non-interactive setup [#non-interactive-setup]

Pass `--yes` and select each category explicitly with a flag. Single-choice categories take one id; multi-choice categories (like `testing`) take a comma-separated list:

```sh
npx -y stanza-cli@latest init my-app --yes \
  --framework=next \
  --ui=tailwind \
  --db=postgres \
  --orm=drizzle \
  --auth=better-auth \
  --testing=vitest,playwright \
  --pm=pnpm
```

`--yes` never fills in defaults for categories you omit — any category without a flag is simply skipped.

## Next steps [#next-steps]

* [Concepts](/docs/concepts) — the mental model behind apps, categories, vendoring, peers, and the manifest.
* [CLI reference](/docs/cli) — every verb, flag, and environment variable.
* [Registry](/docs/registry) — the roadmap of available modules and how to pull from [third-party registries](/docs/registry#third-party-registries).
* [Authoring](/docs/authoring) — build your own modules and host them in your own registry.
* [Agents](/docs/agents) — drive Stanza from Claude Code, Codex, Cursor, or any other coding agent.