Cómo integrar Keystatic en Astro paso a paso

Astro y Keystatic hacen buena pareja: un generador pensado para sitios rápidos y un CMS que guarda el contenido como archivos Markdown en tu repositorio. El resultado es una web estática, veloz y con un panel de edición cómodo, sin base de datos.

Si aún dudas entre frameworks, antes te puede servir la comparativa de Astro vs Next.js para landing pages. Aquí vamos al grano con la integración, siguiendo la documentación oficial de Keystatic.

Qué necesitas

• Un proyecto Astro (nuevo con npm create astro@latest o uno existente).
• Node.js y el proyecto en un repositorio Git.
• El panel de Keystatic se renderiza en el servidor, así que para desplegarlo necesitarás un adaptador SSR (por ejemplo @astrojs/node o el de Vercel).

Paso 1: Instala las dependencias

npx astro add react markdoc
npm install @keystatic/core @keystatic/astro

npx astro add react markdoc instala y configura las integraciones de React (el panel de Keystatic usa React) y Markdoc; luego añadimos los paquetes de Keystatic.

Paso 2: Configura Astro

Añade la integración de Keystatic en astro.config.mjs, junto a React y Markdoc.

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import markdoc from '@astrojs/markdoc';
import keystatic from '@keystatic/astro';

export default defineConfig({
  integrations: [react(), markdoc(), keystatic()],
});

Paso 3: Crea la configuración de Keystatic

En la raíz del proyecto crea keystatic.config.ts con tu almacén y tus colecciones. Es la misma configuración que en Next.js: aquí definimos una colección de posts en src/content/posts.

import { config, fields, collection } from '@keystatic/core';

export default config({
  storage: {
    kind: 'local',
  },
  collections: {
    posts: collection({
      label: 'Posts',
      slugField: 'title',
      path: 'src/content/posts/*',
      format: { contentField: 'content' },
      schema: {
        title: fields.slug({ name: { label: 'Title' } }),
        content: fields.markdoc({ label: 'Content' }),
      },
    }),
  },
});

Paso 4: Abre el panel

La integración de Keystatic ya expone el panel. Arranca el proyecto con npm run dev y abre http://127.0.0.1:4321/keystatic: desde ahí creas y editas tus entradas, que se guardan como archivos en src/content/posts. Recuerda que, como el panel es dinámico, al desplegar necesitas un adaptador SSR configurado.

Paso 5: Muestra el contenido

Como el contenido vive en src/content, puedes leerlo con las content collections nativas de Astro y su función getCollection.

---
import { getCollection } from 'astro:content';
const posts = await getCollection('posts');
---
<ul>
  {posts.map((post) => (
    <li><a href={`/posts/${post.slug}`}>{post.data.title}</a></li>
  ))}
</ul>

Para una entrada individual usas getEntry y el componente <Content /> que Astro genera a partir del Markdown. Así cierras el ciclo: editas en el panel y Astro renderiza el HTML final.

Lo que decide si funciona en producción

En Astro el panel de Keystatic es dinámico, y ahí está la diferencia con un sitio estático puro: aunque las páginas públicas se generen como HTML, el panel de edición necesita un servidor que lo ejecute. Por eso el adaptador SSR no es un detalle del final, es una decisión de arquitectura.

Conviene probar el despliegue con el adaptador desde el principio, aunque aún no tengas contenido. Así descubres temprano si tu hosting lo soporta y cuánto cuesta. Después sí: modo local para desarrollar, GitHub para producción, y el cliente editando sin tocar código.

Si tu equipo no quiere mantener un servidor para el panel, la alternativa honesta es otra: un CMS gestionado o un flujo de edición directo en el repositorio. Keystatic brilla cuando quieres un panel amigable sobre archivos, no cuando quieres cero infraestructura.

¿Necesitas una web en Astro rápida y fácil de editar? En Codegea la montamos con el CMS adecuado para tu caso. Mira el servicio de integración de CMS o cuéntanos tu proyecto desde la página de contacto.