Meeko como framework full-stack

Meeko conserva el motor independiente en @meekojs/meeko. El modo de aplicación usa @meekojs/meeko/framework y Vite usa @meekojs/meeko/vite. El servidor se reparte en estas subrutas:

• @meekojs/meeko/server: núcleo portable de la aplicación (createServerApp, defineServerRuntime, contratos API/RPC, sesiones, middleware, Socket, createSocketUpgradeHandler, OpenAPI y, desde 1.3, contentSecurityPolicy). Sólo usa Web APIs y node:async_hooks; no carga TypeScript, Vite, ws ni el sistema de archivos.
• @meekojs/meeko/node: adaptador Node (serveNode, toNodeListener, createNodeAssetReader, attachNodeWebSocketServer y createNodeSocketUpgradeHandler).
• @meekojs/meeko/password (desde 1.2): hashPassword, verifyPassword y needsRehash con scrypt; necesita node:crypto, así que sirve en Node, Bun y Deno, no en Workers (véase Contraseñas).
• @meekojs/meeko/bun: adaptador Bun (createBunServer y createBunAssetReader).
• @meekojs/meeko/deno: adaptador Deno (serveDeno y createDenoAssetReader).
• @meekojs/meeko/cloudflare: adaptador Cloudflare Workers (createWorker, createSocketRoomClass, DurableObjectSocketPubSub, D1SessionDriver, createCloudflareAssetReader y createCloudflarePrerenderSource).
• @meekojs/meeko/build: herramientas de build que leen el sistema de archivos y cargan TypeScript (discoverRoutes, discoverErrorPage, discoverConfiguredRoutes, composeFrameworkRoutes, loadMeekoConfig, readMeekoConfigSync, resolveConfigSources, discoverServerManifest, prerenderRoutes, prerenderProject, buildProject y, desde 1.3, inlineScriptHashes). El servidor de producción no la importa.

Todas las subrutas pertenecen al mismo paquete y versión. Los destinos de servidor publicados son Node 24, Bun, Deno y Cloudflare Workers, y la misma suite de conformidad los comprueba (véase Build, despliegue y verificación). Desde 1.3, el adaptador static genera además un sitio de archivos, sin servidor, para un hosting estático (véase Sitio estático). El build y las herramientas de desarrollo siguen ejecutándose con Node. SSR está activo por defecto.

La aplicación generada necesita Node 24 o posterior y TypeScript 7 para comprobar sus declaraciones; el compilador de .meeko utiliza internamente TypeScript 6 sólo durante el desarrollo y el build. El paquete es ESM. vite es un peer opcional: una aplicación que sólo usa el motor puede importar @meekojs/meeko sin iniciar el framework, el servidor, sesiones o Socket. El adaptador Node carga ws al activar attachNodeWebSocketServer, no al importar el motor.

Crear una aplicación#

meeko init-framework my-app
cd my-app
npm install
npm run dev

El starter crea meeko.config.ts, app/app.meeko, app/pages, app/styles/main.css, un layout con outlet y un .env.example con las variables de Meeko; no necesita server/runtime.ts, porque las sesiones funcionan sin configuración (véase Autenticación). Meeko genera las entradas cliente/servidor y sus configuraciones de build bajo .meeko/; el consumidor ejecuta meeko dev, meeko check, meeko build y meeko start mediante los scripts de package.json; meeko preview ejecuta también el build. La aplicación puede organizarse así:

app/{pages,layouts,middleware,components,composables,utils,stores,styles}/
server/{api,rpc,socket,middleware,utils}/
shared/{types,schemas,utils,constants,enums}/
layers/base/app/pages/
modules/auth/app/pages/
public/
meeko.config.ts
tsconfig.json
.meeko/{types,manifests,generated,output}/

Meeko genera entradas Vite y configuraciones TypeScript por ámbito sólo bajo .meeko/. El único tsconfig.json raíz conecta VS Code con esos proyectos generados para conservar diagnósticos y autocompletado en archivos .ts. server/runtime.ts, opcional, es código de la aplicación: declara servicios, política de Socket y, si no bastan las de Meeko, sus propias sesiones. El starter del motor aislado continúa disponible con meeko init <directory>.

Migrar un starter full-stack anterior#

Una aplicación generada con 0.0.4 puede adoptar el host de proyecto actual sin mantener entradas manuales. Cambie sus scripts a meeko dev, meeko check, meeko build y meeko start; ejecute primero el nuevo build y compare cualquier personalización propia. Después puede retirar server.mjs, las entradas cliente/servidor, las configuraciones Vite y los tsconfig.* por ámbito que Meeko genera ahora bajo .meeko/. El tsconfig.json raíz sí permanece como enlace para el editor.

Si desea la convención actual de layouts, mueva el layout raíz a app/layouts/default.meeko. No conserve simultáneamente ese archivo y app/pages/+layout.meeko, porque ambos representarían el mismo nivel del árbol. Traslade las personalizaciones representables a middleware, handlers y convenciones públicas soportadas. Si una personalización del host o de Vite no tiene todavía una API pública equivalente, conserve el host manual; la migración no debe borrar ni atribuir a meeko.config.ts capacidades que no ofrece.

Migrar server/session.ts a server/runtime.ts#

Meeko ya no carga server/session.ts. Si el archivo existe, meeko check, meeko dev y meeko build se detienen con las instrucciones de migración en lugar de ignorarlo. Traslade el SessionManager que devolvía createSessionManager(production) al export por defecto de server/runtime.ts y elimine server/session.ts:

// Antes: server/session.ts
export function createSessionManager(production: boolean) {
	return new SessionManager({ store: createStore(production), production })
}

// Después: server/runtime.ts
import { defineServerRuntime, SessionManager } from '@meekojs/meeko/server'

export default defineServerRuntime(({ production, prerendering }) => ({
	sessions: new SessionManager({ store: createStore(production && !prerendering), production: production && !prerendering }),
	services: (request) => ({/* servicios por petición */}),
}))

meeko build crea el runtime con prerendering: true para renderizar las rutas render: "prerender"; durante esa fase no se sirve tráfico de clientes, por lo que la aplicación puede usar un store en memoria en lugar de abrir la base de producción. Las aplicaciones que importaban herramientas de build desde @meekojs/meeko/server deben importarlas desde @meekojs/meeko/build (discoverRoutes, discoverServerManifest, loadMeekoConfig, prerenderProject…), y toNodeListener, attachNodeWebSocketServer y createNodeSocketUpgradeHandler desde @meekojs/meeko/node. createServerDispatcher, createLocalCalls, generateOpenApi y loadSocketChannels exigen ahora un cargador explícito, por ejemplo (file) => import(pathToFileURL(file).href) en Node.

app/styles/main.css es opcional y se carga automáticamente como hoja global en desarrollo y en el build. Vite la incluye en el asset CSS de producción; Meeko enlaza ese asset en el HTML SSR y prerenderizado. Los bloques <style> de .meeko siguen disponibles para estilos locales.

PostCSS y Tailwind. Vite procesa con PostCSS tanto app/styles/main.css como los <style> de los componentes, con el postcss.config.* de la raíz del proyecto. Para Tailwind 4, instale tailwindcss y @tailwindcss/postcss, declare el plugin y cargue Tailwind en la hoja global; Tailwind lee las clases de los .meeko:

// postcss.config.mjs
export default { plugins: { '@tailwindcss/postcss': {} } }

/* app/styles/main.css */
@import 'tailwindcss';

En un <style scoped>, @apply necesita @reference "tailwindcss"; (o la ruta de la hoja con su tema) al principio del bloque. Desde 1.2, el CSS de cada componente es el módulo Componente.meeko?meeko-style=…&lang.css, junto a su archivo, así que los plugins de PostCSS resuelven @reference y los @import relativos desde la carpeta del componente. El selector ya lleva el atributo de ámbito cuando Tailwind expande @apply, así que las declaraciones heredan el scope:

<!-- app/components/Card.meeko -->
<style scoped>
	@reference '../styles/main.css'; /* con el @theme del proyecto */

	.card {
		@apply rounded-lg bg-brand p-4;
	}
</style>

Tailwind genera también las clases que sólo aparecen en literales de bind:class (bind:class="open.value ? 'ring-4' : undefined"), porque lee el texto de los .meeko. meekoUtilities() convive con Tailwind si va antes en la lista de plugins (plugins: [meekoUtilities(), tailwindcss()], con import tailwindcss from '@tailwindcss/postcss'): Tailwind recibe ya las reglas generadas en lugar de @utilities.

@tailwindcss/postcss detecta las fuentes desde el directorio de trabajo (process.cwd()), no desde la raíz del proyecto. Los comandos de la CLI que reciben el proyecto (dev, build, start, preview, check, routes, prerender y check-app) cambian el directorio de trabajo a esa raíz antes de cargar la configuración y PostCSS, así que meeko dev ../app funciona desde cualquier carpeta; las rutas relativas del argumento se resuelven antes, contra la carpeta de lanzamiento. Las APIs programáticas (buildProject, startProject…) no tocan el cwd del proceso: llámelas con el cwd en la raíz o fije el origen con @import 'tailwindcss' source('../..'); (relativo a la hoja) o con la opción base del plugin. Desde una carpeta mayor, Tailwind recorre todo su contenido; desde la raíz de un disco puede agotar la memoria.

Durante el SSR y el prerender, Meeko incrusta en el documento el CSS de los <style> de los componentes ya procesado por PostCSS y los plugins CSS de Vite (desde 1.8; antes llegaba sin procesar), así que un @apply con ámbito o un @utilities dentro de un componente se aplican desde el primer pintado, sin esperar al JavaScript. Es el mismo CSS que el asset del componente; los <style> en línea conservan el nonce o los hashes de la CSP, la deduplicación y el orden del árbol (layouts, página e hijos). Van al final del <head>, después de app/styles/main.css, de las hojas de los módulos y del head de document, que es donde el cliente añade después el CSS de los componentes: una regla con ámbito y una global de igual especificidad se resuelven igual en el primer pintado que tras hidratar (desde 1.8; antes la global ganaba sólo hasta que cargaba el JavaScript). En meeko dev, el cliente de Vite adopta esos <style> en lugar de añadir una copia, y la HMR los sustituye: una regla que se borra del <style> deja de aplicarse sin recargar. La página de error de un fallo del servidor, que no se hidrata, también incrusta su CSS.

@tailwindcss/vite. Meeko no lee vite.config.*, pero un módulo puede registrar el plugin de Vite de Tailwind con addVitePlugin. Sustituye a @tailwindcss/postcss (no declare los dos); meeko dev y meeko build lo aplican a app/styles/main.css y a los <style> de los componentes, con @theme, @apply con ámbito y las clases de bind:class. A diferencia del plugin de PostCSS, detecta las fuentes desde la raíz de Vite, que es la del proyecto:

// modules/tailwind.mjs
import { defineMeekoModule } from '@meekojs/meeko/framework'
import tailwindcss from '@tailwindcss/vite'

export default defineMeekoModule({
	meta: { name: 'tailwind' },
	setup(_options, meeko) {
		meeko.addVitePlugin(tailwindcss())
	},
})

// meeko.config.mjs
export default { modules: ['./modules/tailwind.mjs'] }

Un host de Vite propio que sólo usa el plugin meeko() no recibe los addVitePlugin; ahí se añade tailwindcss() a su plugins. Con @tailwindcss/vite, meekoSortClasses: "stylesheet" no ve las utilidades (procesa la hoja sin los plugins de Vite de los módulos); use "tailwind".

Orden de las clases con Prettier. Con meekoSortClasses: "tailwind" (desde 1.8), el plugin de Prettier (@meekojs/prettier-plugin o @meekojs/meeko/prettier) ordena las clases de cada class="…" estático con el orden oficial de Tailwind CSS 4, el de prettier-plugin-tailwindcss (que no reconoce el parser meeko). Carga el design system de app/styles/main.css, o de la hoja que indique meekoTailwindStylesheet (relativa a la raíz del proyecto), con sus @import, @theme, @plugin y @utility, usando el tailwindcss instalado en el proyecto; funciona igual con @tailwindcss/postcss que con @tailwindcss/vite. Las clases que Tailwind no conoce, como las de meekoUtilities() o las del <style> del componente, van primero y en su orden. No toca bind:class ni el class de una etiqueta de componente.

{ "plugins": ["@meekojs/prettier-plugin"], "meekoSortClasses": "tailwind", "meekoTailwindStylesheet": "app/styles/main.css" }

<!-- antes -->
<div class="text-white custom p-4 bg-brand flex hover:bg-brand/80"></div>
<!-- después -->
<div class="custom flex bg-brand p-4 text-white hover:bg-brand/80"></div>

Si tailwindcss 4 no está instalado, la hoja no existe o Tailwind la rechaza, las clases no se ordenan (sólo se normalizan) y se avisa una vez. El design system se reutiliza mientras no cambien la hoja ni lo que importa. En un workspace no confiable del editor, "tailwind" se comporta como "off", igual que "stylesheet", porque ejecutaría los @plugin del proyecto.

Utilidades generadas con TypeScript. Desde 1.2, el plugin de PostCSS meekoUtilities() de @meekojs/meeko/postcss genera reglas con una función de TypeScript en lugar de repetirlas a mano. La at-rule @utilities "<ruta>" [layer(<nombre>)]; se sustituye por las reglas que devuelve el export por defecto del módulo:

// postcss.config.ts
import { meekoUtilities } from '@meekojs/meeko/postcss'

export default { plugins: [meekoUtilities()] }
// O, con la forma de objeto: { plugins: { "@meekojs/meeko/postcss": {} } }

/* app/styles/main.css */
@layer tokens, utilities;
@import './tokens/colors.css' layer(tokens);
@utilities "./utilities/color.ts" layer(utilities);

// app/styles/utilities/palette.ts
export const colors = ['gray', 'blue', 'red'] as const
export const steps = Array.from({ length: 12 }, (_, i) => i + 1)

// app/styles/utilities/color.ts
import { defineUtilities } from '@meekojs/meeko/postcss'
import { colors, steps } from './palette'

export default defineUtilities(({ rule, atRule }) => [
	colors.map((name) => rule(`.color[data-color='${name}']`, Object.fromEntries(steps.map((step) => [`--color-${step}`, `var(--${name}-${step})`])))),
	rule('.color', { color: 'var(--color-11)' }, rule('&:hover', { backgroundColor: 'var(--color-3)' }), atRule('media', '(prefers-contrast: more)', { color: 'var(--color-12)' })),
])

Genera @layer utilities { .color[data-color='gray'] { --color-1: var(--gray-1); … } … .color { color: var(--color-11); &:hover { … } @media (prefers-contrast: more) { … } } }. Un bucle de preprocesador, como @each $size in sm, md, lg de postcss-each (que no forma parte de PostCSS: sin ese plugin, la regla llega al navegador tal cual y no hace nada), se escribe como un map de TypeScript:

// app/styles/utilities/button-sizes.ts
import { defineUtilities } from '@meekojs/meeko/postcss'

const sizes = { sm: '0.25rem 0.5rem', md: '0.5rem 1rem', lg: '0.75rem 1.5rem' }

export default defineUtilities(({ rule }) => Object.entries(sizes).map(([size, padding]) => rule(`.button[data-size='${size}']`, { padding })))

La at-rule:

• Ruta. Entre comillas y relativa a la hoja que contiene la at-rule: la hoja global, un archivo que esta importa con @import o el <style> de un .meeko, que resuelve desde la carpeta del componente. Admite .ts, .mts, .js y .mjs. Sin archivo de origen (CSS procesado sin la opción from de PostCSS), la ruta es relativa a meekoUtilities({ root }), por defecto process.cwd().
• layer(x) envuelve el resultado en @layer x { … }; layer sin nombre crea una capa anónima. Sin layer, las reglas quedan en el lugar de la at-rule.
• No lleva bloque { … }. Puede aparecer varias veces y dentro de otras reglas o at-rules.
• Va después de los @import. Para CSS es una regla más, y los @import deben preceder a cualquier regla: Vite avisa (@import statements must precede all other statements) y no incluye un @import que sigue a un @utilities.
• No colisiona con Tailwind. El nombre es @utilities; @utility, de Tailwind 4, no se toca.

El módulo exporta por defecto defineUtilities(fn) o una función sin envolver. fn recibe los helpers, puede ser async y devuelve un nodo, un array de salidas (anidado a cualquier profundidad, se aplana en orden) o null, false y undefined, que se omiten, para escribir condición && rule(…).

Las declaraciones son un objeto: las claves en camelCase pasan a kebab-case (borderRadius → border-radius, WebkitAppearance → -webkit-appearance, msFlex → -ms-flex); las claves en kebab-case ("border-radius") y las propiedades personalizadas --* se escriben tal cual. Un valor es una cadena, que puede terminar en !important, o un número, que se escribe sin unidades (opacity: 0.5, zIndex: 10). undefined omite la declaración y un array escribe una declaración por valor, para los valores de respaldo (display: ["-webkit-box", "flex"], también un array as const).

Desde 1.3, las declaraciones están tipadas con csstype: el editor autocompleta las propiedades estándar y con prefijo de proveedor, y las palabras clave de su valor (position: "sticky"), y una propiedad mal escrita (backgroundColr) o una palabra clave que no existe es un error de tipos en el editor y al comprobar el módulo con TypeScript. Las longitudes y los tiempos son cadenas con unidad (padding: "4px", transitionDuration: "200ms"), salvo el 0: padding: 4 es un error, porque se escribiría padding: 4, que el navegador descarta. Los números valen donde CSS los admite sin unidad (opacity, zIndex, flexGrow, lineHeight, fontWeight…). En atRule, el objeto admite además los descriptores de @font-face (src, fontDisplay, unicodeRange…), @property (syntax, inherits, initialValue), @page, @counter-style, @font-palette-values y @view-transition (tipo UtilityAtRuleDeclarations). Un objeto que se construye fuera de la llamada pierde las palabras clave (const base = { position: "absolute" } es { position: string }): anótelo con UtilityDeclarations o use as const. Un objeto con claves dinámicas, como el { [k: string]: string } de Object.fromEntries en el ejemplo de la paleta o un Record<string, string>, se acepta sin comprobar sus claves. A la inversa, UtilityDeclarations ya no tiene firma de índice: leerlo con una clave string (decls[key]) es el error TS7053 con noImplicitAny; use Object.entries(decls) o una clave keyof UtilityDeclarations. Para una propiedad o una at-rule que csstype todavía no conoce, escriba el CSS con css`…`.

Los tipos UtilityHelpers, UtilityDeclarations, UtilityAtRuleDeclarations (desde 1.3), UtilityValue, UtilityOutput, UtilityNode, UtilityRule, UtilityAtRule, UtilityCss, UtilityFunction y MeekoUtilitiesOptions se exportan desde el mismo subpath.

Los errores detienen la hoja con el archivo CSS y la línea del @utilities, que Vite muestra en su overlay: un módulo que no existe o con otra extensión, un módulo que no compila, un export por defecto que no es una función, una excepción de la función (con su mensaje), un selector, un nombre de propiedad, un valor o unos parámetros de at-rule no válidos (un ; o una llave en un valor, un número NaN) y un valor de la salida que no es un nodo de los helpers, por ejemplo una cadena de CSS sin css. Tras corregir el módulo, la siguiente edición regenera la hoja.

Carga del módulo y actualización en caliente. import() nativo guarda en caché cada módulo del grafo durante toda la vida del proceso: una query en el módulo de entrada lo recarga a él, pero no a los archivos locales que importa. Por eso el plugin empaqueta el módulo con rolldown, el bundler que Vite 8 ya incluye (no añade dependencias): los archivos locales, también los que llegan por un alias de tsconfig o por #imports del mismo paquete, forman un único módulo ES que se importa desde una URL data:, y los paquetes de node_modules quedan externos y se cargan una vez con Node, como en cualquier programa. Así se admite todo TypeScript, imports sin extensión incluidos, e import.meta.url, import.meta.dirname e import.meta.filename siguen describiendo el archivo original. El resultado se reutiliza mientras ningún archivo del grafo cambie de fecha de modificación o de tamaño, de modo que una hoja que se transforma muchas veces no vuelve a empaquetar nada. El plugin publica cada archivo del grafo como dependencia de la hoja (mensajes dependency de PostCSS), así que en meeko dev editar color.ts o palette.ts regenera la hoja y Vite actualiza el CSS en caliente, sin recargar la página ni reiniciar el servidor. Guarde estos módulos fuera de las carpetas que Meeko vigila por sus autoimports y sus rutas (app/components, app/composables, app/utils, app/stores, app/pages, app/layouts, shared/…, server/utils, las de imports…): un cambio en ellas recarga la página entera, como cualquier otro archivo de esas carpetas; app/styles/ es el lugar natural. Fuera de Vite 8 (por ejemplo, postcss-cli), si no encuentra rolldown, el plugin importa el módulo con la eliminación de tipos nativa de Node, que exige imports con extensión y sintaxis de TypeScript borrable, recarga sólo el módulo de entrada y lo advierte una vez.

Autoimports. Desde 1.4, el módulo de @utilities y los módulos locales en TypeScript que importa reciben los mismos autoimports de valores que el resto del proyecto: el plugin aplica, dentro del bundle de rolldown, el registro y la transformación del plugin de Vite, así que un app/styles/utilities/color.ts puede usar sin import la constante THEME_COLORS de app/theme/constants.ts si meeko.config.ts declara imports: { appDirs: ["app/theme"] }, igual que un componente. Como en el editor y en meeko check, cada módulo recibe los de su ámbito según su carpeta (app/, shared/ o server/ de la aplicación o de un layer); un módulo fuera de esas carpetas no recibe ninguno. Los módulos de @utilities se ejecutan en Node mientras se genera el CSS, así que el registro se limita a lo que tiene sentido ahí:

Usar uno de la segunda columna no da un ReferenceError opaco: el nombre se sustituye por un valor que, al usarse (leerlo, llamarlo, convertirlo en texto), lanza un error con el autoimport, su origen y el motivo, que el plugin muestra en la línea del @utilities: "./utilities/color.ts" lanzó un error al generar las utilidades: app/styles/utilities/color.ts usa el autoimport SECRET, que no está disponible al generar el CSS de @utilities: viene de server/utils/secret.ts, que sólo existe en el servidor. …. Como el error sólo aparece si el valor se usa, un archivo de autoimports que el módulo importa y que además exporta, por ejemplo, un composable con signal sigue sirviendo para leer sus constantes. defineUtilities no es un autoimport: impórtelo de @meekojs/meeko/postcss, porque declararlo global lo ofrecería también a los componentes y llevaría PostCSS al bundle del navegador. Los tipos son los de app/ (.meeko/tsconfig.app.json), así que meeko check y el editor dan TS2304 al usar en app/styles/ un export de server/utils, como en el resto de app/; en cambio aceptan los nombres del navegador y del framework de la tabla, que fallan al generar la hoja con el error anterior.

El proyecto es la carpeta más cercana al módulo con un meeko.config.*, sin pasar de su package.json, o la de ese package.json si depende de @meekojs/meeko; su configuración se ejecuta como en meeko dev, con los setup de sus módulos, una vez por hoja y sólo si el módulo se va a empaquetar con rolldown. Si leerla falla (una configuración o un setup que lanza), la hoja se genera igual, sin autoimports, con un aviso de PostCSS que da el motivo. Los archivos de autoimports que el módulo usa forman parte de su grafo: son dependencias de la hoja, y cambiarlos la regenera. Añadir o quitar un export en una carpeta de autoimports también vuelve a empaquetar el módulo en la siguiente transformación, aunque ningún archivo de su grafo haya cambiado; en meeko dev, esos cambios recargan la página entera, como en cualquier otra carpeta de autoimports. meekoUtilities({ autoImports: false }) desactiva los autoimports y empaqueta los módulos como en 1.3. Fuera de un proyecto Meeko (un postcss-cli o un bundler en otro proyecto) no hay registro y nada cambia. Sin rolldown, con el import() nativo, Node no permite añadir imports: el módulo no recibe autoimports, la configuración no se ejecuta y el aviso de carga nativa lo indica; escriba los imports.

Las reglas generadas en un <style scoped> no reciben el atributo de ámbito: Meeko aplica el ámbito al compilar el bloque y PostCSS genera las reglas después, así que son globales, como las de app/styles/main.css. El plugin sólo se ejecuta en Node, durante meeko dev y el build; @meekojs/meeko/postcss no forma parte del runtime del navegador ni del servidor.

Con Tailwind. Declare meekoUtilities() antes de @tailwindcss/postcss:

// postcss.config.ts
import tailwindcss from '@tailwindcss/postcss'
import { meekoUtilities } from '@meekojs/meeko/postcss'

export default { plugins: [meekoUtilities(), tailwindcss()] }

En ese orden, Tailwind recibe las reglas generadas como el resto de la hoja y procesa, por ejemplo, el @apply de un css`…`; con layer(utilities) quedan en la misma capa utilities que las de Tailwind. En el orden inverso, Tailwind compila primero cada hoja que importa tailwindcss y elimina las at-rules que no conoce, @utilities incluida, sin error; el plugin lo advierte una vez por proceso. En una hoja sin @import "tailwindcss", como el <style> de un componente, el orden no importa.

Hoja global procesada para el editor. Las clases que generan las @utilities, y las de los archivos que la hoja importa, no están escritas en ningún archivo CSS del proyecto. Por eso meeko dev escribe app/styles/main.css ya procesada en .meeko/styles/main.css: la misma hoja que sirve en /app/styles/main.css?direct, con los @import resueltos, las @utilities expandidas y el resto de plugins de PostCSS aplicados, sin minificar y con un comentario inicial que indica que es generada. La escribe en segundo plano en cuanto el servidor escucha, sin retrasar el arranque, y la reescribe cada vez que cambian la hoja o algo de lo que depende: un archivo importado, un módulo de @utilities o un archivo que ese módulo importa. También tras un reinicio de Vite (por ejemplo, al cambiar .env).

• Sólo sustituye el archivo cuando cambia su contenido, y de forma atómica (escribe un temporal y lo renombra), así que un lector nunca ve media hoja. Vite no vigila .meeko/: escribirla no recarga la página ni provoca otra regeneración.
• Si la hoja no compila (un error de PostCSS o de un módulo de @utilities), el archivo conserva la última versión buena, el servidor sigue funcionando y la consola lo indica una vez: [meeko] .meeko/styles/main.css conserva la versión anterior: app/styles/main.css no compila (…). El siguiente cambio que la arregla la regenera.
• Sin app/styles/main.css no hay archivo; si la hoja se borra con meeko dev en marcha, también se borra el archivo.
• meeko build no lo escribe: el CSS del build está minificado y mezcla la hoja global con los <style> de los componentes. El archivo se conserva al detener meeko dev, así que basta con haberlo ejecutado una vez; meeko clean lo elimina con el resto de .meeko/.
• Nada lo carga en ejecución y no debe editarse a mano. Las url() aparecen como las reescribe Vite en desarrollo.

Sirve a las extensiones del editor que completan clases a partir de hojas CSS en disco. Con HTML CSS Support (ecmel.vscode-html-css) en VS Code:

// .vscode/settings.json
{ "css.styleSheets": [".meeko/styles/main.css"] }

La ruta es relativa a la carpeta del workspace. La extensión busca los archivos locales con la búsqueda de VS Code, que aplica files.exclude pero no .gitignore ni search.exclude: encuentra el archivo aunque .meeko/ esté en .gitignore, como en el starter. Si su files.exclude oculta .meeko, la extensión tampoco lo verá; oculte en su lugar sólo las carpetas que no quiera ver, por ejemplo ".meeko/output": true. La extensión guarda cada hoja local en caché y sólo la vuelve a leer cuando se guarda desde el propio editor: tras un cambio que regenera el archivo, ejecute CSS: Clear style sheets cache desde la paleta de comandos para ver las clases nuevas. Por defecto sólo completa en HTML; para los .meeko, añada "css.enabledLanguages": ["html", "meeko"] en la configuración de usuario (la extensión no lo admite por workspace) y reinicie VS Code.

En desarrollo, Vite abre un WebSocket HMR en un puerto derivado del puerto HTTP para que dos aplicaciones Meeko no compitan por el puerto predeterminado de Vite. MEEKO_HMR_PORT permite fijarlo explícitamente cuando el entorno lo exige; el navegador debe poder acceder a ese puerto además del HTTP de la aplicación.

Variables de entorno y .env. Desde 1.2, meeko dev, build, start, preview y check cargan el .env de la raíz del proyecto en process.env, como Vite y Nuxt en desarrollo. Una variable que el entorno ya define tiene prioridad, así que el entorno real de un despliegue nunca se sustituye. La salida de meeko build ejecutada directamente (node .meeko/output/node/index.mjs, un contenedor) no lee .env: en producción las variables llegan del entorno. Cambiar .env exige reiniciar meeko dev. Meeko lee estas variables:

Desde 1.2, todas las variables que lee Meeko empiezan por MEEKO_; el prefijo queda reservado para Meeko, así que las variables propias de la aplicación deben usar otro nombre. HOST y PUBLIC_ORIGIN, los nombres anteriores, siguen funcionando durante 1.x cuando falta la variable nueva, con un aviso por proceso que nombra su reemplazo, y dejarán de leerse en 2.0. PORT no está obsoleta: es el respaldo permanente de MEEKO_PORT.

Si ni MEEKO_PORT (o PORT) ni server.port fijan el puerto, meeko dev usa el primero libre a partir de 4173 (hasta 4192), como Vite: con otro meeko dev ya en 4173, el segundo escribe [meeko] El puerto 4173 está en uso; meeko dev usa el 4174 y la URL real, y deriva de ese puerto el del WebSocket HMR y el descriptor del puente con el editor (.meeko/dev/editor-bridge-4174.json). Un puerto fijado con MEEKO_PORT, PORT o server.port no cambia: si está ocupado, meeko dev termina con El puerto 4173 de 127.0.0.1 ya está en uso; usa MEEKO_PORT=<otro puerto> o cierra el otro meeko dev.

URL que se muestra. Desde 1.7.1, meeko dev, meeko start, meeko preview y las salidas de Node, Bun y Deno escriben http://localhost:4173 cuando escuchan en loopback (127.0.0.1 o ::1) o en todas las interfaces (0.0.0.0 o ::). Sólo cambia el texto: el servidor sigue escuchando en la dirección configurada, serveNode(...).url y serveDeno(...).url conservan esa dirección (http://127.0.0.1:4173) y, sin MEEKO_PUBLIC_ORIGIN, Socket sigue tomándola como origen y acepta los otros nombres de loopback, así que una página abierta en localhost conecta igual. Con MEEKO_HOST=0.0.0.0 (o ::, o server.host equivalente) se añade una línea Red: por cada dirección de las interfaces de red, al estilo de Vite: IPv4 con 0.0.0.0, e IPv4 e IPv6 global con ::, sin las de loopback ni las IPv6 de enlace local. La salida de Deno sólo las lista si tiene --allow-sys=networkInterfaces (meeko preview concede -A); sin ese permiso escribe sólo la URL local y nunca pregunta. Con un host concreto, como 192.168.1.20, se muestra ese host. La primera línea es siempre la URL local, sola, para los scripts que la leen:

http://localhost:4173
Red: http://192.168.1.20:4173

El SSR de desarrollo carga @meekojs/meeko desde Node, fuera del module runner de Vite, como el build; así una aplicación que consume Meeko con link: mantiene una sola instancia del runtime aunque Vite recargue sus módulos. Por eso, cuando @meekojs/meeko está enlazado (link: de pnpm, npm link o un workspace: el paquete se resuelve fuera de todo node_modules), meeko dev ejecuta el servidor en un proceso hijo y vigila dist/ y package.json del paquete enlazado. Al reconstruirlo, espera a que la compilación termine (400 ms sin cambios), escribe [meeko] Meeko enlazado cambió; reiniciando meeko dev…, cierra el servidor anterior (Socket, HTTP, Vite y el descriptor del puente con el editor) y arranca otro proceso en el mismo puerto, con el mismo entorno. Si el nuevo proceso no arranca, por ejemplo porque la compilación quedó a medias, lo informa y vuelve a intentarlo con el siguiente cambio. Sólo cuentan las escrituras: leer el build no lo reinicia, aunque Windows notifique como cambio la actualización de la fecha de último acceso. Ctrl+C detiene ambos procesos. Con una instalación normal desde el registro no se vigila nada más.

MEEKO_LINK_WATCH=0 (también desde el .env del proyecto) desactiva el reinicio con un paquete enlazado: un solo proceso sirve hasta que se detiene. Ese proceso conserva el código de servidor de Meeko que cargó, mientras Vite sirve al navegador los archivos nuevos de dist/, así que tras una reconstrucción el HTML del servidor (cabeceras, <head>, SSR) sale del build anterior y la hidratación usa el nuevo. Por eso, en cada reconstrucción, cuando termina, escribe [meeko] Meeko enlazado cambió (…/dist), pero este meeko dev no se reinicia solo (MEEKO_LINK_WATCH=0): el servidor sigue con el código anterior y el navegador recibe el nuevo. Reinicia meeko dev. Reinícielo antes de comprobar el resultado.

Configuración#

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({
	layers: ['./layers/base'],
	modules: ['@acme/meeko-seo', './modules/hello'],
	seo: { siteUrl: 'https://example.com' },
	imports: {
		appDirs: ['app/services'],
		sharedDirs: ['shared/validators'],
		serverDirs: ['server/services', 'server/repositories'],
	},
	document: { lang: 'es', head: { meta: [{ name: 'theme-color', content: '#0f172a' }] } },
})

meeko.config.ts (o .mts, .js, .mjs) se carga con Node y exporta un objeto creado con defineMeekoConfig:

• layers (desde 1.2): carpetas que aportan páginas, componentes, autoimports y plugins; véase Layers. extends, el nombre anterior, sigue funcionando como alias.
• modules: nombres de los módulos creados con defineMeekoModule (paquetes o rutas), que configuran el proyecto desde código; sus opciones van en la clave de cada uno, como seo. Véase Módulos.
• imports: carpetas de autoimports además de las de por defecto, con el ámbito de la carpeta que las contiene; véase Autoimports y TypeScript.
  • imports.appDirs (desde 1.3): carpetas dentro de app/ ("app/services"), con el ámbito de app/: navegador y SSR, no shared/ ni server/.
  • imports.sharedDirs (desde 1.3): carpetas dentro de shared/ ("shared/validators"), con el ámbito de shared/: aplicación y servidor.
  • imports.serverDirs: carpetas dentro de server/, exclusivas del servidor.
• server: el adaptador de meeko build; véase Build, despliegue y verificación.
• document (desde 1.2): lang y las entradas de <head> de todos los documentos. Los módulos añaden las suyas con meeko.addHead; las de document.head se aplican después, así que el title del proyecto gana. Desde 1.3, document.seo añade la URL canónica y Open Graph de cada página; véase Canónica y Open Graph por página. Desde 1.5, document.idPrefix es el prefijo de los IDs de useId y de form.field (m por defecto).
• dev (desde 1.3): opciones de meeko dev. serverLogs: false desactiva los logs del servidor en la consola del navegador.
• devtools (desde 1.8): true hace que meeko dev monte el panel de Meeko DevTools en la página, sin código de la aplicación; { position: "bottom-left" } elige su esquina. Por defecto, false. Nunca llega a meeko build ni a meeko start.
• site (desde 1.3): la URL pública del sitio ("https://example.com", sólo el origen). Es el origen de las URL absolutas que escribe Meeko: sitemap.xml, robots.txt y document.seo. Sin site, el build usa MEEKO_PUBLIC_ORIGIN. No cambia las comprobaciones de Origin, que siguen leyendo MEEKO_PUBLIC_ORIGIN o publicOrigin de server/runtime.ts al ejecutarse.
• sitemap y robots (desde 1.3): sitemap.xml y robots.txt generados en el build; véase sitemap.xml y robots.txt.
• theme (desde 1.4): el tema claro/oscuro, y temas propios, sin parpadeo, con useTheme(); véase Tema claro/oscuro sin parpadeo.
• alias (desde 1.5): aliases de ruta propios, o cambios de ~/, @/, #shared/ y #server/, los que Meeko define por defecto; véase Aliases de ruta.

Desde 1.2, css: { scopeAttribute: "matched" } limita el atributo de <style scoped> a los elementos que algún selector con ámbito puede seleccionar; con "all", el valor por defecto en 1.x, va en todos los elementos de la plantilla. "matched" pasará a ser el valor por defecto en 2.0. Véase Estilos con ámbito, con el caso de las clases que el script añade con la API del DOM.

La configuración se ejecuta en meeko dev, meeko build y meeko check. En un workspace de confianza el servidor de lenguaje también la ejecuta, con sus módulos, por lo que las listas pueden construirse dinámicamente; en un workspace no confiable (o con trusted: false, ver editores) el editor no ejecuta código del proyecto: lee layers, extends, imports.appDirs, imports.sharedDirs e imports.serverDirs como arrays literales de cadenas y, de modules, sólo las cadenas literales que son carpetas de layer. Desde 1.5 lee también alias cuando es un objeto literal de cadenas y false. Los autoimports y componentes de los módulos no existen para ese editor hasta que se confía en el workspace.

El descubrimiento de servidor también rechaza árboles de cliente imposibles. Por ejemplo, no permite que api.users.get() sea a la vez una función y el padre de api.users.get.post(), ni que un procedimiento rpc.users() sea el padre de rpc.users.get(). El error se produce al generar el manifiesto e identifica ambos archivos, antes de inicializar el cliente o emitir tipos contradictorios.

meeko routes . descubre todas las fuentes, emite .meeko/manifests/routes.json y declaraciones de rutas, contratos y autoimports; desde 1.7 prepara .meeko/ igual que meeko check (también las entradas de Vite, services.d.ts y los tsconfig.*.json), sin ejecutar TypeScript. Vite genera módulos virtuales a partir del mismo descubrimiento para SSR, hidratación y navegación. En desarrollo, editar una página o layout existente actualiza el módulo SSR y recarga el navegador; el servidor conserva el almacén de sesiones. Los sidecars y handlers API/RPC existentes se cargan desde Vite al llamarlos.

Al crear o eliminar una página, un layout, app/app.meeko, app/error.meeko, un middleware de app/middleware o server/middleware, un plugin de app/plugins, o un módulo de server/api, server/rpc o server/socket, en el proyecto o en sus layers, meeko dev vuelve a descubrir las rutas y crea de nuevo la aplicación sin reiniciar el proceso:

• Las peticiones que llegan mientras tanto esperan a la aplicación nueva, y el navegador se recarga.
• El servidor Socket se vuelve a enganchar a la aplicación nueva; las conexiones abiertas se cierran.
• La aplicación nueva llama otra vez a server/runtime.ts, así que un almacén de sesiones en memoria empieza vacío y las sesiones abiertas se pierden.
• Si la aplicación nueva no se puede crear (por ejemplo, con dos layouts raíz), Meeko registra el error y sigue sirviendo la anterior hasta que se corrija.

Cuando Vite se reinicia (al cambiar un .env o una dependencia de su configuración), meeko dev también crea de nuevo la aplicación, con las mismas consecuencias, una vez que el servidor de Vite nuevo está listo. Si coincide con la creación o eliminación de una ruta, crea una sola aplicación.

Crear, editar o eliminar un .ts de una carpeta de autoimports (las de por defecto y, desde 1.3, las de imports.appDirs, sharedDirs y serverDirs) vuelve a leer el registro de autoimports e invalida los módulos, y el navegador se recarga; no hace falta reiniciar. Editar un canal Socket existente, cambiar meeko.config.ts (también las listas de imports) o editar el código de setup de un módulo sigue exigiendo reiniciar npm run dev (los archivos de runtime de un módulo, como sus plugins o componentes, se recargan como los del proyecto). Los tipos y manifiestos de .meeko/ no se regeneran en meeko dev: ejecute npm run check para actualizarlos.

El observador de archivos de Vite ignora todo .meeko/ salvo .meeko/generated, las entradas que sirve. Así, meeko check, el servidor de lenguaje o un build que escriben en .meeko/check, routes, types, manifests, output, build o en los tsconfig.* generados mientras corre meeko dev no recargan el navegador, y el escaneo de dependencias de Vite tampoco entra en .meeko/.

Logs del servidor en la consola del navegador#

Desde 1.3, en meeko dev, lo que el código de servidor escribe con console.log, info, warn, error o debug mientras atiende una petición aparece también en la consola del navegador, como features.devLogs de Nuxt. La terminal lo sigue mostrando igual: los logs se copian, no se desvían.

• Qué se reenvía. Cada llamada se asocia a su petición por el contexto asíncrono de esa petición, así que dos peticiones simultáneas no mezclan sus logs. Cuenta todo lo que se ejecuta para ella: middleware de servidor y de ruta, loaders, <script server>, plugins *.server.ts, el render, los clientes api.* y rpc.* del SSR, handlers de API y RPC y el trabajo asíncrono que inician, también el de waitUntil. Lo que se escribe fuera de una petición (el arranque, la fábrica de server/runtime.ts, Vite, los callbacks de Socket) sólo va a la terminal.
• Cómo llega.
  • El documento HTML lleva los logs de su render en <head>, y el navegador los imprime al cargar, antes de hidratar en la práctica. Los dos scripts que Meeko añade allí llevan el nonce del documento (el 'nonce-…' de su cabecera Content-Security-Policy o, sin él, el atributo nonce de sus scripts, que escribe DocumentOptions.nonce), así que funcionan con una CSP con nonce o con 'strict-dynamic'.
  • Con render: "stream", los que se escriben mientras llegan los valores diferidos van en el stream, detrás del bloque al que pertenecen y siempre fuera de #app, que el navegador hidrata.
  • Una navegación cliente recibe los logs de su petición de datos en el payload.
  • Las peticiones de API y RPC, y lo que se escribe después de completar una respuesta, llegan por el WebSocket de HMR de Vite. Como no se sabe qué pestaña hizo la petición, se imprimen en todas las pestañas abiertas de la aplicación, con el método, la ruta y el requestId.
• Cómo se ve. Cada petición es un grupo de la consola con la insignia server, el método, la ruta y el principio del requestId (el de la cabecera x-request-id), y cada log lleva la misma insignia y su nivel (console.warn es un aviso, console.error un error). Los objetos se pueden desplegar como en el servidor: Map, Set, fechas, bigint, referencias circulares y nombres de clase. Un Error muestra la traza del servidor, con sus archivos y líneas, y su cause. Las funciones, los símbolos y los datos binarios se muestran por su nombre o su descripción. Los getters no se ejecutan y los proxies no se atraviesan. Un valor más profundo de 8 niveles, una colección de más de 100 elementos o un texto de más de 10 000 caracteres se recortan; una petición con más de 500 logs, o con más de 1 MB de ellos, avisa de cuántos quedaron sólo en la terminal.
• Sin duplicados. Cada log llega una sola vez al navegador, por un único camino. El informe de un error de petición que Meeko ya escribe ([meeko] request error <id> y el error con su traza) llega también por este camino y una sola vez. Con server.forwardConsole de Vite, que copia la consola del navegador en la terminal, los logs del servidor no vuelven a la terminal.
• Sólo en desarrollo. Ni la captura de console ni el código del navegador existen en meeko build, meeko start o meeko preview: el HTML, los payloads y los bundles de producción no los incluyen.
• Sólo para el navegador del desarrollador. Las respuestas sólo llevan los logs si la petición llega desde loopback (127.0.0.0/8 o ::1), con una cabecera Host de loopback (localhost, un subdominio de .localhost, 127.x.x.x o [::1]) y sin cabeceras de proxy (Forwarded, Via, X-Forwarded-*, X-Real-IP, CF-Connecting-IP, True-Client-IP y similares). El host de MEEKO_PUBLIC_ORIGIN no cuenta como propio: un túnel o un proxy local (ngrok, cloudflared, los dev tunnels de VS Code, Tailscale) conecta desde loopback y publica justamente ese nombre, así que sus visitantes no reciben los logs aunque el túnel reescriba Host a localhost, porque añade cabeceras de reenvío. Con MEEKO_HOST=0.0.0.0 (para probar desde un móvil, por ejemplo), o tras un túnel, un navegador de otra máquina no recibe logs en sus respuestas: los de sus peticiones se imprimen en las pestañas del propio equipo, porque el WebSocket de HMR de Meeko sólo escucha en 127.0.0.1. Ese puerto (MEEKO_HMR_PORT) no debe publicarse por un túnel: quien se conecte a él recibe los logs de todas las peticiones, como una pestaña local.

Para desactivarlo:

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({ dev: { serverLogs: false } })

El href tipado no admite params en rutas sin parámetros. Para rutas dinámicas exige las claves declaradas en el manifiesto; el runtime comprueba además sus valores y rechaza claves extra.

href tiene dos formas con los mismos tipos. href(id, options) usa el manifiesto de la aplicación en ejecución: en el servidor, el de la petición en curso (SSR, loaders, head, prerender, API, RPC y middleware de servidor); en el navegador, el que recibió mountClientApp, desde la hidratación hasta dispose(). Es la forma habitual en páginas y layouts:

const link = href('/users/[id]', { params: { id: user.id }, search: { tab: 'profile' } })

Fuera de una aplicación (por ejemplo, en una prueba unitaria sin app) la forma corta lanza un error; ahí se pasa el manifiesto con href(routes, id, options), que se mantiene igual.

Layers#

Un layer es una carpeta del proyecto con la misma estructura que la aplicación: su app/pages, sus componentes y autoimports (app/components, app/composables, app/utils, app/stores, app/types, shared/ y server/utils) y, desde 1.2, sus plugins de app/plugins. Las carpetas de imports.appDirs, sharedDirs y serverDirs del proyecto se buscan también dentro de cada layer, con la misma ruta relativa (app/services es layers/base/app/services en el layer ./layers/base). Use layers para una base compartida (diseño, páginas comunes) o para dividir una aplicación grande por áreas.

export default defineMeekoConfig({
	layers: ['./layers/base', './layers/admin'],
})

El orden de las fuentes es: la aplicación, extends, layers, las carpetas de layer que quedan en modules (véase más abajo) y los layers que añaden los módulos con meeko.addLayer. Cada layer necesita su carpeta app/pages y un nombre de carpeta en minúsculas, dígitos y guiones que no se repita; aparece con ese nombre en los diagnósticos. Las rutas de layers y extends deben vivir dentro del proyecto, también después de resolver los enlaces.

Las páginas de un layer se muestran dentro del shell del proyecto: app/app.meeko y el layout raíz de la aplicación (app/layouts/default.meeko o app/pages/+layout.meeko) envuelven también a las páginas de los layers, y los +layout.meeko propios del layer se anidan dentro. Desde 1.5, los layouts con nombre de un layer (layers/base/app/layouts/docs.meeko) también sirven a las páginas del proyecto y de los demás layers; véase Layouts de layers y módulos. Si el proyecto tiene app.meeko o layout raíz, sustituyen a los equivalentes del layer; si no, se usan los del layer. Una página de layer que falla usa el +error.meeko más cercano de su propio árbol, después el app/error.meeko del layer y, por último, la página de error raíz del proyecto. La 404 de una URL sin ruta siempre usa la del proyecto. Los módulos de rutas programáticos (RouteModule.routes() de composeFrameworkRoutes) siguen declarando sus propios layouts. El manifiesto rechaza colisiones de URL y el registro rechaza nombres de autoimport repetidos; el diagnóstico incluye los archivos en conflicto.

extends es el nombre que tenía layers hasta 1.1 y sigue funcionando en 1.x, sin aviso; sus carpetas van antes que las de layers.

Desde 1.5, los aliases de ruta ~/, @/, #shared/ y #server/ se buscan en el proyecto y después en cada layer, en este mismo orden; véase Aliases en los layers.

Carpetas en modules (deprecado)#

Hasta 1.1, modules también listaba carpetas con app/pages, que se comportaban como layers. Desde 1.2, modules es para módulos. Una cadena de modules que apunta a una carpeta con app/pages y sin módulo (sin package.json ni index.ts) sigue funcionando como layer durante toda la serie 1.x, en la misma posición que antes. meeko dev, meeko build y meeko check escriben una vez por proceso:

[meeko] Aviso: "./modules/auth" en modules de meeko.config.ts es una carpeta de layer (tiene app/pages y no es un módulo). Muévela a layers: ["./modules/auth"]; las carpetas en modules dejarán de funcionar en Meeko 2.0.

Para migrar, mueva la cadena de modules a layers. Una carpeta de layer no admite opciones: ["./modules/auth", { … }] es un error.

Módulos#

Un módulo configura el proyecto desde código, como los módulos de Nuxt: añade componentes, autoimports, plugins, middleware y handlers de servidor, entradas de <head>, archivos públicos y plugins de Vite, y reacciona a los hooks del build. Se crea con defineMeekoModule, se registra en modules con su nombre y recibe sus opciones en su propia clave de meeko.config.ts, la que declara su meta.configKey:

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({
	modules: ['@meekojs/i18n', '@meekojs/ui', './modules/accent'],
	i18n: { defaultLocale: 'es', catalogs: { es: 'app/locales/es.json', en: 'app/locales/en.json' } },
	ui: { defaults: { button: { shape: 'pill' } } },
	accent: { initial: 'teal' },
})

No se importa nada: meeko.config.ts sólo nombra los módulos. Una cadena es un nombre de paquete instalado o una ruta relativa al proyecto:

• Un paquete ('@meekojs/i18n', con o sin subruta) se resuelve desde el proyecto. Si el paquete exporta el subpath ./module (como @meekojs/i18n, cuya raíz es su runtime), el módulo es el export por defecto de <paquete>/module; si no, el export por defecto de la raíz (como @meekojs/ui).
• Una ruta ('./modules/accent') es un archivo o una carpeta con package.json (su export import/default) o con index.ts, index.mts, index.js o index.mjs.

El export por defecto debe ser el resultado de defineMeekoModule. Las opciones se combinan así: defaults del módulo y después config[meta.configKey]; los objetos planos se combinan en profundidad y los arrays se sustituyen. Los módulos se ejecutan en el orden de modules, uno tras otro (Meeko espera cada setup), y después el hook ready; ese orden decide el de sus plugins, middleware, entradas de <head> y hojas de estilos. Dos módulos con el mismo meta.name o la misma meta.configKey son un error. Con meta.compatibility.meeko (un rango de npm, como ">=1.2" o "^1.2.0"), la carga falla si la versión de Meeko queda fuera.

Los errores dicen qué falta:

• Una cadena que no resuelve: No se encuentra el módulo de Meeko @meekojs/i18m: no es un paquete instalado ni una ruta del proyecto. ¿Quisiste decir "@meekojs/i18n"? (o, sin parecido, cómo instalarlo).
• Un paquete sin módulo: El paquete x no es un módulo de Meeko: … debe exportar por defecto defineMeekoModule(...), en su subpath ./module o en su raíz.
• La clave de un módulo instalado que no está en modules, como i18n: { … } sin '@meekojs/i18n', es el aviso MEEK127, que indica la entrada que falta: [meeko] Aviso MEEK127: meeko.config.ts tiene la clave "i18n", que es la configKey del módulo @meekojs/i18n, pero @meekojs/i18n no está en modules, así que Meeko ignora sus opciones. Añádalo: modules: ["@meekojs/i18n"]. Es un aviso y no un error durante 1.x, porque esa configuración cargaba (ignorando la clave) hasta 1.7. Cualquier otra clave desconocida da el aviso de siempre, con la clave conocida más parecida.

Tipos de las opciones sin imports#

La clave de cada módulo está tipada aunque meeko.config.ts no importe nada, como hace Nuxt con .nuxt/nuxt.d.ts. El módulo amplía MeekoConfig con su clave (declare module '@meekojs/meeko/framework' { interface MeekoConfig { readonly i18n?: I18nModuleOptions } }) y Meeko escribe .meeko/types/config.d.ts, que importa los tipos de cada módulo de modules, así que esa ampliación se carga sola. Lo generan meeko dev, meeko check, meeko build y meeko routes, y también el servidor de lenguaje de un workspace de confianza al abrir el proyecto, antes de la primera generación (sólo lee las cadenas de modules, sin ejecutar nada).

• meeko check comprueba meeko.config.ts con esos tipos (desde 1.8; antes sólo cuando la carga fallaba): i18n: { defaultLocale: 1 } es TS2322 con su línea y columna. También meeko build, que ejecuta las mismas comprobaciones.

• El editor tipa el archivo con .meeko/tsconfig.config.json, al que apunta el tsconfig.json que crea meeko init. En un proyecto anterior a 1.8, añada { "path": "./.meeko/tsconfig.config.json" } a references. Con él, el editor completa y documenta la clave (i18n, ui) y marca una opción mal tipada.

• Completado de nombres. Dentro de modules: ['…'], el editor ofrece los paquetes instalados que son módulos: las dependencias del package.json del proyecto con la palabra clave meeko-module en el suyo ("keywords": ["meeko-module"]), además de los ya listados. Un módulo publicado debe declararla. Cualquier otra cadena sigue siendo válida.

• Tipos que genera el módulo. Las declaraciones que un módulo escribe con meeko.addTypeTemplate (en .meeko/types/modules/, enlazadas por .meeko/types/modules.d.ts) también tipan meeko.config.ts, en meeko check y en el editor. Así un módulo puede tipar sus opciones con lo que descubre al ejecutarse: @meekojs/icon genera la unión de los nombres de icono disponibles y icon: { include: ['lucide:chek'] } es TS2820 con la sugerencia "lucide:check". meeko check ejecuta los módulos antes de comprobar la configuración, así que la unión está al día.

Los módulos oficiales @meekojs/ui, @meekojs/i18n y @meekojs/icon (iconos de Iconify resueltos al compilar, con <UIIcon>; véase su guía) se registran de esta forma.

Las formas de registro anteriores a 1.8 siguen funcionando durante 1.x con el aviso MEEK126, que indica la cadena y la clave que las sustituyen; véase Actualizar de 1.7 a 1.8.

Escribir un módulo#

El setup se ejecuta en Node, una vez por configuración y proceso, al cargar la configuración: en meeko dev, meeko build, meeko check y en el servidor de lenguaje de un workspace de confianza. Nunca llega al navegador. Recibe las opciones combinadas y el objeto meeko. Las rutas que recibe meeko pueden ser absolutas, URL file: (new URL("./x", import.meta.url), lo habitual en un paquete) o relativas a la raíz del proyecto.

Un módulo de color de acento, que el usuario elige y que se aplica antes de pintar (para el tema claro/oscuro no hace falta un módulo: Meeko lo trae desde 1.4, véase Tema claro/oscuro sin parpadeo):

// modules/accent/index.ts
import { defineMeekoModule } from '@meekojs/meeko/framework'

export type Accent = 'teal' | 'violet' | 'amber'

export interface AccentOptions {
	initial: Accent
	storageKey: string
}

// Tipa la clave `accent` de meeko.config.ts.
declare module '@meekojs/meeko/framework' {
	interface MeekoConfig {
		readonly accent?: Partial<AccentOptions>
	}
}

export default defineMeekoModule<AccentOptions>({
	meta: { name: '@acme/meeko-accent', configKey: 'accent', compatibility: { meeko: '>=1.2' } },
	defaults: { initial: 'teal', storageKey: 'accent' },
	setup(options, meeko) {
		const here = (path: string) => new URL(path, import.meta.url)
		// <AccentPicker /> en cualquier componente, sin import.
		meeko.addComponentsDir(here('./components'), { prefix: 'Accent' })
		// useAccent() sin import, en componentes y en app/.
		meeko.addAutoImports({ name: 'useAccent', from: here('./runtime/use-accent.ts') })
		// Publica la señal del acento antes de hidratar; las opciones llegan al plugin.
		meeko.addPlugin({ src: here('./runtime/accent.plugin.ts'), options: { initial: options.initial, storageKey: options.storageKey } })
		// Aplica el acento guardado antes de pintar, sin parpadeo.
		meeko.addHead({
			script: [{ key: 'accent', children: `document.documentElement.dataset.accent = localStorage.getItem(${JSON.stringify(options.storageKey)}) ?? ${JSON.stringify(options.initial)};` }],
		})
	},
})

// modules/accent/runtime/use-accent.ts
import { createContext, inject } from '@meekojs/meeko'
import type { Signal } from '@meekojs/meeko'
import type { Accent } from '../index.ts'

export const accentKey = createContext<Signal<Accent>>('accent')

export function useAccent(): Signal<Accent> {
	return inject(accentKey)
}

// modules/accent/runtime/accent.plugin.ts
import { effect, signal } from '@meekojs/meeko'
import { definePlugin } from '@meekojs/meeko/framework'
import type { Accent } from '../index.ts'
import { accentKey } from './use-accent.ts'

export default definePlugin<{ initial: Accent; storageKey: string }>((app, options) => {
	// El mismo valor inicial en el servidor y en el navegador, para que la hidratación coincida.
	const accent = signal(options.initial)
	app.provide(accentKey, accent)
	if (app.side === 'client') {
		let first = true
		effect(() => {
			const value = accent.value
			// El script de <head> ya aplicó el acento guardado; después, cada cambio se aplica y se guarda.
			if (first) {
				first = false
				return
			}
			document.documentElement.dataset.accent = value
			localStorage.setItem(options.storageKey, value)
		})
	}
})

Un módulo de SEO genera sitemap.xml a partir de las rutas y robots.txt:

import { defineMeekoModule } from '@meekojs/meeko/framework'

export default defineMeekoModule<{ siteUrl: string }>({
	meta: { name: '@acme/meeko-seo', configKey: 'seo' },
	setup(options, meeko) {
		let routes: readonly { id: string }[] = []
		meeko.hooks.hook('routes:resolved', (context) => {
			routes = context.routes
		})
		meeko.addPublicFile('robots.txt', `User-agent: *\nAllow: /\nSitemap: ${options.siteUrl}/sitemap.xml\n`)
		// Una función se evalúa al escribir el build (y en cada petición en dev), con las rutas ya descubiertas.
		meeko.addPublicFile('sitemap.xml', () =>
			[
				'<?xml version="1.0" encoding="UTF-8"?>',
				'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
				...routes.filter((route) => !route.id.includes('[')).map((route) => `<url><loc>${options.siteUrl}${route.id}</loc></url>`),
				'</urlset>',
			].join('\n'),
		)
	},
})

Los archivos de runtime de un módulo (plugins, componentes, autoimports, middleware y handlers) los procesa Vite como los del proyecto, pero fuera de las carpetas de la aplicación no reciben autoimports: impórtelos de forma explícita. Los componentes .meeko de addComponentsDir sí reciben los autoimports del proyecto.

El objeto meeko#

Un host de Vite propio que sólo usa el plugin meeko() recibe los autoimports, componentes, layers y plugins de aplicación de los módulos, pero no sus addVitePlugin, extendViteConfig, archivos públicos ni hooks: esos los aplican meeko dev y meeko build.

Meeko no tiene un runtimeConfig aparte: un módulo pasa valores a su runtime con las options de addPlugin (públicas si el plugin llega al navegador), y los secretos se leen en el servidor de las variables de entorno o de server/runtime.ts.

Hooks#

Los hooks se ejecutan en el orden en que se registraron y Meeko espera a cada uno. hook() devuelve una función que lo quita.

Plugins de aplicación#

Los archivos de app/plugins (de la aplicación y de sus layers) y los que añaden los módulos se ejecutan al arrancar la aplicación. Cada uno exporta por defecto definePlugin:

// app/plugins/analytics.client.ts
import { definePlugin } from '@meekojs/meeko/framework'

export default definePlugin((app) => {
	effect(() => navigator.sendBeacon('/api/visits', app.route.path.value))
	app.onError((error, info) => console.error('[app]', info.side, error))
})

• Dónde. *.client.ts sólo en el navegador, una vez, antes de la hidratación. *.server.ts sólo en el servidor, una vez por petición de página, antes del render (también al prerenderizar; no en las páginas ya prerenderizadas, ni en API, RPC o handlers). Un .ts sin sufijo, en los dos. Sólo cuentan los archivos que están directamente en app/plugins; las subcarpetas pueden guardar sus auxiliares. Se excluyen *.test.ts, *.spec.ts y *.d.ts.
• Orden. Los de los módulos, en el orden en que los añaden; después los de cada layer y los de la aplicación, por nombre de archivo. Meeko espera a cada setup, que puede ser asíncrono.
• app.provide(key, value). Publica un valor para todos los componentes de la aplicación, que lo leen con inject(key) (y el composable que lo envuelva): las páginas, layouts, app.meeko, la página de error y las páginas a las que se navega en el navegador. En el servidor el valor es de esa petición: no comparta estado mutable entre peticiones. Un componente que se hidrata debe recibir el mismo valor en el servidor y en el navegador; por eso los valores que se renderizan suelen venir de un plugin universal.
• app.onError(handler). En el navegador, el observador recibe lo mismo que mountClientApp({ onError }) (navegación, Socket y eventos, efectos y limpiezas sin un provideErrorHandler más cercano y, desde 1.3, las excepciones y los rechazos globales de la página; véase Errores), con { side: "client", source }. En el servidor recibe los fallos del render de esa petición, con { side: "server", requestId }, además del onError de server/runtime.ts.
• app.resolveLink(resolver). Desde 1.8, recibe cada <MeekoLink> de la aplicación ({ to, href, hreflang }: el ID de la ruta, el href que construyó href() y el hreflang del enlace) y devuelve su href final; aria-current se calcula con ese href. Varios resolvedores se encadenan en el orden de los plugins. Se ejecuta al renderizar el enlace en el servidor, en la hidratación y en la navegación del cliente, así que debe ser puro: el mismo enlace da el mismo href en los dos lados. @meekojs/i18n lo usa para el prefijo de idioma; véase <MeekoLink>.
• app.route. La ruta, como useRoute(). En el servidor es la de la petición; en el navegador sigue a la ruta confirmada, así que un effect que la lee se repite al navegar. app.request es la petición en el servidor y undefined en el navegador; app.side dice dónde se ejecuta.
• Fallos. Un plugin que lanza en el servidor hace fallar la petición, que muestra la página de error sin los valores de los plugins. En el navegador, la hidratación no llega a empezar y la página se queda con el HTML del servidor.

Un host propio pasa los plugins a mountClientApp({ plugins }) y a createServerApp({ plugins }) o createFrameworkHandler({ plugins }), como PluginRegistrations ({ plugin, options?, name? }).

Límites entre servidor y cliente#

El setup de un módulo y su entrada nunca llegan al bundle del navegador, y tampoco sus plugins "server", su middleware, sus handlers, sus carpetas de autoimports con scope: "server" ni los *.server.ts de las carpetas del módulo. El plugin de Vite de Meeko rechaza el build si el grafo del cliente los alcanza (Server-only module reached the client bundle), y si un archivo que el navegador carga importa defineMeekoModule (Meeko module setup reached the client bundle): sólo meeko.config.ts debe importar los módulos. Las opciones de un plugin que se ejecuta en el navegador sí viajan en el bundle del cliente.

Middleware de rutas y servidor#

Coloque middleware de rutas en app/middleware/*.ts (también en subcarpetas). Cada archivo exporta por defecto una función creada con defineRouteMiddleware desde @meekojs/meeko/framework (se autoimporta). Se ejecuta antes del sidecar y el loader, tanto para una petición SSR de página como para una navegación cliente. El contexto ofrece url, match, signal y phase; request sólo existe durante SSR. Devolver undefined continúa; devolver un Response detiene la ruta. Una redirección HTTP durante navegación cliente usa location.assign, con nueva petición de página. Una respuesta distinta de redirección cancela la navegación y comunica el error al callback onNavigationError del host. Sin callback, los fallos de navegación por clic o historial se muestran en la consola; si el callback falla, Meeko registra ese fallo sin crear un rechazo no observado. Al bloquear o fallar una navegación de historial, Meeko restaura la URL de la página que sigue visible. Una llamada directa a app.navigate() devuelve su rechazo al código que la invocó.

Hay dos clases de middleware de ruta:

• Global (la de siempre, sin opciones): se ejecuta en todas las rutas, por nombre de archivo. match.route.id permite limitarlo a rutas concretas.
• Con nombre (desde 1.6): defineRouteMiddleware(fn, { global: false }). Sólo se ejecuta en las rutas que lo piden con middleware en definePage o en un +group.ts.

Las dos existen también sólo de servidor, en app/middleware/*.server.ts con defineServerRouteMiddleware (desde 1.6): véase Middleware de ruta de servidor.

// app/middleware/10-locale.ts: global, en todas las rutas
export default defineRouteMiddleware(({ url, match }) => {
	if (match.route.id !== '/dashboard') return
	if (!url.searchParams.has('locale')) {
		const target = new URL(url)
		target.searchParams.set('locale', 'es')
		return Response.redirect(target)
	}
})

Middleware con nombre#

Un guard que sólo afecta a una parte de la aplicación se declara con nombre y lo piden las rutas que lo necesitan, sin comparar match.route.id ni rutas de archivo:

// app/middleware/auth.ts
export default defineRouteMiddleware(
	({ url, phase, request }) => {
		// Una cookie pública que indica la sesión: la cookie de sesión de Meeko es HttpOnly.
		const cookies = phase === 'server' ? (request.headers.get('cookie') ?? '') : document.cookie
		if (!cookies.includes('signed-in=1')) {
			const login = new URL('/login', url)
			login.searchParams.set('next', url.pathname)
			return Response.redirect(login)
		}
	},
	{ global: false },
)

// app/pages/(dashboard)/+group.ts: todas las páginas del grupo
export default defineGroup({ layout: 'dashboard', middleware: ['auth'] })

<!-- app/pages/(dashboard)/admin/users.meeko: la página añade el suyo -->
<script
	server
	lang="ts"
>
	export const route = definePage({ middleware: ['admin'] })
</script>
<template><h1>Usuarios</h1></template>

• Nombre. Es la ruta del archivo dentro de app/middleware, sin .ts ni el prefijo numérico de orden de cada parte: auth.ts y 10-auth.ts son "auth", y admin/20-role.ts es "admin/role". Letras, dígitos, - y _, y / entre carpetas. Dos archivos que dan el mismo nombre, si uno de ellos es con nombre, detienen el descubrimiento.
• Herencia. middleware se acumula de fuera hacia dentro: los +group.ts exteriores, los interiores y la página, sin repetir (cuenta la primera aparición). middleware: false en un grupo o en una página quita los heredados; los grupos interiores y la página pueden volver a añadir. middleware: [] no cambia nada.
• Orden. Primero todos los globales, en su orden de siempre; después los de la ruta, en el orden declarado. El primero que devuelve un Response detiene la ruta y los siguientes no se ejecutan. Es el mismo contrato en SSR, en la navegación del navegador, en render: "client", en el prerender y en el adaptador static.
• Literales. Como render y layout, Meeko lo lee sin ejecutar el archivo: { global: false } debe ser un objeto literal con el literal true o false, y middleware, un array literal de textos o false. Un valor calculado da las opciones de defineRouteMiddleware deben ser un objeto literal… o middleware debe ser un array literal… con el archivo. Un spread en las opciones de la página que puede llevar middleware (un objeto importado, o una constante del archivo que lo tiene) exige declarar middleware después del último spread: definePage({ ...protegida, render: "ssr", middleware: ["auth"] }), o middleware: [] si no añade ninguno. Si no, el descubrimiento se detiene con el spread protegida puede llevar middleware…, porque la ruta se serviría sin él. Si una página declara un middleware que su manifiesto no lista (un build antiguo), la petición falla con 500 antes del loader, como con layout.
• Errores. Detienen meeko dev, meeko build y meeko check, con el archivo que declara el nombre: el middleware "nowhere" no existe; crea app/middleware/nowhere.ts con defineRouteMiddleware(..., { global: false }) (middleware con nombre disponibles: "admin", "auth"), o app/middleware/nowhere.server.ts… y, para un global, el middleware "locale" (…/10-locale.ts) es global y ya se ejecuta en todas las rutas.
• Tipos y editor. middleware se tipa con la unión de los middleware con nombre (RouteMiddlewareName, que declara .meeko/types/routes.d.ts), con completado en el editor. En una aplicación sin middleware con nombre la unión está vacía (never), así que middleware: ["typo"] ya es un error de tipos. El hover de un nombre en definePage muestra su archivo y sus páginas, y Ctrl+clic lo abre.
• Bundle. Los globales viajan con la entrada del navegador. Cada middleware con nombre que usa alguna ruta es un chunk aparte, que el navegador carga la primera vez que navega a una de sus rutas; uno que ninguna ruta usa no llega al navegador. La hidratación no los ejecuta: el servidor ya lo hizo.
• Manifiesto. Cada ruta guarda sus middleware con nombre resueltos en RouteRecord.middleware (archivos, en orden de ejecución); AppManifest.routeMiddleware sigue listando sólo los globales. Un host propio que use createFrameworkHandler o mountClientApp con rutas que los declaran pasa loadNamedMiddleware(file); sin él, esas rutas fallan en lugar de saltarse sus guards. discoverRouteMiddleware de @meekojs/meeko/build separa los globales de los con nombre.
• Desarrollo. Crear, borrar o renombrar un middleware, cambiar su { global } o el middleware de una página o un +group.ts hace que meeko dev vuelva a descubrir las rutas y cree de nuevo la aplicación.
• Layers y módulos. Como hasta ahora, sólo cuenta app/middleware del proyecto: las páginas de los layers eligen entre los middleware con nombre del proyecto, y los módulos no añaden middleware de ruta.

app/middleware/*.ts se empaqueta también para el navegador, el middleware con nombre incluido: no importe allí server/, secretos ni lógica de autorización que deba ser obligatoria en servidor. Un guard de ruta isomórfico, global o con nombre, mejora la navegación, pero nunca sustituye la validación de sesión y autorización del loader, API o RPC; para proteger la página con la sesión, use un middleware de ruta de servidor. Los archivos *.test.ts, *.spec.ts, *.d.ts y *.client.ts se excluyen del descubrimiento de middleware de rutas; desde 1.6, los *.server.ts son middleware de ruta de servidor.

Middleware de ruta de servidor#

Desde 1.6, un archivo app/middleware/*.server.ts es middleware de ruta sólo de servidor: se declara con defineServerRouteMiddleware (de @meekojs/meeko/framework; se autoimporta en los *.server.ts y en todo server/, como las demás definiciones de servidor), recibe la sesión de la petición y nunca llega al bundle del navegador. Es la forma de expresar «este grupo exige sesión» sin repetir la comprobación en el <script server> de cada página:

// app/middleware/auth.server.ts
import { redirect } from '@meekojs/meeko/framework'

export default defineServerRouteMiddleware(
	({ session, url }) => {
		if (!session.current) redirect(`/login?next=${encodeURIComponent(url.pathname)}`)
	},
	{ global: false },
)

// app/pages/(dashboard)/+group.ts: todas las páginas del grupo exigen sesión
export default defineGroup({ layout: 'dashboard', middleware: ['auth'] })

• Global o con nombre. La misma regla que el isomórfico: sin opciones es global y se ejecuta en todas las rutas; con { global: false } (leído sin ejecutar el archivo) es un middleware con nombre, y auth.server.ts (o 10-auth.server.ts) es "auth". middleware: ["auth"] en definePage o en un +group.ts resuelve a auth.ts o a auth.server.ts, con la misma herencia y middleware: false; si los dos existen y alguno es con nombre, el nombre está duplicado y el descubrimiento se detiene. El export por defecto de un *.server.ts debe ser una llamada a defineServerRouteMiddleware(...), directa o a través de una constante del archivo (as const incluido), de un import con alias o de export { auth as default }. Hasta 1.5 esos archivos se ignoraban, así que un helper que viviera allí, sin export por defecto o con otro (export default function parseCookies…), detiene el descubrimiento con un middleware de ruta de servidor debe exportar por defecto defineServerRouteMiddleware(...)… mueve los helpers a server/utils en lugar de ejecutarse en cada petición como middleware global. Cada clase de archivo usa su definición: defineRouteMiddleware en un *.server.ts, o defineServerRouteMiddleware en un *.ts, es un error con el archivo.
• Contexto. El de usePage() en el <script server>: url, params, search, request, signal y context (el RequestContext), con session, services, platform y requestId a mano, además de match. La IP del cliente, tras el proxy si MEEKO_TRUST_PROXY lo permite, es context.clientAddress. params y search son los de la URL, sin validar todavía con los schemas de la página, porque el middleware se ejecuta antes que su <script server> o su load. defineServerRouteMiddleware<Services> tipa services, y session sigue a MeekoSession. Con createFrameworkHandler sin createContext, leer context o session lanza un error.
• Cómo corta. Igual que el <script server>: redirect(), notFound() o un error, y también devolviendo un Response. Devolver undefined continúa.
• Cuándo se ejecuta. En la petición del documento (SSR), y al navegar en el navegador dentro de la petición de los datos de la página, la misma que ejecuta el <script server>: una redirección o un error llegan al navegador igual que los de un redirect() del <script server>, y la navegación los sigue. En render: "stream", antes del primer byte, como el loader crítico.
• Orden. Siempre el mismo: primero el middleware isomórfico (los globales y después los con nombre, en el orden declarado) y después el de servidor (los globales y después los con nombre, en el orden declarado). Al navegar, el navegador ejecuta el isomórfico y la petición de datos vuelve a ejecutarlo en el servidor antes del de servidor, como hasta ahora. El primero que corta detiene la ruta.
• render: "client" y render: "prerender". Una página render: "client" no pide sus datos al servidor al navegar, y una prerenderizada se renderiza en el build, sin la petición ni la sesión de cada visitante. Pedir un middleware de servidor con nombre en una de ellas (también heredado de un +group.ts) detiene el descubrimiento: el middleware de servidor "auth" (…) necesita una página con datos del servidor, pero … usa render: "client"…; quítelo de esa página con middleware: false o use render: "ssr" o "stream". Los globales de servidor no se ejecutan en esas páginas, tampoco en su primera carga, para que su comportamiento no dependa de cómo se llegó a ellas. El adaptador static, que sólo admite páginas prerenderizadas, avisa de que no los ejecuta.
• Límite de seguridad. El plugin de Vite rechaza cualquier *.server.* que alcance el grafo del navegador, y el módulo virtual del middleware del cliente nunca los incluye; el manifiesto del navegador tampoco lleva sus rutas. Pueden importar server/ y #server/… sin MEEK108, y meeko check los comprueba con los tipos del servidor.
• Tipos y editor. RouteMiddlewareName incluye sus nombres, salvo en el middleware de una página render: "client", que sólo admite los isomórficos; el hover de un nombre en definePage o defineGroup muestra el archivo, que es «sólo servidor», y sus páginas. Un nombre inexistente o global da los mismos errores en meeko dev, meeko build y meeko check.
• Manifiesto y host propio. Cada ruta guarda en RouteRecord.serverMiddleware su cadena completa de servidor, en orden de ejecución: los globales y después los con nombre (las rutas render: "client" y "prerender" no la llevan). Un host propio que use createFrameworkHandler pasa loadServerMiddleware(file), que carga cada archivo de esa lista; sin él, una ruta que lista alguno, aunque sea sólo un global, falla en lugar de saltárselo. Las rutas de un módulo programático de composeFrameworkRoutes reciben también los globales del proyecto.
• Desarrollo. Crear o borrar uno, o cambiar su { global }, hace que meeko dev vuelva a descubrir las rutas.

Cuándo usar cada uno:

• El isomórfico (*.ts) mejora la navegación: decide en el navegador, sin una petición, y redirige antes de pedir nada. No puede leer la sesión (su cookie es HttpOnly) ni importar código de servidor.
• El de servidor (*.server.ts) protege la página: comprueba la sesión antes de que el servidor renderice o envíe sus datos.
• Ninguno protege server/api ni el RPC. El middleware de ruta sólo se ejecuta para las páginas: los endpoints de API y los procedimientos RPC necesitan sus propias guardas (auth: "required", comprobaciones en el handler o middleware de servidor), aunque sólo los llamen páginas protegidas.

Middleware de servidor#

Para interceptar HTTP en el servidor antes del handler de página o API/RPC, coloque middleware en server/middleware/*.ts y use defineServerMiddleware desde @meekojs/meeko/server. Recibe Request y next(request); debe devolver un Response. Puede continuar, modificar una respuesta o cortocircuitar. Meeko ejecuta los archivos por nombre, de fuera hacia dentro; next() sólo se puede llamar una vez. El middleware se ejecuta antes de crear el contexto de sesión de la petición, también para las páginas prerenderizadas; los archivos públicos del build se sirven antes del middleware. Los controles integrados de autenticación, autorización, contratos y CSRF de API/RPC siguen ejecutándose dentro del handler.

// server/middleware/10-request-header.ts
import { defineServerMiddleware } from '@meekojs/meeko/server'

export default defineServerMiddleware(async (request, next) => {
	const response = await next()
	const headers = new Headers(response.headers)
	headers.set('x-content-type-options', 'nosniff')
	return new Response(response.body, {
		status: response.status,
		statusText: response.statusText,
		headers,
	})
})

El middleware de servidor no tiene RequestContext: para la IP del cliente use clientAddress(request) (desde 1.7), que aplica MEEKO_TRUST_PROXY como context.clientAddress y rateLimit; nunca lea X-Forwarded-For a mano (véase IP del cliente tras un proxy).

Este pipeline envuelve páginas SSR y /api y /_meeko/rpc; los assets estáticos, el servidor de desarrollo Vite y los upgrades WebSocket tienen sus propios handlers. Los archivos *.test.ts, *.spec.ts, *.d.ts y *.client.ts se excluyen. El descubrimiento automático de middleware se limita por ahora al proyecto raíz: los layers aportan rutas, autoimports y plugins, pero sus carpetas app/middleware y server/middleware no participan. Un módulo añade middleware de servidor con meeko.addServerMiddleware, que se ejecuta antes que el del proyecto (véase Módulos). Editar un archivo de middleware existente invalida módulos y recarga el navegador en desarrollo; al añadir o quitar uno, meeko dev recrea la aplicación sin reiniciar (véase Configuración). npm run check comprueba los tipos en sus ámbitos respectivos.

Los callbacks onNavigationError pueden devolver una promesa: si el observador falla, Meeko registra tanto el fallo del observador como el error de navegación original sin generar un rechazo sin manejar. Los observadores onError del servidor tampoco modifican la respuesta cuando lanzan o rechazan; el registro de respaldo incluye el requestId disponible y categorías de error, sin mensajes privados.

Los eventos de componentes pueden observarse por raíz con provideErrorHandler en el <script> de app/app.meeko o de un layout; se autoimporta y el callback recibe unknown y su ErrorSource. Los hijos heredan el observador más cercano, también después de un reemplazo HMR. mountClientApp({ onError }) define el observador de toda la aplicación: recibe la navegación, los canales Socket, los eventos, efectos y limpiezas que no tienen un provideErrorHandler más cercano y, desde 1.3, las excepciones no capturadas y las promesas rechazadas sin manejar de la página (Fallos globales del navegador). Sin onError, navegación, Socket y esos fallos globales consultan el primer proveedor activo de esa aplicación cuando no existe un onNavigationError u onError explícito del canal. Ese proveedor se desregistra al liberar su raíz; un fallo del observador se registra con el error original. Las llamadas directas a app.navigate() y socket.emit() mantienen sus rechazos para el código que las espera. En SSR no hay eventos de navegador ni conexiones Socket.

Si un middleware servidor llama a next(), Meeko espera también ese trabajo aunque el middleware olvide esperar la promesa. Un fallo del tramo siguiente se propaga al handler HTTP; si fallan ambos, se conserva cada error en un AggregateError. El middleware debe devolver una respuesta del pipeline o una respuesta propia.

Routing, layouts y SSR#

app/pages admite index.meeko, [id].meeko, [...slug].meeko, grupos (group), +error.meeko y, para las opciones de ruta, un bloque <script server> en la página o un sidecar *.route.ts. El layout compartido vive en app/layouts/default.meeko y recibe props.outlet; el navegador lo conserva entre rutas y libera las páginas salientes. Desde 1.5, cualquier app/layouts/<nombre>.meeko es un layout con nombre que la página elige con definePage({ layout }) o un +group.ts. Los +layout.meeko junto a páginas siguen admitidos para proyectos anteriores y layouts anidados; no se puede combinar uno en la raíz de app/pages con app/layouts/default.meeko. Un layer usa las mismas convenciones. href comprueba IDs y parámetros a partir del manifiesto generado.

El tipo del outlet en app/app.meeko y en cada layout es Component<Record<string, unknown>> importado desde @meekojs/meeko. Incluye renderWithState, requerido por <component is="props.outlet"> para transferir el estado SSR.

<MeekoOutlet /> y <MeekoLink>#

Desde 1.2, dos etiquetas propias de Meeko sustituyen a esos patrones. No se importan: el compilador las reconoce.

• <MeekoOutlet /> pinta, en app/app.meeko y en los layouts (app/layouts/*.meeko o +layout.meeko), el layout o la página que van dentro. Lee el outlet que Meeko pasa, así que el layout no necesita declarar defineProps<{ outlet }>(). Hasta 1.4, si declaraba sus props, outlet debía estar entre ellas; desde 1.5, un layout con <MeekoOutlet /> declara sólo las suyas (defineProps<{ title?: string }>()) y Meeko añade outlet a su ComponentProps. Equivale a <component is="props.outlet">: el navegador conserva el layout entre rutas y sólo cambia lo que hay dentro. En otro componente, o con atributos o contenido, da MEEK104.
• <MeekoLink to="/users/[id]" bind:params="{ id: user.id }" bind:search="{ tab: 'perfil' }"> renderiza un <a> cuyo href construye href(): to sólo admite rutas que existen, las rutas dinámicas exigen bind:params con sus claves y bind:search añade la query string. meeko check y el editor marcan el error en el atributo (Argument of type '"/nowhere"' is not assignable…). En la ruta activa (la misma ruta sin query ni fragmento) añade aria-current="page", que la navegación actualiza; con match="prefix", también marca su sección (véase más abajo). El resto de atributos y los hijos pasan al <a> tal cual: class, target, rel, aria-*, data-* y on:click. href y bind:href no se admiten, porque el enlace lo construye to (MEEK105).
• match: la página o la sección. Desde 1.5, match="exact" (por defecto) marca el enlace sólo en su ruta, y match="prefix", también en las rutas que están por debajo. En su propia ruta el enlace lleva aria-current="page", y en una ruta por debajo, aria-current="true", que significa «el elemento actual de un conjunto»: la sección en la que está la página. La comparación es por segmentos completos, sobre las rutas codificadas como href() y sin query ni fragmento: /dashboard cubre /dashboard/stats y /dashboard/r%201, pero no /dashboards; /dash no cubre /dashboard. to="/" sólo coincide exacta, también con match="prefix", porque si no marcaría todas las páginas. En una ruta dinámica, la sección es la de sus params: <MeekoLink to="/users/[id]" bind:params="{ id: '7' }" match="prefix"> cubre /users/7/posts, no /users/8/posts. match admite bind:match con una expresión de tipo "exact" | "prefix"; otro valor estático es MEEK105. El valor sale en el HTML del servidor, la hidratación no lo cambia y la navegación lo actualiza, también en un layout que el navegador conserva.
• Resolvedores de enlaces: idioma y otros prefijos. Desde 1.8, el href pasa por los resolvedores que registran los plugins y módulos con app.resolveLink. Con @meekojs/i18n, <MeekoLink to="/guide"> apunta a /en/guide en una página /en/… y a /guide en el idioma por defecto, sin escribir el prefijo; hreflang="es" (o bind:hreflang, o la clave hreflang de bind) fuerza otro idioma y queda además en el <a>. bind:resolve="false" deja el href de href() tal cual, para un enlace que no debe cambiar; resolve="false" estático es MEEK105. El tipado de to, params y search, aria-current (con el href resuelto, así que /guide está activo en /en/guide) y la navegación del cliente no cambian. Sin resolvedores, el href es el de href().

<!-- /en/guide en una página /en/…, /guide en el idioma por defecto -->
<MeekoLink to="/guide">Guía</MeekoLink>
<!-- /guide en cualquier idioma -->
<MeekoLink
	to="/guide"
	hreflang="es"
>
	Versión en español
</MeekoLink>
<MeekoLink
	to="/admin"
	bind:resolve="false"
>
	Administración
</MeekoLink>

• Tipos de sus props. Desde 1.4, @meekojs/meeko/framework exporta MeekoLinkProps<K> (to, params y search de la ruta K; desde 1.5, también match, y desde 1.8, resolve), MeekoOutletProps (sin props) y MeekoThemeToggleProps (las de <MeekoThemeToggle>), y RouteId, el ID de cualquier ruta de la aplicación (el tipo de to). Todos se autoimportan: los tipos de las props donde se usan los componentes, como los tipos de cada componente, y RouteId en todo el proyecto, como href. El editor muestra las props en el hover de las etiquetas y abre su tipo con «Ir a definición». Sirven para tipar un componente que recibe una ruta, sin import:

<!-- app/components/NavLink.meeko -->
<script lang="ts">
	const props = defineProps<{ href: MeekoLinkProps['to']; label: string }>()
</script>
<template><a bind:href="href(props.href)">{props.label}</a></template>

MeekoLinkProps["to"] y RouteId son el mismo tipo: la unión de las rutas que declara .meeko/types/routes.d.ts (meeko check, meeko dev), o string sin esas declaraciones. <NavLink href="/nowhere"> es un error de tipos en el padre. Un tipo del proyecto con uno de esos nombres (por ejemplo, en app/types) tiene prioridad.

<!-- app/layouts/default.meeko -->
<template>
	<header>
		<MeekoLink
			to="/"
			class="brand"
		>
			Inicio
		</MeekoLink>
		<MeekoLink
			to="/users/[id]"
			bind:params="{ id: session.userId }"
		>
			Mi perfil
		</MeekoLink>
	</header>
	<main><MeekoOutlet /></main>
</template>

<style scoped>
	a[aria-current='page'] {
		font-weight: 700;
	}
</style>

Un menú de secciones marca la sección en todas sus páginas y, de forma distinta, la página exacta. El CSS distingue los dos valores de aria-current, los mismos que leen los lectores de pantalla:

<!-- app/layouts/default.meeko -->
<template>
	<nav aria-label="Secciones">
		<MeekoLink
			to="/"
			match="prefix"
		>
			Inicio
		</MeekoLink>
		<MeekoLink
			to="/dashboard"
			match="prefix"
		>
			Panel
		</MeekoLink>
		<MeekoLink
			to="/users"
			match="prefix"
		>
			Usuarios
		</MeekoLink>
		<MeekoLink
			to="/settings"
			match="prefix"
		>
			Ajustes
		</MeekoLink>
	</nav>
	<main><MeekoOutlet /></main>
</template>

<style scoped>
	/* La sección de la página actual: /dashboard/stats marca «Panel». */
	nav a[aria-current='true'] {
		border-bottom: 2px solid currentColor;
	}
	/* La página exacta: /dashboard marca «Panel» con más peso. */
	nav a[aria-current='page'] {
		border-bottom: 2px solid currentColor;
		font-weight: 700;
	}
</style>

En /dashboard/stats, «Panel» lleva aria-current="true"; en /dashboard, aria-current="page"; en /dashboards, ninguno de los dos, y «Inicio» sólo se marca en /. Para un enlace o un componente propio, useRoute().isActive() aplica la misma regla (véase Ruta actual).

En el editor, to=" sugiere las rutas del proyecto y lleva a su página con Ctrl+clic. meeko init-framework genera el shell y el layout con estas etiquetas.

Un proyecto anterior a 1.2 con un componente propio llamado MeekoLink o MeekoOutlet (en app/components, de un módulo o importado o declarado en el <script>) lo conserva: la etiqueta es ese componente, con sus props, y no la de Meeko. meeko check, meeko build y el editor lo avisan con MEEK106; renombre el componente para usar la etiqueta propia.

<MeekoTeleport>#

Desde 1.5, <MeekoTeleport to="…"> pinta su contenido en otro lugar del documento sin sacarlo del componente que lo declara. Tampoco se importa. El caso típico es que una página ponga sus acciones en la barra de su layout:

<!-- app/layouts/default.meeko -->
<template>
	<header class="bar">
		<MeekoLink to="/">Inicio</MeekoLink>
		<div id="toolbar"></div>
	</header>
	<main><MeekoOutlet /></main>
</template>

<!-- app/pages/notes/[id].meeko -->
<script lang="ts">
	const isMobile = signal(false)
	async function save(): Promise<void> {
		/* … */
	}
</script>
<template>
	<MeekoTeleport
		to="#toolbar"
		bind:disabled="isMobile.value"
	>
		<AppButton on:click="save">Guardar</AppButton>
	</MeekoTeleport>
	<article>…</article>
</template>

• Destino. to="body" añade el contenido al final de <body> y to="#id", dentro del elemento con ese id, después de lo que ya tiene. Sólo se admiten esas dos formas: body, o # seguido de una letra y de letras ASCII, dígitos, - o _. Meeko busca el id con getElementById y nunca interpreta to como selector CSS ni como HTML. Un to estático que no cumple esa forma da MEEK114; bind:to acepta una expresión de tipo "body" | `#${string}` (MeekoTeleportTarget) que se valida al renderizar. <MeekoTeleport> admite to, bind:to, disabled, bind:disabled, if:when y each:of; cualquier otro atributo da MEEK114.
• Ámbito del autor. El contenido se compila en la plantilla del componente que lo declara, como el de un if:when: lee sus señales, sus eventos llaman a sus funciones, recibe su provide/inject y sus manejadores de errores, puede usar sus snippets y conserva el atributo de su <style scoped>. Se libera con el componente: al desmontarlo, al cambiar de página o cuando su if:when o su fila de each:of desaparecen, y sus nodos salen del destino con él.
• Primer HTML. En SSR, "stream" y "prerender" (también con el adaptador static), el HTML ya trae el contenido en su destino, sin saltos al hidratar: el de to="body" va tras la aplicación y antes de los scripts de Meeko, y el de to="#id" dentro de ese elemento, se renderice éste antes o después que el teleport. Varios teleports al mismo destino conservan el orden en que aparecen en la página. La hidratación encuentra el contenido por sus marcadores (<!--meeko:portal:…-->) y no cambia el DOM.
• Destino inexistente. Si la página no renderiza el elemento del #id (o es un elemento sin contenido, como <input>), el render falla con un error claro en desarrollo. En producción el contenido se pinta en su sitio, donde se hidrata, y el servidor avisa una vez con console.warn. En el navegador, un destino que no existe deja el contenido en su sitio con un aviso; el siguiente cambio de to o disabled vuelve a buscarlo.
• disabled. Con disabled (o mientras bind:disabled es verdadero) el contenido se pinta en su sitio. Cambiarlo mueve los mismos nodos entre el destino y su sitio, sin volver a renderizarlos, así que conservan su estado; el elemento que tenía el foco lo pierde, como en cualquier movimiento del DOM.
• Navegador. Lo que el navegador renderiza (una navegación, un if:when que aparece, una fila nueva o un hijo diferido) se pinta primero en su sitio y pasa a su destino al terminar ese montaje, antes del siguiente pintado, y se añade al final del destino. El destino debe vivir al menos tanto como el teleport: un elemento del layout o de app/app.meeko para una página, o del propio componente.

Para modales, menús y tooltips no hace falta teleport: <dialog> con showModal() y el atributo popover ya los muestran en la top layer del navegador, por encima de todo y sin problemas de z-index u overflow, con el foco y Escape resueltos. Use <MeekoTeleport> cuando el contenido deba vivir en otro sitio del layout, como una barra de acciones, unas migas de pan o un aviso al final de <body>.

Las páginas, los layouts, app/app.meeko y app/error.meeko no pueden ser componentes genéricos: Meeko les pasa sus props y no puede elegir sus parámetros de tipo, así que generic en su <script> da MEEK100. Lleve el contenido genérico a un componente de app/components y úselo desde la página.

Si una página falla y existe +error.meeko, Meeko la carga y renderiza con el mismo contexto de petición y estado SSR. El observador del servidor recibe el fallo original con su requestId; el HTML muestra un mensaje público y no incluye detalles privados. Si también falla la página de error, el servidor registra ese segundo fallo y entrega una respuesta segura.

Layouts con nombre#

Desde 1.5, cada app/layouts/<nombre>.meeko es un layout con nombre: default, dashboard, auth, blank… Una subcarpeta forma parte del nombre: app/layouts/admin/panel.meeko es "admin/panel". El nombre son letras, dígitos, - y _ (y / entre carpetas), y empieza por una letra o un dígito; un archivo con otro nombre (_partes.meeko) no es un layout y puede guardar otros componentes. Un layout con nombre es un layout normal: pinta la página con <MeekoOutlet /> y declara sus props con defineProps.

La página elige su layout en sus opciones de ruta, en <script server> o en el sidecar *.route.ts:

<!-- app/pages/connections.meeko -->
<script
	server
	lang="ts"
>
	export const route = definePage({ layout: 'dashboard' })
</script>
<template><h1>Conexiones</h1></template>

• Sin layout, la página usa el que heredan sus carpetas de sus +group.ts o, si no hay, default, como hasta 1.4.
• layout: false quita el layout con nombre: quedan app/app.meeko y los +layout.meeko de sus carpetas.
• Un literal. Como render, meeko build lee layout sin ejecutar el archivo: debe ser un texto literal o false dentro de definePage({ ... }). Un valor calculado da layout debe ser un literal de texto… con el archivo. Un nombre que no existe detiene meeko dev, meeko build y meeko check: el layout "nowhere" no existe; crea app/layouts/nowhere.meeko (layouts disponibles: …). En los tipos, layout es la unión de los layouts de la aplicación, con completado en el editor; el hover del nombre muestra su archivo y sus páginas, y Ctrl+clic lo abre.
• Orden de anidamiento. app/app.meeko → el layout con nombre → los +layout.meeko de las carpetas y grupos, de fuera hacia dentro → la página. Los grupos (group) y los +layout.meeko funcionan igual que antes, dentro del layout con nombre. Sigue siendo un error tener a la vez app/pages/+layout.meeko y app/layouts/default.meeko; un app/pages/+layout.meeko sin default se anida dentro del layout con nombre que elija la página.

app/app.meeko
└─ app/layouts/dashboard.meeko        (layout: "dashboard")
   └─ app/pages/(dashboard)/+layout.meeko
      └─ app/pages/(dashboard)/connections.meeko

Navegación. El navegador conserva los layouts que comparten la página saliente y la nueva, como siempre: si las dos usan el mismo layout con nombre, sigue montado con su estado (el DOM, el foco, el scroll de la barra lateral, lo escrito en un campo) y sólo cambia lo de dentro; si usan otro, el layout se libera y se monta el nuevo. Vale igual para páginas SSR, render: "stream", render: "client", prerenderizadas y las del adaptador static.

Página de error. Una página que falla en el navegador (su loader, notFound() o un dato) muestra su +error.meeko o app/error.meeko dentro de sus propios layouts, el layout con nombre incluido, con las props de sus +group.ts y sin las de la página. La 404 de una URL sin ruta usa el layout default (si existe), con sus valores por defecto. Desde 1.8, una página que responde 404 en el servidor (notFound() o un ApiError con ese estado) da el mismo documento, que se hidrata; con un +error.meeko más cercano, éste va dentro de los layouts de la página, sin hidratar. Si un layout falla al pintarlo, o el error es otro, el documento de error no tiene layouts, porque un layout puede ser lo que ha fallado.

Opciones por carpeta: +group.ts#

Para no repetir layout en cada página, un +group.ts en cualquier carpeta de app/pages (un grupo (dashboard) o una carpeta normal) declara las opciones de su carpeta y sus subcarpetas. defineGroup se autoimporta:

// app/pages/(dashboard)/+group.ts
export default defineGroup({ layout: 'dashboard', layoutProps: { showAlert: false } })

• Herencia en cascada. Los +group.ts se aplican del exterior al interior y después la página. layout de la página, o del grupo más interior que lo declara, gana.
• layoutProps se combinan por clave entre los grupos y la página, y la página gana. Un grupo o una página que elige un layout distinto del heredado empieza sin las props heredadas, que eran para otro layout.
• layout: false en una página (o un grupo) dentro de un grupo quita el layout con nombre y deja sus +layout.meeko.
• Literales. Meeko lee el archivo sin ejecutarlo, como render: layout es un literal o false, layoutProps un objeto literal de textos, números, booleanos, null, arrays y objetos, y middleware un array literal de textos o false. Un valor calculado, un spread o una opción desconocida detienen el descubrimiento con el archivo. Por eso funciona igual en el prerender y en el sitio estático.
• middleware (desde 1.6). Los middleware con nombre de las páginas del grupo, que se suman a los de los grupos exteriores; middleware: false quita los heredados. Véase Middleware con nombre.
• Tipos. defineGroup({ layout: "dashboard", layoutProps: { … } }) tipa layoutProps contra ese layout en el propio archivo. Un grupo que hereda el layout, y una página que no lo elige en su definePage, se comprueban en meeko check contra el heredado (MEEK_PAGE_LAYOUT_PROPS: Las layoutProps de app/pages/(dashboard)/reports/+group.ts no coinciden con las props del layout dashboard). Un +group.ts fuera de app/pages no configura nada: meeko check avisa con MEEK115.

Para migrar un grupo con su propio layout, como app/pages/(dashboard)/+layout.meeko, mueva el archivo a app/layouts/dashboard.meeko y añada app/pages/(dashboard)/+group.ts con export default defineGroup({ layout: "dashboard" }). El layout ya no se anida dentro de default, sino que lo sustituye, y cualquier página de otra carpeta puede elegirlo; los +layout.meeko que queden en subcarpetas siguen anidándose dentro.

Layouts de layers y módulos#

Un layer aporta sus app/layouts/*.meeko a toda la aplicación, y un módulo los suyos con meeko.addLayout(name, file) (véase El objeto meeko). Ante dos layouts con el mismo nombre gana el del proyecto, después el del propio layer de la página, después los demás layers en su orden y por último los módulos; dos módulos con el mismo nombre son un error. default mantiene la regla de 1.4: el del proyecto envuelve también a las páginas de los layers, el default de un layer sólo envuelve sus propias páginas cuando el proyecto no tiene uno (ni app/pages/+layout.meeko), y el de un módulo sirve cuando ni el proyecto ni el layer lo tienen.

Props del layout desde la página#

El layout declara props normales. La página se las pasa tipadas contra las Props del layout que elige, sin el outlet:

<!-- app/layouts/dashboard.meeko -->
<script lang="ts">
	export interface Props {
		title?: string
		showAlert?: boolean
	}
	const props = defineProps<Props>({ showAlert: false })
</script>
<template>
	<header>{props.title}</header>
	<AppAlert if:when="props.showAlert" />
	<main><MeekoOutlet /></main>
</template>

Como Meeko renderiza el layout sin las props que una página no le pasa, las de un layout con nombre deben ser opcionales o tener valor por defecto; meeko check lo comprueba (MEEK_LAYOUT_PROPS).

1. Con las opciones de ruta (layoutProps). Estáticas o calculadas con los datos del servidor, como head: llegan en el HTML del SSR desde el primer byte.

// app/pages/connections.route.ts (o export const route en <script server>)
export const route = definePage({ layout: 'dashboard', layoutProps: { title: 'Conexiones', showAlert: true } })

export const route = definePage({
	layout: 'dashboard',
	load: async ({ context }) => ({ user: await users.current(context) }),
	layoutProps: ({ data }) => ({ title: data.user.name }),
})

Con código de nivel superior en <script server>, escribe las props como un export más. Desde 1.8, export const layoutProps se tipa con sus propios valores y se comprueba contra el layout; como head, no llega a la página, así que un dato que sólo lee el layout viaja una vez, si no lo exportas también por separado:

<script server lang="ts">
	export const route = definePage({ layout: 'docs' })

	const { params } = usePage()
	const snapshot = await readPage(params.slug)
	export const doc = { html: snapshot.html }
	export const layoutProps = { nav: snapshot.nav, title: snapshot.title }
</script>

Exportarlo y declarar además route.layoutProps es MEEK072.

La función recibe el mismo contexto que head (params, search, request, context, signal, state y data); con código de nivel superior en <script server>, data son sus exports, ya tipados desde 1.8 si las opciones son un objeto literal sin spread. Se combinan con las de los +group.ts, y ganan. Viajan en el payload (layoutProps), así que deben poder serializarse en JSON: una prop con undefined ({ title: data.user?.name } sin usuario, o layout.set({ title: undefined })) deja la prop sin valor, así que el layout usa su valor por defecto, en el servidor y en el navegador; un valor que JSON no representa (una fecha, un Map, una instancia) hace fallar la página con un error que nombra la página, el layout y la prop. En una página render: "client", el objeto ya llega al HTML del servidor y la función se ejecuta en el navegador después de load. export const layoutProps en <script server> no es una opción: sería un dato más de la página.

2. Desde el <script> de la página: useLayout(). Se autoimporta y, en una página, su tipo sigue al layout que eligen su definePage o sus +group.ts (en otro componente, useLayout<"dashboard">()):

<!-- app/pages/connections.meeko -->
<script lang="ts">
	const layout = useLayout() // LayoutHandle de "dashboard"
	const failing = signal(false)
	effect(() => layout.set({ showAlert: failing.value }))
</script>
<template>
	<p>Título actual: {layout.props.title}</p>
	<button on:click="() => failing.value = !failing.value">Probar conexión</button>
</template>

• layout.set(patch) cambia las props que nombra y conserva las demás; layout.props lee las que recibe el layout (reactivas); layout.name es el nombre del layout. Una prop que el layout no declara, o con otro tipo, es un error de tipos.
• El layout no se vuelve a montar: con las props reactivas de 1.2, sólo cambia lo que lee esas props.
• Nada queda pegado. Al navegar a otra página, el layout recibe las props de la nueva (sus layoutProps, las de sus +group.ts y, para el resto, los valores por defecto del layout), también si el layout se conserva. Una página que ya se fue no puede escribir.
• SSR sin mismatch. El layout se renderiza antes que la página, así que lo que el setup de la página escribe con set durante el render llega al HTML con un segundo render de la página en el servidor (con el mismo estado de la petición y los mismos datos, como un pase de await), y el payload lleva esas props: el navegador hidrata exactamente ese HTML. Un render que escribe valores distintos cada vez se detiene en el tercero. En el navegador, lo que la página escribe mientras se renderiza y se hidrata se aplica al terminar de montarla; después, cada set se aplica al momento.
• Una página sin layout con nombre (layout: false) recibe un useLayout() que no hace nada. Fuera de una página que renderiza Meeko (una prueba unitaria), useLayout() lanza un error.

Markup en zonas del layout. Las props son para datos. Para poner contenido de la página en una zona del layout (botones de la cabecera, migas de pan) use <MeekoTeleport>, que mueve markup de la página a un destino del layout.

Tipos. .meeko/types/routes.d.ts declara GeneratedLayouts (las props de cada layout) y GeneratedPageLayouts (el layout de cada ruta). LayoutProps<"dashboard"> (autoimportado) es el tipo de las props que una página puede pasar a dashboard; LayoutName es la unión de los nombres y PageLayout<"/connections">, el layout de una ruta.

Comparación con Nuxt. En Nuxt, definePageMeta({ layout: "dashboard" }) elige el layout, pero no hay una forma tipada de pasarle props: se recurre a useState, a provide/inject o a route.meta (como un showAlert en meta), sin tipos contra el layout y con estado que puede quedar de la página anterior. En Meeko, layout y layoutProps se comprueban contra las Props del layout, llegan en el HTML del servidor, useLayout() las cambia de forma reactiva y cada navegación vuelve a las de la página nueva.

Página de error de la aplicación (app/error.meeko)#

app/error.meeko, junto a app/app.meeko, es la página de error de toda la aplicación. Recibe las mismas props que +error.meeko, { status: number; message: string }, y meeko check las comprueba igual. Se usa en dos casos:

• URL sin ruta. Una petición de página (GET o HEAD con accept: text/html, o la navegación con accept: application/meeko+json) responde 404 con app/error.meeko dentro de los layouts raíz: app/app.meeko y app/layouts/default.meeko (o app/pages/+layout.meeko). Las props son { status: 404, message: "NOT_FOUND" }. Como la página de error de una ruta, el documento se titula Error (<title> en SSR y document.title al navegar a una URL sin ruta). El documento lleva el payload de hidratación, así que el navegador lo hidrata y la navegación posterior funciona. En el navegador, un enlace o navigate() a una URL sin ruta carga el documento: esa URL puede pertenecer a middleware de servidor, a un archivo o a una redirección, y consultarla antes con fetch ejecutaría dos veces un GET con efectos. Si nada más la atiende, el servidor responde con app/error.meeko. Por la misma razón, volver con el historial a una entrada sin ruta recarga el documento; la navegación desde la página 404 hacia rutas de la aplicación sí es del cliente.
• Página que falla. El +error.meeko más cercano sigue ganando; si no hay ninguno, se usa app/error.meeko. Lo mismo vale para el loader de una ruta render: "client" en el navegador.

/api/..., /_meeko/..., los assets y las peticiones que no son de página mantienen sus respuestas 404 (JSON o texto). Sin app/error.meeko nada cambia: una URL sin ruta responde 404 en texto plano y el navegador recarga el documento. app/error.meeko y app/pages/+error.meeko definirían el mismo nivel, por eso tenerlos a la vez es un error de descubrimiento. En un layer o módulo, app/error.meeko respalda sus propias páginas; la 404 usa la del proyecto. Un host propio pasa la página con errorPage a createFrameworkHandler y a mountClientApp (AppManifest.errorPage en createServerApp).

Código de servidor de la página#

Una página declara su código de servidor en un bloque <script server lang="ts"> dentro del propio .meeko, de modo que app/pages sólo contiene archivos .meeko. El bloque admite dos formas. Pueden convivir en el mismo bloque, salvo load, que no se combina con código de nivel superior:

• Código de nivel superior (desde 1.1). El bloque es código de servidor normal: lee la petición, consulta la base de datos, redirige o responde 404, y cada export const es un dato de la página que llega tipado al <script> y a la plantilla.
• Opciones de ruta. export const route = definePage({ params, search, render, prerenderEntries, load, head }), la forma de 1.0, que sigue funcionando sin cambios; desde 1.5, también layout y layoutProps (véase Layouts con nombre), y desde 1.7, sitemapEntries (véase Rutas dinámicas en el sitemap).

Código de nivel superior y datos exportados#

<!-- app/pages/users/[id].meeko -->
<script
	server
	lang="ts"
>
	import { definePage } from '@meekojs/meeko/framework'
	import * as v from 'valibot'

	export const route = definePage({ params: v.object({ id: v.string() }) })

	const { params, context } = usePage() // la petición en curso, tipada por route.params
	if (!context.session.current) redirect('/login')
	const row = await db.users.findById(params.id) // db: un autoimport de server/utils; row no sale del servidor
	if (!row) notFound()
	export const user = { id: row.id, name: row.name } // se envía a la página
	export const head = { title: `Perfil de ${user.name}` }
</script>

<script lang="ts">
	const name = signal(user.name) // `user` está en ámbito y tipado
</script>

<template>
	<h1>{user.name}</h1>
	<input model="name" />
</template>

• Cuándo se ejecuta. Las sentencias del bloque que no son imports, tipos ni export const route se ejecutan en cada petición: en SSR y en la petición de datos de cada navegación cliente, después del middleware y de validar params y search con route, igual que load. Admiten await de nivel superior. Los imports, los tipos y las opciones de ruta se evalúan una vez por módulo.
• Exports. Cada export const o export let (también desestructurado, export const { a, b } = ...) salvo route y head es un campo de datos de la página. Sólo cruzan los nombres exportados: el resto del bloque, sus imports y sus variables privadas no llegan al bundle cliente ni al payload. Un export que es una promesa se espera antes de renderizar.
• En la página. El <script> y la plantilla ven cada export como un valor normal, de sólo lectura en profundidad, con el tipo del export ya esperado. No es una señal: llega en el payload y se sustituye en cada navegación, cuando el bloque vuelve a ejecutarse. Para estado editable, cree una señal a partir de él (signal(user.name)). Declarar en el <script> un nombre que ya exporta el bloque da MEEK075. La página no necesita declarar data en defineProps; si lo declara, meeko check comprueba que sea compatible con los exports.
• export const head. Fija el <head> de la página como route.head: un objeto { title, description } o una función sin argumentos que lo devuelve, calculada en el servidor con los valores del bloque. No forma parte de los datos. Declarar a la vez export const head y route.head da MEEK072. Desde 1.2, useHead y useSeoMeta en el nivel superior del bloque son una alternativa, y export const head gana sobre ellas (véase Head del documento).
• API de la petición. usePage() devuelve { url, params, search, request, context, signal }: params y search salen de los schemas de route o, sin schema, de los segmentos del ID de ruta; context es el contexto de la petición (sesión, servicios, plataforma) y signal se aborta si el cliente se desconecta, se revoca la sesión o se cancela la respuesta. redirect(url, status?) detiene el bloque y responde con una redirección (302 por defecto; admite 301, 302, 303, 307 y 308), que una navegación cliente sigue como la de un loader. notFound() detiene el bloque y responde 404 con la página de error más cercana (+error.meeko o app/error.meeko). Las tres se importan de @meekojs/meeko/framework o se usan sin import dentro del bloque. Valen mientras se ejecuta el código de nivel superior: también dentro de un helper del bloque al que ese código llama (function requireAdmin() { … redirect("/login") }), aunque sea async. Donde no hay página en curso dan MEEK073, y en ejecución lanzan un error con ese código: en las opciones de ruta, en un bloque sin código de nivel superior, en el <script> del componente (desde 1.3, también sin import en el <script> y en la plantilla) y, desde 1.7, en una función que Meeko llama al calcular el head, cuando el código de nivel superior ya terminó (export const head = () => … y la función de useHead(() => …) o useSeoMeta(() => …)); lea allí los valores que obtuvo el nivel superior. meeko check no puede saber si una función del bloque se llama más tarde (desde un temporizador, por ejemplo): en ese caso el error sólo aparece en ejecución.
• Serialización. Los exports viajan en JSON, como los datos de load. meeko check da un error de tipos en un export que no se puede serializar: funciones, undefined, bigint, símbolos e instancias de clase como Date o Map. En ejecución, un valor que serializeJson rechaza hace fallar la respuesta con 500, como un loader.
• Estado entre peticiones. Como el bloque se ejecuta en cada petición, una variable de nivel superior (const cache = new Map()) es nueva cada vez. Un valor que deba compartirse entre peticiones vive en un módulo importado.

Meeko considera que un bloque tiene código de nivel superior si exporta con export const o export let un nombre distinto de route (incluido head), o si usa usePage, redirect o notFound (desde 1.2, también useHead o useSeoMeta) fuera de cualquier función y fuera de las opciones de ruta. Un bloque sin ninguna de las dos cosas mantiene el comportamiento de 1.0: se evalúa una vez como módulo y admite export default, export function o una constante privada usada por load. Con código de nivel superior se aplican estas reglas:

El editor da a los exports su tipo en el <script> y en la plantilla, y «ir a definición» sobre user lleva al export del bloque.

Opciones de ruta con definePage#

<!-- app/pages/users/[id].meeko -->
<script
	server
	lang="ts"
>
	import { definePage } from '@meekojs/meeko/framework'
	import * as v from 'valibot'

	export const route = definePage({
		params: v.object({ id: v.string() }),
		load: async ({ params, signal }) => ({ id: params.id, signalAborted: signal.aborted }),
		head: ({ data }) => ({ title: data.id }),
	})
</script>

<script lang="ts">
	export interface Props {
		params: { id: string }
		search: Record<string, string | string[]>
		data: { id: string; signalAborted: boolean }
	}
	const props = defineProps<Props>()
</script>

<template><h1>{props.data.id}</h1></template>

Reglas comunes#

El bloque es un módulo TypeScript independiente del componente:

• Sólo servidor. El componente compilado nunca lo incluye. Se ejecuta en el servidor con los autoimports de server/utils y puede importar server/ y módulos *.server.*; sus imports relativos se resuelven desde la carpeta de la página. Sólo una ruta render: "client" lo envía al navegador (véase «Modos de render»).
• Opciones de ruta. Igual que un sidecar: export const route = definePage({ ... }) o, sin código de nivel superior, export default. render y, desde 1.5, layout deben ser literales que meeko build pueda leer sin ejecutarlo.
• Sólo en páginas. Un <script server> en un componente, un layout, +layout.meeko o +error.meeko es un error (MEEK044). Un segundo bloque da MEEK004, sin lang="ts" da MEEK006 y con un valor (server="...") da MEEK043.
• Comprobación. meeko check comprueba el bloque con TypeScript en el ámbito del servidor y compara su loader, o sus exports, con las props de la página; los errores señalan la línea y columna del .meeko.

head({ data }), o export const head, devuelve el title de la página y, desde 1.1, su description. En SSR, title va en <title> y description en <meta name="description">, antes del <head> del host; en una navegación se aplican a document.title y a esa meta. Una página sin title o sin description deja los que aporta el host en document.head, o ninguno, igual en SSR que al navegar. Desde 1.2, el head de la ruta admite también las etiquetas y atributos de useHead (meta, link, script, style, htmlAttrs, bodyAttrs y titleTemplate como cadena) y tiene la máxima prioridad frente a useHead y a document de la configuración; el título y la descripción del host quedan detrás del head que gestiona Meeko (véase Head del documento).

Como alternativa, las opciones de ruta pueden vivir en un sidecar *.route.ts junto a la página (app/pages/users/[id].route.ts), la forma disponible desde 1.0. Un sidecar no admite código de nivel superior. Una página no puede declarar ambos: Meeko detiene el descubrimiento de rutas con un error que nombra los dos.

Las opciones de ruta validan params y search antes del loader y del código de nivel superior. El loader puede devolver un Response para redirigir; el código de nivel superior usa redirect(). En una navegación cliente, si la petición de datos responde 404 (por notFound() o por un ApiError con estado 404 del loader), el navegador muestra el +error.meeko más cercano, o app/error.meeko, con { status: 404, message }, donde message es el código público del error (NOT_FOUND), igual que el documento SSR. meeko check . compara el ComponentProps de cada página con los params, search y datos que entrega su sidecar; un error de contrato identifica ambos archivos. También comprueba que app/app.meeko y los layouts acepten el outlet suministrado por Meeko, y que +error.meeko y app/error.meeko acepten status y message. Estos contratos rechazan props declaradas como any, never o unknown. Los datos del loader son obligatorios para la página cuando el sidecar declara load; una query repetida sin schema puede producir string[], además de string. El handler SSR crea el estado de useState y el contexto de sesión por petición; transfiere sólo props, estado público y datos de ruta serializables. El navegador hidrata ese payload y pide datos al servidor durante la navegación, por lo que un sidecar privado no entra al bundle cliente; sólo los sidecars render: "client" son públicos (véase «Modos de render»). mountClientApp gestiona historial, cancelación y limpieza. Si un host usa loadRoute directamente en cliente, su loader recibe un estado provisional: Meeko aplica sus cambios al confirmar la ruta y los descarta al cancelar o fallar. Las señales de ese estado deben usarse durante load, sin conservar referencias después de retornar. Se puede usar render: "prerender" con prerenderEntries para rutas dinámicas; sin ellas, meeko build falla (Dynamic prerender route /posts/[id] requires prerenderEntries) y, desde 1.7, también meeko check y meeko dev al descubrir las rutas, salvo que un spread de las opciones pueda traerlas, que se deja al build. meeko build lee render del sidecar sin ejecutarlo: debe ser un literal de texto dentro de definePage({ ... }), de un objeto exportado o de una constante local del mismo archivo; un valor calculado, una clave computada (["render"] o [clave]) que no vaya seguida de un render literal, un spread sin render explícito posterior o una reexportación detienen el build con el archivo afectado. El build escribe el HTML y el payload de navegación bajo .meeko/output/node/prerender/ (meeko prerender . repite ese paso sobre un build existente). El servidor sirve esas páginas pasando por el middleware de servidor, el contexto de sesión y el middleware de ruta; inserta la meta CSRF de la sesión en <head> sin reescribir el documento. Sin sesión responde con ETag, Vary: cookie y cache-control: public, max-age=0, must-revalidate, y devuelve 304 ante If-None-Match; con sesión responde private, no-store. Una CDN o caché compartida delante del servidor debe respetar Vary: cookie o no almacenar respuestas de peticiones con cookie; si ignora Vary, configúrela para omitir la caché cuando la petición traiga la cookie de sesión, porque de lo contrario podría entregar la versión anónima a un usuario con sesión y dejarlo sin meta CSRF. PrerenderedPage.headOffset del índice prerender/manifest.json se mide en unidades de código UTF-16 del HTML almacenado leído como texto (índices de cadena de JavaScript), no en bytes: un adaptador debe leer el archivo como texto UTF-8 y usar el valor tal cual, sin calcularlo a partir de bytes. Una URL con query string, una entrada dinámica no generada o un host con nonce CSP propio (sin server.contentSecurityPolicy, que desde 1.7 sirve el archivo con sus hashes) se renderizan con SSR. La comprobación del loader cubre tanto definePage({ load() { /* ... */ } }) como definePage(options) cuando el tipo de options conserva un load obligatorio.

Dónde se usa cada API#

El <script> y la plantilla de un componente se ejecutan en SSR y también en el navegador; <script server> y los sidecars *.route.ts se ejecutan en el servidor, fuera del componente. Desde 1.3, meeko check, meeko build y el editor señalan cada API en el lugar donde no existe, con un mensaje que dice dónde se usa, y el autocompletado del <script> y de la plantilla deja de ofrecer las de servidor:

Desde 1.6, un middleware de ruta de servidor (app/middleware/*.server.ts) es código de servidor como server/: usa redirect() y notFound() mientras se ejecuta, como el nivel superior de <script server>, y defineServerRouteMiddleware se autoimporta allí; en el <script> o la plantilla de un componente es MEEK108.

Con render: "client", el bloque o el sidecar se ejecutan en el navegador (véase Modos de render) y no pueden usar las APIs de servidor de la tabla: un autoimport de servidor, un import de server/ o uno de *.server.* detienen el build, y el editor marca el autoimport con MEEK_AUTOIMPORT. Un componente dentro de server/ (una plantilla de correo, por ejemplo) sólo se renderiza en el servidor, así que puede usar las APIs de servidor. El build y meeko dev sólo aplican MEEK108 al bundle del navegador: un componente fuera de server/ que sólo importa código de servidor (una plantilla en app/emails/ que renderiza una ruta de API) sigue compilando, como en 1.2. meeko check y el editor, que no conocen el grafo de imports, comprueban todo componente fuera de server/ como código del navegador, igual que en 1.2; para que lo acepten, ponga esos componentes en server/.

MEEK108 señala código que ya fallaba antes de 1.3: el autoimport de servidor no se resolvía en el bundle del navegador, @meekojs/meeko/server y /cloudflare no se pueden cargar allí, un import de server/ detenía meeko build, y las macros y onMounted no existen fuera del <script>. MEEK109 es un aviso porque ese código compila y se carga: definePage en el componente no configura la ruta, y las funciones de /node, /bun, /deno, /password y /build sólo fallan al llamarlas en el navegador (véase Política de estabilidad).

Modos de render#

render del sidecar elige cómo llega cada página al navegador:

El código de nivel superior de <script server> sigue el modo como un loader: con "ssr" y "stream" se ejecuta en cada petición y con "prerender" una vez por entrada durante meeko build. En "stream", un export creado con defer(...) llega después de la página, como un valor diferido del loader (véase Streaming SSR). Con "client" no se admite (MEEK074), porque el bloque se ejecuta en el navegador.

<!-- app/pages/notes/index.meeko: el bloque se ejecuta en el navegador -->
<script
	server
	lang="ts"
>
	import { definePage } from '@meekojs/meeko/framework'

	export const route = definePage({
		render: 'client',
		load: async ({ url, params, search, signal, state }) => api.notes.list({ signal }),
		head: ({ data }) => ({ title: `${data.length} notas` }),
	})
</script>

Con render: "client" el bloque <script server> (o el sidecar) es público: entra en el bundle del navegador con los autoimports de cliente, aunque su etiqueta diga server.

Con render: "client" el servidor ejecuta el middleware de servidor y de ruta, crea el contexto de sesión y valida params y search con los schemas del sidecar (una entrada inválida responde 400). Después renderiza app/app.meeko y los layouts con un outlet vacío, sin llamar a load ni a head, y envía un payload con render: "client" y sólo params y search. Sin layouts, #app queda vacío. En el navegador, Meeko hidrata los layouts, ejecuta load con ClientPageLoadContext (url, params, search, signal y state, sin request ni context) y confirma la página por la misma vía transaccional que una navegación; head se ejecuta después de load y su title se aplica a document.title. Un fallo del loader muestra el +error.meeko más cercano dentro de los layouts, con el mismo mensaje público que el servidor (500 informa al observador de errores de navegación; un ClientError 4xx conserva su estado y código).

La navegación funciona en ambos sentidos entre páginas SSR y de cliente y conserva los layouts comunes: cada ruta elige su origen de datos. Las páginas "client" usan su sidecar en el navegador y las demás piden su payload al servidor. Sólo los sidecars "client" entran al bundle cliente, mediante el módulo virtual virtual:meeko-client-routes; la entrada generada los carga con mountClientApp({ loadClientRoute }). Por eso el build aplica la misma frontera que al resto del código cliente: importar server/ o un módulo *.server.* desde ese sidecar detiene meeko build, y en el navegador sólo hay autoimports de cliente, por lo que usar un util de server/utils falla con un error que nombra el autoimport.

Compromisos de "client":

• SEO. El HTML inicial no contiene los datos ni el <title> de la página. Los buscadores que no ejecutan JavaScript sólo ven los layouts. Use "ssr" o "prerender" para contenido indexable.
• Seguridad de los datos. El sidecar es público: no puede contener secretos ni comprobar permisos. Los datos llegan por API o RPC, y cada endpoint debe aplicar sus propias guardas (sesión, CSRF, autorización y validación). El middleware de ruta protege la navegación, pero no los datos.
• Prerender. Una página "client" no se puede prerenderizar: declarar prerenderEntries junto a render: "client" detiene meeko check/meeko build con un error explícito.
• Build coherente. El servidor compara el render del sidecar con el del manifiesto del build y responde con error si difieren; vuelva a ejecutar meeko build (o reinicie meeko dev) al cambiar el modo de una ruta.

Streaming SSR (render: "stream")#

Un loader marca con defer los datos que pueden llegar después de la página. defer(promise, { timeoutMs }) o defer((signal) => promise, { timeoutMs }) devuelve un Deferred<T> con status ("pending", "resolved" o "rejected"), value y error ({ code, status }). Leer esos campos en una plantilla o un effect se suscribe al resultado, porque están respaldados por señales.

Con una fábrica, Meeko la invoca cuando el loader devuelve y le pasa un AbortSignal que se aborta cuando el valor deja de esperarse: al agotar timeoutMs, si el cliente se desconecta, si se revoca la sesión, si el stream se cancela, en una petición HEAD o, en el navegador, al salir de la ruta. Pásela a fetch o a su cliente de base de datos para cancelar de verdad el trabajo. Una promesa ya iniciada no se puede cancelar: Meeko sólo deja de esperarla, salvo que el propio trabajo use context.signal del loader, que también se aborta en esos casos (salvo el timeout, que es propio de cada valor).

// app/pages/posts/[id].route.ts
import { defer, definePage } from '@meekojs/meeko/framework'

export const route = definePage({
	render: 'stream',
	load: async ({ params }) => ({
		post: await api.posts.get({ params }), // crítico: entra en el HTML inicial
		comments: defer((signal) => api.comments.list({ params, signal }), { timeoutMs: 5_000 }),
	}),
	head: ({ data }) => ({ title: data.post.title }),
})

<p if:when="props.data.comments.status === 'pending'">Cargando comentarios…</p>
<ul if:when="props.data.comments.status === 'resolved'">
	…
</ul>
<p if:when="props.data.comments.status === 'rejected'">No se pudieron cargar ({props.data.comments.error?.code}).</p>

Fase 0, antes del primer byte. El servidor resuelve la ruta, crea el contexto y la sesión, ejecuta el middleware, valida params y search, espera el loader crítico (todo lo que no está en defer), renderiza de forma síncrona la página y todos sus layouts con los diferidos en pending y calcula head, que ve el estado escrito durante el render. Después sella el estado (StateStore.seal(): una escritura posterior lanza STATE_SEALED y el valor diferido que la provocó se rechaza con 500), espera los cambios de sesión que sigan en curso (create, rotate o revoke iniciados por el loader) y llama a context.session.verify(); una sesión revocada mientras corría el loader responde 401 en lugar de un 200 parcial. Estado, cabeceras, cookies, token CSRF y <title> quedan fijados ahí: no se puede redirigir ni cambiar la sesión desde trabajo diferido. Desde ese momento create, rotate y revoke fallan con SESSION_LOCKED/500 antes de tocar el almacén, de modo que la sesión del navegador sigue siendo válida: sólo se rechaza el valor diferido que lo intentó, el fallo llega a onError y los demás valores siguen llegando.

El sellado se aplica a todos los modos de render, no sólo a "stream". Una escritura de estado desde una promesa que nadie espera (ni el loader con await ni un defer) lanza STATE_SEALED dentro de esa promesa; si no la captura, es un rechazo no manejado y Node termina el proceso con su configuración por defecto. Espere ese trabajo en el loader o devuélvalo con defer.

Fase 1, el stream. La respuesta lleva cache-control: no-store, no-transform y x-accel-buffering: no. Primero se envía el documento hasta #app, el payload #meeko-payload (con deferred: [{ id, path, status: "pending" }] y null en cada path) y la entrada cliente con <script type="module" async>, que respeta el nonce CSP del host. Por cada valor que se resuelve, en el orden en que se resuelve, sigue un <script type="application/json" data-meeko-deferred="N">{"deferred":N,"value":…}</script> (o "error":{"code","status"}), y al final </body></html>. Son bloques de datos, no scripts ejecutables, así que una CSP estricta sin 'unsafe-inline' no necesita excepciones.

Errores y cancelación. Un rechazo se serializa sólo como { code, status } con las mismas reglas que la API: un ApiError conserva su código y estado; cualquier otro error se convierte en INTERNAL_ERROR/500 y su causa privada se envía a onError con el requestId de la respuesta. Un valor que no termina en timeoutMs (10 s por defecto) se rechaza con DEFERRED_TIMEOUT/504. Los diferidos siguen RequestContext.signal: si el cliente se desconecta o falla una escritura del adaptador, el stream se cancela, Meeko deja de esperar los diferidos pendientes y aborta la señal de sus fábricas y la signal del loader, sin informar a onError; si se revoca la sesión, los que quedan se envían como SESSION_REVOKED/401. Una petición HEAD recibe las cabeceras finales sin cuerpo y aborta igualmente esas señales. Una promesa pasada directamente a defer sigue ejecutándose hasta terminar por su cuenta.

Navegador. El cliente hidrata con todos los diferidos en pending, como los renderizó el servidor, y aplica los valores ya llegados sólo cuando termina la hidratación. Encuentra los bloques que ya estaban en el documento y los que añade el parser después mediante un MutationObserver sobre <body>. Sólo acepta los bloques que son hijos directos de <body> y están después de #meeko-payload, donde los escribe el servidor; un bloque con el mismo aspecto dentro de #app (por ejemplo, HTML de usuario) se ignora. Si el documento termina sin el bloque de algún valor (por ejemplo, porque falló una escritura), ese valor se rechaza con DEFERRED_INCOMPLETE/502. En una navegación cliente a una ruta "stream", Meeko pide accept: application/meeko+json y el servidor responde application/meeko+ndjson: la primera línea es el payload, con el que se confirma la ruta, y cada línea siguiente es { "deferred": id, "value" | "error" }. Una línea mal formada se informa a onError y no detiene la lectura; si la conexión falla a mitad, el fallo se informa y los valores que no llegaron se rechazan con DEFERRED_INCOMPLETE/502. Navegar a otra ruta cancela la lectura pendiente. Las demás rutas siguen respondiendo application/meeko+json.

stream frente a ssr. Con render: "ssr" o "prerender", un defer se espera dentro del servidor antes de renderizar: el HTML siempre contiene el valor resuelto (o su error) y es seguro para SEO, así que una página puede pasar de un modo a otro sin cambiar la plantilla. Con "prerender", un valor rechazado no se guarda: la petición responde 500 y meeko build se detiene indicando la ruta y el path del valor. El HTML prerenderizado y su index.meeko.json salen de la misma ejecución del loader. Use "stream" cuando una parte secundaria de la página (comentarios, recomendaciones, métricas) es lenta y no debe retrasar el primer pintado ni la interactividad. Compromisos:

• SEO. El contenido diferido no está en el HTML inicial del SSR, sino en bloques de datos posteriores que sólo se muestran al ejecutar JavaScript. Lo que deba indexarse tiene que ir en el loader crítico o en una página "ssr".
• Proxies y CDN. Un proxy, balanceador o CDN que almacena la respuesta completa antes de reenviarla anula el streaming: el usuario espera igual que con "ssr". Meeko envía x-accel-buffering: no (respetado por nginx) y cache-control: no-store, no-transform: no-transform pide a los intermediarios que no compriman ni reescriban el cuerpo, porque una compresión o reescritura con buffer retendría los bloques. En Cloudflare, no-transform desactiva la compresión hacia el visitante y las funciones que modifican el HTML, pero no la inspección de sólo lectura: si una zona la tiene activa, cree una Configuration Rule con «Response Body Buffering» en «None» para esas rutas. En local, wrangler dev y meeko preview --adapter cloudflare (Miniflare) comprimen con gzip las respuestas text/html aunque lleven no-transform y sólo escriben el cuerpo comprimido al terminar, así que una página "stream" parece llegar entera al final salvo que el cliente envíe accept-encoding: identity. En producción, la compresión de Cloudflare sí respeta no-transform. Otros intermediarios o funciones serverless sin respuestas en streaming deben configurarse aparte. Los adaptadores Node, Bun y Deno escriben cada bloque en cuanto se produce; la suite de conformidad comprueba que el primer byte llega antes que el valor diferido.
• Cabeceras finales. Redirecciones, cookies, CSRF y <title> dependen sólo de los datos críticos. Mover algo a defer lo saca de esas decisiones.
• Loaders en el navegador. Un sidecar "client" (o un host que usa loadRoute) también puede devolver defer: el navegador aplica el mismo timeoutMs, el valor se actualiza cuando su promesa termina y la señal de una fábrica se aborta al agotar el plazo o al salir de la ruta.
• Claves. Un valor diferido puede estar bajo cualquier clave propia, incluidas constructor y prototype, salvo __proto__: el servidor responde 500 al renderizar.

Caché de páginas SSR#

Desde 1.7, cache de definePage permite revalidar y cachear una página "ssr" o "stream" sin ejecutar su loader ni su render en cada petición:

<!-- app/pages/docs/[...slug].meeko -->
<script
	server
	lang="ts"
>
	import { definePage } from '@meekojs/meeko/framework'

	export const route = definePage({
		cache: {
			// Barato: una consulta de la fecha de modificación, no del documento.
			etag: async ({ params }) => (await docs.updatedAt(params.slug))?.toISOString(),
			maxAge: 60,
			staleWhileRevalidate: 600,
			memory: { maxEntries: 500 },
		},
		load: ({ params }) => docs.get(params.slug),
	})
</script>

• etag(ctx) devuelve la versión del contenido (una cadena o un número) y se llama antes del loader y del render, con url, params y search ya validados, request, signal y context. Meeko la combina con el tema de la petición (cookie y client hint), el build y el tipo de respuesta (documento o payload de navegación) en un ETag débil, W/"…". Si coincide con If-None-Match, responde 304 sin loader, sin plugins y sin render. Debe cambiar con todo lo que cambia el HTML salvo el tema: si la página lee una cabecera o un parámetro de búsqueda que no está en params, inclúyalo. undefined deja esa respuesta sin ETag.
• maxAge y staleWhileRevalidate (segundos) escriben Cache-Control: public, max-age=N, stale-while-revalidate=M. Sin maxAge, public, max-age=0, must-revalidate: el navegador revalida cada vez, y el ETag le ahorra el cuerpo.
• memory (true o { maxEntries, maxBytes }, por defecto 1000 entradas y 32 MiB por ruta y proceso) guarda el HTML y el payload renderizados en una LRU, con la clave URL, tema y tipo de respuesta, y el ETag con el que se renderizaron. Desde 1.7, en una ruta con schema search, la parte de la URL tras ? es el search validado: un parámetro que la ruta no declara (?utm_source=…, un número aleatorio para saltarse la caché) comparte la copia en lugar de llenar la LRU; sin schema, cuenta la query tal como llega, porque la página la recibe entera. Mientras etag devuelva lo mismo, Meeko sirve la copia sin loader ni render; cuando cambia, la copia se descarta y la página se renderiza otra vez. Necesita etag. Dos peticiones simultáneas que no encuentran copia renderizan las dos.

La respuesta lleva Vary: Accept, Cookie (y Sec-CH-Prefers-Color-Scheme con el tema en "system"), porque el documento y el payload comparten URL y el HTML depende del tema y de la sesión. Con server.contentSecurityPolicy, el documento de una página con cache no lleva nonce y su CSP lleva los hashes del código en línea que escribe Meeko, nunca los de un <script> o un <style> que llegue dentro de la página (véase CSP y cabeceras en los adaptadores con servidor); el 304 no lleva CSP, así que el navegador conserva la de su copia.

Qué nunca se cachea. La caché sólo se aplica en producción (en meeko dev cada petición renderiza lo que acaba de compilar) y a peticiones GET y HEAD sin sesión:

• una petición con la cookie de sesión, aunque haya caducado, o con session.current, sale como siempre, con no-store y sin ETag: su HTML lleva el token CSRF de esa sesión;
• una respuesta que pone una cookie (un loader que crea la sesión, por ejemplo) sale con no-store, sin ETag y sin copia en memoria; en desarrollo, Meeko lo avisa una vez por ruta en la consola;
• desde 1.7, una petición con la cabecera Authorization sale con no-store y sin ETag, sin leer ni escribir la copia: se responde para esas credenciales;
• un host con su propio nonce (DocumentOptions.nonce sin server.contentSecurityPolicy) no cachea: la copia llevaría el nonce de otra respuesta;
• una petición con la cookie de un solo uso del resultado de un formulario sin JavaScript (__Host-meeko-form, o meeko-form sin HTTPS) no recibe 304 ni la copia en memoria, no se guarda y, en una página prerenderizada, se renderiza en lugar de servir el archivo;
• y, en cualquier respuesta de la aplicación, Set-Cookie con un Cache-Control public o, desde 1.7, con s-maxage (también si lo añade server.headers) se convierte en private, no-store sin ETag.

Personalizar con cookies propias. Meeko sólo reconoce su cookie de sesión. Una página con cache que personaliza el HTML con otra cookie (idioma, moneda, un carrito anónimo, un test A/B) lo comparte: etag no la ve si no la lee, y memory sirve la misma copia a todos. Vary: Cookie sólo evita que una caché compartida mezcle respuestas con cookies distintas. Si el HTML depende de una cookie propia, incluya su valor en lo que devuelve etag y no use memory, o no use cache en esa página.

Middleware. El middleware de ruta (isomórfico y de servidor) se ejecuta siempre, antes del 304 y de la copia en memoria: una guarda nunca se salta por la caché. Con memory, los plugins de aplicación no se ejecutan en una petición servida desde la copia.

render: "stream". Sólo usa el ETag y el 304: su cuerpo sale mientras se resuelven los valores defer, así que guardarlo obligaría a esperar a todos (lo contrario de un stream) y fijaría valores que pueden cambiar en cada petición. Su Cache-Control añade no-transform, como siempre, y su CSP lleva los hashes del documento sin los valores diferidos, que son bloques de datos JSON. Con "prerender", cache sólo afecta al SSR de las URL que no se prerenderizaron; una página "client" no admite cache (error de tipos y TypeError al definirla).

cache se lee al ejecutar la ruta, como load: meeko build no la lee del archivo. definePage la valida al cargar el módulo (un campo desconocido, un número negativo o memory sin etag lanzan TypeError).

Enlaces, anclas y scroll#

mountClientApp convierte en navegación cliente los clics en enlaces del mismo origen hacia una ruta de la aplicación, también los del HTML insertado con html. Un enlace a un fragmento de la página actual (#seccion, o /docs#seccion estando en /docs) no se intercepta: el navegador desplaza la página y añade la entrada al historial sin volver a pedir ni renderizar la página, y volver atrás o adelante entre esos fragmentos tampoco la renderiza. app.navigate("#seccion") hace lo mismo.

Una navegación nueva empieza arriba de la página o, si su URL tiene un fragmento que nombra un elemento (id o name), en ese elemento, de forma inmediata aunque la página use scroll-behavior: smooth. Una navegación con replace sólo se desplaza al fragmento, si lo hay. Si la petición de datos de una navegación recibe HTML en lugar de un payload (un hosting estático que sirve el index.html prerenderizado, un proxy o una CDN), Meeko carga ese documento en vez de fallar.

Atrás y adelante devuelven al lector a la posición que tenía en cada entrada del historial, aunque tenga un fragmento; una entrada sin posición guardada va a su fragmento, si lo hay. La posición se aplica junto con el DOM de la página, antes del primer frame y dentro de la View Transition. Si aún no cabe porque falta contenido, como un valor de defer, Meeko espera hasta 10 s a que llegue, y lo deja si el lector u otro código mueven la página o si se navega a otra. Al recargar o volver desde otro documento, restaura el navegador.

Para ello Meeko pone history.scrollRestoration en manual, añade meekoEntry a history.state y guarda las posiciones en sessionStorage, y conserva lo demás que haya en history.state. Si escribes en él, mantén lo que ya hay: history.replaceState({ ...history.state, propio: 1 }, ''). Solo se recuerda el desplazamiento de la ventana, no el de un contenedor propio. No hay una opción para controlar este desplazamiento: si necesitas otra posición, desplázate después de que termine app.navigate().

View Transitions nativas#

Activa las transiciones de navegación cliente en meeko.config.ts:

export default defineMeekoConfig({
	viewTransitions: true,
})

La opción es booleana y está desactivada por defecto. Meeko carga la página, sus módulos y sus datos antes de iniciar document.startViewTransition(), y coloca dentro del callback el cambio de DOM y de head. No anima SSR, la hidratación inicial ni los cambios de fragmento de la página actual. Funciona con enlaces internos y atrás/adelante. Sin la API, con la pestaña oculta o con prefers-reduced-motion: reduce, navega normalmente.

Tampoco anima una página demasiado grande: por encima de 4.000 elementos, en la página de origen o en la de destino, navega sin transición. En un documento así, con una pantalla de alta densidad o en un teléfono, cada frame de la transición bloquea la página durante segundos. Si la grande es la de destino, Meeko captura la página de origen y salta la animación al aplicar el cambio. Si llamas a document.startViewTransition() por tu cuenta, comprueba lo mismo con isTooLargeToAnimate.

El navegador proporciona una transición básica; personaliza la animación desde app/styles/main.css con CSS nativo:

.project-surface {
	view-transition-name: project-surface;
}

::view-transition-group(project-surface) {
	animation-duration: 280ms;
	animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}

Usa el mismo view-transition-name en el elemento de origen y destino. Cada nombre debe ser único entre los elementos visibles de una página; los duplicados pueden impedir la animación, aunque la navegación se completa. No se necesita una directiva ni un componente envolvente. Consulta la API nativa.

Desde 1.8, la transición de una navegación lleva el tipo meeko-route, así el CSS la distingue de la que inicia un componente. Da nombre a un elemento sólo durante las navegaciones:

html:active-view-transition-type(meeko-route) .tabs-indicator {
	view-transition-name: tabs-indicator;
}

Un navegador sin tipos de transición (Chrome anterior a 125, Safari anterior a 18.2, Firefox anterior a 147) anima igual la navegación e ignora esas reglas.

Para desactivar o activar una navegación concreta, usa app.navigate('/projects', { viewTransition: false }) en un host que dispone del ClientApp devuelto por mountClientApp. Los enlaces admiten un atributo HTML estándar, tanto en <MeekoLink> como en <a>:

<MeekoLink
	to="/projects"
	data-meeko-view-transition="false"
>
	Abrir sin transición
</MeekoLink>

data-meeko-view-transition="true" activa ese enlace aunque la opción global esté desactivada; movimiento reducido sigue teniendo prioridad. La promesa de navegación espera al cambio de DOM, sin esperar al final de la animación. Una navegación posterior o desmontar la aplicación omite la animación anterior; una actualización abortada no puede sustituir la página nueva. Los fallos de animación no se convierten en fallos de navegación; los errores del render siguen propagándose como antes.

Esta opción controla cambios dentro del mismo documento. Las navegaciones a documentos nuevos pueden usar @view-transition { navigation: auto; } en las hojas de ambas páginas del mismo origen, sujeto al soporte del navegador y a las reglas de esa API. Los modales de UI mantienen sus animaciones locales y no necesitan capturas de toda la página. El ejemplo /transitions de la web pública apps/ui incluye una superficie compartida entre lista y detalle, además de enlaces sin transición.

Estado de navegación#

useNavigation() devuelve { pending }, una señal de sólo lectura que vale true desde que empieza una navegación hasta que su página se confirma, falla o se cancela, incluida la primera carga de una página "client" y la carga de los await useApi/await useRpcQuery de la página nueva (véase Navegación y render: "client"). En SSR y fuera de mountClientApp vale siempre false. Desde 1.7 se autoimporta, como useRoute (un export propio con ese nombre tiene prioridad).

import { useNavigation } from '@meekojs/meeko/framework'

const nav = useNavigation()
// <p if:when="nav.pending.value">Cargando…</p>

Ruta actual#

Desde 1.2, useRoute() devuelve la ruta confirmada que renderiza el componente, con una señal de sólo lectura por valor (tipo RouteState):

Se autoimporta en las aplicaciones (un export propio llamado useRoute en app/composables u otra carpeta de autoimports tiene prioridad sobre el del framework) y, como useNavigation, puede llamarse también desde código anidado que se ejecuta con el componente (un composable, un computed, un effect u onMounted), pero no desde un manejador de eventos, un temporizador ni el callback de una promesa, donde no hay raíz activa: ahí lanza (useNavigation devuelve un estado fijo con pending en false); pídela en el script y úsala en el manejador. Funciona en páginas, layouts, app/app.meeko, app/error.meeko y sus componentes:

• SSR. Los valores son los de la petición, también en las rutas "prerender" y "stream" y en los layouts de una ruta "client". El servidor no recibe el fragmento, así que en SSR url nunca lo lleva.
• Hidratación. El navegador hidrata con los mismos valores que el SSR, sin desajustes, también cuando el HTML se renderizó para otra URL: el 404.html del adaptador static, que el hosting sirve en cualquier URL inexistente, o una página prerenderizada que un hosting estático sirve con cualquier query string. El payload lleva la URL del render (campo opcional url, desde 1.6). Justo después de la hidratación, url y path pasan a ser los de la dirección del navegador, con su #fragmento; en la página 404 también search, y en una página, params y search siguen siendo los que validó el servidor.
• Navegación. Los valores cambian sólo cuando una navegación se confirma, a la vez que el outlet, nunca mientras useNavigation().pending vale true; la página anterior se libera antes de que se actualicen los efectos que leen la ruta. También cambian al volver atrás o adelante en el historial y en una navegación sólo de fragmento, donde path se mantiene y cambia url. El render previo que carga los await de datos de la página nueva ya ve la ruta de destino.
• Fuera de una aplicación. Fuera de un render del framework o de mountClientApp (por ejemplo, en una prueba unitaria con renderToString), useRoute() lanza un error que lo explica, en lugar de inventar una ruta; pase la ruta al componente como prop en esas pruebas.

isActive. Desde 1.5, route.isActive(to, { params, prefix }) dice si una ruta está activa con la misma regla que <MeekoLink match>, para los enlaces y componentes propios. to es un RouteId y params, los de esa ruta, con el tipo de href(): obligatorios en una ruta dinámica, no admitidos en las demás, y una ruta que no existe es un error de tipos. Devuelve "page" cuando la ruta confirmada es la de to, "true" con prefix: true cuando está por debajo de ella por segmentos completos, y false en otro caso; "/" sólo coincide exacta. Ignora la query string y el fragmento y compara las rutas codificadas. El resultado sirve tal cual para bind:aria-current, porque bind: elimina el atributo cuando el valor es false, y como condición, porque "page" y "true" son verdaderos. Lee path, así que la plantilla, un computed o un effect que lo usan se actualizan al navegar; en SSR y al hidratar devuelve lo mismo, sin desajustes.

Un layout con barra lateral marca así la sección activa, igual en el HTML del servidor y después de cada navegación:

<!-- app/layouts/default.meeko -->
<script lang="ts">
	const route = useRoute()
	const links = [
		{ to: '/', label: 'Inicio' },
		{ to: '/users', label: 'Usuarios' },
		{ to: '/settings', label: 'Ajustes' },
	] as const
	const inSettings = computed(() => route.isActive('/settings', { prefix: true }) !== false)
</script>

<template>
	<aside>
		<nav>
			<a
				each:of="links"
				each:as="link"
				each:key="link.to"
				bind:href="href(link.to)"
				bind:aria-current="route.isActive(link.to, { prefix: true })"
			>
				{link.label}
			</a>
		</nav>
		<p if:when="inSettings.value">Los cambios se guardan al salir.</p>
	</aside>
	<main><MeekoOutlet /></main>
</template>

Los componentes recibidos como props mantienen la dirección del contrato: un componente que exige label no satisface un outlet que puede renderizarlo sin label. meeko check diagnostica la expresión que pasa el componente. Al guardar un módulo TypeScript importado por un .meeko abierto, la extensión de VS Code vuelve a comprobar sus diagnósticos y tokens semánticos.

Head del documento: document, useHead y useSeoMeta#

Desde 1.2, Meeko gestiona el <head> de cada documento y los atributos de <html> y <body> a partir de tres fuentes, que se combinan con una sola regla de prioridad:

• document en meeko.config.ts. El documento común de la aplicación: lang y un head con etiquetas y atributos. Se renderiza en todos los documentos HTML: SSR, "stream", "prerender", la página 404 de app/error.meeko, el documento de error de una ruta que falla y el shell de una ruta "client". Se fija en el build (y también llega al bundle del navegador, porque termina en el HTML), así que debe ser serializable: titleTemplate sólo puede ser una cadena (su tipo, DocumentHead, no admite una función, así que el editor y meeko check la marcan como error de tipos en meeko.config.ts) y meeko build rechaza una función. Su title es el título del sitio: lo muestran, tal cual y sin plantilla, las páginas sin título propio (véase Título más abajo). Los módulos de Meeko añaden su head antes del de la aplicación, que gana.
• useHead(input). En páginas, layouts, app/app.meeko, app/error.meeko, componentes y composables, en el nivel superior del script o en un composable que éste llama. También en el código de nivel superior de <script server>, como alternativa a export const head (véase más abajo). input puede ser un objeto, un getter o una señal; con un getter o una señal, el navegador actualiza el documento cuando cambian los valores que lee.
• useSeoMeta(input). Atajo tipado sobre useHead: description, robots, themeColor, colorScheme, author, keywords, applicationName, referrer y los campos twitter* producen <meta name>; los og* (ogTitle, ogDescription, ogImage, ogImageAlt, ogImageWidth, ogImageHeight, ogUrl, ogType, ogSiteName, ogLocale) producen <meta property>; title es el título y canonical, <link rel="canonical">. Un campo undefined o null no produce nada.

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({
	document: {
		lang: 'es',
		head: {
			// «Zapatillas · Mi tienda» en una página titulada; «Mi tienda» en una sin título.
			title: 'Mi tienda',
			titleTemplate: '%s · Mi tienda',
			link: [{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }],
			// Se ejecuta mientras el navegador lee <head>, antes de pintar; la hidratación no lo repite.
			// (Para un tema claro/oscuro, use theme: Meeko trae el script, la cookie y useTheme().)
			script: [{ children: 'document.documentElement.dataset.theme = localStorage.getItem("theme") ?? "light"' }],
		},
	},
})

<!-- app/pages/products/[id].meeko -->
<script
	server
	lang="ts"
>
	const { params } = usePage()
	export const product = await findProduct(params.id)
</script>

<script lang="ts">
	const quantity = signal(1)
	useSeoMeta({
		title: product.name,
		description: product.summary,
		ogImage: product.image,
		twitterCard: 'summary_large_image',
		canonical: `https://tienda.example/products/${product.id}`,
	})
	useHead(() => ({ title: `${product.name} (${quantity.value})` }))
</script>

HeadInput admite title, titleTemplate ("%s · Sitio" o (title) => string; en document.head, meeko.addHead y el head de la ruta, sólo la cadena), meta, link, script (externo con src o en línea con children; async, defer, module y type), style (con children y media), htmlAttrs y bodyAttrs (lang, dir, class, data-*; un valor undefined no aporta nada y los atributos on* se rechazan).

Prioridad. De menor a mayor: document de la configuración, app/app.meeko, cada layout (el más interno gana), la página con sus componentes y, por último, el head de la ruta (export const head, route.head o useHead en <script server>). Dentro de un mismo nivel gana la llamada posterior, de modo que un componente de la página que se monta después (por ejemplo, tras un if:) sustituye a lo que fijó la página. Los atributos de <html> y <body> se combinan por nombre con la misma prioridad.

Título. titleTemplate es el de la entrada de más prioridad que lo declara, y se aplica al título de más prioridad de app/app.meeko, los layouts, la página y el head de la ruta, también al de las páginas de error: "Error" o, por encima, el que declare con useHead la propia página de error (app/error.meeko o +error.meeko), a la que no ganan los títulos de sus layouts. El title de document.head (o el que añade un módulo con meeko.addHead) es distinto: es el título del sitio y nunca pasa por la plantilla. Una página sin título propio muestra ese título tal cual, y lo mismo una cuyo título ganador es una cadena vacía, en lugar de una plantilla alrededor de nada. Sin título del sitio, una página sin título no tiene <title> gestionado (queda el del host, si lo hay) y un título vacío se escribe vacío. La regla es la misma en el SSR, al hidratar y al navegar en el cliente. Con la configuración del ejemplo:

Deduplicación. Cada etiqueta tiene una clave: key si la declara o, si no, su clave natural. En meta, name (sin distinguir mayúsculas), property o httpEquiv, junto con su media si lo tiene (dos theme-color para claro y oscuro conviven); en link, rel y href, salvo rel: "canonical" y rel: "icon", que son únicos aunque cambie href; en script, src o el código; en style, el CSS. Con la misma clave sólo queda la etiqueta de más prioridad, en el lugar donde apareció la primera. Así, un icon de document sustituye al <link rel="icon" href="data:,"> que Meeko escribe por defecto, y un meta name="viewport" sustituye al viewport por defecto.

SSR y CSP. El servidor escribe <html lang="…"> y los atributos como atributos reales, escapados. Dentro de <head>, tras la meta CSRF y los estilos de los componentes, el título y las etiquetas gestionadas van entre los comentarios <!--meeko:head--> y <!--/meeko:head-->, antes del HTML de confianza del host (DocumentOptions.head, que conserva su propio <title> como título por defecto). Los valores de los atributos se escapan; el contenido de script y style en línea no se escapa, pero no puede cerrar su etiqueta: </ se escribe <\/ (y <!--, <\!-- en un script), y en los scripts JSON (application/ld+json, application/json, importmap, speculationrules) cada < se escribe \u003c. El nonce CSP de la petición (DocumentOptions.nonce) se añade a los <script> y <style> gestionados. Una página prerenderizada conserva el head y recibe la meta CSRF justo después de <meta charset> y de las etiquetas por defecto que la aplicación no sustituyó.

Navegador. Al hidratar, Meeko adopta las etiquetas del SSR sin duplicarlas ni volver a ejecutar los scripts. Cuando cambia un getter o una señal de useHead, actualiza el título, los atributos y las etiquetas. Al navegar, las entradas de los componentes que se desmontan desaparecen y vuelve lo que habían sustituido (por ejemplo, el canonical del layout o la description de app/app.meeko); al volver atrás, la página restaura las suyas. Las etiquetas nuevas se insertan antes de <!--/meeko:head--> con el nonce CSP del documento; un script que cambia es un elemento nuevo, que el navegador ejecuta. El head de la ruta viaja en el payload de navegación, igual que title y description en 1.1. Fuera de una aplicación de Meeko (por ejemplo, en una prueba unitaria con renderToString), useHead no hace nada. Un host propio que pasa DocumentOptions.config a createFrameworkHandler debe pasar el mismo valor a mountClientApp({ document }); la entrada que genera Meeko ya lo hace.

<script server>. useHead y useSeoMeta en el código de nivel superior hacen que el bloque tenga código de nivel superior, como usePage. Sus entradas forman el head de la ruta junto con export const head (o route.head), que gana sobre ellas. Como viajan en el payload, su titleTemplate debe ser una cadena.

Canónica y Open Graph por página#

Desde 1.3, document.seo añade a cada documento las etiquetas que dependen de la página y que, sin él, cada página tendría que repetir con useSeoMeta:

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({
	site: 'https://example.com',
	document: { seo: true, head: { titleTemplate: '%s · Mi sitio' } },
})

seo: true las activa todas; un objeto desactiva las que valen false (seo: { ogDescription: false }). El origen es site o, sin él, MEEKO_PUBLIC_ORIGIN del entorno del build; con canonical u ogUrl activos y sin ninguno de los dos, meeko build falla con un mensaje que lo pide. Se fija en el build (seo.origin del manifiesto), así que una página renderizada con SSR usa el mismo origen que una prerenderizada. En meeko dev sin origen esas dos etiquetas no se escriben.

Son las etiquetas de menor prioridad: una página o un layout que declara la misma etiqueta (con useSeoMeta, useHead o el head de la ruta, con cualquier key) la sustituye, igual que a las de document.head. Las páginas de error (app/error.meeko, +error.meeko y el 404.html del adaptador static) no reciben canonical ni og:url, porque se sirven en cualquier URL. Al navegar en el cliente, las etiquetas siguen a la página confirmada. Un host propio que pasa DocumentOptions.config con seo debe incluir seo.origin.

Tema claro/oscuro sin parpadeo#

Desde 1.4, Meeko trae el tema claro/oscuro (y temas propios): la elección se guarda en una cookie, el servidor escribe el tema en <html> desde el primer byte y los componentes pintan en el HTML del servidor los iconos correctos, sin esperar a JavaScript. Cuando el servidor no puede saberlo (una página prerenderizada, el adaptador static o el modo "system" sin client hint), un script mínimo y bloqueante de <head> lo aplica antes del primer pintado.

// meeko.config.ts
import { defineMeekoConfig } from '@meekojs/meeko/framework'

export default defineMeekoConfig({
	theme: true, // light y dark, "system" por defecto, data-theme y la cookie meeko-theme
})

/* app/styles/main.css: los colores de cada tema, con color-scheme también sin JavaScript. */
:root {
	color-scheme: light;
	--bg: #fff;
	--ink: #111;
}
:root[data-theme='dark'] {
	color-scheme: dark;
	--bg: #111;
	--ink: #eee;
}
/* Sin atributo (modo "system" que el servidor no pudo resolver y sin JavaScript), manda el sistema. */
@media (prefers-color-scheme: dark) {
	:root:not([data-theme]) {
		color-scheme: dark;
		--bg: #111;
		--ink: #eee;
	}
}