> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertz.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Vertz and configure the compiler

## Install the runtime

First, install the `vtz` CLI — a standalone binary that includes the dev server, test runner, and package manager:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/vertz-dev/vertz/main/install.sh | sh
```

This installs to `~/.vtz/bin/` and works on macOS and Linux (both x64 and ARM). See [Runtime](/runtime) for alternative installation methods and available commands.

Verify it's installed:

```bash theme={null}
vtz --version
```

## Create a new project (recommended)

The fastest way to get started:

```bash theme={null}
vtz create vertz my-app
cd my-app
vtz install
vtz dev
```

This scaffolds a project with the compiler, dev server, SSR, and a starter template — everything configured and ready to go.

Available templates: `todo-app` (default), `hello-world` (minimal counter), `landing-page` (multi-page marketing site). Pass `--template <name>` to choose:

```bash theme={null}
vtz create vertz my-app --template landing-page
```

<Note>
  Alternatively, you can use npx: `npx @vertz/create-vertz-app my-app --template landing-page`
</Note>

## Manual setup

<Info>
  **AI coding agents:** Use `vtz create vertz my-app` above instead. The manual setup below is for
  adding Vertz to an existing project that already has its own build pipeline.
</Info>

Add Vertz to an existing project.

### 1. Install packages

```bash theme={null}
vtz add @vertz/ui @vertz/theme-shadcn
```

`@vertz/ui` is the UI runtime (JSX, signals, router, forms). Add `@vertz/server`, `@vertz/db`, `@vertz/schema`, `@vertz/fetch`, etc. as you need them. `@vertz/theme-shadcn` provides design tokens for the `css()` utility (optional but recommended).

<Note>
  A convenience meta package named `vertz` re-exports everything under subpaths (`vertz/ui`,
  `vertz/server`, ...). It works, but we recommend the granular `@vertz/*` packages — smaller
  installs, clearer dependencies, and LLM coding assistants pick the right imports more reliably.
</Note>

### 2. Configure TypeScript

Update your `tsconfig.json` to use the Vertz JSX runtime:

```json theme={null}
{
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx",
    "jsxImportSource": "@vertz/ui",
    "moduleResolution": "bundler",
    "target": "ESNext",
    "module": "ESNext"
  }
}
```

The key settings are `jsx: "react-jsx"` and `jsxImportSource: "@vertz/ui"` — this tells TypeScript to use the Vertz JSX factory instead of React's.

### 3. Create the entry point

Create `src/app.tsx`:

```tsx theme={null}
import { mount } from '@vertz/ui';

function App() {
  return <h1>Hello, Vertz!</h1>;
}

mount(App);
```

### 4. Start the dev server

The Vertz CLI provides a dev server with SSR and HMR:

```bash theme={null}
vtz dev
```

Or add it to your `package.json` scripts:

```json theme={null}
{
  "scripts": {
    "dev": "vertz dev",
    "build": "vertz build",
    "start": "vertz start"
  }
}
```

The dev server:

* Compiles `.tsx` files through the Vertz compiler plugin
* Server-side renders on first load
* Hot-reloads with state preservation (HMR)
* Extracts and injects scoped CSS

<Note>
  The Vertz runtime (`vtz`) starts in \~5ms with built-in SSR, HMR, and test runner. See
  [Runtime](/runtime) for installation and available commands.
</Note>

## Project structure

See [Project Structure](/project-structure) for a complete guide to file conventions, including server entry points, app type detection, and how `vertz dev` decides what to run.

## Next steps

<CardGroup cols={2}>
  <Card title="Components" icon="puzzle-piece" href="/guides/ui/components">
    Write your first component with props and children.
  </Card>

  <Card title="Styling" icon="paintbrush" href="/guides/ui/styling">
    Scoped CSS with `css()` and parameterized styles with `variants()`.
  </Card>
</CardGroup>