Instalación

Versión 0.x

El paquete es pre-1.0: hasta la 1.0.0, una versión menor puede romper. Cada ruptura viene marcada como BREAKING en el CHANGELOG, y las que cambian el schema generado traen guía de migración. Fija la versión en tu package.json y lee el changelog antes de subirla. Lo que todavía le falta al paquete está en Limitaciones.

Requisitos

• Node 24 o superior.
• Una cuenta de Cloudflare.
• Un proyecto Astro con el adaptador de Cloudflare. Si no lo tienes, el primer paso lo crea.
• Un token de GitHub con permiso read:packages — el paquete se publica en GitHub Packages, y GitHub Packages exige autenticación también para leer, aunque el paquete sea público. Se genera en Settings → Developer settings → Personal access tokens.

Crea el proyecto

1. Crea la aplicación con la CLI de Cloudflare, eligiendo Astro y la plantilla en blanco:

   pnpm create cloudflare@latest mi-sitio --framework=astro

2. Añade React, que es lo que usa el administrador:

   pnpm astro add react

3. Apunta el scope @kevolution-co a GitHub Packages, con un .npmrc en la raíz del proyecto:

   .npmrc

   @kevolution-co:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

   ${GITHUB_TOKEN} lo expande npm desde tu entorno al leer el fichero, así que el token no queda escrito en el repositorio. Sin este paso el add del punto siguiente falla con un 401.

4. Exporta el token e instala el CMS:

   export GITHUB_TOKEN=ghp_…
   pnpm add @kevolution-co/cms

Crea los recursos de Cloudflare

Cada comando imprime un identificador que hay que pegar en wrangler.jsonc.

npx wrangler d1 create mi-sitio
npx wrangler r2 bucket create mi-sitio
npx wrangler kv namespace create KV
npx wrangler kv namespace create SESSION

wrangler.jsonc

{
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "mi-sitio",
      "database_id": "<id>",
      "migrations_dir": "migrations",
      "migrations_pattern": "migrations/*/migration.sql"
    }
  ],
  "r2_buckets": [{ "binding": "R2", "bucket_name": "mi-sitio" }],
  "kv_namespaces": [
    { "binding": "SESSION", "id": "<id>" },
    { "binding": "KV", "id": "<id>" }
  ],
  "send_email": [{ "name": "EMAIL" }]
}

nodejs_compat es obligatorio

La autenticación usa node:crypto. Sin esa marca de compatibilidad el sitio falla al arrancar.

Y el secreto con el que se firman las sesiones, que no es un binding sino una variable:

openssl rand -base64 32

.dev.vars

BETTER_AUTH_SECRET=el-valor-que-acabas-de-generar

En producción, npx wrangler secret put BETTER_AUTH_SECRET. .dev.vars va en el .gitignore. Los detalles, en Autenticación.

migrations_pattern tampoco es opcional

drizzle-kit escribe migrations/<fecha>_<nombre>/migration.sql, un nivel más hondo que el migrations/*.sql que wrangler busca por defecto. Sin esa línea, wrangler d1 migrations apply no encuentra nada y responde «No migrations to apply!» aunque las tengas ahí delante.

Por qué hay dos namespaces de KV

Solo uno es del CMS. KV es el suyo, y toda clave que escribe lleva prefijo: hoy la única es settings:site, los ajustes del sitio. La configuración de OAuth vivirá en settings:auth-providers cuando existan los proveedores sociales, que todavía no.

SESSION es de @astrojs/cloudflare, que guarda ahí las sesiones de Astro. Tienes que declararlo aunque tú no lo uses: si no aparece en kv_namespaces, el adaptador sustituye el array entero por el suyo y KV desaparece sin avisar. El sitio arranca, pero env.KV es undefined.

Cómo se leen los bindings

Desde Astro 7 y @astrojs/cloudflare 14, Astro.locals.runtime.env ya no existe. Los bindings se importan:

import { env } from 'cloudflare:workers'

El CMS lo hace por ti; solo lo necesitas si quieres acceder a un binding directamente.

Configura el email

Enviar correo transaccional —verificación de cuenta, recuperación de contraseña— exige tres cosas:

1. Un plan Workers de pago. Email Sending no está en el gratuito.
2. Un dominio que use DNS de Cloudflare, dado de alta en Compute → Email Service → Email Sending.
3. Que la dirección remitente pertenezca a ese dominio.

Y un bloque email en tu config, con esa dirección:

cms.config.ts

import { defineConfig } from '@kevolution-co/cms'

export default defineConfig({
  email: { from: 'noreply@tudominio.com', siteName: 'Mi sitio' },
  collections: [],
})

Este bloque son los valores de arranque. Los mismos tres se pueden cambiar después sin desplegar desde los ajustes del sitio, que viven en KV.

Sin esto no entra nadie

La verificación de correo es obligatoria: una cuenta no inicia sesión hasta confirmar su dirección. Si falta el binding o from está vacío, la primera lectura de sesión falla con MISSING_EMAIL. El contenido y la API REST siguen funcionando, pero nadie puede autenticarse.

En desarrollo local no hace falta nada de esto: wrangler dev simula el envío y vuelca el contenido del mensaje a un fichero cuya ruta imprime en la consola. Un from cualquiera vale mientras no sea vacío.

Si añades "remote": true al binding pierdes esa simulación y empiezas a enviar correo real desde tu máquina, con los tres requisitos de arriba ya cumplidos. Déjalo fuera mientras desarrolles.

Los detalles están en Email.

Define tu primera colección

cms.config.ts

import { defineCollection, defineConfig } from '@kevolution-co/cms'

export default defineConfig({
  collections: [
    defineCollection({
      slug: 'posts',
      admin: { useAsTitle: 'title' },
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'slug', type: 'text', required: true, unique: true, index: true },
        { name: 'body', type: 'textarea' },
      ],
    }),
  ],
})

astro.config.mjs

import cloudflare from '@astrojs/cloudflare'
import react from '@astrojs/react'
import cms from '@kevolution-co/cms/astro'
import { defineConfig } from 'astro/config'
import cmsConfig from './cms.config'

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
  integrations: [react(), cms(cmsConfig)],
})

output: 'server', el adaptador de Cloudflare y @astrojs/react son obligatorios: la integración comprueba los tres al arrancar y falla nombrando el que falte. La referencia completa —opciones, rutas inyectadas y qué pone en Astro.locals.cms— está en Integración de Astro.

Genera y aplica las migraciones

Tu configuración no crea tablas por sí sola: produce migraciones SQL que revisas antes de aplicar.

Instala drizzle-kit, que es quien escribe el SQL, y añade su configuración:

pnpm add -D drizzle-kit

drizzle.config.ts

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: 'sqlite',
  schema: './.cms/schema.ts',
  out: './migrations',
})

Genera:

pnpm cms db:migrate

✔ Cargando config
✔ Emitiendo .cms/
2 colecciones desde /mi-sitio/cms.config.ts
  /mi-sitio/.cms/schema.ts
  /mi-sitio/.cms/types.d.ts

Son dos colecciones y tú solo has declarado una: users la añade el CMS por su cuenta, porque es la tabla de usuarios de la autenticación.

Lee el SQL que ha salido en migrations/ y, si estás conforme, aplícalo:

pnpm cms db:apply

Aplicando en local sobre el binding DB
🚣 8 commands executed successfully.

No hace falta que le digas cuál es la base: la saca del binding de tu wrangler.jsonc. Si el SQL no te convence, pnpm cms db:pop borra esa migración y vuelves a empezar.

Añade .cms/ a tu .gitignore —se regenera siempre— y commitea migrations/.

La integración vuelve a generar .cms/ en cada arranque y vigila tu cms.config.ts, así que en desarrollo no tienes que llamar a db:generate a mano. Lo que nunca es automático es generar o aplicar una migración: eso siempre lo pides tú.

Por último, deja que TypeScript vea los tipos generados:

tsconfig.json

{
  "include": [
    ".astro/types.d.ts",
    "./.cms/types.d.ts",
    "**/*"
  ]
}

Hay que nombrarlo: un comodín no entra en un directorio cuyo nombre empieza por punto. Con esa línea, Astro.locals.cms.collections.posts queda tipado con tus colecciones sin que declares nada más.

No todos los cambios cuestan lo mismo

Añadir un campo es un ALTER TABLE … ADD y quitarlo un DROP COLUMN. Cambiarle el tipo recrea la tabla copiando las filas, que en una grande de D1 puede pasarse de los límites de la consulta. Y renombrar todavía no está soportado: db:migrate se planta sin generar nada. Los detalles, en Schema y migraciones.

El ciclo completo, con el aviso de deriva y lo que SQLite no te deja hacer, está en Schema y migraciones.

Arranca

pnpm dev

Ya puedes leer contenido desde una plantilla, con los tipos de tus colecciones:

src/pages/index.astro

---
export const prerender = false

const { docs } = await Astro.locals.cms.collections.posts.find({ limit: 5 })
---

<ul>{docs.map((post) => <li>{post.title}</li>)}</ul>

prerender = false es imprescindible en cualquier página que lea contenido: en build no hay bindings de Cloudflare y no hay nada que leer.

También responden /api/cms/posts —los seis endpoints de la API REST— y /admin, que en una instalación vacía te lleva al asistente de configuración: pide los ajustes del sitio y la primera cuenta, y con eso cierra el registro.

Leer por la API REST pide sesión

Un GET a /api/cms/<slug> responde 401 salvo que la colección declare access: { read: 'public' }. La sesión se obtiene por /api/auth/* y viaja en una cookie. Desde una plantilla, Astro.locals.cms no pasa por ahí y lee siempre.

Todavía no hay roles

Cualquier cuenta con sesión puede leer, escribir y borrar en cualquier colección. El registro sí está cerrado —lo cierra la primera cuenta, la que crea el asistente de /admin—, pero da acceso solo a quien te fíes por completo del sitio entero. Ver Autenticación.