# Installation

> Get a deck running, in either mode

Node.js 20 or newer. Any of npm, pnpm, yarn, or bun.

## Markdown mode: no install

```bash
npx @getnarro/cli new deck.md    # write a starter deck
npx @getnarro/cli dev deck.md    # serve it with hot reload
npx @getnarro/cli build deck.md  # static build into dist/
```

Nothing is scaffolded and no config file is created. The CLI brings its own
runtime, so a lone `.md` file in an empty directory is a complete deck.

`markdown-minimal` scaffolds the same thing with a `package.json` that pins the
CLI version and gives you scripts:

```bash
npm create narro@latest my-deck -- --template markdown-minimal
```

For a deck that needs its own dependencies, pinned versions, or React layouts,
`markdown-app` puts the same `deck.md` inside a Vite project:

```bash
npm create narro@latest my-deck -- --template markdown-app
```

## React mode: scaffold a project

```bash
npm create narro@latest my-deck
cd my-deck
npm install
npm run dev
```

`npm create narro` prompts for a template. To skip the prompt:

```bash
npm create narro@latest my-deck -- --template developer
```

### Templates

<!-- generated:templates -->
**Markdown**

| Template | What it is | Notes |
| --- | --- | --- |
| `markdown-minimal` | One `deck.md` and a pinned CLI. Nothing to build. | **start here** |
| `markdown-app` | The same deck inside a Vite project, for React components and custom CSS. | — |
| `markdown-docs` | Documentation-shaped deck: long code samples, wide tables. | ships an example deck |

**React**

| Template | What it is | Notes |
| --- | --- | --- |
| `minimal` | Three slides and nothing else. Start here to write your own. | **start here** |
| `corporate` | Restrained business deck, dark theme. | ships an example deck |
| `developer` | Code-heavy technical talk with terminal chrome. | ships an example deck |
| `creative` | Bold colour and large type. | ships an example deck |
| `bold-statement` | One idea per slide, very large type. | ships an example deck |
| `visual-story` | Full-bleed imagery with overlay text. | ships an example deck |
| `data-narrative` | Charts and figures, light theme. | ships an example deck |
| `startup-pitch` | Ten-slide investor pitch, filled in. | ships an example deck |
| `tech-conference` | Conference talk with a title card and code slides. | ships an example deck |
| `template0` | Reference deck exercising every component. Read it, do not start from it. | ships an example deck |
<!-- /generated:templates -->

Pass `--mode markdown` to be prompted with only the markdown templates, or
`npx create-narro --list` to print the table above from the version you have
installed.

**Scripting it.** `--yes` takes the default for anything you did not pass and
never opens a prompt, which is what a CI job or an agent needs:

```bash
npx create-narro my-deck --yes --skip-install                      # minimal, React
npx create-narro my-deck --yes --mode markdown --skip-install      # markdown-minimal
npx create-narro my-deck --yes --template markdown-app --skip-install
```

A `--template` that is not on the list above is an error naming the ones that
are — it is never quietly replaced with a default.

## Adding Narro to an existing app

```bash
npm install @getnarro/core @getnarro/shared-ui
```

`react` and `react-dom` 19+ are peer dependencies. Styling assumes Tailwind CSS
v4; add `@tailwindcss/vite` to your Vite config if you do not have it.

## What a scaffolded project looks like

```bash
my-deck/
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── src/
    ├── App.tsx       # the deck — this is the file you edit
    ├── main.tsx      # mounts App
    └── index.css     # Tailwind entry
```

A markdown template swaps `src/App.tsx` for a `deck.md` at the project root and
a `src/main.tsx` that mounts the compiled deck.

## Scripts

| Command | What it does |
| --- | --- |
| `npm run dev` | Dev server with hot reload, on <http://localhost:5173> |
| `npm run build` | Production build into `dist/` |
| `npm run preview` | Serve the built deck |
| `npm run fit` | Measure the built deck in a browser and report slides that clip |
| `npm run lint` | The CI gate — `narro check --strict` for a markdown deck, Prettier for a React one |

## Which versions this reference describes

The `@getnarro/*` packages version independently: a fix to the CLI does not move
`core`, and `@getnarro/docs` has its own release line. So the reference you are
reading can describe a runtime newer than the one your project installed, and
nothing about that failure is loud — a prop that does not exist yet is simply
ignored.

Two things make it visible:

- `narro check` prints the version of the CLI, the dialect, `core` and
  `shared-ui` that actually answered. That is the runtime you have.
- This copy of the documentation was generated against:

<!-- generated:runtime-versions -->
| Package | Version this reference was generated against |
| --- | --- |
| `@getnarro/cli` | 0.8.0 |
| `@getnarro/core` | 0.6.0 |
| `@getnarro/docs` | 0.10.0 |
| `@getnarro/markdown` | 0.9.0 |
| `@getnarro/marketplace` | 0.2.0 |
| `@getnarro/mcp-server` | 0.3.10 |
| `@getnarro/shared-ui` | 0.6.0 |
| `create-narro` | 0.8.0 |
<!-- /generated:runtime-versions -->

If those disagree and something documented is missing, the runtime is older than
the reference. `npm i -D @getnarro/docs` installs the documentation over the same
registry that installed your packages, so it pins alongside them.