Meeko as a full-stack framework

Meeko keeps the standalone engine in @meekojs/meeko. Application mode uses @meekojs/meeko/framework, and Vite uses @meekojs/meeko/vite. The server is split across these subpaths:

• @meekojs/meeko/server: portable application core (createServerApp, defineServerRuntime, API/RPC contracts, sessions, middleware, Socket, createSocketUpgradeHandler, OpenAPI and, since 1.3, contentSecurityPolicy). It only uses Web APIs and node:async_hooks; it does not load TypeScript, Vite, ws or the filesystem.
• @meekojs/meeko/node: Node adapter (serveNode, toNodeListener, createNodeAssetReader, attachNodeWebSocketServer and createNodeSocketUpgradeHandler).
• @meekojs/meeko/password (since 1.2): hashPassword, verifyPassword and needsRehash with scrypt; it requires node:crypto, so it works in Node, Bun and Deno, but not Workers (see Passwords).
• @meekojs/meeko/bun: Bun adapter (createBunServer and createBunAssetReader).
• @meekojs/meeko/deno: Deno adapter (serveDeno and createDenoAssetReader).
• @meekojs/meeko/cloudflare: Cloudflare Workers adapter (createWorker, createSocketRoomClass, DurableObjectSocketPubSub, D1SessionDriver, createCloudflareAssetReader and createCloudflarePrerenderSource).
• @meekojs/meeko/build: build tools that read the filesystem and load TypeScript (discoverRoutes, discoverErrorPage, discoverConfiguredRoutes, composeFrameworkRoutes, loadMeekoConfig, readMeekoConfigSync, resolveConfigSources, discoverServerManifest, prerenderRoutes, prerenderProject, buildProject and, since 1.3, inlineScriptHashes). The production server does not import this subpath.

All subpaths belong to the same package and version. Published server targets are Node 24, Bun, Deno and Cloudflare Workers, checked by the same conformance suite (see Build, deployment and verification). Since 1.3, the static adapter also generates a file-based site, without a server, for static hosting (see Static site). Build and development tools still run on Node. SSR is enabled by default.

The generated application requires Node 24 or later and TypeScript 7 to check its declarations; the .meeko compiler uses TypeScript 6 internally only during development and build. The package is ESM. vite is an optional peer: an application that only uses the engine can import @meekojs/meeko without starting the framework, server, sessions or Socket. The Node adapter loads ws when you enable attachNodeWebSocketServer, not when you import the engine.

Create an application#

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

The starter creates meeko.config.ts, app/app.meeko, app/pages, app/styles/main.css, a layout with an outlet and an .env.example with Meeko's variables; it does not need server/runtime.ts, because sessions work without configuration (see Authentication). Meeko generates client/server entry points and their build configurations under .meeko/; you run meeko dev, meeko check, meeko build and meeko start through the package.json scripts; meeko preview also runs the build. You can organize the application like this:

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 generates Vite entry points and per-scope TypeScript configurations only under .meeko/. The single root tsconfig.json connects VS Code to these generated projects to preserve diagnostics and completion in .ts files. The optional server/runtime.ts is application code: it declares services, Socket policy and, if Meeko's sessions are not enough, your own sessions. The standalone engine starter remains available with meeko init <directory>.

Migrate an earlier full-stack starter#

An application generated with 0.0.4 can adopt the current project host without maintaining manual entry points. Change its scripts to meeko dev, meeko check, meeko build and meeko start; run the new build first and compare any customizations. You can then remove server.mjs, the client/server entry points, Vite configurations and per-scope tsconfig.* files that Meeko now generates under .meeko/. Keep the root tsconfig.json as the editor link.

If you want the current layout convention, move the root layout to app/layouts/default.meeko. Do not keep both that file and app/pages/+layout.meeko, because they would represent the same tree level. Move customizations that can be expressed through supported public conventions to middleware, handlers and those conventions. If a host or Vite customization has no equivalent public API yet, keep the manual host; migration must not delete customizations or attribute capabilities to meeko.config.ts that it does not offer.

Migrate server/session.ts to server/runtime.ts#

Meeko no longer loads server/session.ts. If the file exists, meeko check, meeko dev and meeko build stop with migration instructions rather than ignoring it. Move the SessionManager returned by createSessionManager(production) to the default export of server/runtime.ts and remove server/session.ts:

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

// After: 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) => ({/* per-request services */}),
}))

meeko build creates the runtime with prerendering: true to render render: "prerender" routes; no client traffic is served during that phase, so the application can use an in-memory store instead of opening the production database. Applications that imported build tools from @meekojs/meeko/server must import them from @meekojs/meeko/build (discoverRoutes, discoverServerManifest, loadMeekoConfig, prerenderProject…), and import toNodeListener, attachNodeWebSocketServer and createNodeSocketUpgradeHandler from @meekojs/meeko/node. createServerDispatcher, createLocalCalls, generateOpenApi and loadSocketChannels now require an explicit loader, such as (file) => import(pathToFileURL(file).href) in Node.

app/styles/main.css is optional and loads automatically as a global stylesheet during development and build. Vite includes it in the production CSS asset; Meeko links that asset in SSR and prerendered HTML. .meeko <style> blocks remain available for local styles.

PostCSS and Tailwind. Vite processes both app/styles/main.css and component <style> blocks with PostCSS, using the project root's postcss.config.*. For Tailwind 4, install tailwindcss and @tailwindcss/postcss, declare the plugin and load Tailwind in the global stylesheet; Tailwind reads classes from .meeko files:

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

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

In a <style scoped>, @apply requires @reference "tailwindcss"; (or the stylesheet path with your theme) at the start of the block. Since 1.2, each component's CSS is the module Componente.meeko?meeko-style=…&lang.css, next to its file, so PostCSS plugins resolve @reference and relative @import paths from the component folder. The selector already has the scope attribute when Tailwind expands @apply, so the declarations inherit the scope:

<!-- app/components/Card.meeko -->
<style scoped>
	@reference '../styles/main.css'; /* with the project's @theme */

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

Tailwind also generates classes that only appear in bind:class literals (bind:class="open.value ? 'ring-4' : undefined"), because it reads the text of .meeko files. meekoUtilities() works alongside Tailwind if it comes first in the plugin list (plugins: [meekoUtilities(), tailwindcss()], with import tailwindcss from '@tailwindcss/postcss'): Tailwind receives the generated rules instead of @utilities.

@tailwindcss/postcss detects sources from the working directory (process.cwd()), not the project root. CLI commands that accept the project (dev, build, start, preview, check, routes, prerender and check-app) change the working directory to that root before loading configuration and PostCSS, so meeko dev ../app works from any folder; relative argument paths are resolved first, against the launch folder. Programmatic APIs (buildProject, startProject…) do not change the process cwd: call them with the cwd at the root or set the source with @import 'tailwindcss' source('../..'); (relative to the stylesheet) or the plugin's base option. From a broader folder, Tailwind scans all of its contents; from a drive root it can exhaust memory.

During SSR and prerendering, Meeko embeds component <style> CSS already processed by PostCSS and Vite CSS plugins in the document (since 1.8; previously it arrived unprocessed), so a scoped @apply or an @utilities inside a component applies from the first render, without waiting for JavaScript. It is the same CSS as the component asset; inline <style> elements preserve the CSP nonce or hashes, deduplication and tree order (layouts, page and children). They go at the end of <head>, after app/styles/main.css, module stylesheets and the document head, where the client later adds component CSS: a scoped rule and a global rule of equal specificity resolve the same way on the first render as after hydration (since 1.8; previously the global rule won only until JavaScript loaded). In meeko dev, the Vite client adopts those <style> elements instead of adding a copy, and HMR replaces them: a rule removed from <style> stops applying without a reload. The error page for a server failure, which does not hydrate, also embeds its CSS.

@tailwindcss/vite. Meeko does not read vite.config.*, but a module can register Tailwind's Vite plugin with addVitePlugin. It replaces @tailwindcss/postcss (do not declare both); meeko dev and meeko build apply it to app/styles/main.css and component <style> blocks, with @theme, scoped @apply and bind:class classes. Unlike the PostCSS plugin, it detects sources from the Vite root, which is the project root:

// 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'] }

A custom Vite host that only uses the meeko() plugin does not receive addVitePlugin registrations; add tailwindcss() to its plugins there. With @tailwindcss/vite, meekoSortClasses: "stylesheet" does not see utilities (it processes the stylesheet without modules' Vite plugins); use "tailwind".

Class ordering with Prettier. With meekoSortClasses: "tailwind" (since 1.8), the Prettier plugin (@meekojs/prettier-plugin or @meekojs/meeko/prettier) sorts the classes in each static class="…" using the official Tailwind CSS 4 order, the same as prettier-plugin-tailwindcss (which does not recognize the meeko parser). It loads the design system from app/styles/main.css, or the stylesheet specified by meekoTailwindStylesheet (relative to the project root), with its @import, @theme, @plugin and @utility, using the project's installed tailwindcss; it works the same with @tailwindcss/postcss and @tailwindcss/vite. Classes unknown to Tailwind, such as those from meekoUtilities() or the component's <style>, go first, in their original order. It does not touch bind:class or a component tag's class.

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

<!-- before -->
<div class="text-white custom p-4 bg-brand flex hover:bg-brand/80"></div>
<!-- after -->
<div class="custom flex bg-brand p-4 text-white hover:bg-brand/80"></div>

If tailwindcss 4 is not installed, the stylesheet does not exist or Tailwind rejects it, classes are not sorted (only normalized), and a warning appears once. The design system is reused until the stylesheet or its imports change. In an untrusted editor workspace, "tailwind" behaves like "off", as does "stylesheet", because it would execute the project's @plugin declarations.

Utilities generated with TypeScript. Since 1.2, the meekoUtilities() PostCSS plugin from @meekojs/meeko/postcss generates rules with a TypeScript function instead of repeating them by hand. The @utilities "<ruta>" [layer(<nombre>)]; at-rule is replaced by the rules returned by the module's default export:

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

export default { plugins: [meekoUtilities()] }
// Or, with the object form: { 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)' })),
])

It generates @layer utilities { .color[data-color='gray'] { --color-1: var(--gray-1); … } … .color { color: var(--color-11); &:hover { … } @media (prefers-contrast: more) { … } } }. A preprocessor loop, such as @each $size in sm, md, lg from postcss-each (which is not part of PostCSS: without that plugin, the rule reaches the browser unchanged and does nothing), is written as a TypeScript map:

// 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 })))

The at-rule:

• Path. Quoted and relative to the stylesheet containing the at-rule: the global stylesheet, a file it imports with @import or a .meeko <style>, which resolves from the component folder. It supports .ts, .mts, .js and .mjs. Without a source file (CSS processed without PostCSS's from option), the path is relative to meekoUtilities({ root }), which defaults to process.cwd().
• layer(x) wraps the result in @layer x { … }; layer without a name creates an anonymous layer. Without layer, rules stay at the at-rule's position.
• It has no block { … }. It can appear multiple times and inside other rules or at-rules.
• It goes after @import declarations. To CSS it is another rule, and @import declarations must precede every rule: Vite warns (@import statements must precede all other statements) and does not include an @import that follows an @utilities.
• It does not conflict with Tailwind. Its name is @utilities; Tailwind 4's @utility is left untouched.

The module's default export is defineUtilities(fn) or an unwrapped function. fn receives the helpers, can be async and returns a node, an array of outputs (nested to any depth, flattened in order) or null, false and undefined, which are omitted, so you can write condición && rule(…).

Declarations are an object: camelCase keys become kebab-case (borderRadius → border-radius, WebkitAppearance → -webkit-appearance, msFlex → -ms-flex); kebab-case keys ("border-radius") and custom properties --* are written as-is. A value is a string, which can end in !important, or a number, written without units (opacity: 0.5, zIndex: 10). undefined omits the declaration, and an array writes one declaration per value, for fallbacks (display: ["-webkit-box", "flex"], including an as const array).

Since 1.3, declarations are typed with csstype: the editor completes standard and vendor-prefixed properties and their value keywords (position: "sticky"), and a misspelled property (backgroundColr) or nonexistent keyword is a type error in the editor and when checking the module with TypeScript. Lengths and times are strings with units (padding: "4px", transitionDuration: "200ms"), except for 0: padding: 4 is an error, because it would write padding: 4, which the browser discards. Numbers are valid where CSS allows them without units (opacity, zIndex, flexGrow, lineHeight, fontWeight…). In atRule, the object also accepts descriptors for @font-face (src, fontDisplay, unicodeRange…), @property (syntax, inherits, initialValue), @page, @counter-style, @font-palette-values and @view-transition (the UtilityAtRuleDeclarations type). An object built outside the call loses its keywords (const base = { position: "absolute" } is { position: string }): annotate it with UtilityDeclarations or use as const. An object with dynamic keys, such as the { [k: string]: string } from Object.fromEntries in the palette example or a Record<string, string>, is accepted without checking its keys. Conversely, UtilityDeclarations no longer has an index signature: reading it with a string key (decls[key]) produces TS7053 with noImplicitAny; use Object.entries(decls) or a keyof UtilityDeclarations key. For a property or at-rule that csstype does not know yet, write the CSS with css`…`.

The types UtilityHelpers, UtilityDeclarations, UtilityAtRuleDeclarations (since 1.3), UtilityValue, UtilityOutput, UtilityNode, UtilityRule, UtilityAtRule, UtilityCss, UtilityFunction and MeekoUtilitiesOptions are exported from the same subpath.

Errors stop the stylesheet with the CSS file and the @utilities line, which Vite shows in its overlay: a missing module or one with another extension, a module that does not compile, a default export that is not a function, an exception from the function (with its message), an invalid selector, property name, value or at-rule parameters (a ; or brace in a value, a NaN number), and an output value that is not a helper node, such as a CSS string without css. After you fix the module, the next edit regenerates the stylesheet.

Module loading and hot updates. Native import() caches every module in the graph for the lifetime of the process: a query on the entry module reloads that module, but not the local files it imports. That is why the plugin bundles the module with rolldown, the bundler already included in Vite 8 (it adds no dependencies): local files, including those reached through a tsconfig alias or the same package's #imports, form a single ES module imported from a data: URL, while node_modules packages remain external and load once with Node, as in any program. This supports all TypeScript, including extensionless imports, and import.meta.url, import.meta.dirname and import.meta.filename still describe the original file. The result is reused until a file in the graph changes its modification time or size, so a stylesheet transformed many times does not rebundle anything. The plugin publishes each graph file as a stylesheet dependency (PostCSS dependency messages), so in meeko dev, editing color.ts or palette.ts regenerates the stylesheet and Vite hot-updates the CSS without reloading the page or restarting the server. Keep these modules outside folders that Meeko watches for auto-imports and routes (app/components, app/composables, app/utils, app/stores, app/pages, app/layouts, shared/…, server/utils, the imports folders…): a change there reloads the entire page, like any other file in those folders; app/styles/ is the natural location. Outside Vite 8 (for example, postcss-cli), if rolldown is not found, the plugin imports the module with Node's native type stripping, which requires imports with extensions and erasable TypeScript syntax, reloads only the entry module and warns once.

Auto-imports. Since 1.4, the @utilities module and the local TypeScript modules it imports receive the same value auto-imports as the rest of the project: inside the rolldown bundle, the plugin applies the Vite plugin's registry and transformation, so app/styles/utilities/color.ts can use the THEME_COLORS constant from app/theme/constants.ts without an import if meeko.config.ts declares imports: { appDirs: ["app/theme"] }, just like a component. As in the editor and meeko check, each module receives those for its scope according to its folder (app/, shared/ or server/ in the application or a layer); a module outside those folders receives none. @utilities modules run in Node while generating CSS, so the registry is limited to what makes sense there:

Using one from the second column does not produce an opaque ReferenceError: the name is replaced by a value that, when used (read, called, converted to text), throws an error with the auto-import, its origin and the reason, which the plugin shows on the @utilities line: "./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. …. Because the error only appears if the value is used, an auto-import file that the module imports and that also exports, for example, a composable using signal, still works for reading its constants. defineUtilities is not an auto-import: import it from @meekojs/meeko/postcss, because declaring it globally would also offer it to components and bring PostCSS into the browser bundle. Types are those of app/ (.meeko/tsconfig.app.json), so meeko check and the editor report TS2304 when using a server/utils export in app/styles/, just as in the rest of app/; however, they accept the browser and framework names in the table, which fail when generating the stylesheet with the error above.

The project is the closest folder to the module with a meeko.config.*, without going beyond its package.json, or that package.json folder if it depends on @meekojs/meeko; its configuration runs as in meeko dev, with its modules' setup functions, once per stylesheet and only if the module will be bundled with rolldown. If reading it fails (a configuration or setup that throws), the stylesheet is still generated without auto-imports, with a PostCSS warning giving the reason. Auto-import files used by the module are part of its graph: they are stylesheet dependencies, and changing them regenerates it. Adding or removing an export in an auto-import folder also rebundles the module on the next transformation, even if no graph file has changed; in meeko dev, those changes reload the entire page, as in any other auto-import folder. meekoUtilities({ autoImports: false }) disables auto-imports and bundles modules as in 1.3. Outside a Meeko project (postcss-cli or a bundler in another project), there is no registry and nothing changes. Without rolldown, using native import(), Node cannot add imports: the module receives no auto-imports, configuration does not run and the native loading warning says so; write the imports explicitly.

Rules generated inside a <style scoped> do not receive the scope attribute: Meeko applies the scope when compiling the block and PostCSS generates rules afterward, so they are global, like those in app/styles/main.css. The plugin only runs in Node during meeko dev and build; @meekojs/meeko/postcss is not part of the browser or server runtime.

With Tailwind. Declare meekoUtilities() before @tailwindcss/postcss:

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

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

In that order, Tailwind receives generated rules like the rest of the stylesheet and processes, for example, @apply from a css`…`; with layer(utilities) they go into the same utilities layer as Tailwind's. In the reverse order, Tailwind first compiles each stylesheet importing tailwindcss and removes unknown at-rules, including @utilities, without an error; the plugin warns once per process. In a stylesheet without @import "tailwindcss", such as a component's <style>, the order does not matter.

Processed global stylesheet for the editor. Classes generated by @utilities, and those in files imported by the stylesheet, are not written in any project CSS file. That is why meeko dev writes the processed app/styles/main.css to .meeko/styles/main.css: the same stylesheet served at /app/styles/main.css?direct, with @import declarations resolved, @utilities expanded and other PostCSS plugins applied, unminified and with an initial comment marking it as generated. It writes it in the background as soon as the server listens, without delaying startup, and rewrites it whenever the stylesheet or a dependency changes: an imported file, an @utilities module or a file that module imports. Also after a Vite restart (for example, when .env changes).

• It only replaces the file when its contents change, atomically (writing a temporary file and renaming it), so a reader never sees half a stylesheet. Vite does not watch .meeko/: writing it does not reload the page or trigger another regeneration.
• If the stylesheet does not compile (a PostCSS or @utilities module error), the file keeps the last good version, the server continues working and the console reports it once: [meeko] .meeko/styles/main.css conserva la versión anterior: app/styles/main.css no compila (…). The next change that fixes it regenerates it.
• Without app/styles/main.css, there is no file; if the stylesheet is deleted while meeko dev is running, the file is also deleted.
• meeko build does not write it: build CSS is minified and combines the global stylesheet with component <style> blocks. The file remains when you stop meeko dev, so running it once is enough; meeko clean removes it along with the rest of .meeko/.
• Nothing loads it at runtime, and you must not edit it manually. url() values appear as rewritten by Vite during development.

It serves editor extensions that complete classes from CSS stylesheets on disk. With HTML CSS Support (ecmel.vscode-html-css) in VS Code:

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

The path is relative to the workspace folder. The extension finds local files through VS Code search, which applies files.exclude but not .gitignore or search.exclude: it finds the file even if .meeko/ is in .gitignore, as in the starter. If your files.exclude hides .meeko, the extension will not see it either; instead, hide only folders you do not want to see, for example ".meeko/output": true. The extension caches each local stylesheet and only rereads it when saved from the editor itself: after a change that regenerates the file, run CSS: Clear style sheets cache from the command palette to see new classes. By default it only completes in HTML; for .meeko files, add "css.enabledLanguages": ["html", "meeko"] to user settings (the extension does not support it per workspace) and restart VS Code.

During development, Vite opens an HMR WebSocket on a port derived from the HTTP port so that two Meeko applications do not compete for Vite's default port. MEEKO_HMR_PORT lets you set it explicitly when the environment requires it; the browser must be able to access that port as well as the application's HTTP port.

Environment variables and .env. Since 1.2, meeko dev, build, start, preview and check load the project root's .env into process.env, like Vite and Nuxt during development. An environment variable that is already defined takes precedence, so a deployment's real environment is never replaced. The output of meeko build executed directly (node .meeko/output/node/index.mjs, a container) does not read .env: in production, variables come from the environment. Changing .env requires restarting meeko dev. Meeko reads these variables:

Since 1.2, all variables read by Meeko start with MEEKO_; the prefix is reserved for Meeko, so application variables must use another name. HOST and PUBLIC_ORIGIN, the previous names, continue working during 1.x when the new variable is missing, with a per-process warning naming its replacement, and will stop being read in 2.0. PORT is not deprecated: it is the permanent fallback for MEEKO_PORT.

If neither MEEKO_PORT (or PORT) nor server.port sets the port, meeko dev uses the first available one starting at 4173 (up to 4192), like Vite: with another meeko dev already on 4173, the second prints [meeko] El puerto 4173 está en uso; meeko dev usa el 4174 and the actual URL, and derives the HMR WebSocket port and editor bridge descriptor (.meeko/dev/editor-bridge-4174.json) from that port. A port set with MEEKO_PORT, PORT or server.port does not change: if occupied, meeko dev exits with El puerto 4173 de 127.0.0.1 ya está en uso; usa MEEKO_PORT=<otro puerto> o cierra el otro meeko dev.

Displayed URL. Since 1.7.1, meeko dev, meeko start, meeko preview and Node, Bun and Deno output print http://localhost:4173 when listening on loopback (127.0.0.1 or ::1) or all interfaces (0.0.0.0 or ::). Only the text changes: the server still listens on the configured address, serveNode(...).url and serveDeno(...).url keep that address (http://127.0.0.1:4173) and, without MEEKO_PUBLIC_ORIGIN, Socket still uses it as its origin and accepts other loopback names, so a page opened on localhost connects the same way. With MEEKO_HOST=0.0.0.0 (or ::, or equivalent server.host), a Red: line is added for each network interface address, like Vite: IPv4 with 0.0.0.0, and IPv4 and global IPv6 with ::, excluding loopback and link-local IPv6 addresses. Deno output only lists them if it has --allow-sys=networkInterfaces (meeko preview grants -A); without that permission, it prints only the local URL and never prompts. With a specific host, such as 192.168.1.20, that host is displayed. The first line is always the local URL alone, for scripts that read it:

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

Development SSR loads @meekojs/meeko from Node, outside Vite's module runner, like the build; this keeps a single runtime instance in an application consuming Meeko with link:, even when Vite reloads its modules. That is why, when @meekojs/meeko is linked (pnpm link:, npm link or a workspace: the package resolves outside any node_modules), meeko dev runs the server in a child process and watches the linked package's dist/ and package.json. When you rebuild it, it waits until compilation finishes (400 ms without changes), prints [meeko] Meeko enlazado cambió; reiniciando meeko dev…, closes the previous server (Socket, HTTP, Vite and the editor bridge descriptor) and starts another process on the same port with the same environment. If the new process fails to start, for example because compilation was incomplete, it reports this and retries on the next change. Only writes count: reading the build does not restart it, even if Windows reports an update to the last access time as a change. Ctrl+C stops both processes. A normal registry installation watches nothing extra.

MEEKO_LINK_WATCH=0 (also from the project's .env) disables restarting with a linked package: a single process serves until stopped. That process keeps the Meeko server code it loaded, while Vite serves the new dist/ files to the browser, so after a rebuild, server HTML (headers, <head>, SSR) comes from the previous build and hydration uses the new one. For this reason, after each rebuild finishes, it prints [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. Restart it before checking the result.

Configuration#

// 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 (or .mts, .js, .mjs) loads with Node and exports an object created with defineMeekoConfig:

• layers (since 1.2): folders that contribute pages, components, auto-imports and plugins; see Layers. extends, the previous name, still works as an alias.
• modules: names of modules created with defineMeekoModule (packages or paths), which configure the project through code; their options go in each module's key, such as seo. See Modules.
• imports: auto-import folders in addition to the defaults, with the scope of their containing folder; see Auto-imports and TypeScript.
  • imports.appDirs (since 1.3): folders inside app/ ("app/services"), with app/ scope: browser and SSR, not shared/ or server/.
  • imports.sharedDirs (since 1.3): folders inside shared/ ("shared/validators"), with shared/ scope: application and server.
  • imports.serverDirs: folders inside server/, exclusive to the server.
• server: the meeko build adapter; see Build, deployment and verification.
• document (since 1.2): lang and <head> entries for all documents. Modules add their own with meeko.addHead; document.head entries apply afterward, so the project's title wins. Since 1.3, document.seo adds each page's canonical URL and Open Graph; see Canonical URL and Open Graph per page. Since 1.5, document.idPrefix is the ID prefix for useId and form.field (m by default).
• dev (since 1.3): meeko dev options. serverLogs: false disables server logs in the browser console.
• devtools (since 1.8): true makes meeko dev mount the Meeko DevTools panel on the page, without application code; { position: "bottom-left" } chooses its corner. Default: false. It never reaches meeko build or meeko start.
• site (since 1.3): the site's public URL ("https://example.com", origin only). This is the origin for absolute URLs Meeko writes: sitemap.xml, robots.txt and document.seo. Without site, the build uses MEEKO_PUBLIC_ORIGIN. It does not change Origin checks, which still read MEEKO_PUBLIC_ORIGIN or publicOrigin from server/runtime.ts at runtime.
• sitemap and robots (since 1.3): sitemap.xml and robots.txt generated at build time; see sitemap.xml and robots.txt.
• theme (since 1.4): light/dark theme and custom themes, without a flash, with useTheme(); see Light/dark theme without a flash.
• alias (since 1.5): custom path aliases, or changes to ~/, @/, #shared/ and #server/, Meeko's defaults; see Path aliases.

Since 1.2, css: { scopeAttribute: "matched" } limits the <style scoped> attribute to elements that a scoped selector can match; with "all", the default in 1.x, it goes on every template element. "matched" will become the default in 2.0. See Scoped styles, including classes added by a script through the DOM API.

Configuration runs in meeko dev, meeko build and meeko check. In a trusted workspace, the language server also executes it, including its modules, so lists can be built dynamically; in an untrusted workspace (or with trusted: false, see editors), the editor does not execute project code: it reads layers, extends, imports.appDirs, imports.sharedDirs and imports.serverDirs as literal string arrays and, from modules, only literal strings that are layer folders. Since 1.5, it also reads alias when it is a literal object of strings and false. Module auto-imports and components do not exist for that editor until you trust the workspace.

Server discovery also rejects impossible client trees. For example, it does not allow api.users.get() to be both a function and the parent of api.users.get.post(), or a procedure rpc.users() to be the parent of rpc.users.get(). The error occurs when generating the manifest and identifies both files, before initializing the client or emitting contradictory types.

meeko routes . discovers all sources, emits .meeko/manifests/routes.json and route, contract and auto-import declarations; since 1.7, it prepares .meeko/ just like meeko check (including Vite entry points, services.d.ts and tsconfig.*.json), without running TypeScript. Vite generates virtual modules from the same discovery for SSR, hydration and navigation. During development, editing an existing page or layout updates the SSR module and reloads the browser; the server keeps its session store. Existing sidecars and API/RPC handlers load from Vite when called.

When you create or delete a page, a layout, app/app.meeko, app/error.meeko, middleware in app/middleware or server/middleware, a plugin in app/plugins, or a module in server/api, server/rpc or server/socket, in the project or its layers, meeko dev rediscovers routes and recreates the application without restarting the process:

• Incoming requests wait for the new application, and the browser reloads.
• The Socket server reattaches to the new application; open connections close.
• The new application calls server/runtime.ts again, so an in-memory session store starts empty and open sessions are lost.
• If the new application cannot be created (for example, with two root layouts), Meeko logs the error and continues serving the previous one until you fix it.

When Vite restarts (after a change to an .env or a configuration dependency), meeko dev also recreates the application, with the same consequences, once the new Vite server is ready. If this coincides with creating or deleting a route, it creates only one application.

Creating, editing or deleting a .ts file in an auto-import folder (the defaults and, since 1.3, those in imports.appDirs, sharedDirs and serverDirs) rereads the auto-import registry and invalidates modules, and the browser reloads; no restart is needed. Editing an existing Socket channel, changing meeko.config.ts (including imports lists) or editing a module's setup code still requires restarting npm run dev (module runtime files, such as plugins or components, reload like project files). Types and manifests in .meeko/ are not regenerated in meeko dev: run npm run check to update them.

Vite's file watcher ignores all of .meeko/ except .meeko/generated, the entry points it serves. As a result, meeko check, the language server or a build writing to .meeko/check, routes, types, manifests, output, build or generated tsconfig.* files while meeko dev runs do not reload the browser, and Vite's dependency scanner does not enter .meeko/ either.

Server logs in the browser console#

Since 1.3, in meeko dev, anything server code writes with console.log, info, warn, error or debug while handling a request also appears in the browser console, like Nuxt's features.devLogs. The terminal still shows it as usual: logs are copied, not redirected.

• What is forwarded. Each call is associated with its request through that request's asynchronous context, so simultaneous requests do not mix their logs. Everything executed for it counts: server and route middleware, loaders, <script server>, *.server.ts plugins, rendering, SSR api.* and rpc.* clients, API and RPC handlers and the asynchronous work they start, including waitUntil. Anything written outside a request (startup, the server/runtime.ts factory, Vite, Socket callbacks) only goes to the terminal.
• How it arrives.
  • The HTML document carries its render logs in <head>, and the browser prints them on load, in practice before hydration. The two scripts Meeko adds there carry the document nonce (the 'nonce-…' in its Content-Security-Policy header or, without it, the nonce attribute of its scripts, written by DocumentOptions.nonce), so they work with a nonce-based CSP or 'strict-dynamic'.
  • With render: "stream", logs written as deferred values arrive go in the stream, after their corresponding block and always outside #app, which the browser hydrates.
  • Client navigation receives its data request's logs in the payload.
  • API and RPC request logs, and anything written after a response completes, arrive through Vite's HMR WebSocket. Since the requesting tab is unknown, they print in every open application tab, with the method, path and requestId.
• How it looks. Each request is a console group with the server badge, method, path and beginning of the requestId (from the x-request-id header), and each log has the same badge and its level (console.warn is a warning, console.error an error). Objects can be expanded as on the server: Map, Set, dates, bigint, circular references and class names. An Error shows the server stack trace, with its files and lines, and its cause. Functions, symbols and binary data display by name or description. Getters are not executed and proxies are not traversed. A value deeper than 8 levels, a collection with more than 100 items or text longer than 10,000 characters is truncated; a request with more than 500 logs, or more than 1 MB of logs, warns how many stayed only in the terminal.
• No duplicates. Each log reaches the browser once, through a single path. Meeko's existing request error report ([meeko] request error <id> and the error with its stack trace) also arrives through this path, once. With Vite's server.forwardConsole, which copies the browser console to the terminal, server logs do not return to the terminal.
• Development only. Neither console capture nor browser code exists in meeko build, meeko start or meeko preview: production HTML, payloads and bundles do not include them.
• Only for the developer's browser. Responses only carry logs if the request arrives from loopback (127.0.0.0/8 or ::1), with a loopback Host header (localhost, a .localhost subdomain, 127.x.x.x or [::1]) and without proxy headers (Forwarded, Via, X-Forwarded-*, X-Real-IP, CF-Connecting-IP, True-Client-IP and similar). The MEEKO_PUBLIC_ORIGIN host does not count as local: a tunnel or local proxy (ngrok, cloudflared, VS Code dev tunnels, Tailscale) connects from loopback and publishes exactly that name, so its visitors do not receive logs even if the tunnel rewrites Host to localhost, because it adds forwarding headers. With MEEKO_HOST=0.0.0.0 (for testing from a phone, for example), or behind a tunnel, a browser on another machine does not receive logs in its responses: its request logs print in tabs on the developer's own machine, because Meeko's HMR WebSocket only listens on 127.0.0.1. That port (MEEKO_HMR_PORT) must not be exposed through a tunnel: anyone connecting to it receives logs for all requests, like a local tab.

To disable it:

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

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

Typed href does not accept params for routes without parameters. For dynamic routes it requires the keys declared in the manifest; the runtime also checks their values and rejects extra keys.

href has two forms with the same types. href(id, options) uses the running application's manifest: on the server, the current request's manifest (SSR, loaders, head, prerendering, API, RPC and server middleware); in the browser, the one received by mountClientApp, from hydration until dispose(). This is the usual form in pages and layouts:

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

Outside an application (for example, in a unit test without an app), the short form throws an error; pass the manifest with href(routes, id, options) there, which remains unchanged.

Layers#

A layer is a project folder with the same structure as the application: its app/pages, components and auto-imports (app/components, app/composables, app/utils, app/stores, app/types, shared/ and server/utils) and, since 1.2, its app/plugins plugins. The project's imports.appDirs, sharedDirs and serverDirs folders are also searched inside each layer, using the same relative path (app/services is layers/base/app/services in the ./layers/base layer). Use layers for a shared base (design, common pages) or to split a large application into areas.

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

Source order is: the application, extends, layers, layer folders remaining in modules (see below), and layers added by modules with meeko.addLayer. Each layer needs its app/pages folder and a unique folder name containing lowercase letters, digits and hyphens; that name appears in diagnostics. Paths in layers and extends must live inside the project, including after resolving links.

Layer pages appear inside the project's shell: app/app.meeko and the application's root layout (app/layouts/default.meeko or app/pages/+layout.meeko) also wrap layer pages, and the layer's own +layout.meeko files nest inside. Since 1.5, a layer's named layouts (layers/base/app/layouts/docs.meeko) also serve pages in the project and other layers; see Layouts from layers and modules. If the project has app.meeko or a root layout, they replace the layer's equivalents; otherwise, the layer's are used. A failing layer page uses the closest +error.meeko in its own tree, then the layer's app/error.meeko and finally the project's root error page. A 404 for a URL without a route always uses the project's error page. Programmatic route modules (RouteModule.routes() from composeFrameworkRoutes) still declare their own layouts. The manifest rejects URL collisions and the registry rejects duplicate auto-import names; the diagnostic includes the conflicting files.

extends was the name of layers until 1.1 and continues working in 1.x without a warning; its folders come before those in layers.

Since 1.5, the path aliases ~/, @/, #shared/ and #server/ are searched in the project and then each layer, in this same order; see Aliases in layers.

Folders in modules (deprecated)#

Until 1.1, modules also listed folders containing app/pages, which behaved as layers. Since 1.2, modules is for modules. A modules string pointing to a folder with app/pages and no module (no package.json or index.ts) still works as a layer throughout the 1.x series, in the same position as before. meeko dev, meeko build and meeko check print once per process:

[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.

To migrate, move the string from modules to layers. A layer folder does not accept options: ["./modules/auth", { … }] is an error.

Modules#

A module configures the project through code, like Nuxt modules: it adds components, auto-imports, plugins, server middleware and handlers, <head> entries, public files and Vite plugins, and responds to build hooks. Create it with defineMeekoModule, register it in modules by name and give it options in its own meeko.config.ts key, declared by its 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' },
})

Nothing is imported: meeko.config.ts only names the modules. A string is an installed package name or a project-relative path:

• A package ('@meekojs/i18n', with or without a subpath) resolves from the project. If the package exports the ./module subpath (like @meekojs/i18n, whose root is its runtime), the module is the default export of <paquete>/module; otherwise, it is the root's default export (like @meekojs/ui).
• A path ('./modules/accent') is a file or a folder with package.json (its import/default export) or with index.ts, index.mts, index.js or index.mjs.

The default export must be the result of defineMeekoModule. Options merge as follows: the module's defaults, then config[meta.configKey]; plain objects merge deeply and arrays are replaced. Modules run in modules order, one after another (Meeko awaits each setup), then the ready hook; that order determines their plugins, middleware, <head> entries and stylesheets. Two modules with the same meta.name or meta.configKey are an error. With meta.compatibility.meeko (an npm range, such as ">=1.2" or "^1.2.0"), loading fails if the Meeko version is outside it.

Errors explain what is missing:

• An unresolved string: No se encuentra el módulo de Meeko @meekojs/i18m: no es un paquete instalado ni una ruta del proyecto. ¿Quisiste decir "@meekojs/i18n"? (or, without a similar name, how to install it).
• A package without a module: El paquete x no es un módulo de Meeko: … debe exportar por defecto defineMeekoModule(...), en su subpath ./module o en su raíz.
• The key of an installed module missing from modules, such as i18n: { … } without '@meekojs/i18n', produces warning MEEK127, which indicates the missing entry: [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"]. It is a warning rather than an error during 1.x, because that configuration loaded (ignoring the key) until 1.7. Any other unknown key produces the usual warning, with the most similar known key.

Option types without imports#

Each module's key is typed even if meeko.config.ts imports nothing, as Nuxt does with .nuxt/nuxt.d.ts. The module augments MeekoConfig with its key (declare module '@meekojs/meeko/framework' { interface MeekoConfig { readonly i18n?: I18nModuleOptions } }) and Meeko writes .meeko/types/config.d.ts, which imports types from every module in modules, so the augmentation loads automatically. It is generated by meeko dev, meeko check, meeko build and meeko routes, and also by the language server in a trusted workspace when opening the project, before the first generation (it only reads modules strings, without executing anything).

• meeko check checks meeko.config.ts with those types (since 1.8; previously only when loading failed): i18n: { defaultLocale: 1 } produces TS2322 with its line and column. So does meeko build, which runs the same checks.

• The editor types the file through .meeko/tsconfig.config.json, referenced by the tsconfig.json created by meeko init. In a project predating 1.8, add { "path": "./.meeko/tsconfig.config.json" } to references. With it, the editor completes and documents the key (i18n, ui) and marks incorrectly typed options.

• Name completion. Inside modules: ['…'], the editor offers installed packages that are modules: dependencies from the project's package.json with the meeko-module keyword in their own ("keywords": ["meeko-module"]), plus those already listed. A published module must declare it. Any other string remains valid.

• Module-generated types. Declarations written by a module with meeko.addTypeTemplate (in .meeko/types/modules/, linked by .meeko/types/modules.d.ts) also type meeko.config.ts in meeko check and the editor. This lets a module type its options with what it discovers when running: @meekojs/icon generates the union of available icon names, and icon: { include: ['lucide:chek'] } produces TS2820 with the suggestion "lucide:check". meeko check runs modules before checking configuration, so the union is up to date.

The official modules @meekojs/ui, @meekojs/i18n and @meekojs/icon (Iconify icons resolved at compile time, with <UIIcon>; see its guide) register this way.

Registration forms from before 1.8 continue working during 1.x with warning MEEK126, which indicates their replacement string and key; see Upgrade from 1.7 to 1.8.

Write a module#

setup runs in Node, once per configuration and process, when loading configuration: in meeko dev, meeko build, meeko check and the language server of a trusted workspace. It never reaches the browser. It receives the merged options and the meeko object. Paths received by meeko can be absolute, file: URLs (new URL("./x", import.meta.url), typical in a package) or relative to the project root.

An accent color module, chosen by the user and applied before rendering (no module is needed for light/dark themes: Meeko includes them since 1.4, see Light/dark theme without a flash):

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

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

export interface AccentOptions {
	initial: Accent
	storageKey: string
}

// Types the `accent` key in 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 /> in any component, without an import.
		meeko.addComponentsDir(here('./components'), { prefix: 'Accent' })
		// useAccent() without an import, in components and app/.
		meeko.addAutoImports({ name: 'useAccent', from: here('./runtime/use-accent.ts') })
		// Expose the accent signal before hydration; options are passed to the plugin.
		meeko.addPlugin({ src: here('./runtime/accent.plugin.ts'), options: { initial: options.initial, storageKey: options.storageKey } })
		// Apply the saved accent before painting, without flicker.
		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) => {
	// The same initial value on the server and in the browser, so hydration matches.
	const accent = signal(options.initial)
	app.provide(accentKey, accent)
	if (app.side === 'client') {
		let first = true
		effect(() => {
			const value = accent.value
			// The <head> script has already applied the saved accent; each subsequent change is applied and saved.
			if (first) {
				first = false
				return
			}
			document.documentElement.dataset.accent = value
			localStorage.setItem(options.storageKey, value)
		})
	}
})

An SEO module generates sitemap.xml from routes, and 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`)
		// A function is evaluated when writing the build (and on each request in dev), with routes already discovered.
		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'),
		)
	},
})

A module's runtime files (plugins, components, auto-imports, middleware and handlers) are processed by Vite like project files, but outside application folders they receive no auto-imports: import them explicitly. .meeko components from addComponentsDir do receive the project's auto-imports.

The meeko object#

A custom Vite host that only uses the meeko() plugin receives module auto-imports, components, layers and application plugins, but not their addVitePlugin, extendViteConfig, public files or hooks: those are applied by meeko dev and meeko build.

Meeko has no separate runtimeConfig: a module passes values to its runtime through addPlugin options (public if the plugin reaches the browser), and secrets are read on the server from environment variables or server/runtime.ts.

Hooks#

Hooks run in registration order, and Meeko awaits each one. hook() returns a function that removes it.

Application plugins#

Files in app/plugins (in the application and its layers) and those added by modules run when the application starts. Each one exports definePlugin by default:

// 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))
})

• Where. *.client.ts only in the browser, once, before hydration. *.server.ts only on the server, once per page request, before rendering (also during prerendering; not on already prerendered pages, or in API, RPC or handlers). An unsuffixed .ts runs in both. Only files directly inside app/plugins count; subfolders can hold their helpers. *.test.ts, *.spec.ts and *.d.ts are excluded.
• Order. Module plugins, in the order they are added; then each layer's and the application's, by filename. Meeko awaits each setup, which can be asynchronous.
• app.provide(key, value). Publishes a value for all application components, which read it with inject(key) (and any composable wrapping it): pages, layouts, app.meeko, the error page and pages navigated to in the browser. On the server, the value belongs to that request: do not share mutable state between requests. A hydrating component must receive the same value on the server and in the browser; that is why rendered values usually come from a universal plugin.
• app.onError(handler). In the browser, the observer receives the same as mountClientApp({ onError }) (navigation, Socket and events, effects and cleanups without a closer provideErrorHandler and, since 1.3, the page's global exceptions and rejections; see Errors), with { side: "client", source }. On the server, it receives that request's render failures with { side: "server", requestId }, in addition to onError in server/runtime.ts.
• app.resolveLink(resolver). Since 1.8, receives every <MeekoLink> in the application ({ to, href, hreflang }: the route ID, the href built by href() and the link's hreflang) and returns its final href; aria-current is computed from that href. Multiple resolvers are chained in plugin order. It runs when the link renders on the server, during hydration and during client navigation, so it must be pure: the same link produces the same href on both sides. @meekojs/i18n uses it for the language prefix; see <MeekoLink>.
• app.route. The route, like useRoute(). On the server it is the request's route; in the browser it follows the confirmed route, so an effect that reads it reruns on navigation. app.request is the request on the server and undefined in the browser; app.side tells you where it runs.
• Failures. A plugin throwing on the server fails the request, which shows the error page without plugin values. In the browser, hydration never starts and the page keeps the server HTML.

A custom host passes plugins to mountClientApp({ plugins }) and createServerApp({ plugins }) or createFrameworkHandler({ plugins }) as PluginRegistrations ({ plugin, options?, name? }).

Server and client boundaries#

A module's setup and its entry point never reach the browser bundle, nor do its "server" plugins, middleware, handlers, auto-import folders with scope: "server" or *.server.ts files in module folders. Meeko's Vite plugin rejects the build if the client graph reaches them (Server-only module reached the client bundle), or if a file loaded by the browser imports defineMeekoModule (Meeko module setup reached the client bundle): only meeko.config.ts should import modules. Options for a plugin that runs in the browser do travel in the client bundle.

Route and server middleware#

Put route middleware in app/middleware/*.ts (including subfolders). Each file exports by default a function created with defineRouteMiddleware from @meekojs/meeko/framework (automatically imported). It runs before the sidecar and loader, both for an SSR page request and client navigation. The context provides url, match, signal and phase; request only exists during SSR. Returning undefined continues; returning a Response stops the route. An HTTP redirect during client navigation uses location.assign, making a new page request. A non-redirect response cancels navigation and reports the error to the host's onNavigationError callback. Without a callback, click or history navigation failures appear in the console; if the callback fails, Meeko logs that failure without creating an unobserved rejection. When a history navigation is blocked or fails, Meeko restores the URL of the page still visible. A direct app.navigate() call returns its rejection to its caller.

There are two kinds of route middleware:

• Global (the original kind, without options): runs on every route, by filename. match.route.id lets you restrict it to specific routes.
• Named (since 1.6): defineRouteMiddleware(fn, { global: false }). It only runs on routes that request it through middleware in definePage or a +group.ts.

Both also have server-only versions in app/middleware/*.server.ts with defineServerRouteMiddleware (since 1.6): see Server route middleware.

// app/middleware/10-locale.ts: global, on all routes
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)
	}
})

Named middleware#

Declare a guard affecting only part of the application as named middleware, requested by the routes that need it, without comparing match.route.id or file paths:

// app/middleware/auth.ts
export default defineRouteMiddleware(
	({ url, phase, request }) => {
		// A public cookie indicating the session: Meeko's session cookie is 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: all pages in the group
export default defineGroup({ layout: 'dashboard', middleware: ['auth'] })

<!-- app/pages/(dashboard)/admin/users.meeko: the page adds its own -->
<script
	server
	lang="ts"
>
	export const route = definePage({ middleware: ['admin'] })
</script>
<template><h1>Users</h1></template>

• Name. The file path inside app/middleware, without .ts or each part's numeric ordering prefix: auth.ts and 10-auth.ts are "auth", and admin/20-role.ts is "admin/role". Letters, digits, - and _, and / between folders. Two files producing the same name, if either is named middleware, stop discovery.
• Inheritance. middleware accumulates from outside inward: outer +group.ts files, inner ones and the page, without duplicates (the first occurrence counts). middleware: false in a group or page removes inherited middleware; inner groups and the page can add it again. middleware: [] changes nothing.
• Order. First all globals, in their usual order; then the route's middleware in declared order. The first to return a Response stops the route, and subsequent middleware does not run. The contract is the same in SSR, browser navigation, render: "client", prerendering and the static adapter.
• Literals. Like render and layout, Meeko reads it without executing the file: { global: false } must be an object literal with the literal true or false, and middleware a literal array of strings or false. A computed value produces las opciones de defineRouteMiddleware deben ser un objeto literal… or middleware debe ser un array literal…, with the file. A spread in page options that may contain middleware (an imported object, or a file-local constant containing it) requires declaring middleware after the last spread: definePage({ ...protegida, render: "ssr", middleware: ["auth"] }), or middleware: [] if adding none. Otherwise discovery stops with el spread protegida puede llevar middleware…, because the route would be served without it. If a page declares middleware absent from its manifest (an old build), the request fails with 500 before the loader, as with layout.
• Errors. They stop meeko dev, meeko build and meeko check, with the file declaring the name: 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… and, for a global, el middleware "locale" (…/10-locale.ts) es global y ya se ejecuta en todas las rutas.
• Types and editor. middleware is typed with the union of named middleware (RouteMiddlewareName, declared by .meeko/types/routes.d.ts), with editor completion. In an application without named middleware, the union is empty (never), so middleware: ["typo"] is already a type error. Hovering over a name in definePage shows its file and pages, and Ctrl+click opens it.
• Bundle. Globals travel with the browser entry point. Each named middleware used by a route is a separate chunk, loaded by the browser the first time it navigates to one of its routes; middleware used by no route never reaches the browser. Hydration does not run them: the server already did.
• Manifest. Each route stores its resolved named middleware in RouteRecord.middleware (files, in execution order); AppManifest.routeMiddleware still lists only globals. A custom host using createFrameworkHandler or mountClientApp with routes declaring them passes loadNamedMiddleware(file); without it, those routes fail instead of skipping their guards. discoverRouteMiddleware from @meekojs/meeko/build separates globals from named middleware.
• Development. Creating, deleting or renaming middleware, changing its { global } or the middleware of a page or +group.ts makes meeko dev rediscover routes and recreate the application.
• Layers and modules. As before, only the project's app/middleware counts: layer pages choose from the project's named middleware, and modules do not add route middleware.

app/middleware/*.ts is also bundled for the browser, including named middleware: do not import server/, secrets or authorization logic that must be enforced on the server there. An isomorphic route guard, global or named, improves navigation but never replaces session validation and authorization in the loader, API or RPC; to protect a page with the session, use server route middleware. *.test.ts, *.spec.ts, *.d.ts and *.client.ts files are excluded from route middleware discovery; since 1.6, *.server.ts files are server route middleware.

Server route middleware#

Since 1.6, an app/middleware/*.server.ts file is server-only route middleware: declare it with defineServerRouteMiddleware (from @meekojs/meeko/framework; automatically imported in *.server.ts and throughout server/, like other server definitions), and it receives the request's session and never reaches the browser bundle. It expresses “this group requires a session” without repeating the check in every page's <script server>:

// 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: all pages in the group require a session
export default defineGroup({ layout: 'dashboard', middleware: ['auth'] })

• Global or named. The same rule as isomorphic middleware: without options it is global and runs on every route; with { global: false } (read without executing the file), it is named middleware, and auth.server.ts (or 10-auth.server.ts) is "auth". middleware: ["auth"] in definePage or a +group.ts resolves to auth.ts or auth.server.ts, with the same inheritance and middleware: false; if both exist and either is named, the name is duplicated and discovery stops. The default export of a *.server.ts must be a call to defineServerRouteMiddleware(...), directly or through a file-local constant (including as const), an aliased import or export { auth as default }. Until 1.5, those files were ignored, so a helper living there without a default export or with another one (export default function parseCookies…) stops discovery with un middleware de ruta de servidor debe exportar por defecto defineServerRouteMiddleware(...)… mueve los helpers a server/utils instead of running on each request as global middleware. Each file kind uses its own definition: defineRouteMiddleware in a *.server.ts, or defineServerRouteMiddleware in a *.ts, is an error identifying the file.
• Context. The same as usePage() in <script server>: url, params, search, request, signal and context (the RequestContext), with session, services, platform and requestId readily available, plus match. The client IP, behind the proxy if MEEKO_TRUST_PROXY allows it, is context.clientAddress. params and search come from the URL and are not yet validated with page schemas, because middleware runs before its <script server> or load. defineServerRouteMiddleware<Services> types services, and session follows MeekoSession. With createFrameworkHandler without createContext, reading context or session throws an error.
• How it stops execution. Like <script server>: redirect(), notFound() or an error, and also returning a Response. Returning undefined continues.
• When it runs. On the document request (SSR), and during browser navigation within the page data request, the same one that executes <script server>: a redirect or error reaches the browser just like one from a <script server> redirect(), and navigation follows it. In render: "stream", before the first byte, like the critical loader.
• Order. Always the same: first isomorphic middleware (globals, then named middleware in declared order), then server middleware (globals, then named middleware in declared order). During navigation, the browser runs isomorphic middleware and the data request runs it again on the server before server middleware, as before. The first to stop execution stops the route.
• render: "client" and render: "prerender". A render: "client" page does not request its data from the server during navigation, and a prerendered page renders at build time, without each visitor's request or session. Requesting named server middleware on either (including inherited middleware from a +group.ts) stops discovery: el middleware de servidor "auth" (…) necesita una página con datos del servidor, pero … usa render: "client"…; remove it from that page with middleware: false or use render: "ssr" or "stream". Global server middleware does not run on these pages, even on their first load, so behavior does not depend on how you reached them. The static adapter, which only supports prerendered pages, warns that it does not run them.
• Security boundary. The Vite plugin rejects any *.server.* reaching the browser graph, and the client middleware virtual module never includes these files; the browser manifest does not carry their paths either. They can import server/ and #server/… without MEEK108, and meeko check checks them with server types.
• Types and editor. RouteMiddlewareName includes their names, except in the middleware of a render: "client" page, which only accepts isomorphic middleware; hovering over a name in definePage or defineGroup shows the file, marks it as “server-only” and shows its pages. A nonexistent or global name produces the same errors in meeko dev, meeko build and meeko check.
• Manifest and custom host. Each route stores its complete server chain in RouteRecord.serverMiddleware, in execution order: globals, then named middleware (render: "client" and "prerender" routes do not have it). A custom host using createFrameworkHandler passes loadServerMiddleware(file), which loads each listed file; without it, a route listing any, even just a global, fails instead of skipping it. Routes from a programmatic composeFrameworkRoutes module also receive the project's globals.
• Development. Creating or deleting one, or changing its { global }, makes meeko dev rediscover routes.

When to use each kind:

• Isomorphic middleware (*.ts) improves navigation: it decides in the browser, without a request, and redirects before requesting anything. It cannot read the session (its cookie is HttpOnly) or import server code.
• Server middleware (*.server.ts) protects the page: it checks the session before the server renders or sends its data.
• Neither protects server/api or RPC. Route middleware only runs for pages: API endpoints and RPC procedures need their own guards (auth: "required", handler checks or server middleware), even if only protected pages call them.

Server middleware#

To intercept HTTP on the server before the page or API/RPC handler, put middleware in server/middleware/*.ts and use defineServerMiddleware from @meekojs/meeko/server. It receives Request and next(request); it must return a Response. It can continue, modify a response or short-circuit. Meeko executes files by name, from outside inward; next() can only be called once. Middleware runs before creating the request's session context, including for prerendered pages; public build files are served before middleware. Built-in API/RPC authentication, authorization, contract and CSRF checks still run inside the 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,
	})
})

Server middleware has no RequestContext: for the client IP, use clientAddress(request) (since 1.7), which applies MEEKO_TRUST_PROXY like context.clientAddress and rateLimit; never read X-Forwarded-For manually (see Client IP behind a proxy).

This pipeline wraps SSR pages, /api and /_meeko/rpc; static assets, the Vite development server and WebSocket upgrades have their own handlers. *.test.ts, *.spec.ts, *.d.ts and *.client.ts files are excluded. Automatic middleware discovery is currently limited to the root project: layers contribute routes, auto-imports and plugins, but their app/middleware and server/middleware folders do not participate. A module adds server middleware with meeko.addServerMiddleware, which runs before the project's middleware (see Modules). Editing an existing middleware file invalidates modules and reloads the browser during development; when you add or remove one, meeko dev recreates the application without restarting (see Configuration). npm run check checks types in their respective scopes.

onNavigationError callbacks can return a promise: if the observer fails, Meeko logs both the observer failure and the original navigation error without generating an unhandled rejection. Server onError observers also do not change the response when they throw or reject; fallback logging includes the available requestId and error categories, without private messages.

Component events can be observed per root with provideErrorHandler in the <script> of app/app.meeko or a layout; it is automatically imported, and the callback receives unknown and its ErrorSource. Children inherit the closest observer, including after an HMR replacement. mountClientApp({ onError }) defines the application-wide observer: it receives navigation, Socket channels, events, effects and cleanups without a closer provideErrorHandler and, since 1.3, the page's uncaught exceptions and unhandled promise rejections (Global browser failures). Without onError, navigation, Socket and those global failures consult the application's first active provider when there is no explicit onNavigationError or channel onError. That provider is unregistered when its root is disposed; an observer failure is logged with the original error. Direct calls to app.navigate() and socket.emit() keep their rejections for the code awaiting them. SSR has no browser events or Socket connections.

If server middleware calls next(), Meeko also awaits that work even if the middleware forgets to await the promise. A downstream failure propagates to the HTTP handler; if both fail, each error is preserved in an AggregateError. Middleware must return a pipeline response or its own response.

Routing, layouts and SSR#

app/pages supports index.meeko, [id].meeko, [...slug].meeko, (group) groups, +error.meeko and, for route options, a <script server> block in the page or a *.route.ts sidecar. The shared layout lives in app/layouts/default.meeko and receives props.outlet; the browser preserves it between routes and disposes of outgoing pages. Since 1.5, any app/layouts/<nombre>.meeko is a named layout that the page selects with definePage({ layout }) or a +group.ts. +layout.meeko files alongside pages remain supported for older projects and nested layouts; you cannot combine one at the root of app/pages with app/layouts/default.meeko. A layer uses the same conventions. href checks IDs and parameters against the generated manifest.

The outlet type in app/app.meeko and each layout is Component<Record<string, unknown>>, imported from @meekojs/meeko. It includes renderWithState, required by <component is="props.outlet"> to transfer SSR state.

<MeekoOutlet /> and <MeekoLink>#

Since 1.2, two built-in Meeko tags replace these patterns. You do not import them: the compiler recognizes them.

• <MeekoOutlet /> renders the inner layout or page in app/app.meeko and layouts (app/layouts/*.meeko or +layout.meeko). It reads the outlet Meeko passes, so the layout does not need to declare defineProps<{ outlet }>(). Up to 1.4, if it declared props, outlet had to be among them; since 1.5, a layout with <MeekoOutlet /> declares only its own (defineProps<{ title?: string }>()) and Meeko adds outlet to its ComponentProps. It is equivalent to <component is="props.outlet">: the browser preserves the layout between routes and only changes its contents. In another component, or with attributes or content, it produces MEEK104.
• <MeekoLink to="/users/[id]" bind:params="{ id: user.id }" bind:search="{ tab: 'perfil' }"> renders an <a> whose href is built by href(): to only accepts existing routes, dynamic routes require bind:params with their keys, and bind:search adds the query string. meeko check and the editor flag the error on the attribute (Argument of type '"/nowhere"' is not assignable…). On the active route (the same path without query or fragment), it adds aria-current="page", which navigation updates; with match="prefix", it also marks its section (see below). Other attributes and children pass through to the <a> unchanged: class, target, rel, aria-*, data-* and on:click. href and bind:href are not supported, because to builds the link (MEEK105).
• match: page or section. Since 1.5, match="exact" (the default) marks the link only on its own route, and match="prefix" also on routes below it. On its own route, the link has aria-current="page"; on a route below it, aria-current="true", meaning “the current item in a set”: the section containing the page. Comparison uses complete segments, on paths encoded as by href(), without query or fragment: /dashboard covers /dashboard/stats and /dashboard/r%201, but not /dashboards; /dash does not cover /dashboard. to="/" only matches exactly, even with match="prefix", since otherwise it would mark every page. On a dynamic route, the section follows its params: <MeekoLink to="/users/[id]" bind:params="{ id: '7' }" match="prefix"> covers /users/7/posts, not /users/8/posts. match supports bind:match with an expression of type "exact" | "prefix"; another static value produces MEEK105. The value appears in the server HTML, hydration leaves it unchanged, and navigation updates it, including in a layout the browser preserves.
• Link resolvers: language and other prefixes. Since 1.8, the href passes through the resolvers that plugins and modules register with app.resolveLink. With @meekojs/i18n, <MeekoLink to="/guide"> points to /en/guide on an /en/… page and to /guide in the default language, without writing the prefix; hreflang="es" (or bind:hreflang, or the hreflang key of bind) forces another language and is also kept on the <a>. bind:resolve="false" leaves the href from href() as is, for a link that must not change; a static resolve="false" is MEEK105. The typing of to, params and search, aria-current (with the resolved href, so /guide is active on /en/guide) and client navigation do not change. Without resolvers, the href is the one from href().

<!-- /en/guide on an /en/… page, /guide in the default language -->
<MeekoLink to="/guide">Guide</MeekoLink>
<!-- /guide in any language -->
<MeekoLink
	to="/guide"
	hreflang="es"
>
	Spanish version
</MeekoLink>
<MeekoLink
	to="/admin"
	bind:resolve="false"
>
	Administration
</MeekoLink>

• Prop types. Since 1.4, @meekojs/meeko/framework exports MeekoLinkProps<K> (to, params and search for route K; since 1.5, also match, and since 1.8, resolve), MeekoOutletProps (no props) and MeekoThemeToggleProps (the props of <MeekoThemeToggle>), plus RouteId, the ID of any application route (the type of to). All are auto-imported: prop types where the components are used, like component types, and RouteId throughout the project, like href. The editor shows props on tag hover and opens their type with “Go to definition”. You can use them to type a component that receives a route, without an 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"] and RouteId are the same type: the union of routes declared by .meeko/types/routes.d.ts (meeko check, meeko dev), or string without those declarations. <NavLink href="/nowhere"> is a type error in the parent. A project type with one of those names (for example, in app/types) takes priority.

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

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

A section menu marks the section on all its pages and marks the exact page differently. CSS distinguishes the two aria-current values, the same ones screen readers read:

<!-- app/layouts/default.meeko -->
<template>
	<nav aria-label="Secciones">
		<MeekoLink
			to="/"
			match="prefix"
		>
			Home
		</MeekoLink>
		<MeekoLink
			to="/dashboard"
			match="prefix"
		>
			Dashboard
		</MeekoLink>
		<MeekoLink
			to="/users"
			match="prefix"
		>
			Users
		</MeekoLink>
		<MeekoLink
			to="/settings"
			match="prefix"
		>
			Settings
		</MeekoLink>
	</nav>
	<main><MeekoOutlet /></main>
</template>

<style scoped>
	/* The current page section: /dashboard/stats marks “Dashboard”. */
	nav a[aria-current='true'] {
		border-bottom: 2px solid currentColor;
	}
	/* The exact page: /dashboard marks “Dashboard” with a heavier weight. */
	nav a[aria-current='page'] {
		border-bottom: 2px solid currentColor;
		font-weight: 700;
	}
</style>

On /dashboard/stats, “Panel” has aria-current="true"; on /dashboard, aria-current="page"; on /dashboards, neither, and “Inicio” is only marked on /. For your own link or component, useRoute().isActive() applies the same rule (see Current route).

In the editor, to=" suggests project routes and takes you to their page with Ctrl+click. meeko init-framework generates the shell and layout with these tags.

A project from before 1.2 with its own component named MeekoLink or MeekoOutlet (in app/components, from a module, or imported or declared in <script>) keeps it: the tag is that component, with its props, rather than Meeko's tag. meeko check, meeko build and the editor warn with MEEK106; rename the component to use the built-in tag.

<MeekoTeleport>#

Since 1.5, <MeekoTeleport to="…"> renders its content elsewhere in the document while keeping it within the component that declares it. You do not import it either. A typical case is a page putting its actions in its layout's toolbar:

<!-- app/layouts/default.meeko -->
<template>
	<header class="bar">
		<MeekoLink to="/">Home</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">Save</AppButton>
	</MeekoTeleport>
	<article>…</article>
</template>

• Target. to="body" appends the content to <body> and to="#id" inserts it inside the element with that id, after its existing content. Only these two forms are supported: body, or # followed by a letter and ASCII letters, digits, - or _. Meeko looks up the id with getElementById and never interprets to as a CSS selector or HTML. A static to that does not match this form produces MEEK114; bind:to accepts an expression of type "body" | `#${string}` (MeekoTeleportTarget), validated at render time. <MeekoTeleport> supports to, bind:to, disabled, bind:disabled, if:when and each:of; any other attribute produces MEEK114.
• Author scope. The content compiles in the declaring component's template, like the content of an if:when: it reads its signals, its events call its functions, it receives its provide/inject and error handlers, can use its snippets, and retains its <style scoped> attribute. It is disposed of with the component: on unmount, on page changes, or when its if:when or each:of row disappears, its nodes leave the target too.
• Initial HTML. In SSR, "stream" and "prerender" (including the static adapter), the HTML already contains the content at its target, without shifts during hydration: to="body" content goes after the application and before Meeko's scripts; to="#id" content goes inside that element, whether it renders before or after the teleport. Multiple teleports to the same target retain their order on the page. Hydration finds the content by its markers (<!--meeko:portal:…-->) and leaves the DOM unchanged.
• Missing target. If the page does not render the #id element (or it is a void element such as <input>), rendering fails with a clear error in development. In production, the content renders in place, where it hydrates, and the server warns once with console.warn. In the browser, a missing target leaves content in place with a warning; the next change to to or disabled looks it up again.
• disabled. With disabled (or while bind:disabled is true), content renders in place. Changing it moves the same nodes between the target and their original position without rerendering, so they retain their state; the focused element loses focus, as with any DOM move.
• Browser. Content rendered by the browser (navigation, an appearing if:when, a new row or a deferred child) first renders in place and moves to its target at the end of that mount, before the next paint, appending to the target. The target must live at least as long as the teleport: a layout or app/app.meeko element for a page, or an element of the component itself.

Modals, menus and tooltips do not need a teleport: <dialog> with showModal() and the popover attribute already show them in the browser's top layer, above everything and without z-index or overflow issues, handling focus and Escape. Use <MeekoTeleport> when content must live elsewhere in the layout, such as an action bar, breadcrumbs or a notice at the end of <body>.

Pages, layouts, app/app.meeko and app/error.meeko cannot be generic components: Meeko passes their props and cannot choose their type parameters, so generic on their <script> produces MEEK100. Move generic content into an app/components component and use it from the page.

If a page fails and +error.meeko exists, Meeko loads and renders it with the same request context and SSR state. The server observer receives the original failure with its requestId; the HTML shows a public message without private details. If the error page also fails, the server logs that second failure and returns a safe response.

Named layouts#

Since 1.5, each app/layouts/<nombre>.meeko is a named layout: default, dashboard, auth, blank… A subfolder forms part of the name: app/layouts/admin/panel.meeko is "admin/panel". The name contains letters, digits, - and _ (and / between folders), starting with a letter or digit; a file with another name (_partes.meeko) is not a layout and can hold other components. A named layout is a normal layout: it renders the page with <MeekoOutlet /> and declares its props with defineProps.

The page selects its layout in its route options, in <script server> or the *.route.ts sidecar:

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

• Without layout, the page uses the layout inherited from its folders' +group.ts files or, if none, default, as up to 1.4.
• layout: false removes the named layout: app/app.meeko and its folders' +layout.meeko files remain.
• A literal. Like render, meeko build reads layout without executing the file: it must be a string literal or false inside definePage({ ... }). A computed value produces layout debe ser un literal de texto… with the file. A nonexistent name stops meeko dev, meeko build and meeko check: el layout "nowhere" no existe; crea app/layouts/nowhere.meeko (layouts disponibles: …). In types, layout is the union of application layouts, with editor completion; hovering the name shows its file and pages, and Ctrl+click opens it.
• Nesting order. app/app.meeko → named layout → folder and group +layout.meeko files, from outermost to innermost → page. (group) groups and +layout.meeko files work as before, inside the named layout. Having both app/pages/+layout.meeko and app/layouts/default.meeko remains an error; an app/pages/+layout.meeko without default nests inside the named layout the page selects.

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

Navigation. The browser preserves layouts shared by the outgoing and incoming pages, as always: if both use the same named layout, it stays mounted with its state (DOM, focus, sidebar scroll, text entered in a field) and only its contents change; if they use different layouts, the old one is disposed of and the new one mounts. This works equally for SSR, render: "stream", render: "client", prerendered pages and the static adapter.

Error page. A page that fails in the browser (its loader, notFound() or data) shows its +error.meeko or app/error.meeko inside its own layouts, including the named layout, with its +group.ts props and without the page's props. The 404 for an unmatched URL uses the default layout (if present), with its default values. Since 1.8, a page that responds 404 on the server (notFound() or an ApiError with that status) gives the same document, which hydrates; with a nearer +error.meeko, that page goes inside the page's layouts, without hydration. If a layout fails while painting it, or the error is another one, the error document has no layouts, because a layout may be what failed.

Per-folder options: +group.ts#

To avoid repeating layout on each page, a +group.ts in any app/pages folder (a (dashboard) group or a normal folder) declares options for that folder and its subfolders. defineGroup is auto-imported:

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

• Cascading inheritance. +group.ts files apply from outermost to innermost, then the page. The page's layout, or that of the innermost group declaring it, wins.
• layoutProps merge by key between groups and the page, with the page winning. A group or page selecting a different layout from the inherited one starts without inherited props, which belonged to another layout.
• layout: false on a page (or group) inside a group removes the named layout and keeps its +layout.meeko files.
• Literals. Meeko reads the file without executing it, like render: layout is a literal or false, layoutProps is an object literal of strings, numbers, booleans, null, arrays and objects, and middleware is an array literal of strings or false. A computed value, spread or unknown option stops discovery, naming the file. This is why it works equally in prerendering and a static site.
• middleware (since 1.6). Named middleware for the group's pages, added to outer groups' middleware; middleware: false removes inherited middleware. See Named middleware.
• Types. defineGroup({ layout: "dashboard", layoutProps: { … } }) checks layoutProps against that layout in the file itself. A group inheriting its layout, and a page not selecting one in definePage, are checked by meeko check against the inherited layout (MEEK_PAGE_LAYOUT_PROPS: Las layoutProps de app/pages/(dashboard)/reports/+group.ts no coinciden con las props del layout dashboard). A +group.ts outside app/pages configures nothing: meeko check warns with MEEK115.

To migrate a group with its own layout, such as app/pages/(dashboard)/+layout.meeko, move the file to app/layouts/dashboard.meeko and add app/pages/(dashboard)/+group.ts with export default defineGroup({ layout: "dashboard" }). The layout now replaces default rather than nesting inside it, and any page in another folder can select it; remaining subfolder +layout.meeko files still nest inside.

Layouts from layers and modules#

A layer contributes its app/layouts/*.meeko to the entire application, and a module contributes its layouts with meeko.addLayout(name, file) (see The meeko object). When two layouts have the same name, the project wins, then the page's own layer, then other layers in order, and finally modules; two modules with the same name are an error. default keeps the 1.4 rule: the project's layout also wraps layer pages; a layer's default only wraps its own pages when the project has none (nor app/pages/+layout.meeko), and a module's is used when neither project nor layer has one.

Layout props from the page#

The layout declares normal props. The page passes them, checked against the selected layout's Props, excluding 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>

Because Meeko renders the layout without props a page does not pass, named layout props must be optional or have default values; meeko check verifies this (MEEK_LAYOUT_PROPS).

1. With route options (layoutProps). Static or calculated from server data, like head: they reach the SSR HTML from the first byte.

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

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

With top-level code in <script server>, write the props as one more export. Since 1.8, export const layoutProps is typed by its own values and checked against the layout; like head, it does not reach the page, so data that only the layout reads travels once, unless you also export it separately:

<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>

Exporting it and also declaring route.layoutProps is MEEK072.

The function receives the same context as head (params, search, request, context, signal, state and data); with top-level code in <script server>, data contains its exports, typed since 1.8 when the options are an object literal without a spread. They merge with +group.ts props and take priority. They travel in the payload (layoutProps), so they must be JSON-serializable: an undefined prop ({ title: data.user?.name } without a user, or layout.set({ title: undefined })) leaves the prop unset, so the layout uses its default value on both server and browser; a value JSON cannot represent (a date, a Map, an instance) fails the page with an error naming the page, layout and prop. On a render: "client" page, the object already reaches the server HTML and the function runs in the browser after load. export const layoutProps in <script server> is not an option: it would be another page data field.

2. From the page's <script>: useLayout(). It is auto-imported and, in a page, its type follows the layout selected by its definePage or +group.ts files (in another component, useLayout<"dashboard">()):

<!-- app/pages/connections.meeko -->
<script lang="ts">
	const layout = useLayout() // LayoutHandle for "dashboard"
	const failing = signal(false)
	effect(() => layout.set({ showAlert: failing.value }))
</script>
<template>
	<p>Current title: {layout.props.title}</p>
	<button on:click="() => failing.value = !failing.value">Test connection</button>
</template>

• layout.set(patch) changes the named props and preserves the others; layout.props reads the props the layout receives (reactive); layout.name is the layout's name. A prop the layout does not declare, or with another type, is a type error.
• The layout does not remount: with 1.2 reactive props, only what reads those props changes.
• Nothing carries over. On navigation to another page, the layout receives the new page's props (its layoutProps, those of its +group.ts files and, for the rest, the layout's default values), even if the layout is preserved. A page that has already left cannot write.
• SSR without mismatches. The layout renders before the page, so what the page setup writes with set during rendering reaches the HTML through a second server render of the page (with the same request state and data, like an await pass), and the payload contains those props: the browser hydrates exactly that HTML. A render writing different values each time stops on the third pass. In the browser, what the page writes while rendering and hydrating applies when mounting finishes; afterwards, each set applies immediately.
• A page without a named layout (layout: false) receives a useLayout() that does nothing. Outside a page rendered by Meeko (a unit test), useLayout() throws an error.

Markup in layout areas. Props are for data. To put page content in a layout area (header buttons, breadcrumbs), use <MeekoTeleport>, which moves page markup to a layout target.

Types. .meeko/types/routes.d.ts declares GeneratedLayouts (each layout's props) and GeneratedPageLayouts (each route's layout). LayoutProps<"dashboard"> (auto-imported) is the type of props a page can pass to dashboard; LayoutName is the union of names, and PageLayout<"/connections"> is a route's layout.

Comparison with Nuxt. In Nuxt, definePageMeta({ layout: "dashboard" }) selects the layout, but there is no typed way to pass it props: you resort to useState, provide/inject or route.meta (such as a showAlert in meta), without checking against the layout's types and with state that can carry over from the previous page. In Meeko, layout and layoutProps are checked against the layout's Props, reach the server HTML, useLayout() changes them reactively, and each navigation resets to the new page's props.

Application error page (app/error.meeko)#

app/error.meeko, alongside app/app.meeko, is the application-wide error page. It receives the same props as +error.meeko, { status: number; message: string }, and meeko check checks them in the same way. It is used in two cases:

• Unmatched URL. A page request (GET or HEAD with accept: text/html, or navigation with accept: application/meeko+json) responds 404 with app/error.meeko inside the root layouts: app/app.meeko and app/layouts/default.meeko (or app/pages/+layout.meeko). The props are { status: 404, message: "NOT_FOUND" }. Like a route's error page, the document is titled Error (<title> in SSR and document.title when navigating to an unmatched URL). The document includes the hydration payload, so the browser hydrates it and subsequent navigation works. In the browser, a link or navigate() to an unmatched URL loads the document: that URL may belong to server middleware, a file or a redirect, and checking it first with fetch would run a GET with side effects twice. If nothing else handles it, the server responds with app/error.meeko. For the same reason, returning through history to an unmatched entry reloads the document; navigation from the 404 page to application routes is client-side.
• Failed page. The nearest +error.meeko still takes priority; if none exists, app/error.meeko is used. The same applies to a render: "client" route's browser loader.

/api/..., /_meeko/..., assets and non-page requests keep their 404 responses (JSON or text). Without app/error.meeko, nothing changes: an unmatched URL responds 404 in plain text and the browser reloads the document. app/error.meeko and app/pages/+error.meeko would define the same level, so having both is a discovery error. In a layer or module, app/error.meeko backs up its own pages; the 404 uses the project's page. A custom host passes the page through errorPage to createFrameworkHandler and mountClientApp (AppManifest.errorPage in createServerApp).

Page server code#

A page declares its server code in a <script server lang="ts"> block inside the .meeko file itself, so app/pages contains only .meeko files. The block supports two forms. They can coexist in the same block, except load, which cannot be combined with top-level code:

• Top-level code (since 1.1). The block is normal server code: it reads the request, queries the database, redirects or responds 404, and each export const is page data that reaches <script> and the template with its type.
• Route options. export const route = definePage({ params, search, render, prerenderEntries, load, head }), the 1.0 form, still works unchanged; since 1.5, also layout and layoutProps (see Named layouts), and since 1.7, sitemapEntries (see Dynamic routes in the sitemap).

Top-level code and exported data#

<!-- 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() // the current request, typed by route.params
	if (!context.session.current) redirect('/login')
	const row = await db.users.findById(params.id) // db: an auto-import from server/utils; row stays on the server
	if (!row) notFound()
	export const user = { id: row.id, name: row.name } // sent to the page
	export const head = { title: `Profile of ${user.name}` }
</script>

<script lang="ts">
	const name = signal(user.name) // `user` is in scope and typed
</script>

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

• When it runs. Block statements other than imports, types and export const route run on each request: in SSR and each client navigation's data request, after middleware and validation of params and search with route, just like load. They support top-level await. Imports, types and route options evaluate once per module.
• Exports. Each export const or export let (including destructuring, export const { a, b } = ...) except route and head is a page data field. Only exported names cross the boundary: the rest of the block, its imports and private variables do not reach the client bundle or payload. An export that is a promise is awaited before rendering.
• In the page. <script> and the template see each export as a normal, deeply read-only value, with the already-awaited export type. It is not a signal: it arrives in the payload and is replaced on each navigation when the block runs again. For editable state, create a signal from it (signal(user.name)). Declaring a name in <script> that the block already exports produces MEEK075. The page does not need to declare data in defineProps; if it does, meeko check checks compatibility with the exports.
• export const head. Sets the page's <head> like route.head: a { title, description } object or a zero-argument function returning it, calculated on the server from block values. It is not part of the data. Declaring both export const head and route.head produces MEEK072. Since 1.2, top-level useHead and useSeoMeta in the block are an alternative, with export const head taking priority (see Document head).
• Request API. usePage() returns { url, params, search, request, context, signal }: params and search come from route schemas or, without a schema, from the route ID segments; context is the request context (session, services, platform) and signal aborts if the client disconnects, the session is revoked or the response is canceled. redirect(url, status?) stops the block and responds with a redirect (302 by default; supports 301, 302, 303, 307 and 308), which client navigation follows like a loader redirect. notFound() stops the block and responds 404 with the nearest error page (+error.meeko or app/error.meeko). All three are imported from @meekojs/meeko/framework or used without an import inside the block. They work while top-level code runs: also inside a block helper called by that code (function requireAdmin() { … redirect("/login") }), even if it is async. Where no page is in progress, they produce MEEK073, and at runtime throw an error with that code: in route options, in a block without top-level code, in the component's <script> (since 1.3, also without an import in <script> and the template) and, since 1.7, in a function Meeko calls to calculate the head after top-level code has finished (export const head = () => … and the function passed to useHead(() => …) or useSeoMeta(() => …)); read values obtained by top-level code there. meeko check cannot know whether a block function is called later (from a timer, for example): in that case, the error only appears at runtime.
• Serialization. Exports travel in JSON, like load data. meeko check produces a type error for a non-serializable export: functions, undefined, bigint, symbols and class instances such as Date or Map. At runtime, a value rejected by serializeJson fails the response with 500, like a loader.
• State between requests. Because the block runs on each request, a top-level variable (const cache = new Map()) is new each time. A value that must be shared between requests belongs in an imported module.

Meeko considers a block to have top-level code if it exports a name other than route (including head) with export const or export let, or uses usePage, redirect or notFound (since 1.2, also useHead or useSeoMeta) outside any function and outside route options. A block with neither retains 1.0 behavior: it evaluates once as a module and supports export default, export function or a private constant used by load. With top-level code, these rules apply:

The editor gives exports their type in <script> and the template, and “Go to definition” on user takes you to the block's export.

Route options with 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>

Common rules#

The block is a TypeScript module independent of the component:

• Server only. The compiled component never includes it. It runs on the server with server/utils auto-imports and can import server/ and *.server.* modules; relative imports resolve from the page's folder. Only a render: "client" route sends it to the browser (see “Rendering modes”).
• Route options. Just like a sidecar: export const route = definePage({ ... }) or, without top-level code, export default. render and, since 1.5, layout must be literals that meeko build can read without executing it.
• Pages only. A <script server> in a component, layout, +layout.meeko or +error.meeko is an error (MEEK044). A second block produces MEEK004, omitting lang="ts" produces MEEK006, and a value (server="...") produces MEEK043.
• Checking. meeko check checks the block with TypeScript in server scope and compares its loader or exports with the page props; errors point to the .meeko line and column.

head({ data }), or export const head, returns the page's title and, since 1.1, its description. In SSR, title goes in <title> and description in <meta name="description">, before the host's <head>; on navigation, they apply to document.title and that meta tag. A page without title or description leaves those provided by the host in document.head, or none, equally in SSR and navigation. Since 1.2, route head also supports useHead tags and attributes (meta, link, script, style, htmlAttrs, bodyAttrs and titleTemplate as a string), with the highest priority over useHead and configuration document; the host's title and description remain after Meeko's managed head (see Document head).

Alternatively, route options can live in a *.route.ts sidecar next to the page (app/pages/users/[id].route.ts), the form available since 1.0. A sidecar does not support top-level code. A page cannot declare both: Meeko stops route discovery with an error naming both files.

Route options validate params and search before the loader and top-level code. A loader can return a Response to redirect; top-level code uses redirect(). On client navigation, if the data request responds 404 (from notFound() or a loader ApiError with status 404), the browser shows the nearest +error.meeko, or app/error.meeko, with { status: 404, message }, where message is the public error code (NOT_FOUND), just like the SSR document. meeko check . compares each page's ComponentProps with the params, search and data its sidecar provides; a contract error identifies both files. It also checks that app/app.meeko and layouts accept the outlet supplied by Meeko, and that +error.meeko and app/error.meeko accept status and message. These contracts reject props declared as any, never or unknown. Loader data is required for the page when the sidecar declares load; a repeated query parameter without a schema can produce string[] as well as string. The SSR handler creates useState state and session context per request; it transfers only props, public state and serializable route data. The browser hydrates that payload and requests server data during navigation, so a private sidecar does not enter the client bundle; only render: "client" sidecars are public (see “Rendering modes”). mountClientApp manages history, cancellation and cleanup. If a host uses loadRoute directly on the client, its loader receives provisional state: Meeko applies its changes when confirming the route and discards them on cancellation or failure. That state's signals must be used during load, without retaining references after returning. You can use render: "prerender" with prerenderEntries for dynamic routes; without them, meeko build fails (Dynamic prerender route /posts/[id] requires prerenderEntries) and, since 1.7, so do meeko check and meeko dev during route discovery, unless an options spread might supply them, which is left to the build. meeko build reads render from the sidecar without executing it: it must be a string literal inside definePage({ ... }), an exported object or a local constant in the same file; a calculated value, a computed key (["render"] or [clave]) not followed by a literal render, a spread without a subsequent explicit render, or a re-export stops the build, naming the affected file. The build writes HTML and navigation payloads under .meeko/output/node/prerender/ (meeko prerender . repeats that step on an existing build). The server serves these pages through server middleware, session context and route middleware; it inserts the session CSRF meta tag in <head> without rewriting the document. Without a session, it responds with ETag, Vary: cookie and cache-control: public, max-age=0, must-revalidate, returning 304 for If-None-Match; with a session, it responds private, no-store. A CDN or shared cache in front of the server must respect Vary: cookie or avoid storing responses to requests with cookies; if it ignores Vary, configure it to bypass caching when a request has the session cookie, otherwise it could deliver the anonymous version to a user with a session, leaving them without a CSRF meta tag. PrerenderedPage.headOffset in the prerender/manifest.json index is measured in UTF-16 code units of the stored HTML read as text (JavaScript string indices), not bytes: an adapter must read the file as UTF-8 text and use the value as is, without calculating it from bytes. A URL with a query string, an ungenerated dynamic entry or a host with its own CSP nonce (without server.contentSecurityPolicy, which since 1.7 serves the file with its hashes) renders with SSR. Loader checking covers both definePage({ load() { /* ... */ } }) and definePage(options) when the type of options retains a required load.

Where each API is used#

A component's <script> and template run in SSR and in the browser; <script server> and *.route.ts sidecars run on the server, outside the component. Since 1.3, meeko check, meeko build and the editor flag each API where it does not exist, with a message explaining where to use it, and <script> and template autocomplete no longer offer server APIs:

Since 1.6, server route middleware (app/middleware/*.server.ts) is server code like server/: it uses redirect() and notFound() while running, like top-level <script server> code, and defineServerRouteMiddleware is auto-imported there; in a component's <script> or template it produces MEEK108.

With render: "client", the block or sidecar runs in the browser (see Rendering modes) and cannot use the table's server APIs: a server auto-import, an import from server/ or a *.server.* import stops the build, and the editor flags the auto-import with MEEK_AUTOIMPORT. A component inside server/ (an email template, for example) only renders on the server, so it can use server APIs. The build and meeko dev only apply MEEK108 to the browser bundle: a component outside server/ imported only by server code (a template in app/emails/ rendered by an API route) still compiles, as in 1.2. meeko check and the editor, which do not know the import graph, check every component outside server/ as browser code, just as in 1.2; put those components in server/ for them to be accepted.

MEEK108 flags code that already failed before 1.3: the server auto-import did not resolve in the browser bundle, @meekojs/meeko/server and /cloudflare cannot load there, a server/ import stopped meeko build, and macros and onMounted do not exist outside <script>. MEEK109 is a warning because that code compiles and loads: definePage in a component does not configure the route, and /node, /bun, /deno, /password and /build functions only fail when called in the browser (see Stability policy).

Rendering modes#

The sidecar's render selects how each page reaches the browser:

Top-level <script server> code follows the mode like a loader: with "ssr" and "stream" it runs on each request, and with "prerender" once per entry during meeko build. In "stream", an export created with defer(...) arrives after the page, like a deferred loader value (see Streaming SSR). It is not supported with "client" (MEEK074), because the block runs in the browser.

<!-- app/pages/notes/index.meeko: the block runs in the browser -->
<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>

With render: "client", the <script server> block (or sidecar) is public: it enters the browser bundle with client auto-imports, even though its tag says server.

With render: "client", the server runs server and route middleware, creates session context and validates params and search against the sidecar schemas (invalid input responds 400). It then renders app/app.meeko and layouts with an empty outlet, without calling load or head, and sends a payload with render: "client" and only params and search. Without layouts, #app is empty. In the browser, Meeko hydrates the layouts, runs load with ClientPageLoadContext (url, params, search, signal and state, without request or context) and confirms the page through the same transactional path as navigation; head runs after load and its title applies to document.title. A loader failure shows the nearest +error.meeko inside the layouts, with the same public message as the server (500 reports to the navigation error observer; a 4xx ClientError retains its status and code).

Navigation works in both directions between SSR and client pages, preserving common layouts: each route selects its data source. "client" pages use their sidecar in the browser and others request their payload from the server. Only "client" sidecars enter the client bundle, through the virtual:meeko-client-routes virtual module; the generated entry point loads them with mountClientApp({ loadClientRoute }). This is why the build applies the same boundary as for other client code: importing server/ or a *.server.* module from that sidecar stops meeko build, and only client auto-imports exist in the browser, so using a server/utils utility fails with an error naming the auto-import.

Tradeoffs of "client":

• SEO. The initial HTML contains neither page data nor its <title>. Search engines that do not run JavaScript only see the layouts. Use "ssr" or "prerender" for indexable content.
• Data security. The sidecar is public: it cannot contain secrets or check permissions. Data arrives through API or RPC, and each endpoint must apply its own guards (session, CSRF, authorization and validation). Route middleware protects navigation, but not data.
• Prerendering. A "client" page cannot be prerendered: declaring prerenderEntries alongside render: "client" stops meeko check/meeko build with an explicit error.
• Consistent build. The server compares the sidecar's render with the build manifest's and responds with an error if they differ; rerun meeko build (or restart meeko dev) when changing a route's mode.

Streaming SSR (render: "stream")#

A loader uses defer to mark data that can arrive after the page. defer(promise, { timeoutMs }) or defer((signal) => promise, { timeoutMs }) returns a Deferred<T> with status ("pending", "resolved" or "rejected"), value and error ({ code, status }). Reading these fields in a template or effect subscribes to the result, because they are backed by signals.

With a factory, Meeko invokes it when the loader returns and passes an AbortSignal that aborts when the value is no longer awaited: on timeoutMs, if the client disconnects, the session is revoked, the stream is canceled, on a HEAD request or, in the browser, when leaving the route. Pass it to fetch or your database client to actually cancel the work. An already-started promise cannot be canceled: Meeko only stops awaiting it, unless the work itself uses the loader's context.signal, which also aborts in those cases (except the timeout, which is specific to each value).

// 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 }), // critical: included in the initial HTML
		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'">Loading comments…</p>
<ul if:when="props.data.comments.status === 'resolved'">
	…
</ul>
<p if:when="props.data.comments.status === 'rejected'">Could not load ({props.data.comments.error?.code}).</p>

Phase 0, before the first byte. The server resolves the route, creates context and session, runs middleware, validates params and search, awaits the critical loader (everything outside defer), synchronously renders the page and all its layouts with deferred values in pending, and calculates head, which sees state written during rendering. It then seals state (StateStore.seal(): a later write throws STATE_SEALED and the deferred value causing it is rejected with 500), awaits ongoing session changes (create, rotate or revoke started by the loader), and calls context.session.verify(); a session revoked while the loader ran responds 401 instead of a partial 200. State, headers, cookies, CSRF token and <title> are fixed at that point: deferred work cannot redirect or change the session. From then on, create, rotate and revoke fail with SESSION_LOCKED/500 before touching the store, so the browser session remains valid: only the deferred value attempting it is rejected, the failure reaches onError, and other values keep arriving.

Sealing applies to every rendering mode, not just "stream". A state write from a promise nobody awaits (neither the loader with await nor a defer) throws STATE_SEALED inside that promise; without a catch, it is an unhandled rejection and Node terminates the process with its default configuration. Await that work in the loader or return it with defer.

Phase 1, the stream. The response has cache-control: no-store, no-transform and x-accel-buffering: no. First it sends the document through #app, the #meeko-payload payload (with deferred: [{ id, path, status: "pending" }] and null at each path) and the client entry point with <script type="module" async>, respecting the host's CSP nonce. For each value that resolves, in resolution order, a <script type="application/json" data-meeko-deferred="N">{"deferred":N,"value":…}</script> follows (or "error":{"code","status"}), and finally </body></html>. These are data blocks, not executable scripts, so a strict CSP without 'unsafe-inline' needs no exceptions.

Errors and cancellation. A rejection serializes only as { code, status }, with the same rules as the API: an ApiError retains its code and status; any other error becomes INTERNAL_ERROR/500, and its private cause goes to onError with the response's requestId. A value that does not finish within timeoutMs (10 s by default) is rejected with DEFERRED_TIMEOUT/504. Deferred values follow RequestContext.signal: if the client disconnects or an adapter write fails, the stream is canceled, Meeko stops awaiting pending deferred values and aborts their factory signals and the loader's signal, without reporting to onError; if the session is revoked, remaining values are sent as SESSION_REVOKED/401. A HEAD request receives final headers without a body and also aborts those signals. A promise passed directly to defer continues running until it finishes on its own.

Browser. The client hydrates with all deferred values in pending, as the server rendered them, and applies already-arrived values only when hydration finishes. It finds blocks already in the document and those subsequently added by the parser through a MutationObserver on <body>. It only accepts direct children of <body> after #meeko-payload, where the server writes them; a similar-looking block inside #app (user HTML, for example) is ignored. If the document ends without a value's block (for example, because a write failed), that value is rejected with DEFERRED_INCOMPLETE/502. On client navigation to a "stream" route, Meeko requests accept: application/meeko+json and the server responds application/meeko+ndjson: the first line is the payload, with which the route is confirmed, and each following line is { "deferred": id, "value" | "error" }. A malformed line is reported to onError without stopping reading; if the connection fails halfway through, the failure is reported and values that did not arrive are rejected with DEFERRED_INCOMPLETE/502. Navigating to another route cancels the pending read. Other routes still respond application/meeko+json.

stream versus ssr. With render: "ssr" or "prerender", a defer is awaited inside the server before rendering: HTML always contains the resolved value (or its error) and is safe for SEO, so a page can switch modes without changing its template. With "prerender", a rejected value is not saved: the request responds 500 and meeko build stops, naming the route and the value's path. Prerendered HTML and its index.meeko.json come from the same loader execution. Use "stream" when a secondary part of the page (comments, recommendations, metrics) is slow and must not delay the first paint or interactivity. Tradeoffs:

• SEO. Deferred content is absent from the initial SSR HTML; it is in subsequent data blocks shown only when JavaScript runs. Content that must be indexed must go in the critical loader or an "ssr" page.
• Proxies and CDNs. A proxy, load balancer or CDN that stores the entire response before forwarding it defeats streaming: the user waits as with "ssr". Meeko sends x-accel-buffering: no (respected by nginx) and cache-control: no-store, no-transform: no-transform asks intermediaries not to compress or rewrite the body, since buffered compression or rewriting would hold back blocks. On Cloudflare, no-transform disables compression to the visitor and features that modify HTML, but not read-only inspection: if a zone enables it, create a Configuration Rule with “Response Body Buffering” set to “None” for those routes. Locally, wrangler dev and meeko preview --adapter cloudflare (Miniflare) gzip text/html responses even with no-transform and write the compressed body only when finished, so a "stream" page appears to arrive all at once at the end unless the client sends accept-encoding: identity. In production, Cloudflare compression does respect no-transform. Other intermediaries or serverless functions without streaming responses require separate configuration. Node, Bun and Deno adapters write each block as soon as it is produced; the conformance suite checks that the first byte arrives before the deferred value.
• Final headers. Redirects, cookies, CSRF and <title> depend only on critical data. Moving something into defer removes it from those decisions.
• Browser loaders. A "client" sidecar (or a host using loadRoute) can also return defer: the browser applies the same timeoutMs, updates the value when its promise finishes, and aborts a factory's signal on timeout or when leaving the route.
• Keys. A deferred value can be under any own key, including constructor and prototype, except __proto__: the server responds 500 when rendering.

SSR page caching#

Since 1.7, definePage's cache lets you revalidate and cache an "ssr" or "stream" page without running its loader or render on each request:

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

	export const route = definePage({
		cache: {
			// Cheap: query the modification date, rather than the document.
			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) returns the content version (a string or number) and runs before the loader and render, with validated url, params and search, plus request, signal and context. Meeko combines it with the request theme (cookie and client hint), build and response type (document or navigation payload) into a weak ETag, W/"…". If it matches If-None-Match, it responds 304 without a loader, plugins or render. It must change with everything that changes the HTML except the theme: if the page reads a header or search parameter outside params, include it. undefined leaves that response without an ETag.
• maxAge and staleWhileRevalidate (seconds) write Cache-Control: public, max-age=N, stale-while-revalidate=M. Without maxAge, public, max-age=0, must-revalidate: the browser revalidates each time and the ETag saves the body transfer.
• memory (true or { maxEntries, maxBytes }, defaulting to 1000 entries and 32 MiB per route and process) stores rendered HTML and payload in an LRU, keyed by URL, theme and response type, with the ETag used to render them. Since 1.7, on a route with a search schema, the URL part after ? is the validated search: an undeclared parameter (?utm_source=…, a random number to bypass the cache) shares the copy instead of filling the LRU; without a schema, the query counts as received, because the page receives it all. While etag returns the same value, Meeko serves the copy without a loader or render; when it changes, the copy is discarded and the page renders again. Requires etag. Two simultaneous requests finding no copy both render.

The response has Vary: Accept, Cookie (and Sec-CH-Prefers-Color-Scheme with the theme in "system"), because document and payload share a URL and HTML depends on theme and session. With server.contentSecurityPolicy, a cached page's document has no nonce and its CSP contains hashes of inline code Meeko writes, never of a <script> or <style> arriving inside the page (see CSP and headers in server adapters); the 304 has no CSP, so the browser keeps its copy's policy.

What is never cached. Caching only applies in production (in meeko dev, each request renders what was just compiled) and to sessionless GET and HEAD requests:

• a request with the session cookie, even expired, or with session.current, goes out as usual with no-store and no ETag: its HTML contains that session's CSRF token;
• a response setting a cookie (a loader creating a session, for example) goes out with no-store, no ETag and no memory copy; in development, Meeko warns once per route in the console;
• since 1.7, a request with the Authorization header goes out with no-store and no ETag, without reading or writing the copy: the response is for those credentials;
• a host with its own nonce (DocumentOptions.nonce without server.contentSecurityPolicy) does not cache: the copy would contain another response's nonce;
• a request with the single-use cookie containing a JavaScript-free form's result (__Host-meeko-form, or meeko-form without HTTPS) receives neither 304 nor the memory copy, is not stored, and on a prerendered page renders instead of serving the file;
• and, in any application response, Set-Cookie with a public Cache-Control or, since 1.7, with s-maxage (including when added by server.headers) becomes private, no-store without an ETag.

Personalizing with your own cookies. Meeko only recognizes its session cookie. A page with cache that personalizes HTML using another cookie (language, currency, anonymous cart, A/B test) shares it: etag does not see it unless it reads it, and memory serves the same copy to everyone. Vary: Cookie only prevents a shared cache mixing responses with different cookies. If HTML depends on your own cookie, include its value in what etag returns and do not use memory, or do not use cache on that page.

Middleware. Route middleware (isomorphic and server) always runs, before the 304 and the memory copy: caching never bypasses a guard. With memory, application plugins do not run on a request served from the copy.

render: "stream". Only uses ETag and 304: its body goes out as defer values resolve, so storing it would require waiting for all of them (the opposite of a stream) and fix values that can change on each request. Its Cache-Control adds no-transform, as always, and its CSP contains the document hashes without deferred values, which are JSON data blocks. With "prerender", cache only affects SSR for URLs that were not prerendered; a "client" page does not support cache (type error and TypeError when defining it).

cache is read when the route executes, like load: meeko build does not read it from the file. definePage validates it when loading the module (an unknown field, a negative number or memory without etag throws TypeError).

Links, anchors and scrolling#

mountClientApp turns clicks on same-origin links to application routes into client navigation, including links in HTML inserted with html. A link to a current-page fragment (#seccion, or /docs#seccion while on /docs) is not intercepted: the browser scrolls the page and adds the history entry without requesting or rendering the page again, and going back or forward between those fragments does not render it either. app.navigate("#seccion") does the same.

A new navigation starts at the top of the page or, if its URL has a fragment naming an element (id or name), at that element, immediately even if the page uses scroll-behavior: smooth. Navigation with replace only scrolls to the fragment, if any. If a navigation data request receives HTML instead of a payload (static hosting serving the prerendered index.html, a proxy or CDN), Meeko loads that document instead of failing.

Back and forward return the reader to the position they had in each history entry, even one with a fragment; an entry with no saved position goes to its fragment, if any. The position is applied together with the DOM of the page, before the first frame and inside the View Transition. If it does not fit yet because content is missing, such as a defer value, Meeko waits up to 10 s for it, and gives up if the reader or other code moves the page or if another navigation happens. On a reload or a return from another document, the browser restores it.

To do this Meeko sets history.scrollRestoration to manual, adds meekoEntry to history.state and stores the positions in sessionStorage, and it keeps whatever else is in history.state. If you write to it, keep what is there: history.replaceState({ ...history.state, own: 1 }, ''). Only the scroll of the window is remembered, not that of your own container. There is no option to control this scrolling: if you need another position, scroll after app.navigate() finishes.

Native View Transitions#

Enable client navigation transitions in meeko.config.ts:

export default defineMeekoConfig({
	viewTransitions: true,
})

The option is boolean and disabled by default. Meeko loads the page, its modules and data before starting document.startViewTransition(), placing the DOM and head change inside the callback. It does not animate SSR, initial hydration or current-page fragment changes. It works with internal links and back/forward navigation. Without the API, with a hidden tab or with prefers-reduced-motion: reduce, it navigates normally.

It does not animate a page that is too large either: above 4,000 elements, on the source or the destination page, it navigates without a transition. In a document that size, on a high-density screen or a phone, each frame of the transition blocks the page for seconds. If the destination is the large one, Meeko captures the source page and skips the animation when it applies the change. If you call document.startViewTransition() yourself, check the same with isTooLargeToAnimate.

The browser provides a basic transition; customize the animation from app/styles/main.css with native CSS:

.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);
}

Use the same view-transition-name on the source and destination elements. Each name must be unique among visible elements on a page; duplicates can prevent animation, though navigation still completes. No directive or wrapper component is needed. See the native API.

Since 1.8, a navigation's transition has the type meeko-route, so CSS can tell it from one that a component starts. Name an element only during navigations:

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

A browser without transition types (Chrome before 125, Safari before 18.2, Firefox before 147) still animates the navigation and ignores those rules.

To disable or enable a particular navigation, use app.navigate('/projects', { viewTransition: false }) in a host with the ClientApp returned by mountClientApp. Links support a standard HTML attribute, on both <MeekoLink> and <a>:

<MeekoLink
	to="/projects"
	data-meeko-view-transition="false"
>
	Open without a transition
</MeekoLink>

data-meeko-view-transition="true" enables that link even when the global option is disabled; reduced motion still takes priority. The navigation promise waits for the DOM change, without waiting for the animation to finish. A subsequent navigation or application unmount skips the previous animation; an aborted update cannot replace the new page. Animation failures do not become navigation failures; render errors continue propagating as before.

This option controls changes within the same document. Navigation to new documents can use @view-transition { navigation: auto; } in both same-origin pages' stylesheets, subject to browser support and that API's rules. UI modals keep their local animations and do not need whole-page snapshots. The /transitions example on the apps/ui public site includes a shared surface between list and detail, plus links without a transition.

Navigation state#

useNavigation() returns { pending }, a read-only signal that is true from the start of navigation until its page is confirmed, fails or is canceled, including the first load of a "client" page and loading the new page's await useApi/await useRpcQuery calls (see Navigation and render: "client"). In SSR and outside mountClientApp, it is always false. Since 1.7, it is auto-imported, like useRoute (your own export with that name takes priority).

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

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

Current route#

Since 1.2, useRoute() returns the confirmed route rendered by the component, with a read-only signal for each value (RouteState type):

It is auto-imported in applications (your own export named useRoute in app/composables or another auto-import folder takes priority over the framework's), and, like useNavigation, can also be called from nested code running with the component (a composable, computed, effect or onMounted), but not from an event handler, timer or promise callback, where no root is active: there it throws (useNavigation returns a fixed state with pending set to false); get it in the script and use it in the handler. It works in pages, layouts, app/app.meeko, app/error.meeko and their components:

• SSR. Values are those of the request, including on "prerender" and "stream" routes and in layouts of a "client" route. The server does not receive the fragment, so SSR url never includes it.
• Hydration. The browser hydrates with the same values as SSR, without mismatches, even when the HTML was rendered for another URL: the static adapter's 404.html, served by hosting for any nonexistent URL, or a prerendered page served by static hosting with any query string. The payload includes the render URL (optional url field, since 1.6). Just after hydration, url and path become those of the browser address, including its #fragmento; on the 404 page, so does search, while on a page, params and search remain those validated by the server.
• Navigation. Values change only when navigation is confirmed, together with the outlet, never while useNavigation().pending is true; the previous page is disposed of before effects reading the route update. Values also change when going back or forward in history and on fragment-only navigation, where path stays the same and url changes. The preliminary render loading the new page's data await calls already sees the destination route.
• Outside an application. Outside framework rendering or mountClientApp (for example, in a unit test with renderToString), useRoute() throws an explanatory error instead of inventing a route; pass the route to the component as a prop in those tests.

isActive. Since 1.5, route.isActive(to, { params, prefix }) tells you whether a route is active with the same rule as <MeekoLink match>, for your own links and components. to is a RouteId and params are that route's parameters, with the type used by href(): required on a dynamic route, unsupported on others, and a nonexistent route is a type error. It returns "page" when the confirmed route is to, "true" with prefix: true when it is below it by complete segments, and false otherwise; "/" only matches exactly. It ignores query strings and fragments and compares encoded paths. The result works directly for bind:aria-current, because bind: removes the attribute when its value is false, and as a condition, because "page" and "true" are truthy. It reads path, so a template, computed or effect using it updates on navigation; in SSR and hydration it returns the same result, without mismatches.

A layout with a sidebar marks the active section this way, both in server HTML and after each navigation:

<!-- app/layouts/default.meeko -->
<script lang="ts">
	const route = useRoute()
	const links = [
		{ to: '/', label: 'Home' },
		{ to: '/users', label: 'Users' },
		{ to: '/settings', label: 'Settings' },
	] 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">Changes are saved when you leave.</p>
	</aside>
	<main><MeekoOutlet /></main>
</template>

Components received as props retain the contract's direction: a component requiring label does not satisfy an outlet that can render it without label. meeko check diagnoses the expression passing the component. When you save a TypeScript module imported by an open .meeko, the VS Code extension rechecks its diagnostics and semantic tokens.

Document head: document, useHead and useSeoMeta#

Since 1.2, Meeko manages each document's <head> and the attributes of <html> and <body> from three sources, combined using one priority rule:

• document in meeko.config.ts. The application's common document: lang and a head with tags and attributes. It renders in all HTML documents: SSR, "stream", "prerender", the app/error.meeko 404 page, a failed route's error document, and a "client" route's shell. It is fixed at build time (and also reaches the browser bundle, because it ends up in HTML), so it must be serializable: titleTemplate can only be a string (its type, DocumentHead, does not accept a function, so the editor and meeko check flag it as a type error in meeko.config.ts) and meeko build rejects a function. Its title is the site title: pages without their own title show it unchanged, without a template (see Title below). Meeko modules add their head before the application's, which wins.
• useHead(input). In pages, layouts, app/app.meeko, app/error.meeko, components and composables, at script top level or in a composable it calls. Also in top-level <script server> code, as an alternative to export const head (see below). input can be an object, getter or signal; with a getter or signal, the browser updates the document when the values it reads change.
• useSeoMeta(input). Typed shorthand for useHead: description, robots, themeColor, colorScheme, author, keywords, applicationName, referrer and twitter* fields produce <meta name>; og* fields (ogTitle, ogDescription, ogImage, ogImageAlt, ogImageWidth, ogImageHeight, ogUrl, ogType, ogSiteName, ogLocale) produce <meta property>; title is the title and canonical is <link rel="canonical">. An undefined or null field produces nothing.

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

export default defineMeekoConfig({
	document: {
		lang: 'es',
		head: {
			// “Shoes · My store” on a titled page; “My store” on an untitled one.
			title: 'My store',
			titleTemplate: '%s · My store',
			link: [{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }],
			// Runs while the browser reads <head>, before painting; hydration does not repeat it.
			// (For a light/dark theme, use theme: Meeko provides the script, cookie and 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 supports title, titleTemplate ("%s · Sitio" or (title) => string; in document.head, meeko.addHead and route head, only the string), meta, link, script (external with src or inline with children; async, defer, module and type), style (with children and media), htmlAttrs and bodyAttrs (lang, dir, class, data-*; an undefined value contributes nothing and on* attributes are rejected).

Priority. Lowest to highest: configuration document, app/app.meeko, each layout (innermost wins), the page with its components and, finally, route head (export const head, route.head or useHead in <script server>). Within a level, the later call wins, so a page component mounting later (after an if:, for example) replaces what the page set. <html> and <body> attributes merge by name with the same priority.

Title. titleTemplate comes from the highest-priority entry declaring it, and applies to the highest-priority title from app/app.meeko, layouts, page and route head, including error pages: "Error" or, above it, the title the error page itself (app/error.meeko or +error.meeko) declares with useHead, which its layouts' titles do not override. The title in document.head (or added by a module with meeko.addHead) is different: it is the site title and never passes through the template. A page without its own title shows that title unchanged, as does one whose winning title is an empty string, instead of a template around nothing. Without a site title, a page without a title has no managed <title> (the host's remains, if any), and an empty title is written empty. The rule is the same in SSR, hydration and client navigation. With the example configuration:

Deduplication. Each tag has a key: key if declared, otherwise its natural key. For meta, name (case-insensitive), property or httpEquiv, together with its media if present (two theme-color tags for light and dark coexist); for link, rel and href, except rel: "canonical" and rel: "icon", which are unique even if href changes; for script, src or the code; for style, the CSS. With the same key, only the highest-priority tag remains, in the position where the first appeared. Thus a document icon replaces the <link rel="icon" href="data:,"> Meeko writes by default, and a meta name="viewport" replaces the default viewport.

SSR and CSP. The server writes <html lang="…"> and attributes as real, escaped attributes. Inside <head>, after the CSRF meta tag and component styles, the title and managed tags go between <!--meeko:head--> and <!--/meeko:head--> comments, before trusted host HTML (DocumentOptions.head, which keeps its own <title> as the default title). Attribute values are escaped; inline script and style content is not escaped but cannot close its tag: </ is written <\/ (and <!-- as <\!-- in a script), and in JSON scripts (application/ld+json, application/json, importmap, speculationrules) each < is written \u003c. The request's CSP nonce (DocumentOptions.nonce) is added to managed <script> and <style> tags. A prerendered page keeps the head and receives the CSRF meta tag just after <meta charset> and default tags the application did not replace.

Browser. On hydration, Meeko adopts SSR tags without duplicating them or rerunning scripts. When a useHead getter or signal changes, it updates title, attributes and tags. On navigation, unmounted components' entries disappear and what they replaced returns (for example, the layout's canonical or app/app.meeko's description); going back restores the page's entries. New tags are inserted before <!--/meeko:head--> with the document's CSP nonce; a changed script is a new element, which the browser executes. Route head travels in the navigation payload, just like title and description in 1.1. Outside a Meeko application (for example, in a unit test with renderToString), useHead does nothing. A custom host passing DocumentOptions.config to createFrameworkHandler must pass the same value to mountClientApp({ document }); Meeko's generated entry point already does this.

<script server>. Top-level useHead and useSeoMeta make the block have top-level code, like usePage. Their entries form the route head together with export const head (or route.head), which takes priority over them. Because they travel in the payload, their titleTemplate must be a string.

Per-page canonical URL and Open Graph#

Since 1.3, document.seo adds tags depending on the page to each document, which each page would otherwise need to repeat with 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 enables all of them; an object disables those set to false (seo: { ogDescription: false }). The origin is site or, without it, MEEKO_PUBLIC_ORIGIN from the build environment; with canonical or ogUrl enabled and neither supplied, meeko build fails with a message requesting it. It is fixed at build time (seo.origin in the manifest), so an SSR-rendered page uses the same origin as a prerendered one. In meeko dev without an origin, these two tags are not written.

These are the lowest-priority tags: a page or layout declaring the same tag (with useSeoMeta, useHead or route head, with any key) replaces it, just like document.head tags. Error pages (app/error.meeko, +error.meeko and the static adapter's 404.html) receive neither canonical nor og:url, because they are served at any URL. On client navigation, tags follow the confirmed page. A custom host passing DocumentOptions.config with seo must include seo.origin.

Light/dark theme without flashing#

Since 1.4, Meeko includes light/dark themes (and custom themes): the choice is saved in a cookie, the server writes the theme on <html> from the first byte, and components render the correct icons in server HTML without waiting for JavaScript. When the server cannot know it (a prerendered page, the static adapter or "system" mode without a client hint), a minimal blocking <head> script applies it before the first paint.

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

export default defineMeekoConfig({
	theme: true, // light and dark, "system" by default, data-theme and the meeko-theme cookie
})

/* app/styles/main.css: each theme's colors, with color-scheme even without JavaScript. */
:root {
	color-scheme: light;
	--bg: #fff;
	--ink: #111;
}
:root[data-theme='dark'] {
	color-scheme: dark;
	--bg: #111;
	--ink: #eee;
}
/* Without the attribute (unresolved "system" mode and no JavaScript), the system takes precedence. */
@media (prefers-color-scheme: dark) {
	:root:not([data-theme]) {
		color-scheme: dark;
		--bg: #111;
		--ink: #eee;
	}
}