Actualizar a EmDash 1.0

EmDash 1.0 elimina las API que quedaron obsoletas durante 0.x y mueve a emdash/internal/ los puntos de entrada que solo carga el propio EmDash. Esta guía enumera cada cambio incompatible y lo que debes actualizar en tu sitio.

Actualiza tus dependencias

Actualiza emdash y cualquier otro paquete de EmDash que use tu sitio a sus últimas versiones y luego vuelve a compilar. El siguiente ejemplo actualiza un sitio de Cloudflare:

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

Si tu despliegue ejecuta emdash migrate, ejecútalo con el archivo .emdash/migrations.json generado por una compilación hecha después de actualizar. El comando rechaza un manifiesto escrito por una versión anterior de EmDash.

Después de actualizar, es posible que tu sitio compile y se ejecute sin más cambios. Si la compilación falla o EmDash informa de un error al iniciar, revisa los cambios incompatibles que se describen a continuación.

Para ver la lista completa de cambios de cada paquete, consulta su entrada en la página de versiones.

Cambios incompatibles

Eliminado: cloudflareCache()

En versiones anteriores, cloudflareCache() de @emdash-cms/cloudflare proporcionaba un proveedor de caché de rutas que purgaba las páginas en caché a través de la API REST de Cloudflare.

cloudflareCache() y sus puntos de entrada @emdash-cms/cloudflare/cache y @emdash-cms/cloudflare/cache/config se han eliminado. Un sitio que lo importe no compilará.

¿Qué debo hacer?

Sustitúyelo por el proveedor cacheCloudflare() del adaptador de Astro para Cloudflare, que usa Workers Cache. El adaptador habilita Workers Cache en la configuración de despliegue generada cuando se establece este proveedor.

El siguiente ejemplo muestra el cambio en astro.config.mjs:

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

Workers Cache purga con cache.purge() de cloudflare:workers, por lo que puedes eliminar los secretos CF_ZONE_ID y CF_CACHE_PURGE_TOKEN de tu Worker. La caché de objetos de KV (kvCache()) no cambia.

Eliminado: Comments y CommentForm de emdash/ui

En versiones anteriores, los componentes Comments y CommentForm se exportaban tanto desde emdash/ui como desde emdash/ui/comments.

Ahora solo se exportan desde emdash/ui/comments. Un sitio que importe cualquiera de los dos componentes desde emdash/ui no compilará.

¿Qué debo hacer?

Actualiza la importación. Los componentes en sí no cambian.

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

Eliminado: emdash dev y emdash auth secret

En versiones anteriores, emdash dev iniciaba un servidor de desarrollo respaldado por un ./data.db local, y emdash auth secret generaba un valor para EMDASH_AUTH_SECRET.

Ambos comandos se han eliminado. Al ejecutar cualquiera de ellos, el proceso termina con Unknown command.

¿Qué debo hacer?

Sustituye emdash dev por el script de desarrollo propio de tu sitio, como pnpm dev, o ejecuta astro dev. El sitio usará entonces el adaptador de base de datos de su configuración.

Si tu package.json tiene una clave url bajo emdash, elimínala. Para generar tipos desde un sitio remoto, ejecuta emdash types --url <site-url> o establece EMDASH_URL.

Elimina emdash auth secret de tus scripts. Si tu sitio ya tiene EMDASH_AUTH_SECRET definido, consérvalo: EmDash sigue leyéndolo para que los hashes de IP almacenados de quienes comentan se mantengan estables. Para cifrar en reposo los secretos de los plugins, genera una clave de cifrado con emdash secrets generate.

Eliminado: experimental.registry

En versiones anteriores, podías configurar el registro de plugins con experimental.registry en las opciones de emdash().

La opción se ha eliminado, junto con la propia opción experimental. Un sitio que todavía establezca experimental.registry falla al iniciar con un error que menciona la opción registry de nivel superior.

¿Qué debo hacer?

Mueve el valor sin cambios a la opción registry de nivel superior. Acepta la misma cadena de URL o el mismo objeto de configuración.

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

Si te queda un bloque experimental: {} vacío, elimínalo. Las configuraciones de TypeScript lo notifican como un error.

Cambiado: los puntos de entrada internos se movieron a emdash/internal/

En versiones anteriores, emdash exponía puntos de entrada como emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations y emdash/plugin-test-runtime que solo carga el propio EmDash.

Estos puntos de entrada están ahora bajo emdash/internal/. Lo mismo se aplica a los ejecutores de migraciones de D1 y Hyperdrive de @emdash-cms/cloudflare, que están bajo @emdash-cms/cloudflare/internal/db/. No forman parte de la API pública y sus exportaciones pueden cambiar en cualquier versión. Los sitios que configuran EmDash mediante emdash() en astro.config.mjs no se ven afectados.

¿Qué debo hacer?

Si tu proyecto importa directamente alguna de estas rutas, sustituye la importación por la API pública:

• Para configurar una base de datos, una caché de objetos o un proveedor de medios, usa sqlite(), libsql() o postgres() de emdash/db, memoryCache() de emdash/astro o localMedia() de emdash/media.
• Para probar un plugin, usa @emdash-cms/plugin-test en lugar de emdash/plugin-test-runtime.
• Para ejecutar tu propio middleware antes del de EmDash, establece la opción middleware.outer de emdash().

El middleware interno de autenticación, configuración inicial, redirecciones y contexto de solicitud no tiene un reemplazo público.

Funciones obsoletas

Obsoleto: nombres anteriores de capacidades de plugins

En versiones anteriores, los plugins podían declarar capacidades con nombres como read:content, network:fetch y page:inject sin ninguna advertencia.

EmDash registra una advertencia al iniciar por cada plugin que declara uno de estos nombres obsoletos, e indica el reemplazo actual de cada uno (por ejemplo, read:content → content:read). Los nombres obsoletos siguen funcionando durante toda la serie 1.x.

¿Qué debo hacer?

Si un plugin que usas provoca la advertencia, actualízalo a una versión que use los nombres actuales o pide a su autor que publique una. Si mantienes el plugin, cambia el nombre de las capacidades en su manifiesto. Consulta Capacidades y seguridad para ver los nombres actuales.