Política de estabilidad 1.x

A partir de 1.0.0, @meekojs/meeko sigue Semantic Versioning. Esta página define qué cubre esa promesa, qué queda fuera, cómo se retira una API y en qué entornos se ejecuta Meeko. Los cambios de cada versión se registran en el CHANGELOG; la actualización desde 0.1.0 se explica en la guía de migración a 1.0, la de 1.0 a 1.1, en Actualizar de 1.0 a 1.1, la de 1.1 a 1.2, en Actualizar de 1.1 a 1.2, la de 1.2 a 1.3, en Actualizar de 1.2 a 1.3, la de 1.3 a 1.4, en Actualizar de 1.3 a 1.4, la de 1.4 a 1.5, en Actualizar de 1.4 a 1.5, la de 1.5 a 1.6, en Actualizar de 1.5 a 1.6, la de 1.6 a 1.7, en Actualizar de 1.6 a 1.7, y la de 1.7 a 1.8, en Actualizar de 1.7 a 1.8.

Las prereleases (1.1.0-rc.1) se publican en el dist-tag next de npm y no forman parte de la promesa hasta su versión final.

Un solo paquete#

Compilador, runtime, framework, adaptadores, CLI y servidor de lenguaje se publican juntos en @meekojs/meeko, con una única versión. Durante 1.x no se separarán en paquetes que haya que coordinar.

El código que genera el compilador (módulos .meeko compilados, entradas bajo .meeko/ y builds de meeko build) importa @meekojs/meeko/internal, y ambos deben tener exactamente la misma versión. Por eso meeko init y meeko init-framework fijan la versión exacta en el package.json generado. Al actualizar Meeko, vuelva a compilar o construir: no mezcle código generado por una versión con el runtime de otra, aunque ambas sean 1.x.

API pública#

Lo que se enumera a continuación sólo cambia de forma incompatible en una versión major.

Entradas del paquete#

Las subrutas declaradas en exports de package.json y todos los símbolos y tipos que exportan, estén o no descritos en esta guía, api.md, framework.md, devtools.md y editors.md; su referencia exacta son las declaraciones .d.ts publicadas. Las funciones de bajo nivel para hosts propios (por ejemplo matchRoute, createNavigator, createSocketHub, dispatchApiRoute, dispatchRpc o createRequestContext) también forman parte del contrato:

tests/package-boundaries.test.ts fija la lista exacta de exports de la raíz y de las subrutas de package.json.

Los tipos forman parte del contrato. Hay dos matices:

• Una unión que Meeko entrega a la aplicación puede ganar miembros en un minor: por ejemplo ErrorSource (que gana "uncaught" y "rejection" en 1.3), PageRender, DeferredStatus, DevtoolsReadKind, DevtoolsEventKind, el estado de un SocketClient (que gana "unauthorized" en 1.1) o los códigos de error. Un switch exhaustivo sobre ellas debe tener una rama por defecto. Una unión que la aplicación pasa a Meeko no se estrecha en 1.x.
• Una interfaz de un objeto que Meeko entrega a la aplicación puede ganar miembros en un minor: por ejemplo RouteState, que devuelve useRoute() (gana isActive en 1.5), DataResource y LoadedResource, de useApi y los recursos (ganan refreshing en 1.5), o Form (gana trySubmit, commit y field en 1.5). Léalas y desestructúrelas con normalidad, pero no las implemente a mano (const route: RouteState = { … }), porque un minor puede añadir un miembro obligatorio. En una prueba, un doble parcial con Partial<RouteState> o una conversión as RouteState sigue compilando. Las interfaces que la aplicación pasa a Meeko (opciones, configuración, contratos) sólo ganan miembros opcionales.
• Una corrección de tipos que rechaza código que ya fallaba en ejecución puede publicarse en un minor o un patch, con su entrada en el CHANGELOG.

Excepciones aprobadas#

Cambios que rechazan código válido en ejecución y que se publican en un minor por decisión explícita, cada uno con su migración:

Formato .meeko y módulo generado#

• Las secciones <script lang="ts">, <template> y <style> (con scoped y :global(...)), y en las páginas <script server lang="ts"> (desde 1.1), con sus dos formas: las opciones de ruta y el código de nivel superior cuyos export const son los datos de la página, con la regla que decide cuándo un bloque tiene código de nivel superior. Desde 1.1, el <script lang="ts"> es opcional y admite el atributo generic con los parámetros de tipo del componente, que no se permite en páginas, layouts, app.meeko ni error.meeko.
• La macro defineProps<Props>(), con o sin defaults, y desde 1.1 las macros defineEmits<T>(), defineExpose(value), defineModel<T>(name?, options?), defineSnippets<T>() y useElementRef("name").
• Las directivas {expression}, on:event, bind:name, if:when, each:of/each:as/each:key/each:index y <component is>. Desde 1.1:
  • each:key es opcional y sin él la clave es el índice;
  • on:event en <component> y en las etiquetas de componente equivale a la prop onEvent;
  • las etiquetas de componente con nombre en mayúscula (<AppButton />), cuyo contenido son snippets;
  • las props estáticas en componentes (variant="primary" pasa un literal de texto y un atributo sin valor, true), con is, ref, html, los nombres con guiones y los que llevan : sin ser directivas reservados (desde 1.8, salvo aria-* y data-*);
  • la directiva ref:name. ref="x" y bind:ref conservan su comportamiento de 1.0;
  • model y model:name en las etiquetas de componente, model en <input>, <textarea> y <select>, y los elementos <snippet name params> y <render snippet args />;
  • la directiva html="expression", que inserta HTML sin escapar, normalizado para que encaje en el elemento y sin ejecutar nunca sus <script> al insertarlo en el navegador;
  • html y model son directivas sólo en los elementos HTML estándar; en los elementos personalizados (etiqueta con guion) son atributos literales;
  • <component is="..." /> se cierra solo, como <Etiqueta />.
• Desde 1.8, un elemento HTML no vacío sin contenido puede cerrarse con /> (<div />, <textarea />, <td />, <my-element />) y equivale a escribirlo con su etiqueta de cierre: los nodos que siguen son sus hermanos y el SSR escribe <div></div>. <template>, <script>, <style>, <html>, <head>, <body> y los nombres desconocidos siguen dando MEEK001, y un elemento de tabla o de lista autocerrado seguido de su propia etiqueta de cierre (<td /></td>), MEEK008 (véase Elementos sin contenido).
• Desde 1.4, if:when en <snippet>: el padre pasa ese snippet sólo mientras la condición es verdadera, y sólo si el hijo lo declara opcional.
• Desde 1.5, la etiqueta propia <MeekoTeleport> con to ("body" o "#id", este último con una letra seguida de letras ASCII, dígitos, - o _), bind:to, disabled y bind:disabled, y los tipos MeekoTeleportProps y MeekoTeleportTarget de @meekojs/meeko/framework. Son contrato el destino del contenido en el HTML del servidor (dentro del elemento del id, tras su contenido, o tras la aplicación y antes de los scripts de Meeko con body), el orden de varios teleports al mismo destino, que conserve el ámbito del componente que lo declara, el movimiento de los mismos nodos al cambiar disabled y el comportamiento con un destino inexistente descrito en framework.md. Los comentarios que marcan el contenido son internos.
• Desde 1.5, <component is> acepta una etiqueta HTML (un literal, una expresión cuyo tipo es una unión de etiquetas, o una unión de etiquetas y componentes) y contenido: hijos con una etiqueta, snippets con un componente. Las etiquetas admitidas son el tipo público TagName; un atributo que no es global sólo se escribe mientras la etiqueta del momento lo admite según los datos HTML de Meeko (sin type en <a> ni en <area>). Al cambiar la etiqueta, los hijos se mueven al elemento nuevo con su estado. La directiva bind="obj" escribe un objeto como atributos de un elemento o como props de un componente, sin claves on*; los atributos explícitos ganan y class y style se combinan. bind sigue siendo un atributo literal en los elementos personalizados y ya no es una prop estática.
• Desde 1.4, defineSnippets<T> acepta en cada clave de T una tupla de parámetros o un Snippet<Args>, que cuenta como Args, de modo que T puede derivar del mapa de snippets de otro componente con Omit, Pick o & conservando parámetros y opcionalidad. Una declaración con tuplas conserva el mismo tipo.
• Desde 1.8, el name de <snippet> admite, además de un identificador, segmentos de caracteres de identificador unidos por guiones (/^[A-Za-z_$][\w$]*(?:-[\w$]+)*$/, como cell-email), y defineSnippets<T> acepta claves que salen de un tipo mapeado con template literal sobre los parámetros de tipo del componente ({ [K in keyof Row & string as `cell-${K}`]?: [row: Row, value: Row[K]] }). Son contrato que meeko check y el editor comprueban esos snippets en el padre con el tipo que infieren sus props (nombre inexistente, tipo de cada parámetro y número de params) y que, en el propio componente, una intersección con un tipo mapeado conserva el tipo de sus claves fijas (snippets.cell). El tipo de un acceso por nombre calculado dentro del componente queda fuera: TypeScript no lo resuelve sobre un parámetro de tipo.
• Desde 1.4, con theme en meeko.config.ts, la etiqueta propia <MeekoThemeToggle> (obsoleta desde 1.8, se retira en 2.0; usa UIThemeToggle de @meekojs/ui): sus props (mode, themes, labels, messages, class, id), un snippet por elección, el marcado que estiliza la aplicación (el <form method="post" action="/_meeko/theme"> raíz con data-meeko-theme-toggle, el <button> de mode="cycle", los <span data-meeko-theme-icon> de los iconos, el role="radiogroup" y sus botones role="radio" con aria-checked y data-meeko-theme-option de mode="select"), el atributo data-theme-choice de <html> con la elección, la regla de <head> que muestra el icono de la elección, y el endpoint POST /_meeko/theme con las reglas de framework.md (temas válidos, Origin del propio sitio, 303 sólo a una ruta del mismo origen). Los textos por defecto y el CSS de la regla pueden cambiar en un minor.
• Desde 1.5, la etiqueta propia <MeekoAwait>: sus props (for, como expresión o con bind:for, reserve, messages, class, id), sus snippets (default con refreshing, pending y error con error y retry), los estados descritos en framework.md, el estrechamiento de los datos de for en su contenido, y el marcado que estiliza la aplicación: un <div> con data-meeko-await (pending, error o ready), aria-busy="true" mientras carga o recarga, data-meeko-refreshing durante una recarga y, con reserve, data-meeko-reserve y data-meeko-reserve-min. Son contrato que la reserva sólo aplica min-block-size en pending, sin atributos style, y que la memoria vive en sessionStorage; la clave de cada zona, el formato guardado, el texto del script de <head>, los textos por defecto y el número de zonas recordadas pueden cambiar en un minor.
• Desde 1.5, las etiquetas propias <MeekoPopover> y <MeekoSelect> (obsoletas desde 1.8, se retiran en 2.0; usa UIPopover y UISelect de @meekojs/ui) (véase Componentes integrados): sus props, sus snippets (trigger, anchor y el contenido; option, value, group, empty y loading), su modelo, sus eventos (toggle con { open }, change) y lo expuesto (show, hide, toggle); el marcado que estiliza la aplicación (data-meeko-popover y data-meeko-popover-trigger, data-meeko-select con data-open, data-multiple, data-disabled y data-loading, las opciones role="option" con data-active, data-selected y data-disabled); los roles y atributos ARIA documentados; el teclado documentado; los <input type="hidden"> de name, y que no usen atributos style="…". Son detalle de implementación, y pueden cambiar en un minor, las reglas de la capa de cascada meeko, las propiedades personalizadas --meeko-popover-*, los textos por defecto y la forma de los IDs.
• Desde 1.8, un class o un style estático junto a bind:class o bind:style en el mismo elemento (o en un <component is> que sólo puede ser etiqueta) escribe un único atributo en SSR, al hidratar y al actualizar: las clases dinámicas van tras las estáticas, y las declaraciones dinámicas de style tras las estáticas, que pierden. Si el valor dinámico es undefined, null, false o está vacío, queda el texto estático tal cual. Antes, el SSR escribía el atributo dos veces y la hidratación fallaba.
• Desde 1.8, aria-* y data-* en minúsculas, estáticos o con bind:, en una etiqueta de componente o en un <component is> que sólo puede ser componente, pasan una prop con ese nombre (antes, MEEK032); data-meeko* y las mayúsculas siguen siendo MEEK032. Sólo convierte en válido código que no compilaba.
• Desde 1.8, cuando el script escribe los eventos de defineEmits (un tipo literal, o una interface o un type locales sin extends ni parámetros), props no enumera sus callbacks (onSave) en Object.keys, in, la propagación ni la desestructuración con resto; leerlos (props.onSave) y emit no cambian. El tipo de props nunca los declaraba, así que el código tipado no los enumeraba a propósito.
• Desde 1.8, un literal de texto en PascalCase en <component is> (is="to ? 'MeekoLink' : 'a'", 'UICard') nombra <MeekoLink> o un componente importado, autoimportado o declarado en el script, que el compilador resuelve como su etiqueta: una región if:when por nombre, cuya condición es el camino de ?: hasta su literal, y otra para las etiquetas HTML; cada atributo va sólo a las ramas que lo admiten. Las etiquetas HTML se escriben en minúscula. Es aditivo: antes, un literal en PascalCase era MEEK112 (no es una etiqueta), y is con un valor de componente o con etiquetas HTML no cambia. Un nombre desconocido o un valor junto a nombres es MEEK132. El reparto de regiones y marcadores es detalle de implementación. resolveComponent("MeekoLink") y la entrada MeekoLink de ComponentRegistry (salvo que el proyecto tenga un componente con ese nombre) cargan <MeekoLink> como componente desde @meekojs/meeko/builtins/link.
• Desde 1.8, bind: en un elemento SVG o MathML escribe el nombre con el caso del estándar, como el atributo estático (bind:viewBox escribe viewBox, no viewbox); antes, el atributo en minúsculas no tenía efecto en el SVG y la hidratación no coincidía.
• Desde 1.8, <MeekoLink> con bind:to de tipo unión de rutas acepta bind:params con los parámetros de alguna de ellas, o ninguno, y bind:search con undefined; con una sola ruta la comprobación no cambia.
• Desde 1.8, defineProps puede desestructurarse en su declaración const (const { label, size = "md", class: className, ...rest } = defineProps<Props>()): cada nombre lee su prop donde se usa y es reactivo en el script y en la plantilla, salvo donde un ámbito más cercano declara el mismo nombre; los defaults del patrón equivalen al argumento de defaults; ...rest es una vista de sólo lectura y reactiva de las demás props, sin los manejadores de defineEmits. Los defaults (en las dos formas) pueden leer constantes de nivel superior que sólo usan literales e imports. Es aditivo: sólo convierte en válido código que antes era MEEK015 o TS2304. Los tipos de los defaults se calculan por variante de una unión de props, así que un default de una prop que una variante declara never ya no la permite en esa variante para el padre.
• Desde 1.8, con una unión de props, un valor por defecto literal de defineProps (kind = "a", en el patrón o en el argumento) hace opcional su prop para el padre sólo en las variantes que admiten ese valor, en ComponentProps, las declaraciones .d.meeko.ts y el editor; un default que no es literal sigue siendo opcional en todas las variantes y es MEEK131 si alguna que exige la prop no lo admite. Es una corrección: hasta ahora, un padre podía omitir el discriminante de cualquier variante (<Child b="hello" /> con kind = "a"), el componente recibía { kind: "a", b: "hello" }, que no es ninguna variante, y fallaba en ejecución. Ese padre deja de compilar; para migrar, pasa el discriminante (kind="b"). Las uniones sin default en el discriminante y las props que no son uniones no cambian.
• Desde 1.8, los datos HTML de Meeko salen del estándar (src/shared/html-data, generados por scripts/html-data.ts): las etiquetas y atributos que acepta <component is> y bind="obj" son un superconjunto de los de 1.7. Los tipos públicos AttributeValues<Tag, Name> y AttributeValueOf<Tag, Name> (de @meekojs/meeko), y los valores de ElementAttributes<Tag>, sugieren los valores del estándar sin restringir lo que se acepta; un literal fuera de ellos es el aviso MEEK122. hidden con un texto no vacío ("until-found") escribe ese texto, y los atributos booleanos del estándar que 1.7 no trataba como tales se escriben vacíos.
• Las reglas del setup desde 1.1: useElementRef, useApi, useRpcQuery y useRpcMutation sólo en el nivel superior; await de nivel superior sólo sobre useApi, useRpcQuery, useElementRef, useSocket y useSocketClient; la división del setup en el primer await de navegador, cuya continuación sólo se ejecuta en el navegador y admite sentencias de expresión y de control de flujo.
• La forma de cada módulo compilado: ComponentProps, ComponentExposed, ComponentModels y ComponentSnippets (desde 1.1), css (con el plugin de Vite de Meeko, desde 1.8 depende del grafo: en el grafo SSR —meeko dev, el build de Node, el prerender, static y Cloudflare— y en el cliente de meeko dev, es el CSS del <style> ya procesado por el PostCSS y los plugins CSS del proyecto, el mismo que incrustan el SSR y el prerender y que reaplica la HMR; en el bundle de cliente de producción es la salida del compilador, como antes de 1.8, porque ahí ningún código de Meeko lo lee y la hoja que Vite empaqueta ya aplica el CSS procesado. En un host que no procesa CSS y resuelve ese módulo como una cadena vacía, como Vitest sin test.css: true, también es la salida del compilador. Con compile() sin la opción styleModule, siempre es la salida del compilador), renderWithState, renderToString, hydrate y hydrateScope, cuya función de liberación lleva exposed. En un componente con generic, los tipos y las funciones llevan sus parámetros de tipo. Las marcas hasDataAwait, __meekoChildren, __meekoReactiveProps (desde 1.2), __meekoChannels y __meekoTag son internas.
• Desde 1.8, dónde van los <style> en línea del SSR y del prerender: al final del <head>, después de las hojas globales (app/styles/main.css, las de addStylesheet y el head de document), donde el cliente añade después el CSS de los componentes, de modo que el primer pintado y la página hidratada tienen la misma cascada; antes iban delante de las hojas globales y una regla global de igual especificidad ganaba sólo hasta hidratar. La página de error de un fallo del servidor, que no se hidrata, también incrusta su CSS. El atributo data-vite-dev-id que meeko dev añade a esos <style> para que Vite los adopte es detalle de implementación.
• El tipo Component<Props>.

El código JavaScript generado no es público; véase Fuera del contrato.

CLI#

Los comandos y opciones que muestra meeko --help:

También forman parte del contrato:

• el bin meeko-language-server, con los mismos transportes que meeko lsp;
• el código de salida 1 ante errores;
• los códigos de diagnóstico (MEEK0xx, MEEK1xx y MEEK_*; véase Códigos de diagnóstico);
• la forma { code, message, filename, location } de meeko check --json.

El texto de los mensajes puede mejorar en cualquier versión; desde 1.1 está en español. Un minor puede añadir diagnósticos para código que ya fallaba en ejecución o violaba un contrato documentado, y puede dejar de emitir uno cuando el código que señalaba pasa a ser válido. Un código retirado no se reutiliza con otro significado.

Códigos de diagnóstico#

Los códigos a partir de MEEK043 son nuevos en 1.1. Los errores de TypeScript conservan su código TSxxxx, que puede cambiar al actualizar TypeScript o la forma del código que comprueba: en 1.1, una prop obligatoria que falta en una etiqueta de componente da TS2345 en lugar de TS2769.

La versión de TypeScript que incluye el paquete puede actualizarse en un minor. Si eso cambia los diagnósticos de meeko check, el CHANGELOG lo indica.

Convenciones de proyecto#

• meeko.config.ts con defineMeekoConfig: extends, modules, imports.serverDirs, la unión discriminada server (node, bun, deno y cloudflare, con sus campos documentados, y desde 1.3 static, con contentSecurityPolicy, headers y headerFiles) y, desde 1.2, css.scopeAttribute, layers, document (lang y head) y las claves de opciones de los módulos (meta.configKey; desde 1.4, una clave propia de MeekoConfig hace fallar la carga, véase Excepciones aprobadas). Desde 1.3, site, sitemap (true o { exclude }), robots (true o { allow, disallow }) y document.seo (true o { canonical, ogUrl, ogTitle, ogDescription, origin }), con las etiquetas, archivos y prioridades descritos en framework.md, dev.serverLogs, imports.appDirs e imports.sharedDirs, estas dos con el ámbito y las reglas de rutas de Carpetas de autoimports. Desde 1.4, theme (true o { themes, default, system, darkThemes, attribute, colorScheme, cookie, storageKey, clientHints }), con el comportamiento de Tema claro/oscuro sin parpadeo: el atributo o la clase de <html>, el script en línea de <head> y su orden de lectura (cookie, localStorage, valor por defecto). Desde 1.2, modules lista módulos de defineMeekoModule (un módulo, un paquete, una ruta o [módulo, opciones]); extends es un alias de layers. Desde 1.8, la forma documentada es el nombre del paquete o la ruta, con las opciones en la clave de su meta.configKey: es contrato que un paquete se resuelva por su subpath ./module si lo exporta y, si no, por su raíz; que .meeko/types/config.d.ts importe los tipos de los módulos de modules y que .meeko/tsconfig.config.json incluya meeko.config.ts con ellos (su texto concreto no); que la palabra clave meeko-module del package.json de una dependencia la ofrezca en el completado de modules, y que dos módulos con la misma meta.configKey sean un error (antes se leían las mismas opciones dos veces).
• El documento HTML que renderiza el servidor: desde 1.2, el título y las etiquetas que gestiona Meeko van entre los comentarios <!--meeko:head--> y <!--/meeko:head-->, antes del HTML de DocumentOptions.head, y la meta CSRF sigue a <meta charset> y a las etiquetas por defecto (viewport e icono) que la aplicación no sustituye. La prioridad y la deduplicación de useHead descritas en framework.md son estables.
• app/:
  • app.meeko, error.meeko, pages/, layouts/default.meeko, middleware/, components/, composables/, utils/, stores/ y styles/main.css;
  • páginas index.meeko, [id].meeko, [...slug].meeko y grupos (group), con +layout.meeko, +error.meeko y las opciones de ruta en <script server> o en sidecars *.route.ts;
  • desde 1.5, los layouts con nombre layouts/<nombre>.meeko (también en subcarpetas: layouts/admin/panel.meeko es "admin/panel"), que las páginas eligen con layout en definePage, y los archivos +group.ts de las carpetas de pages, con export default defineGroup({ layout, layoutProps }) en literales;
  • desde 1.6, el middleware con nombre: un archivo de middleware/ con defineRouteMiddleware(fn, { global: false }), cuyo nombre es su ruta sin .ts ni el prefijo numérico de orden de cada parte (10-auth.ts es "auth"), que las rutas piden con middleware (un array literal de nombres, o false) en definePage y en defineGroup. Son contrato el orden (los globales y después los de la ruta, de los +group.ts exteriores a la página, sin repetir) y que un nombre que no existe o que es global detenga el descubrimiento;
  • desde 1.6, el middleware de ruta de servidor: middleware/*.server.ts cuyo export por defecto es defineServerRouteMiddleware(...) (cualquier otro export por defecto, o ninguno, detiene el descubrimiento), global o con nombre con la misma regla de nombres (auth.server.ts es "auth", y auth.ts y auth.server.ts con nombre son un duplicado). Son contrato que nunca llegue al navegador, que se ejecute en el servidor después de todo el middleware isomórfico (globales y luego con nombre, y después los de servidor en el mismo orden), en SSR y en la petición de datos de cada navegación, que no se ejecute en las páginas render: "client" ni "prerender", y que pedir uno con nombre en ellas detenga el descubrimiento.
• server/:
  • api/ (<nombre>.<método>.ts), rpc/, socket/, middleware/ y utils/;
  • server/runtime.ts, cuyo export por defecto es defineServerRuntime(...).
• shared/, public/, layers y módulos.
• Desde 1.5, los aliases de ruta ~/ (la raíz del proyecto), @/ (app/), #shared/ (shared/) y #server/ (server/, sólo en el código de servidor), sus ámbitos, su búsqueda en el proyecto y después en cada layer, y la opción alias de meeko.config.ts (un prefijo terminado en / con una carpeta del proyecto o false). Son contrato la prioridad de los paths del tsconfig.json del proyecto y de un resolve.alias de Vite sobre ellos, y que un imports de package.json con el mismo prefijo # gane y desactive el alias. La forma de los paths en los tsconfig generados no es contrato.
• Desde 1.2, app/plugins/*.ts en la aplicación y sus layers, con los sufijos .client.ts (sólo navegador, antes de hidratar) y .server.ts (sólo servidor, una vez por petición de página).
• Los sufijos .client.ts, .server.ts y .shared.ts, y las exclusiones *.test.ts, *.spec.ts y *.d.ts. Desde 1.6, un app/middleware/*.server.ts, que hasta 1.5 se ignoraba, es middleware de ruta de servidor (véase Excepciones aprobadas).
• Los autoimports api, rpc, socket, useSocket, useState, href y provideErrorHandler, y desde 1.1 onMounted, useApi, useRpcQuery y useRpcMutation, y desde 1.2 useRoute, useForm, useStorage, useApiMutation, useHead y useSeoMeta, y desde 1.4 useTheme, y desde 1.5 useId (de @meekojs/meeko), useLayout, defineGroup y ClientError e isClientError (sólo en los componentes y en los módulos de app/, no en server/, *.server.ts ni los archivos de ruta), y desde 1.6 defineServerRouteMiddleware (en los *.server.ts y en todo server/, como las definiciones de servidor), y desde 1.7 useNavigation, createRoot y defer (este en el código de servidor: <script server>, también dentro de las opciones de ruta, los sidecars *.route.ts, server/ y los *.server.ts) (un export propio con uno de esos nombres tiene prioridad sobre el del framework). Desde 1.4, los tipos de cada componente autoimportado: su nombre de etiqueta (la regla de nombres de app/components y de addComponentsDir, prefijo incluido) seguido de Props, Snippets, Models y Exposed (AppCardProps…), iguales a ComponentProps, ComponentSnippets, ComponentModels y ComponentExposed de su módulo, null incluido, con el ámbito del componente; un autoimport del proyecto con el mismo nombre tiene prioridad (véase Tipos de cada componente). En el código de nivel superior de <script server>, usePage, redirect y notFound se pueden usar sin import, y desde 1.2 también useHead y useSeoMeta.
• Las variables de entorno MEEKO_HOST, MEEKO_PORT (con PORT como respaldo permanente), MEEKO_PUBLIC_ORIGIN, MEEKO_HMR_PORT y, desde 1.2, MEEKO_REDIS_URL, MEEKO_REDIS_PREFIX, MEEKO_SESSION_TTL, MEEKO_SESSION_SAMESITE y MEEKO_TRUST_PROXY, y desde 1.8 el valor cloudflare de MEEKO_TRUST_PROXY y MEEKO_TRUSTED_PROXIES (véase Cloudflare Tunnel y Traefik), y el prefijo MEEKO_, reservado para las variables que lee Meeko. HOST y PUBLIC_ORIGIN están obsoletas desde 1.2.

Salidas de build#

En el sitio estático también son estables:

• <ruta>/index.html y <ruta>/index.meeko.json por página, 404.html, sitemap.xml y robots.txt en la raíz; desde 1.7, una <url> de sitemap.xml puede llevar <lastmod>, <changefreq> y <priority> (en ese orden, tras <loc>), en todos los adaptadores;
• _headers (bloque /*) y _meeko/headers.conf (una línea add_header <Nombre> "<valor>" always; por cabecera), con los que choca un archivo de public/ del mismo nombre.

En Cloudflare también son estables:

• el binding MEEKO_SOCKET;
• la migración meeko-socket-v1, que no se renombra;
• la reserva de public/_meeko/;
• los campos de wrangler.jsonc que pertenecen a Meeko.

El contenido de chunks/, los nombres de archivos con hash y el resto de .meeko/ no son públicos.

Formatos de red y persistidos#

Estos formatos permiten clientes externos, proxies, CSP y despliegues graduales:

• Payload de página. Versión v: 2, con render, head (title y, desde 1.1, description) y deferred:
  • el documento lo lleva en <script id="meeko-payload" type="application/json">, dentro de un HTML con <div id="app">;
  • la navegación lo pide con accept: application/meeko+json, y la respuesta es application/meeko+json o, en una ruta "stream", application/meeko+ndjson (el payload en la primera línea y un valor { "deferred", "value" | "error" } en cada línea siguiente); desde 1.3, el cliente del adaptador static lo pide como el archivo <ruta>/index.meeko.json, sin accept;
  • desde 1.3, un documento con un payload error: true hidrata app/error.meeko en cualquier URL, también en una que coincide con una ruta (el 404.html de un hosting estático);
  • con app/error.meeko, una URL sin ruta responde 404 con un payload error: true, sin route y con props { status, message };
  • desde 1.1, el campo opcional resources lleva los datos de los await useApi(...) y await useRpcQuery(...) que leyó el render, como objeto por clave de petición. El formato de esas claves es interno y puede cambiar en cualquier versión: sólo el servidor y el navegador de la misma versión lo interpretan. Un payload sin resources sigue siendo válido;
  • desde 1.5, el campo opcional layoutProps lleva las props con que el servidor renderizó el layout con nombre de la página (las de sus +group.ts, sus layoutProps y lo que escribió con useLayout()), y el manifiesto de rutas (RouteRecord, ErrorPageRecord, .meeko/manifests/routes.json y el de virtual:meeko-manifest/client) el campo opcional layout ({ name, file, props? }). Un payload o un manifiesto sin ellos siguen siendo válidos. Desde 1.6, el manifiesto de rutas gana el campo opcional middleware, con los archivos de los middleware con nombre de la ruta en orden de ejecución, y el campo opcional serverMiddleware, con la cadena completa de los de servidor, los globales y después los con nombre (el manifiesto de virtual:meeko-manifest/client no lo lleva); un manifiesto sin ellos sigue siendo válido: su ruta ejecuta los globales isomórficos y ningún middleware de servidor.
  • desde 1.6, el campo opcional url lleva la URL para la que se renderizó el documento (pathname y search, sin origen ni fragmento); el navegador hidrata useRoute() con ella y después toma la suya. Un payload sin url sigue siendo válido e hidrata con la URL del navegador.
• Streaming. Los bloques <script type="application/json" data-meeko-deferred="N">, hijos directos de <body> y posteriores a #meeko-payload.
• Endpoints. /api/... según los archivos de server/api, POST /_meeko/rpc/<ruta> con cuerpo JSON y /_meeko/socket/<canal>?room=<sala>, cuyos mensajes de texto son { event, payload }. Los errores tienen la forma { code, status, requestId }; desde 1.2, un 400 por entrada no válida puede añadir issues: [{ path, message }], y rateLimit responde 429 RATE_LIMITED con Retry-After en segundos. Desde 1.2, las mutaciones retrySafe y las llamadas de api.* y rpc.* con idempotencyKey envían la cabecera Idempotency-Key con un UUID como cadena de Structured Fields ("…"), y el servidor la expone validada en RequestContext.idempotencyKey.
• Formularios nativos. Desde 1.7, un endpoint con form acepta application/x-www-form-urlencoded y multipart/form-data con los campos reservados return y _csrf, y responde 303 See Other (salvo 403 INVALID_ORIGIN o INVALID_CSRF, con el cuerpo de error de siempre). Los nuevos códigos INVALID_FORM y FILES_NOT_ALLOWED (400) llegan a la página en el resultado.
• Cabeceras:
  • x-meeko-csrf en las mutaciones;
  • x-meeko-csrf-token y x-request-id en las respuestas;
  • cache-control: no-store y x-accel-buffering: no en los streams;
  • desde 1.7, en una página con cache: ETag débil (W/"…"), Cache-Control: public, max-age=… (con no-transform en un stream), Vary: Accept, Cookie y 304 ante If-None-Match.
• Meta y cookie. La meta meeko-csrf-token y la cookie de sesión, que por defecto es __Host-meeko.sid (o meeko.sid sin Secure) y se configura con cookieName. Desde 1.4, con theme, la cookie del tema (meeko-theme por defecto, theme.cookie) y la clave de localStorage (theme.storageKey) guardan el nombre del tema o system en texto plano. Desde 1.7, la cookie de un solo uso de los formularios nativos se llama __Host-meeko-form (meeko-form sin HTTPS), es HttpOnly y SameSite=Lax y dura 60 segundos; su contenido y la clave meeko:form:<ruta> de sharedState que lo lleva al navegador son internos: sólo los interpretan el servidor y el navegador de la misma versión.
• Tema. Desde 1.4, con theme, los documentos que renderiza el servidor llevan Vary: Cookie, Sec-CH-Prefers-Color-Scheme, Accept-CH: Sec-CH-Prefers-Color-Scheme y, cuando la elección es system, Critical-CH: Sec-CH-Prefers-Color-Scheme (sin clientHints, sólo Vary: Cookie). El payload de una página que lee el tema lleva lo que renderizó el servidor en la clave meeko:theme de sharedState.
• Socket.
  • Los códigos de cierre documentados: 1003, 1008, 1009, 1011 y 1013, y desde 1.1 4401 (sesión rechazada) y 4403 (autorización del canal rechazada).
  • Las respuestas del handshake: 400, 403 INVALID_ORIGIN, 404 y las de los límites por HTTP. Desde 1.1, un rechazo de sesión (401) o de autorización del canal (403) completa el upgrade y cierra en seguida con 4401 o 4403, con un motivo fijo y sin llamar a los handlers. Véase framework.md.
• Redis:
  • el canal <prefix>socket:<canal>:<sala> con el sobre { v: 1, event, payload };
  • el canal de revocaciones <prefix>revoked;
  • desde 1.2, los contadores de rateLimit en <prefix>ratelimit:<resumen> (el resumen de la ruta y el sujeto no es contrato);
  • los registros de sesión que escriben RedisSessionStore y SqlSessionStore;
  • el esquema de referencia de D1SessionDriver.schema() y, desde 1.7, el de D1SessionDriver.rateLimitSchema();
  • desde 1.7, las columnas de los contadores de rateLimit en SQL (key, window_ends_at y count) del esquema de referencia de PostgreSQL de framework.md. La clave del contador de la que sale key no es contrato: si cambia, los contadores vuelven a empezar.
• Prerender. El índice prerender/manifest.json ({ version: 1, pages }); desde 1.3, cada página tiene el campo opcional scriptHashes, las fuentes CSP 'sha256-…' de sus scripts en línea, y desde 1.4 styleHashes, las de sus <style> en línea.

Un minor sólo puede añadir campos opcionales a estos formatos. Debe aceptar lo que escribió cualquier 1.x anterior y no cambia la versión de un formato. Durante un despliegue gradual pueden convivir instancias de dos minors con el mismo Redis o la misma base. El navegador y el servidor de una misma aplicación deben salir del mismo build; un payload con otra versión se rechaza con un mensaje explícito.

DevTools y editor#

• Protocolo DevTools 1.
  • El hook window.__MEEKO_DEVTOOLS__ (sólo en desarrollo), con protocolVersion: 1.
  • Sus métodos snapshot, subscribe, select, highlight, setBreakpoint y setSignal.
  • Los tipos Devtools* de la raíz.
  • Un minor puede añadir campos o tipos de evento. Pasar a otra versión del protocolo requiere una major. La extensión de Chrome mantiene su propio número de versión.
  • Desde 1.1, DevtoolsInstance tiene el campo opcional signalSites (tipo DevtoolsSignalSite), con la declaración de cada señal. Es un campo añadido dentro del protocolo 1: un hook o una captura sin él siguen siendo válidos.
• Opción devtools de meeko.config.ts (desde 1.8, aditiva). devtools: boolean | { panel?: boolean; position?: "bottom-right" | "bottom-left" | "top-right" | "top-left" } (tipo MeekoDevtoolsConfig) y position de mountDevtoolsPanel (tipo DevtoolsPanelPosition). Por defecto, false en toda la serie 1.x: sin la opción nada cambia. El panel sólo existe en meeko dev; que nunca llegue a meeko build, meeko start ni a una página prerenderizada forma parte del contrato. El aspecto del panel, el atajo Alt+Mayús+M y la clave meeko:devtools-panel de localStorage no forman parte del contrato y pueden cambiar en un minor.
• Servidor de lenguaje.
  • El arranque con meeko lsp --stdio o meeko-language-server.
  • Las initializationOptions trusted, projectContracts y diagnosticsDelay.
  • Las capacidades LSP estándar que anuncia. Un minor puede añadir capacidades y acciones rápidas.

Fuera del contrato#

• @meekojs/meeko/internal. Es el contrato entre el compilador y su runtime. Sólo está garantizado dentro de la misma versión exacta y puede cambiar en cualquier patch. No lo importe a mano. Lo mismo vale, desde 1.5, para @meekojs/meeko/builtins/*, los módulos compilados de <MeekoThemeToggle>, <MeekoAwait>, <MeekoPopover> y <MeekoSelect> que el compilador importa en los componentes que usan esas etiquetas.
• El código y los archivos generados.
  • Lo que hay bajo .meeko/: tipos, manifiestos, entradas, tsconfig por ámbito, builds intermedios y chunks/.
  • El contenido de .meeko/styles/main.css, la hoja global procesada que escribe meeko dev para el editor: sigue a lo que Vite y PostCSS generan en desarrollo y puede cambiar en cualquier versión. Su ruta sí se mantiene durante 1.x, para que la configuración del editor que la nombra (css.styleSheets) siga funcionando. Véase framework.md.
  • Los módulos virtuales de Vite (virtual:meeko-*).
  • El JavaScript que emite el compilador.
  • Una entrada propia que importe esos módulos debe fijar la versión exacta de Meeko.
• El puente del editor. El protocolo de valores en vivo entre el navegador, meeko dev y el editor (eventos meeko:live* de HMR, los descriptores .meeko/dev/editor-bridge-<puerto>.json, uno por servidor de desarrollo, la ruta /__meeko/editor-bridge y sus mensajes, incluido el campo alias) es sólo de desarrollo y no forma parte del contrato público: puede cambiar en cualquier versión. La extensión de VS Code ignora un descriptor con otra versión del protocolo. Véase devtools.md.
• Los logs del servidor en el navegador. Lo que meeko dev añade para reenviar la consola del servidor (desde 1.3): los bloques <script type="application/json" data-meeko-server-logs>, el campo devServerLogs de los payloads de navegación, el evento meeko:server-logs de HMR, sus módulos /@id/__x00__meeko:server-logs* y la forma serializada de los valores. Sólo existen en desarrollo, nunca en meeko build ni en meeko start, y pueden cambiar en cualquier versión. Lo estable es la opción dev.serverLogs. Véase framework.md.
• Las extensiones propias del servidor de lenguaje. La petición LSP meeko/executionZones y los modificadores de token semántico propios de Meeko (signal, computed, resource y reactive; modification es el estándar de LSP) son internos de la extensión de VS Code, que se publica junto al servidor. No son contrato público: pueden cambiar o desaparecer en un minor. Otro cliente LSP puede usarlos, pero debe tolerar esos cambios. Véase editors.md.
• La presentación. El texto de mensajes de error y diagnósticos, el HTML y los estilos de los paneles DevTools, los títulos de CodeLens, hovers y zonas del editor, la salida de consola y el formato de los logs.
• El repositorio. Los ejemplos, pruebas, benchmarks y scripts no se publican en npm.
• El rendimiento. Las cifras de rendimiento y tamaño, que pueden mejorar o variar entre versiones.

Deprecación#

1. Una API pública sólo se depreca en un minor y siempre con un reemplazo documentado, salvo que la funcionalidad desaparezca por completo; en ese caso se explica el motivo.
2. La deprecación se anuncia en el CHANGELOG, en la documentación y con @deprecated en el JSDoc, para que el editor la marque.
3. Donde es viable, el uso deprecado emite además un aviso:
   • un aviso de meeko check o del servidor de lenguaje para sintaxis y convenciones;
   • un aviso de consola en desarrollo, una vez por proceso, para APIs de runtime.
4. Lo deprecado sigue funcionando durante toda la serie 1.x y sólo se retira en la siguiente major, cuya guía de migración lo recoge.

APIs deprecadas#

El sistema de temas (theme, cookie, script y regla de iconos de <head>, useTheme, useThemeToggle y POST /_meeko/theme) permanece en core. Sólo se retiran las tres etiquetas; la guía de 1.8 explica su reemplazo.

El alias useSocket es la misma función que useSocketClient, así que no emite aviso de consola: el editor lo marca por su @deprecated. No afecta al autoimport useSocket("canal", opciones) de los clientes generados, que no está deprecado. Véase framework.md.

Los segmentos byId construyen las mismas peticiones que la llamada del segmento y tampoco emiten aviso de consola: el editor tacha cada método que se llama a través de ellos. La clave clientKey del manifiesto, createLocalCalls().api("users.byId", ...) y useApi no cambian ni están deprecados. Véase framework.md.

Un módulo importado o [módulo, opciones] en modules se sigue cargando igual, con las opciones en línea combinadas después de config[meta.configKey]; meeko dev, meeko build y meeko check escriben MEEK126 una vez por proceso y entrada, y el editor lo marca en meeko.config.*. Un módulo sin meta.configKey sólo recibe opciones con [módulo, opciones]: su autor debe declarar una antes de 2.0. @meekojs/i18n/module (y @meekojs/meeko/i18n/module) no están deprecados: son el subpath que resuelve '@meekojs/i18n'; sólo lo está importarlos en meeko.config.ts. Véase Actualizar de 1.7 a 1.8.

Una carpeta de layer listada en modules se sigue aplicando como layer, en la misma posición que antes, y meeko dev, meeko build y meeko check escriben un aviso una vez por proceso. extends no está deprecado: es un alias de layers. Véase framework.md.

MEEK128, MEEK129 y MEEK130 son sólo avisos de meeko check y del editor: en 1.x no cambian el SSR, la hidratación ni el código generado, y meeko check no falla por ellos. MEEK128 resuelve los nombres con el checker de TypeScript (una variable local window no es la global) y no avisa si la limpieza, o su registro, está protegida con typeof <global> o import.meta.env.SSR, ni dentro de onMounted, de un manejador de evento o de la continuación tras el primer await de navegador. En 2.0 los tres serán errores.

MEEK122 es sólo un aviso de meeko check, meeko build y el editor: en 1.x no cambia el SSR, la hidratación ni el código generado, y el valor se escribe igual. En 2.0, un literal fuera de AttributeValues<Tag, Name> en un atributo con valores cerrados será un error; un string calculado seguirá admitido.

MEEK107 es sólo un aviso de meeko check, meeko build y el servidor de lenguaje: en 1.x no cambia el SSR, la hidratación ni el código generado, y un string sin marcar se sigue insertando igual. En 2.0, el valor de html tendrá que ser asignable a TrustedHtml | null | undefined y el aviso pasará a ser un error. Los tipos literales de texto (html="'<br>'") siguen admitidos. Véase api.md.

MEEK109 es sólo un aviso de meeko check, meeko build y el servidor de lenguaje, y en 1.x el código generado no cambia. Esos usos compilan y se cargan en el navegador, pero no hacen nada (definePage fuera de <script server> y de los sidecars no configura la ruta) o fallan al llamarlos allí (las funciones de los adaptadores, de /password y de /build necesitan Node, Bun o Deno). Lo que ya fallaba antes de 1.3 es el error MEEK108 directamente: un autoimport de servidor no se resolvía en el bundle del navegador, @meekojs/meeko/server y /cloudflare no se pueden cargar allí (crean un AsyncLocalStorage de node:async_hooks), un import de server/ detenía meeko build, y las macros y onMounted no existen fuera del <script>. Véase framework.md.

HOST y PUBLIC_ORIGIN sólo se leen cuando falta MEEKO_HOST o MEEKO_PUBLIC_ORIGIN, y entonces meeko dev, start, preview y las salidas de meeko build escriben un aviso una vez por proceso que nombra la variable nueva. Véase framework.md.

Una vulnerabilidad que no se pueda corregir de forma compatible es la única excepción. En ese caso, el cambio mínimo necesario puede publicarse en un patch o un minor, con su explicación y migración en el CHANGELOG.

Cambios previstos para 2.0#

Además de retirar lo deprecado, 2.0 cambiará estos valores por defecto. En 1.x cada uno se puede activar antes con su opción.

Con "matched", una clase o un atributo que el script añade con la API del DOM a un elemento sin ref: ni on: deja de recibir los estilos con ámbito si ese elemento se quedó sin el atributo. Véase api.md.

Entornos soportados#

Las versiones de Bun, Deno y workerd de la tabla son las que se prueban. Pueden actualizarse en un minor y el CHANGELOG lo indica. Dejar de admitir Node 24 requiere una major.

Navegadores#

El runtime se publica compilado a ES2022, sin polyfills. Usa, entre otros, Object.hasOwn, Array.prototype.at, MutationObserver, fetch con cuerpos ReadableStream (navegación a rutas "stream") y WebSocket (Socket). El bundle cliente de una aplicación usa el objetivo por defecto de Vite 8, baseline-widely-available. Se admiten los navegadores que cumplen ese objetivo.

Las pruebas E2E se ejecutan con Chrome y con Chromium, Firefox y WebKit de Playwright. WebKit de Playwright no equivale a una prueba en Safari real.

Seguridad#

Las vulnerabilidades se informan de forma privada desde la pestaña Security de meekojs/meeko, nunca en un issue abierto. SECURITY.md detalla las versiones con soporte, qué incluir en el informe y los plazos de respuesta.

ESLint#

Durante Meeko 1.x, defineEslint ordena por defecto sólo los imports, con perfectionist/sort-imports y perfectionist/sort-named-imports, nivel warn, autofix y orden natural ascendente. En 2.0, esas dos reglas pasarán a error. perfectionist: true activa además el conjunto recommended-natural salvo sort-classes y sort-modules; esa lista la decide la versión de Perfectionist que fija el plugin. Puedes desactivarlas todas con perfectionist: false, apagar una con off o exigir error mediante rules; véase Ordenar con Perfectionist, que también lista los casos en los que --fix cambia el comportamiento. Los avisos pueden bloquear un CI que use --max-warnings 0.