Bien démarrer
Un site qui fonctionne en une minute.

Prérequis

• Node.js 22.12 ou plus récent (vérifiez avec node --version)
• npm, qui est fourni avec Node.js
• Facultatif : Chrome, si vous voulez des audits Lighthouse en local

vagejs fonctionne sur macOS, Windows et Linux. Les sites qu'il construit sont de simples fichiers : les visiteurs n'ont besoin de rien de particulier.

Créer un nouveau site

npm create vagejs@latest my-site

Cette commande crée un dossier my-site avec des pages d'exemple, un layout, des réglages, un fichier AGENTS.md pour les assistants IA et des workflows GitHub. Le dossier ne doit pas encore exister, ou doit être vide.

Elle demande ensuite Install and start the site now? (installer et lancer le site maintenant ?). Appuyez sur Entrée, et elle installe tout avec le gestionnaire de paquets que vous avez utilisé pour la lancer (npm, pnpm, yarn ou bun). Puis elle vous demande avec quoi vous voulez construire le site :

Build your site with:
  1. Claude Code
  2. Codex
  3. The browser editor (no coding tool needed)
  4. Just open the site

Elle ne liste que les assistants qu'elle trouve sur votre ordinateur : Claude Code, Codex, Gemini CLI, VS Code (Copilot chat) et Cursor. Dans tous les cas, votre site s'ouvre dans le navigateur.

• Claude Code, Codex ou Gemini CLI démarrent directement dans le terminal, avec un premier prompt qui demande à votre assistant de lire le fichier AGENTS.md du site, de vous poser des questions sur votre activité et de passer en revue les prochaines étapes avec vous. Le site continue de tourner pendant que l'assistant est ouvert, et Ctrl+C interrompt l'assistant, pas le site. S'il vous demande si vous faites confiance au dossier, répondez oui : c'est le site que vous venez de créer.
• VS Code ouvre son chat avec ce premier prompt. Cursor ouvre le dossier, et le prompt est affiché pour que vous le colliez dans son chat.
• L'éditeur dans le navigateur s'ouvre à côté du site, avec une liste de prochaines étapes pour votre nouveau site.

Ou modifiez simplement src/pages/index.md, enregistrez, et la page se recharge.

Quand c'est un assistant IA, un script ou une CI qui lance la commande, elle ne pose aucune question et ne démarre rien. Elle affiche à la place les prochaines étapes (cd my-site, npm install, npm start) et demande aux assistants de lire AGENTS.md et de parcourir npx vage next-steps avec vous, en vous demandant les vraies informations. La commande se termine toujours. Ajoutez -- --yes pour installer et lancer sans question, ou -- --no-install pour créer uniquement les fichiers.

Pour relancer le site plus tard, ouvrez un terminal dans le dossier et lancez npm start :

cd my-site
npm start

Vous préférez l'ouvrir vous-même ? npm run dev lance le même serveur sans ouvrir de navigateur et affiche son adresse. Si le navigateur affiche HTTP 431, consultez le dépannage.

Ce que vous obtenez

Vous voulez voir le résultat ? Les exemples (en anglais) présentent trois sites terminés créés à partir du même modèle, avec leur code source.

my-site/
├── src/pages/         every .md or .mdx file is a page (a blog index is included)
├── src/layouts/       the HTML around each page
├── public/            files copied as-is (favicons, images)
├── vage.config.ts     site settings
├── links.lock.json    the websites your pages may link to
├── AGENTS.md          instructions for AI coding assistants
└── .github/           CI checks, dependency updates and an optional live-site check

Par défaut, les pages sont en Markdown simple (.md). Les pages .mdx et les layouts React ou Vue nécessitent quelques paquets supplémentaires : voir React, Vue et MDX. Pour des pages en plusieurs langues, voir les sites multilingues.

Les commandes du quotidien

Toutes les commandes et options se trouvent dans la référence de la CLI.

Ajouter vagejs à un projet existant

npm install --save-dev vagejs

Créez ensuite src/pages/index.md (avec un title dans son frontmatter) et un vage.config.ts :

import { defineConfig } from "vagejs";

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

Ajoutez des scripts à package.json pour que tout le monde lance les mêmes commandes :

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

Mettre à jour vagejs

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

Tant que vagejs est en 0.x, une nouvelle version mineure (de 0.10 à 0.11, par exemple) peut changer le comportement. Lisez d'abord le changelog. Figez le rule pack avec guidelines: { rulePack: "<version>" } si vous voulez que les informations sur les fournisseurs, comme les noms des robots, ne changent que lorsque vous le décidez.

Avant de publier

1. Réglez site dans vage.config.ts sur votre vrai domaine. vage check vous avertit tant qu'il vaut encore https://example.com.
2. Lancez npm run check et corrigez chaque erreur. Vérifications et audits explique chaque résultat.
3. Choisissez un hébergeur dans Déploiement.

Ensuite : écrivez vos premières pages. Pour des explications plus longues, comme l'ajout d'une deuxième langue ou d'un composant interactif, consultez les guides.