Installation
Requirements and updates.

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

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

npm install --save-dev vagejs

Then create src/pages/index.md (with a title in its frontmatter) and a vage.config.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:

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

Update

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 first. Pin the rule pack with guidelines: { rulePack: "<version>" } if you want provider facts, like crawler names, to change only when you choose.