# Primeros pasos Un sitio funcionando en un minuto.

> Cómo instalar vagejs y empezar. Requisitos, un comando para crear un sitio, cómo añadir vagejs a un proyecto existente y cómo actualizarlo con seguridad.

Para instalar vagejs necesitas Node.js 22.12 o una versión más reciente. Después, `npm create vagejs@latest my-site` crea un sitio nuevo, lo instala y lo abre en tu navegador. Esta página también explica cómo añadir vagejs a un proyecto existente y cómo actualizarlo.

Actualizado el 28 de octubre de 2026

## Requisitos

-   **Node.js 22.12 o una versión más reciente** (compruébalo con `node --version`)
-   npm, que viene con Node.js
-   Opcional: Chrome, si quieres auditorías de Lighthouse en local

vagejs funciona en macOS, Windows y Linux. Los sitios que genera son archivos normales, así que los visitantes no necesitan nada especial.

## Crea un sitio nuevo

terminal

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

Esto crea una carpeta `my-site` con páginas de ejemplo, una plantilla, la configuración, `AGENTS.md` para los asistentes de IA y flujos de trabajo de GitHub. La carpeta no debe existir todavía, o debe estar vacía.

Luego pregunta **Install and start the site now?** (¿instalar e iniciar el sitio ahora?). Pulsa Enter e instalará todo con el gestor de paquetes con el que lo ejecutaste (npm, pnpm, yarn o bun). Después te pregunta con qué quieres crear el sitio:

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

Solo muestra los asistentes que encuentra en tu ordenador: Claude Code, Codex, Gemini CLI, VS Code (chat de Copilot) y Cursor. Tu sitio se abre en el navegador en cualquier caso.

-   **Claude Code, Codex o Gemini CLI** se inician ahí mismo, en la terminal, con un primer prompt que le pide a tu asistente que lea el `AGENTS.md` del sitio, te pregunte por tu negocio y siga contigo los siguientes pasos. El sitio sigue funcionando mientras el asistente está abierto, y Ctrl+C interrumpe al asistente, no al sitio. Si te pregunta si confías en la carpeta, elige que sí: es el sitio que acabas de crear.
-   **VS Code** abre su chat con ese primer prompt. **Cursor** abre la carpeta, y el prompt se muestra en pantalla para que lo pegues en su chat.
-   **El editor del navegador** se abre junto al sitio, con una lista de [siguientes pasos](https://vagejs.com/docs/content-authoring/#edit-in-your-browser) para tu sitio nuevo.

O simplemente edita `src/pages/index.md`, guarda, y la página se recarga.

Cuando el comando lo ejecuta un asistente de IA, un script o un sistema de CI, no pregunta ni inicia nada. En su lugar muestra los siguientes pasos (`cd my-site`, `npm install`, `npm start`) y les dice a los asistentes que lean `AGENTS.md` y repasen `npx vage next-steps` contigo, pidiéndote los datos reales. El comando siempre termina. Añade `-- --yes` para instalar e iniciar sin preguntar, o `-- --no-install` para solo crear los archivos.

Para volver a iniciar el sitio más tarde, abre una terminal en la carpeta y ejecuta `npm start`:

terminal

```
cd my-site
npm start
```

¿Prefieres abrirlo tú? `npm run dev` inicia el mismo servidor sin abrir el navegador y muestra su dirección. Si el navegador muestra **HTTP 431**, consulta [solución de problemas](https://vagejs.com/docs/troubleshooting/#http-431-in-the-browser).

## Qué obtienes

¿Quieres ver a dónde lleva esto? La [sección de ejemplos](https://vagejs.com/showcase/) (en inglés) tiene tres sitios terminados creados a partir de esta misma plantilla, con su código fuente.

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

Por defecto, las páginas son Markdown normal (`.md`). Las páginas `.mdx` y las plantillas de React o Vue necesitan algunos paquetes más: consulta [React, Vue y MDX](https://vagejs.com/docs/components/). Para páginas en más de un idioma, consulta [sitios multilingües](https://vagejs.com/docs/multi-language/).

## Comandos de cada día

| Comando | Qué hace |
| --- | --- |
| `npm start` | Servidor de desarrollo con recarga en directo, abierto en tu navegador |
| `npm run dev` | El mismo servidor sin abrir el navegador (el que usan los asistentes de IA) |
| `npm run check` | Encuentra enlaces rotos y problemas de SEO, accesibilidad y spam; no escribe nada |
| `npm run build` | Escribe el sitio terminado en `dist/` |
| `npm run audit` | Límites de peso de página y revisiones automáticas de accesibilidad |
| `npm run preview` | Sirve `dist/` como lo haría un hosting estático |

Todos los comandos y opciones están en la [referencia de la CLI](https://vagejs.com/docs/cli/).

## Añade vagejs a un proyecto existente

terminal

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

Después crea `src/pages/index.md` (con un `title` en su frontmatter) y un `vage.config.ts`:

TypeScript

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

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

Añade scripts a `package.json` para que todo el mundo ejecute los mismos comandos:

JSON

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

## Actualiza vagejs

terminal

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

Mientras vagejs esté en 0.x, una nueva versión menor (de 0.10 a 0.11, por ejemplo) puede cambiar su comportamiento. Lee primero el [registro de cambios](https://vagejs.com/changelog/). Fija el paquete de reglas con `guidelines: { rulePack: "<version>" }` si quieres que los datos de proveedores, como los nombres de los rastreadores, cambien solo cuando tú lo decidas.

## Antes de publicar

1.  Pon en `site`, dentro de `vage.config.ts`, tu dominio real. `vage check` te avisa mientras siga siendo `https://example.com`.
2.  Ejecuta `npm run check` y corrige todos los errores. [Revisiones y auditorías](https://vagejs.com/docs/checks/) explica cada resultado.
3.  Elige un hosting en [Publicación](https://vagejs.com/docs/deployment/).

Siguiente: [escribe tus primeras páginas](https://vagejs.com/docs/content-authoring/). Para recorridos más largos, como añadir un segundo idioma o un componente interactivo, consulta las [guías](https://vagejs.com/guides/).