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

> Comment installer vagejs et démarrer : prérequis, une commande pour créer un site, ajouter vagejs à un projet existant et le mettre à jour sans risque.

Pour installer vagejs, il vous faut Node.js 22.12 ou plus récent. Ensuite, `npm create vagejs@latest my-site` crée un nouveau site, l'installe et l'ouvre dans votre navigateur. Cette page explique aussi comment ajouter vagejs à un projet existant et comment le mettre à jour.

Mis à jour le 28 octobre 2026

## 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

terminal

```
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](https://vagejs.com/docs/content-authoring/#edit-in-your-browser) 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` :

terminal

```
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](https://vagejs.com/docs/troubleshooting/#http-431-in-the-browser).

## Ce que vous obtenez

Vous voulez voir le résultat ? Les [exemples](https://vagejs.com/showcase/) (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](https://vagejs.com/docs/components/). Pour des pages en plusieurs langues, voir [les sites multilingues](https://vagejs.com/docs/multi-language/).

## Les commandes du quotidien

| Commande | Ce qu'elle fait |
| --- | --- |
| `npm start` | Serveur de développement avec rechargement en direct, ouvert dans votre navigateur |
| `npm run dev` | Le même serveur sans ouvrir de navigateur (ce qu'utilisent les assistants IA) |
| `npm run check` | Trouve les liens cassés et les problèmes de SEO, d'accessibilité et de spam ; n'écrit rien |
| `npm run build` | Écrit le site final dans `dist/` |
| `npm run audit` | Budgets de poids des pages et vérifications automatiques de l'accessibilité |
| `npm run preview` | Sert `dist/` comme le ferait un hébergeur statique |

Toutes les commandes et options se trouvent dans la [référence de la CLI](https://vagejs.com/docs/cli/).

## Ajouter vagejs à un projet existant

terminal

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

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

TypeScript

```
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 :

JSON

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

## Mettre à jour vagejs

terminal

```
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](https://vagejs.com/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](https://vagejs.com/docs/checks/) explique chaque résultat.
3.  Choisissez un hébergeur dans [Déploiement](https://vagejs.com/docs/deployment/).

Ensuite : [écrivez vos premières pages](https://vagejs.com/docs/content-authoring/). Pour des explications plus longues, comme l'ajout d'une deuxième langue ou d'un composant interactif, consultez les [guides](https://vagejs.com/guides/).