Integración de Astro
La única pieza que instalas. Monta el admin, la API REST y
Astro.locals.cms a partir de tu cms.config.ts.
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)],})El config se importa y se pasa. La integración lo usa para las rutas y el codegen, y sus propias rutas
lo vuelven a importar del fichero, así que el objeto que le pases y el que lea el worker tienen que ser
el mismo: importa tu cms.config.ts y no construyas otro ahí mismo.
Opciones
Sección titulada «Opciones»function cms(config: ResolvedConfig, options?: IntegrationOptions): AstroIntegration
interface IntegrationOptions { bindings?: { db?: string; bucket?: string; kv?: string; email?: string } cors?: string[] skipCodegen?: boolean config?: string}| Opción | Por defecto | Qué hace |
|---|---|---|
bindings.db |
'DB' |
Nombre del binding de D1 del que sale el contenido |
bindings.bucket |
'R2' |
Binding de R2 del perfil de almacenamiento default: donde van los ficheros de toda colección con upload que no nombra otro perfil. Ver Almacenamiento |
bindings.kv |
'KV' |
Binding de KV, donde viven los ajustes del sitio bajo el prefijo settings: y cada global bajo global: |
bindings.email |
'EMAIL' |
Binding de Email Sending, del que salen los correos de verificación y restablecimiento. Ver Email |
cors |
sin CORS | Orígenes permitidos en la API REST. Ver CORS |
skipCodegen |
false |
No regenera .cms/ al arrancar. Exige que ya exista |
config |
busca cms.config.{ts,js,mjs} en la raíz |
Ruta explícita al config |
Almacenamiento
Sección titulada «Almacenamiento»Dónde guarda cada colección sus ficheros no es una opción de la integración: se declara en el config,
con storage en defineConfig y upload.storage / media.storage por nombre de perfil (ver
Almacenamiento de ficheros). La integración solo pone dos cosas:
- El middleware que inyecta pasa el
envdel Worker al CMS, y es ahí, al primer acceso de cada isolate, donde se leen y se comprueban los secretos de los perfiless3en uso y los bindings de losr2conbindingpropio. Un secreto ausente o mal formado (MISSING_STORAGE_SECRET,INVALID_STORAGE_SECRET) o un binding que falta (MISSING_BUCKET) hace fallar toda petición que toque el CMS hasta que se corrige, con un mensaje que nombra la variable y nunca su valor. - La configuración pública que el navegador recibe lleva de cada colección con
uploadsolomimeTypesymaxFileSize.storage, los nombres de variable de las credenciales, elendpointy elbucketno salen del servidor: ni en el HTML del panel ni en los datos de sus páginas.
El panel decide si ofrece subir ficheros preguntando al servidor si la colección tiene dónde guardar
(su perfil se resolvió), no mirando solo el binding bucket: un proyecto cuyo perfil default sea otro
bucket de R2 por su binding, o un servicio S3, ya no necesita el binding R2.
Comprobaciones previas
Sección titulada «Comprobaciones previas»Se hacen en astro:config:setup, antes de cablear nada: un error al arrancar es infinitamente mejor
que un undefined a mitad de una petición. Cada fallo dice qué instalar y qué línea añadir.
| Requisito | Por qué |
|---|---|
@astrojs/cloudflare |
Los bindings solo existen en el runtime de Workers |
@astrojs/react |
El admin son islas de React |
output: 'server' |
El admin y la API se renderizan bajo demanda |
Que el tsconfig.json incluya ./.cms/types.d.ts es un aviso, no un error: sin él todo funciona,
solo pierdes el tipado de Astro.locals.cms.
Rutas inyectadas
Sección titulada «Rutas inyectadas»| Patrón | Qué sirve |
|---|---|
${admin.path}/[...path] |
El panel del admin |
${api.path}/[...path] |
Los seis endpoints de la API REST, más las rutas de ficheros, las dos de cada global y la de ajustes |
/api/auth/[...all] |
La autenticación |
Los dos primeros patrones salen de tu config, así que mover el admin a /panel es cambiar una línea de
cms.config.ts. La de autenticación es fija. Las tres declaran prerender = false por su cuenta: tus
páginas estáticas siguen siendo estáticas.
El tema del panel
Sección titulada «El tema del panel»/admin sirve un documento HTML entero, así que la hoja de estilos de tu sitio no llega sola. admin.css
en cms.config.ts es una ruta —relativa a la raíz de tu proyecto de Astro— que el panel importa después
de la suya:
export default defineConfig({ collections: [posts], admin: { css: './src/styles/app.css' },})El panel define sus colores dentro de @layer base, así que cualquier declaración tuya sin capa le gana por
la regla de capas de la cascada, y si tú también usas @layer base ganas por llegar después. Si defines las
variables de shadcn —--background, --primary, --radius, las de --sidebar-*…— el panel se pinta con
las tuyas sin que tengas que tocar nada más.
Sus utilidades, en cambio, no son tuyas para pisar: viven en una capa propia, kevin-cms, declarada
después de utilities. Si no fuera así, tu hoja —que se importa la segunda— ganaría cualquier colisión de
nombre, incluidas las que nunca pediste: bastaría con que escribieras hidden en cualquier fichero para que
tu .hidden llegara después del @media de md:block del panel y le tumbara la barra lateral. Lo que sí es
un punto de extensión son los componentes de campo.
No hace falta que instales Tailwind ni que toques su config: dist/admin.css se publica ya compilado. Si la
ruta no existe, la integración falla al arrancar con ADMIN_CSS_NOT_FOUND en lugar de dejarte un error de
Vite en la primera petición.
Si no declaras admin.css, el panel la busca solo. Lee el components.json de la raíz de tu proyecto
—el que deja shadcn— y toma su tailwind.css. Si esa ruta existe, la usa igual que si la hubieras escrito a
mano, así que un proyecto con shadcn ve su tema desde el primer arranque sin configurar nada. Solo mira ahí:
sin components.json no hay detección, y no se prueban rutas convencionales.
La precedencia es estricta —lo que declares gana sobre lo detectado, y lo detectado sobre el tema del
panel— y el arranque dice en el log cuál de los tres ha cogido. Que la detección exista no ablanda el error
de arriba: un admin.css que apunta a un fichero inexistente sigue siendo ADMIN_CSS_NOT_FOUND, porque
esa ruta la escribiste tú. Lo que no rompe nada es el otro lado: un components.json ausente, mal formado o
con una tailwind.css que ya no existe deja el panel con su propio tema y sigue arrancando.
Compartir el modo oscuro con tu sitio
Sección titulada «Compartir el modo oscuro con tu sitio»El panel lleva su propio selector de tema —claro, oscuro o automático, en /admin/account—: /admin sirve
un <html> distinto del de tu sitio, así que la clase .dark que tú pongas en tus páginas no le llega. Lo
que sí comparten es el localStorage del origen, y el paquete exporta la clave que usa:
import { THEME_KEY } from '@kevolution-co/cms'
export function ThemeToggle() { return ( <button onClick={() => { const dark = document.documentElement.classList.toggle('dark') localStorage.setItem(THEME_KEY, dark ? 'dark' : 'light') }} > Cambiar el tema </button> )}Con eso, cambiar el tema en tu sitio cambia también el del panel la próxima vez que se abra, y al revés. Si prefieres que vayan por separado, usa cualquier otra clave y no pasa nada: son dos documentos independientes.
El contrato de la clave es corto:
| Valor guardado | Tema del panel |
|---|---|
dark |
Oscuro |
light |
Claro |
| Sin clave | Automático: el del sistema, y cambia con él |
| Cualquier otro | Automático |
El panel guarda el automático borrando la clave (localStorage.removeItem(THEME_KEY)), nunca escribiendo
auto. Importa si tu script trata todo lo que no sea dark como claro: con auto guardado, quien eligió
«Automático» en el panel vería tu sitio en claro con el sistema en oscuro. Si tu sitio ofrece también la
tercera opción, haz lo mismo, y lee la clave así:
const stored = localStorage.getItem(THEME_KEY)const dark = stored === 'dark' || (stored !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches)Para que no haya un parpadeo del tema claro antes del oscuro, la lectura tiene que correr antes del
primer pintado, así que va en un <script is:inline> dentro de <head> y no en una isla —cuando React
hidrata, la versión clara ya se ha pintado—. Envuélvelo en try/catch: localStorage lanza directamente
en un navegador con las cookies bloqueadas, y un tema no vale una página en blanco.
El panel hace lo mismo con su propio script en línea, y es estático: no lleva nada de la petición, así que
su hash siempre es el mismo y se exporta como THEME_SCRIPT_HASH. Si respondes con una
Content-Security-Policy estricta, permítelo por hash en lugar de con 'unsafe-inline':
import { THEME_SCRIPT_HASH } from '@kevolution-co/cms'
const scriptSrc = `script-src 'self' '${THEME_SCRIPT_HASH}'`Es el único script en línea que añade el panel por su cuenta; los de hidratación de las islas son de Astro, y los permites como en el resto de tu sitio.
Astro.locals.cms
Sección titulada «Astro.locals.cms»Un middleware con order: 'pre' —para que el middleware de tu aplicación ya lo encuentre puesto— deja
en locals.cms las colecciones y los globals del config, más la
autenticación:
---export const prerender = false
const { docs } = await Astro.locals.cms.collections.posts.find({ where: { status: { equals: 'published' } } })---El tipado sale de .cms/types.d.ts, que augmenta App.Locals. No declaras nada.
locals.cms es anónimo por defecto: una llamada que no dice quién la hace actúa como un visitante sin
sesión. El ejemplo de arriba funciona porque posts declara access: { read: 'public' }; donde el
servidor decide qué mostrar, la llamada pasa overrideAccess: true, y donde deba valer lo que una persona
puede, { user } o forUser. Ver Control de acceso.
La construcción es perezosa: locals.cms es un accesor y no se lee ningún binding hasta que algo
pide una colección. Una página que solo dibuja una portada estática no paga nada.
locals.cms.auth trae getSession(), getUser() y requireUser(). Su caché de sesión es por
petición, mientras que collections se construye una vez por isolate.
locals.cms.email trae send(), para mandar correo transaccional desde tus propias páginas. Ver
Email.
locals.cms.globals.<slug> trae get() y update(), el documento único de cada
global. Sale del mismo buildAPI que las colecciones —un solo accesor
perezoso detrás de los dos— y el codegen lo tipa igual, con una interfaz por global en
.cms/types.d.ts. Un global vive en KV, así que declararlos no añade ninguna tabla.
locals.cms.settings trae get() y update(), los ajustes del sitio
guardados en KV. Como email, es un accesor anidado: una página que no los lee no resuelve el
binding.
Codegen
Sección titulada «Codegen»Al arrancar, la integración escribe .cms/schema.ts y .cms/types.d.ts junto a tu cms.config.ts, y
registra ese fichero en el watcher: al guardarlo, Astro reinicia y se regeneran.
Generar o aplicar una migración nunca es automático. En dev, si no hay ninguna migración o si el
config se ha movido más allá de la última, lo avisa con el comando que toca.
Módulos virtuales
Sección titulada «Módulos virtuales»Las rutas y el middleware viven dentro del paquete, así que no pueden importar un fichero tuyo por ruta relativa. Cuatro módulos virtuales cierran el hueco.
virtual:kevin-cms/server lleva el config, el schema de Drizzle y los nombres de los bindings. No se
resuelve en el entorno del navegador, a propósito.
virtual:kevin-cms/config es lo que consume el admin, que corre en el navegador, y por eso lleva solo
la parte pública y serializable:
| Va | No va |
|---|---|
admin.path, admin.auth, api.path |
Los nombres de los bindings |
| Slug, etiquetas y opciones de admin de cada colección y de cada global | access, que es la política de autorización |
| Nombre, tipo y validaciones de cada campo | Rutas absolutas de tu máquina |
upload y auth de la colección |
Un defaultValue que sea una función (solo pasa la marca defaultFn: true, para que el panel sepa que el servidor lo calcula) |
admin.css y admin.fieldComponents, que son rutas de build |
virtual:kevin-cms/theme es un import de la hoja de estilos que haya ganado —la que declares en
admin.css o la que se detecte desde components.json—, o export {} cuando no hay ninguna. Ver
El tema del panel.
virtual:kevin-cms/field-components es un import por cada componente de campo que hayas sustituido
con admin.fieldComponents, y un objeto con todos ellos; export default {} si no has sustituido
ninguno. Ver Poner el tuyo.
Ese último sí se resuelve en el navegador, a diferencia de virtual:kevin-cms/server: su contenido
son componentes de React, que es justo lo que el panel necesita allí. Las rutas se comprueban en
astro:config:setup, así que una que no existe es un error al arrancar y no un fallo de resolución de
Vite en la primera petición a /admin.