Actualizar Hollware

Una actualización lleva los paquetes de Hollware a un release nuevo: su código, las migraciones de su base de datos y el admin. Tu contenido se queda donde está, en la base de datos, y las migraciones solo le agregan.

Todos los paquetes de Hollware llevan la misma versión y se mueven juntos: hollware, @hollware/core, @hollware/server y @hollware/admin en el proyecto, y @hollware/client, @hollware/nuxt, @hollware/astro, @hollware/react o @hollware/vue en tus sitios.

Elige el release

Las notas de cada release dicen qué agrega y qué le pide a tu proyecto, si le pide algo. Dentro de 1.x no se rompe nada de lo que se promete: una actualización son los paquetes y después un deploy.

npm view hollware dist-tags   # latest, y rc cuando hay un release candidate

pnpm, desde la versión 11, no instala nada publicado hace menos de un día: espera un día después de un release, o nombra la versión en minimumReleaseAgeExclude mientras tanto.

Actualiza, paso a paso

1. Los paquetes, exactos

npm install -E hollware@1.2.0 @hollware/core@1.2.0 @hollware/server@1.2.0 @hollware/admin@1.2.0

Con pnpm, pnpm add -E con los mismos nombres. -E mantiene la versión exacta, como la escribió npm create hollware: un proyecto se mueve cuando tú lo mueves.

2. Compara con un proyecto del release nuevo

El starter de cada release fija las herramientas con que se probó, wrangler, los plugins de Cloudflare, Vite+ y Vitest, y a veces cambia un archivo que es tuyo. Para ver ambas cosas, crea un proyecto del release nuevo al lado del tuyo, sin instalar nada, y compáralos:

npm create hollware@1.2.0 ../my-cms-1.2.0 -- --no-install --no-git --name my-cms --site my-site
diff -ru --exclude node_modules --exclude .wrangler ../my-cms-1.2.0 .

Toma lo que agrega el release nuevo:

• package.json: las versiones de las herramientas en devDependencies, y cualquier script nuevo.
• wrangler.jsonc: bindings y flags nuevos, y la compatibility_date. Conserva lo tuyo donde difiere a propósito: los ids que tenga, tu HOLLWARE_PUBLIC_URL, tus rutas y tus nombres.
• vite.config.ts, vitest.config.ts, test/: como los trae el release nuevo, salvo que los hayas cambiado tú.

Después instala, regenera los tipos de los bindings y borra el proyecto de comparación:

npm install
npm run types
rm -r ../my-cms-1.2.0

3. En local

npx hollware migrate --local
npm test
npx hollware doctor

migrate aplica las migraciones que le faltan a la base de datos local, y doctor dice qué le falta al proyecto, entre otras cosas un binding que necesite el release nuevo. Levántalo con npx hollware dev y prueba lo que usas.

4. Despliega

npx hollware migrate --check --remote   # lo que agrega el release nuevo; termina con 1 mientras haya pendientes
npx hollware deploy
npx hollware doctor --remote

hollware deploy aplica primero las migraciones nuevas a la base de datos remota, mientras tu Worker actual sigue sirviendo (las migraciones solo agregan, así que sigue funcionando con ellas), después despliega el Worker nuevo y crea en tu cuenta lo que necesite, como un bucket. Toma un bookmark de D1 Time Travel antes de migrar y lo imprime: guárdalo hasta que estés seguro.

Después haz commit del proyecto: package.json, el lockfile, wrangler.jsonc y worker-configuration.d.ts.

5. Tus sitios

Actualiza primero el Hollware y después los sitios que lo leen, a la misma versión. Dentro de 1.x, un sitio con un release más antiguo sigue leyendo un Hollware más nuevo, así que nada es urgente.

Mantenlo al día

Un bot puede abrirte la actualización, con todos los paquetes en un solo pull request, nunca uno por uno. Con Renovate:

{
  "packageRules": [{ "matchPackageNames": ["hollware", "@hollware/**"], "groupName": "Hollware" }]
}

Con Dependabot, en .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule: { interval: weekly }
    groups:
      hollware:
        patterns: ['hollware', '@hollware/*']

El bot mueve los paquetes; el paso 2, la comparación, sigue siendo tuyo cuando las notas del release lo piden. Tu CI corre npm test, y el deploy sigue siendo un comando que ejecutas tú, o un job tuyo.

Lo que cada release le pide a tu proyecto

A la 1.0, desde la 0.11

Los paquetes, como arriba, y estos archivos, que muestra la comparación del paso 2. npx hollware doctor nombra cualquier binding que le falte al proyecto.

• wrangler.jsonc suma las imágenes de tus sitios: un bucket de R2 y el binding de Images. Nombra el bucket como tu Worker; el próximo deploy lo crea.

  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "my-cms-media" }],
  "images": { "binding": "IMAGES" },

• vite.config.ts sirve el servidor local en http://localhost:5199 sea cual sea el HOLLWARE_PUBLIC_URL que escribió el deploy, así que hollware dev sigue funcionando después de desplegar, y le da un HOLLWARE_SECRET de desarrollo, para que los enlaces de preview funcionen en local. También suma la configuración fmt y lint de npm run check.
• vitest.config.ts les da a los tests la misma URL local, como el binding HOLLWARE_PUBLIC_URL.
• test/worker.workerd.test.ts: el test de la base de datos revisa que cada migración esté aplicada, en vez de una lista de tablas que se rompe con cada migración nueva. Tómalo tal cual: el anterior falla con la tabla de imágenes.
• package.json suma el script check.

Después del deploy, el cron reconstruye los documentos guardados de tus revisiones con el pipeline del release nuevo, veinte por minuto; no tienes que hacer nada.

Desde 0.x

Un proyecto 0.x se actualiza de la misma forma, y toma lo que cambió en el camino a la 1.0:

• La estructura de tus sitios vive en la base de datos (0.8). Un hollware.config.ts se lee una vez, en la primera solicitud del nuevo Worker, y se traslada a D1; desde ahí, cambia tus sitios en el admin o por MCP, y borra el archivo.
• Los tokens pueden no tener vencimiento si los creas sin --expires-in-days (0.11).
• Cada cambio queda en el registro de actividad de su sitio (0.11); el dueño decide, en Sitio, si guarda un hash de cada dirección y por cuánto tiempo.
• La vista previa de borradores requiere la url del sitio y el secreto del Worker HOLLWARE_SECRET, que configura hollware deploy (0.11).
• Los enlaces de invitación llevan su secreto después de # (0.11); los enlaces creados antes siguen funcionando.

Volver atrás

Un deploy que salió mal se revierte en dos pasos:

1. Instala de nuevo las versiones anteriores (git checkout de package.json y el lockfile, luego npm install) y ejecuta npx hollware deploy.
2. Si una migración del release nuevo cambió datos que necesitas recuperar, restaura la base de datos al bookmark que imprimió el deploy: npx wrangler d1 time-travel restore <database> --bookmark <id>. Todo lo que se escribió después se pierde. Ver Restaurar.

Las migraciones solo avanzan, y ninguna se deshace. Un release anterior corre sobre una base de datos que migró uno más nuevo cuando las migraciones nuevas solo agregaron, como hacen casi todas; las notas del release dicen cuándo una hace más.