# Installation

> System requirements, creating a new vagejs site, adding vagejs to an existing project, and updating safely.

## Requirements

-   **Node.js 22.12 or newer** (check with `node --version`)
-   npm, which comes with Node.js
-   Optional: Chrome, if you want local Lighthouse audits

vagejs runs on macOS, Windows and Linux. The sites it builds are plain files, so visitors don't need anything special.

## Create a new site

```bash
npm create vagejs@latest my-site
```

This makes a `my-site` folder with example pages, a layout, settings, `AGENTS.md` for AI assistants and GitHub workflows. The folder must not exist yet, or must be empty.

## Add vagejs to an existing project

```bash
npm install --save-dev vagejs
```

Then create `src/pages/index.md` (with a `title` in its frontmatter) and a `vage.config.ts`:

```ts
import { defineConfig } from "vagejs";

export default defineConfig({
  site: "https://example.com",
  title: "My Website",
  lang: "en",
});
```

Add scripts to `package.json` so everyone runs the same commands:

```json
{
  "scripts": { "dev": "vage dev", "build": "vage build", "check": "vage check", "audit": "vage audit", "preview": "vage preview" }
}
```

## Update

```bash
npm outdated vagejs           # see what's available
npm install vagejs@latest     # newest version
npm run check                 # make sure the site still passes
```

While vagejs is 0.x, a new minor version (0.2 to 0.3) can change behavior. Read the [changelog](https://vagejs.com/changelog/) first. Pin the rule pack with `guidelines: { rulePack: "<version>" }` if you want provider facts, like crawler names, to change only when you choose.