1.x stability policy

Starting with 1.0.0, @meekojs/meeko follows Semantic Versioning. This page defines what that promise covers, what falls outside it, how an API is removed and which environments run Meeko. Changes in each version are recorded in the CHANGELOG; upgrading from 0.1.0 is explained in the 1.0 migration guide, from 1.0 to 1.1 in Upgrade from 1.0 to 1.1, from 1.1 to 1.2 in Upgrade from 1.1 to 1.2, from 1.2 to 1.3 in Upgrade from 1.2 to 1.3, from 1.3 to 1.4 in Upgrade from 1.3 to 1.4, from 1.4 to 1.5 in Upgrade from 1.4 to 1.5, from 1.5 to 1.6 in Upgrade from 1.5 to 1.6, from 1.6 to 1.7 in Upgrade from 1.6 to 1.7, and from 1.7 to 1.8 in Upgrade from 1.7 to 1.8.

Prereleases (1.1.0-rc.1) are published under npm's next dist-tag and are outside the promise until their final release.

A single package#

Compiler, runtime, framework, adapters, CLI and language server are published together in @meekojs/meeko, with a single version. During 1.x they will not be split into packages requiring coordination.

Compiler-generated code (compiled .meeko modules, entries under .meeko/ and meeko build builds) imports @meekojs/meeko/internal, and both must have exactly the same version. That is why meeko init and meeko init-framework pin the exact version in the generated package.json. When upgrading Meeko, recompile or rebuild: do not mix code generated by one version with another version's runtime, even if both are 1.x.

Public API#

The following only changes incompatibly in a major release.

Package entry points#

The subpaths declared in package.json exports and all symbols and types they export, whether or not described in this guide, api.md, framework.md, devtools.md and editors.md; their exact reference is the published .d.ts declarations. Low-level functions for custom hosts (for example matchRoute, createNavigator, createSocketHub, dispatchApiRoute, dispatchRpc or createRequestContext) are also part of the contract:

tests/package-boundaries.test.ts pins the exact list of root exports and package.json subpaths.

Types are part of the contract. There are two nuances:

• A union Meeko returns to the application may gain members in a minor release: for example ErrorSource (which gains "uncaught" and "rejection" in 1.3), PageRender, DeferredStatus, DevtoolsReadKind, DevtoolsEventKind, a SocketClient's state (which gains "unauthorized" in 1.1) or error codes. An exhaustive switch over these must have a default branch. A union the application passes to Meeko is not narrowed in 1.x.
• An interface for an object Meeko returns to the application may gain members in a minor release: for example RouteState, returned by useRoute() (gains isActive in 1.5), DataResource and LoadedResource, from useApi and resources (gain refreshing in 1.5), or Form (gains trySubmit, commit and field in 1.5). Read and destructure them normally, but do not implement them by hand (const route: RouteState = { … }), because a minor may add a required member. In a test, a partial double with Partial<RouteState> or an as RouteState assertion still compiles. Interfaces the application passes to Meeko (options, configuration, contracts) only gain optional members.
• A type fix rejecting code that already failed at runtime may ship in a minor or patch release, with a CHANGELOG entry.

Approved exceptions#

Changes rejecting runtime-valid code that ship in a minor release by explicit decision, each with its migration:

.meeko format and generated module#

• The <script lang="ts">, <template> and <style> sections (with scoped and :global(...)), and on pages <script server lang="ts"> (since 1.1), with its two forms: route options and top-level code whose export const declarations are page data, with the rule deciding when a block has top-level code. Since 1.1, <script lang="ts"> is optional and accepts the generic attribute with the component's type parameters, which is not allowed on pages, layouts, app.meeko or error.meeko.
• The defineProps<Props>() macro, with or without defaults, and since 1.1 the defineEmits<T>(), defineExpose(value), defineModel<T>(name?, options?), defineSnippets<T>() and useElementRef("name") macros.
• The {expression}, on:event, bind:name, if:when, each:of/each:as/each:key/each:index and <component is> directives. Since 1.1:
  • each:key is optional and without it the key is the index;
  • on:event on <component> and component tags is equivalent to the onEvent prop;
  • component tags with uppercase names (<AppButton />), whose content consists of snippets;
  • static props on components (variant="primary" passes a text literal and an attribute without a value passes true), with is, ref, html, hyphenated names and names containing : without being directives reserved (since 1.8, except aria-* and data-*);
  • the ref:name directive. ref="x" and bind:ref retain their 1.0 behavior;
  • model and model:name on component tags, model on <input>, <textarea> and <select>, and the <snippet name params> and <render snippet args /> elements;
  • the html="expression" directive, inserting unescaped HTML, normalized to fit the element and never executing its <script> elements when inserted in the browser;
  • html and model are directives only on standard HTML elements; on custom elements (hyphenated tags) they are literal attributes;
  • <component is="..." /> is self-closing, like <Etiqueta />.
• Since 1.8, a non-void HTML element without content can self-close with /> (<div />, <textarea />, <td />, <my-element />) and is equivalent to writing its closing tag: subsequent nodes are siblings, and SSR writes <div></div>. <template>, <script>, <style>, <html>, <head>, <body> and unknown names still give MEEK001, and a self-closed table or list element followed by its own closing tag (<td /></td>) gives MEEK008 (see Elements without content).
• Since 1.4, if:when on <snippet>: the parent passes that snippet only while the condition is true, and only if the child declares it optional.
• Since 1.5, the built-in <MeekoTeleport> tag with to ("body" or "#id", the latter with a letter followed by ASCII letters, digits, - or _), bind:to, disabled and bind:disabled, and the MeekoTeleportProps and MeekoTeleportTarget types from @meekojs/meeko/framework. The content's destination in server HTML (inside the id element, after its content, or after the application and before Meeko scripts with body), ordering of multiple teleports to the same target, retaining the declaring component's scope, moving the same nodes when disabled changes and behavior with a missing target described in framework.md are contractual. Comments marking content are internal.
• Since 1.5, <component is> accepts an HTML tag (a literal, an expression whose type is a union of tags, or a union of tags and components) and content: children with a tag, snippets with a component. Supported tags are the public TagName type; a non-global attribute is written only while the current tag supports it according to Meeko HTML data (no type on <a> or <area>). When the tag changes, children move to the new element with their state. The bind="obj" directive writes an object as element attributes or component props, without on* keys; explicit attributes win and class and style are combined. bind remains a literal attribute on custom elements and is no longer a static prop.
• Since 1.4, defineSnippets<T> accepts a parameter tuple or Snippet<Args> in each key of T, counting as Args, so T can derive from another component's snippet map with Omit, Pick or & while preserving parameters and optionality. A tuple declaration retains the same type.
• Since 1.8, <snippet> name accepts, besides an identifier, identifier-character segments joined by hyphens (/^[A-Za-z_$][\w$]*(?:-[\w$]+)*$/, such as cell-email), and defineSnippets<T> accepts keys from a template literal mapped type over the component's type parameters ({ [K in keyof Row & string as `cell-${K}`]?: [row: Row, value: Row[K]] }). It is contractual that meeko check and the editor check these snippets in the parent with the type inferred from its props (nonexistent name, each parameter's type and number of params), and that within the component, an intersection with a mapped type retains its fixed keys' types (snippets.cell). The type of an access by computed name inside the component is excluded: TypeScript does not resolve it over a type parameter.
• Since 1.4, with theme in meeko.config.ts, the built-in <MeekoThemeToggle> tag (deprecated since 1.8, removed in 2.0; use UIThemeToggle from @meekojs/ui): its props (mode, themes, labels, messages, class, id), one snippet per choice, application-styled markup (the root <form method="post" action="/_meeko/theme"> with data-meeko-theme-toggle, the mode="cycle" <button>, icon <span data-meeko-theme-icon> elements, role="radiogroup" and its role="radio" buttons with aria-checked and data-meeko-theme-option in mode="select"), the <html> data-theme-choice attribute with the choice, the <head> rule showing the chosen icon, and the POST /_meeko/theme endpoint with the framework.md rules (valid themes, same-site Origin, 303 only to a same-origin path). Default text and the rule's CSS may change in a minor.
• Since 1.5, the built-in <MeekoAwait> tag: its props (for, as an expression or with bind:for, reserve, messages, class, id), snippets (default with refreshing, pending and error with error and retry), states described in framework.md, narrowing of for data in its content, and application-styled markup: a <div> with data-meeko-await (pending, error or ready), aria-busy="true" while loading or refreshing, data-meeko-refreshing during refresh and, with reserve, data-meeko-reserve and data-meeko-reserve-min. It is contractual that reservation applies min-block-size only in pending, without style attributes, and that persistence lives in sessionStorage; each zone's key, stored format, <head> script text, default text and number of remembered zones may change in a minor.
• Since 1.5, the built-in <MeekoPopover> and <MeekoSelect> tags (deprecated since 1.8, removed in 2.0; use UIPopover and UISelect from @meekojs/ui) (see Built-in components): their props, snippets (trigger, anchor and content; option, value, group, empty and loading), model, events (toggle with { open }, change) and exposed members (show, hide, toggle); application-styled markup (data-meeko-popover and data-meeko-popover-trigger, data-meeko-select with data-open, data-multiple, data-disabled and data-loading, role="option" options with data-active, data-selected and data-disabled); documented ARIA roles and attributes; documented keyboard behavior; the name <input type="hidden"> elements, and not using style="…" attributes. The meeko cascade layer rules, --meeko-popover-* custom properties, default text and ID shapes are implementation details and may change in a minor.
• Since 1.8, a static class or style alongside bind:class or bind:style on the same element (or on a <component is> that can only be a tag) writes a single attribute in SSR, hydration and updates: dynamic classes follow static classes, and dynamic style declarations follow and override static ones. If the dynamic value is undefined, null, false or empty, static text stays as-is. Previously SSR wrote the attribute twice and hydration failed.
• Since 1.8, lowercase aria-* and data-*, static or with bind:, on a component tag or a <component is> that can only be a component pass a prop with that name (previously MEEK032); data-meeko* and uppercase names still produce MEEK032. This only makes previously uncompilable code valid.
• Since 1.8, when the script writes defineEmits events (a type literal or local interface or type without extends or parameters), props does not enumerate their callbacks (onSave) in Object.keys, in, spreading or rest destructuring; reading them (props.onSave) and emit do not change. The props type never declared them, so typed code did not enumerate them intentionally.
• Since 1.8, a PascalCase text literal in <component is> (is="to ? 'MeekoLink' : 'a'", 'UICard') names <MeekoLink> or an imported, auto-imported or script-declared component, which the compiler resolves like its tag: one if:when region per name, whose condition is the ?: path to its literal, and another for HTML tags; each attribute goes only to branches supporting it. HTML tags are lowercase. This is additive: previously a PascalCase literal gave MEEK112 (not a tag), and is with a component value or HTML tags is unchanged. An unknown name or a value alongside names gives MEEK132. Region and marker distribution is an implementation detail. resolveComponent("MeekoLink") and the MeekoLink entry in ComponentRegistry (unless the project has a component with that name) load <MeekoLink> as a component from @meekojs/meeko/builtins/link.
• Since 1.8, bind: on an SVG or MathML element writes the name with standard casing, like the static attribute (bind:viewBox writes viewBox, not viewbox); previously, the lowercase attribute had no effect on SVG and hydration did not match.
• Since 1.8, <MeekoLink> with a route-union bind:to accepts bind:params with parameters of any of them, or none, and bind:search with undefined; checking for a single route is unchanged.
• Since 1.8, defineProps can be destructured in its const declaration (const { label, size = "md", class: className, ...rest } = defineProps<Props>()): each name reads its prop where used and is reactive in the script and template, except where a closer scope declares the same name; pattern defaults are equivalent to the defaults argument; ...rest is a read-only reactive view of the remaining props, excluding defineEmits handlers. Defaults (in both forms) can read top-level constants using only literals and imports. This is additive: it only makes code previously producing MEEK015 or TS2304 valid. Default types are computed per variant of a props union, so a default for a prop one variant declares never no longer allows it in that variant for the parent.
• Since 1.8, with a props union, a literal defineProps default (kind = "a", in the pattern or argument) makes its prop optional for the parent only in variants accepting that value, in ComponentProps, .d.meeko.ts declarations and the editor; a nonliteral default stays optional in all variants and gives MEEK131 if one requiring the prop does not accept it. This is a fix: previously a parent could omit any variant's discriminant (<Child b="hello" /> with kind = "a"), the component received { kind: "a", b: "hello" }, which matches no variant, and failed at runtime. That parent stops compiling; to migrate, pass the discriminant (kind="b"). Unions without a discriminant default and non-union props are unchanged.
• Since 1.8, Meeko HTML data comes from the standard (src/shared/html-data, generated by scripts/html-data.ts): tags and attributes accepted by <component is> and bind="obj" are a superset of 1.7's. The public AttributeValues<Tag, Name> and AttributeValueOf<Tag, Name> types (from @meekojs/meeko), and ElementAttributes<Tag> values, suggest standard values without restricting acceptance; a literal outside them gives warning MEEK122. hidden with nonempty text ("until-found") writes that text, and standard boolean attributes not treated as such by 1.7 are written empty.
• Setup rules since 1.1: useElementRef, useApi, useRpcQuery and useRpcMutation only at the top level; top-level await only on useApi, useRpcQuery, useElementRef, useSocket and useSocketClient; splitting setup at the first browser await, whose continuation runs only in the browser and accepts expression and control flow statements.
• Each compiled module's shape: ComponentProps, ComponentExposed, ComponentModels and ComponentSnippets (since 1.1), css (with the Meeko Vite plugin, since 1.8 it depends on the graph: in the SSR graph —meeko dev, Node build, prerendering, static and Cloudflare— and the meeko dev client, it is <style> CSS already processed by project PostCSS and CSS plugins, the same CSS embedded by SSR and prerendering and reapplied by HMR; in the production client bundle it is compiler output, as before 1.8, because no Meeko code reads it there and the stylesheet Vite bundles already applies processed CSS. In a host that does not process CSS and resolves that module as an empty string, such as Vitest without test.css: true, it is also compiler output. With compile() without styleModule, it is always compiler output), renderWithState, renderToString, hydrate and hydrateScope, whose disposal function carries exposed. In a component with generic, types and functions carry its type parameters. The hasDataAwait, __meekoChildren, __meekoReactiveProps (since 1.2), __meekoChannels and __meekoTag flags are internal.
• Since 1.8, placement of inline SSR and prerender <style> elements: at the end of <head>, after global stylesheets (app/styles/main.css, those from addStylesheet and document head), where the client later adds component CSS, so first render and hydrated page have the same cascade; previously they preceded global stylesheets and a global rule of equal specificity won only until hydration. The error page for a server failure, which is not hydrated, also embeds its CSS. The data-vite-dev-id attribute meeko dev adds to those <style> elements for Vite to adopt them is an implementation detail.
• The Component<Props> type.

Generated JavaScript is not public; see Outside the contract.

CLI#

The commands and options shown by meeko --help:

Also part of the contract:

• the meeko-language-server binary, with the same transports as meeko lsp;
• exit code 1 on errors;
• diagnostic codes (MEEK0xx, MEEK1xx and MEEK_*; see Diagnostic codes);
• the { code, message, filename, location } shape of meeko check --json.

Message text may improve in any version; since 1.1 it is in Spanish. A minor may add diagnostics for code that already failed at runtime or violated a documented contract, and may stop emitting one when the code it flagged becomes valid. A retired code is not reused with another meaning.

Diagnostic codes#

Codes from MEEK043 onward are new in 1.1. TypeScript errors keep their TSxxxx code, which may change when TypeScript or the shape of the code it checks is updated: in 1.1, a missing required prop on a component tag gives TS2345 instead of TS2769.

The TypeScript version included in the package may be updated in a minor release. If this changes meeko check diagnostics, the CHANGELOG states it.

Project conventions#

• meeko.config.ts with defineMeekoConfig: extends, modules, imports.serverDirs, the server discriminated union (node, bun, deno and cloudflare, with documented fields, and since 1.3 static, with contentSecurityPolicy, headers and headerFiles) and, since 1.2, css.scopeAttribute, layers, document (lang and head) and module option keys (meta.configKey; since 1.4, a built-in MeekoConfig key makes loading fail, see Approved exceptions). Since 1.3, site, sitemap (true or { exclude }), robots (true or { allow, disallow }) and document.seo (true or { canonical, ogUrl, ogTitle, ogDescription, origin }), with the tags, files and priorities described in framework.md, dev.serverLogs, imports.appDirs and imports.sharedDirs, the latter two with the scope and path rules of Auto-import folders. Since 1.4, theme (true or { themes, default, system, darkThemes, attribute, colorScheme, cookie, storageKey, clientHints }), with Light/dark theme without flicker behavior: the <html> attribute or class, the inline <head> script and its read order (cookie, localStorage, default value). Since 1.2, modules lists defineMeekoModule modules (a module, package, path or [módulo, opciones]); extends is an alias for layers. Since 1.8, the documented form is the package name or path, with options under its meta.configKey: it is contractual that a package resolves through its ./module subpath if exported, otherwise its root; that .meeko/types/config.d.ts imports types from modules modules and .meeko/tsconfig.config.json includes meeko.config.ts with them (not their exact text); that a dependency's package.json keyword meeko-module offers it in modules completion, and that two modules with the same meta.configKey are an error (previously the same options were read twice).
• Server-rendered HTML document: since 1.2, the title and tags managed by Meeko go between <!--meeko:head--> and <!--/meeko:head--> comments, before DocumentOptions.head HTML, and the CSRF meta follows <meta charset> and default tags (viewport and icon) not replaced by the application. The useHead priority and deduplication described in framework.md are stable.
• app/:
  • app.meeko, error.meeko, pages/, layouts/default.meeko, middleware/, components/, composables/, utils/, stores/ and styles/main.css;
  • index.meeko, [id].meeko, [...slug].meeko pages and (group) groups, with +layout.meeko, +error.meeko and route options in <script server> or *.route.ts sidecars;
  • since 1.5, named layouts layouts/<nombre>.meeko (including subfolders: layouts/admin/panel.meeko is "admin/panel"), selected by pages through layout in definePage, and +group.ts files in pages folders, with literal export default defineGroup({ layout, layoutProps });
  • since 1.6, named middleware: a middleware/ file with defineRouteMiddleware(fn, { global: false }), named by its path without .ts or each part's numeric ordering prefix (10-auth.ts is "auth"), requested by routes through middleware (a literal array of names, or false) in definePage and defineGroup. The order (global then route middleware, from outer +group.ts files to the page, without repetition) and a missing or global name stopping discovery are contractual;
  • since 1.6, server route middleware: middleware/*.server.ts whose default export is defineServerRouteMiddleware(...) (any other default export, or none, stops discovery), global or named with the same naming rule (auth.server.ts is "auth", and named auth.ts and auth.server.ts are duplicates). It is contractual that it never reaches the browser, runs on the server after all isomorphic middleware (global then named, then server middleware in the same order), in SSR and each navigation's data request, does not run on render: "client" or "prerender" pages, and requesting a named one on those pages stops discovery.
• server/:
  • api/ (<nombre>.<método>.ts), rpc/, socket/, middleware/ and utils/;
  • server/runtime.ts, whose default export is defineServerRuntime(...).
• shared/, public/, layers and modules.
• Since 1.5, the path aliases ~/ (project root), @/ (app/), #shared/ (shared/) and #server/ (server/, server code only), their scopes, lookup in the project followed by each layer, and the meeko.config.ts alias option (a prefix ending in / with a project folder or false). The precedence of project tsconfig.json paths and Vite resolve.alias over them, and a package.json imports with the same # prefix winning and disabling the alias, are contractual. The shape of paths in generated tsconfig files is not contractual.
• Since 1.2, app/plugins/*.ts in the application and its layers, with .client.ts (browser only, before hydration) and .server.ts (server only, once per page request) suffixes.
• The .client.ts, .server.ts and .shared.ts suffixes, and *.test.ts, *.spec.ts and *.d.ts exclusions. Since 1.6, an app/middleware/*.server.ts, ignored until 1.5, is server route middleware (see Approved exceptions).
• The api, rpc, socket, useSocket, useState, href and provideErrorHandler auto-imports, and since 1.1 onMounted, useApi, useRpcQuery and useRpcMutation, since 1.2 useRoute, useForm, useStorage, useApiMutation, useHead and useSeoMeta, since 1.4 useTheme, since 1.5 useId (from @meekojs/meeko), useLayout, defineGroup and ClientError and isClientError (only in components and app/ modules, not in server/, *.server.ts or route files), since 1.6 defineServerRouteMiddleware (in *.server.ts and all server/, like server definitions), and since 1.7 useNavigation, createRoot and defer (the latter in server code: <script server>, including inside route options, *.route.ts sidecars, server/ and *.server.ts) (a custom export with one of these names takes precedence over the framework's). Since 1.4, each auto-imported component's types: its tag name (the app/components and addComponentsDir naming rule, prefix included) followed by Props, Snippets, Models and Exposed (AppCardProps…), identical to its module's ComponentProps, ComponentSnippets, ComponentModels and ComponentExposed, including null, with the component's scope; a project auto-import with the same name takes precedence (see Each component's types). In top-level <script server> code, usePage, redirect and notFound can be used without imports, and since 1.2 so can useHead and useSeoMeta.
• The MEEKO_HOST, MEEKO_PORT (with PORT as a permanent fallback), MEEKO_PUBLIC_ORIGIN, MEEKO_HMR_PORT environment variables and, since 1.2, MEEKO_REDIS_URL, MEEKO_REDIS_PREFIX, MEEKO_SESSION_TTL, MEEKO_SESSION_SAMESITE and MEEKO_TRUST_PROXY, and since 1.8 the cloudflare value of MEEKO_TRUST_PROXY and MEEKO_TRUSTED_PROXIES (see Cloudflare Tunnel and Traefik), and the MEEKO_ prefix, reserved for variables Meeko reads. HOST and PUBLIC_ORIGIN are deprecated since 1.2.

Build outputs#

Also stable in the static site:

• <ruta>/index.html and <ruta>/index.meeko.json per page, 404.html, sitemap.xml and robots.txt at the root; since 1.7, a sitemap.xml <url> may carry <lastmod>, <changefreq> and <priority> (in that order, after <loc>), in all adapters;
• _headers (/* block) and _meeko/headers.conf (one add_header <Nombre> "<valor>" always; line per header), which conflict with a same-named public/ file.

Also stable in Cloudflare:

• the MEEKO_SOCKET binding;
• the meeko-socket-v1 migration, which is not renamed;
• the reservation of public/_meeko/;
• wrangler.jsonc fields belonging to Meeko.

The contents of chunks/, hashed filenames and the rest of .meeko/ are not public.

Network and persisted formats#

These formats support external clients, proxies, CSP and rolling deployments:

• Page payload. Version v: 2, with render, head (title and, since 1.1, description) and deferred:
  • the document carries it in <script id="meeko-payload" type="application/json">, inside HTML with <div id="app">;
  • navigation requests it with accept: application/meeko+json, and the response is application/meeko+json or, on a "stream" route, application/meeko+ndjson (payload on the first line and a { "deferred", "value" | "error" } value on each subsequent line); since 1.3, the static adapter client requests it as the <ruta>/index.meeko.json file, without accept;
  • since 1.3, a document with an error: true payload hydrates app/error.meeko at any URL, including one matching a route (a static host's 404.html);
  • with app/error.meeko, a URL without a route responds 404 with an error: true payload, without route and with { status, message } props;
  • since 1.1, the optional resources field carries data from await useApi(...) and await useRpcQuery(...) read by rendering, as an object keyed by request. Those keys' format is internal and may change in any version: only server and browser of the same version interpret it. A payload without resources remains valid;
  • since 1.5, the optional layoutProps field carries props used by the server to render the page's named layout (from its +group.ts files, its layoutProps and anything written with useLayout()), and the route manifest (RouteRecord, ErrorPageRecord, .meeko/manifests/routes.json and that of virtual:meeko-manifest/client) carries the optional layout field ({ name, file, props? }). A payload or manifest without them remains valid. Since 1.6, the route manifest gains the optional middleware field, with the route's named middleware files in execution order, and the optional serverMiddleware field, with the full server middleware chain, global then named (the virtual:meeko-manifest/client manifest does not carry it); a manifest without them remains valid: its route executes global isomorphic middleware and no server middleware.
  • since 1.6, the optional url field carries the URL the document was rendered for (pathname and search, without origin or fragment); the browser hydrates useRoute() with it and then takes its own. A payload without url remains valid and hydrates with the browser URL.
• Streaming. The <script type="application/json" data-meeko-deferred="N"> blocks, direct children of <body> after #meeko-payload.
• Endpoints. /api/... according to server/api files, POST /_meeko/rpc/<ruta> with a JSON body and /_meeko/socket/<canal>?room=<sala>, whose text messages are { event, payload }. Errors have the { code, status, requestId } shape; since 1.2, a 400 for invalid input may add issues: [{ path, message }], and rateLimit responds 429 RATE_LIMITED with Retry-After in seconds. Since 1.2, retrySafe mutations and api.* and rpc.* calls with idempotencyKey send the Idempotency-Key header with a UUID as a Structured Fields string ("…"), and the server exposes it validated in RequestContext.idempotencyKey.
• Native forms. Since 1.7, an endpoint with form accepts application/x-www-form-urlencoded and multipart/form-data with reserved return and _csrf fields, and responds 303 See Other (except 403 INVALID_ORIGIN or INVALID_CSRF, with the usual error body). The new INVALID_FORM and FILES_NOT_ALLOWED (400) codes reach the page in the result.
• Headers:
  • x-meeko-csrf on mutations;
  • x-meeko-csrf-token and x-request-id on responses;
  • cache-control: no-store and x-accel-buffering: no on streams;
  • since 1.7, on a page with cache: weak ETag (W/"…"), Cache-Control: public, max-age=… (with no-transform on a stream), Vary: Accept, Cookie and 304 for If-None-Match.
• Meta and cookie. The meeko-csrf-token meta and session cookie, defaulting to __Host-meeko.sid (or meeko.sid without Secure) and configured with cookieName. Since 1.4, with theme, the theme cookie (meeko-theme by default, theme.cookie) and localStorage key (theme.storageKey) store the theme name or system as plain text. Since 1.7, the native forms' single-use cookie is named __Host-meeko-form (meeko-form without HTTPS), is HttpOnly and SameSite=Lax and lasts 60 seconds; its contents and the sharedState meeko:form:<ruta> key carrying it to the browser are internal: only server and browser of the same version interpret them.
• Theme. Since 1.4, with theme, server-rendered documents carry Vary: Cookie, Sec-CH-Prefers-Color-Scheme, Accept-CH: Sec-CH-Prefers-Color-Scheme and, when the choice is system, Critical-CH: Sec-CH-Prefers-Color-Scheme (without clientHints, only Vary: Cookie). A page payload reading the theme carries what the server rendered in the sharedState meeko:theme key.
• Socket.
  • Documented close codes: 1003, 1008, 1009, 1011 and 1013, and since 1.1 4401 (session rejected) and 4403 (channel authorization rejected).
  • Handshake responses: 400, 403 INVALID_ORIGIN, 404 and HTTP limit responses. Since 1.1, a session (401) or channel authorization (403) rejection completes the upgrade and immediately closes with 4401 or 4403, with a fixed reason and without calling handlers. See framework.md.
• Redis:
  • the <prefix>socket:<canal>:<sala> channel with the { v: 1, event, payload } envelope;
  • the <prefix>revoked revocation channel;
  • since 1.2, rateLimit counters in <prefix>ratelimit:<resumen> (the route and subject digest is not contractual);
  • session records written by RedisSessionStore and SqlSessionStore;
  • the D1SessionDriver.schema() reference schema and, since 1.7, that of D1SessionDriver.rateLimitSchema();
  • since 1.7, SQL rateLimit counter columns (key, window_ends_at and count) in the framework.md PostgreSQL reference schema. The counter key from which key is derived is not contractual: if it changes, counters restart.
• Prerendering. The prerender/manifest.json index ({ version: 1, pages }); since 1.3, each page has the optional scriptHashes field, the CSP 'sha256-…' sources of its inline scripts, and since 1.4 styleHashes, those of its inline <style> elements.

A minor may only add optional fields to these formats. It must accept anything written by any earlier 1.x and does not change a format's version. During a rolling deployment, instances of two minors may coexist with the same Redis or database. An application's browser and server must come from the same build; a payload with another version is rejected with an explicit message.

DevTools and editor#

• DevTools protocol 1.
  • The window.__MEEKO_DEVTOOLS__ hook (development only), with protocolVersion: 1.
  • Its snapshot, subscribe, select, highlight, setBreakpoint and setSignal methods.
  • Root Devtools* types.
  • A minor may add fields or event types. Moving to another protocol version requires a major. The Chrome extension maintains its own version number.
  • Since 1.1, DevtoolsInstance has the optional signalSites field (DevtoolsSignalSite type), with each signal's declaration. It is a field added within protocol 1: a hook or snapshot without it remains valid.
• meeko.config.ts devtools option (since 1.8, additive). devtools: boolean | { panel?: boolean; position?: "bottom-right" | "bottom-left" | "top-right" | "top-left" } (MeekoDevtoolsConfig type) and mountDevtoolsPanel position (DevtoolsPanelPosition type). Defaults to false throughout 1.x: without the option, nothing changes. The panel exists only in meeko dev; never reaching meeko build, meeko start or a prerendered page is part of the contract. The panel's appearance, Alt+Shift+M shortcut and localStorage meeko:devtools-panel key are outside the contract and may change in a minor.
• Language server.
  • Starting with meeko lsp --stdio or meeko-language-server.
  • The trusted, projectContracts and diagnosticsDelay initializationOptions.
  • The standard LSP capabilities it advertises. A minor may add capabilities and quick fixes.

Outside the contract#

• @meekojs/meeko/internal. This is the contract between compiler and runtime. It is guaranteed only within the same exact version and may change in any patch. Do not import it manually. Since 1.5, the same applies to @meekojs/meeko/builtins/*, the compiled <MeekoThemeToggle>, <MeekoAwait>, <MeekoPopover> and <MeekoSelect> modules the compiler imports into components using those tags.
• Generated code and files.
  • Everything under .meeko/: types, manifests, entries, per-scope tsconfig files, intermediate builds and chunks/.
  • The contents of .meeko/styles/main.css, the processed global stylesheet meeko dev writes for the editor: it follows what Vite and PostCSS generate in development and may change in any version. Its path does remain throughout 1.x, so editor configuration naming it (css.styleSheets) keeps working. See framework.md.
  • Vite virtual modules (virtual:meeko-*).
  • JavaScript emitted by the compiler.
  • A custom entry importing these modules must pin the exact Meeko version.
• The editor bridge. The live-value protocol between browser, meeko dev and editor (HMR meeko:live* events, .meeko/dev/editor-bridge-<puerto>.json descriptors, one per development server, the /__meeko/editor-bridge route and its messages, including the alias field) is development-only and outside the public contract: it may change in any version. The VS Code extension ignores a descriptor with another protocol version. See devtools.md.
• Server logs in the browser. What meeko dev adds to forward server console output (since 1.3): <script type="application/json" data-meeko-server-logs> blocks, the devServerLogs field of navigation payloads, the HMR meeko:server-logs event, its /@id/__x00__meeko:server-logs* modules and the serialized value shape. They exist only in development, never in meeko build or meeko start, and may change in any version. The stable part is the dev.serverLogs option. See framework.md.
• Custom language server extensions. The meeko/executionZones LSP request and Meeko's custom semantic token modifiers (signal, computed, resource and reactive; modification is standard LSP) are internal to the VS Code extension, published alongside the server. They are not public contract: they may change or disappear in a minor. Another LSP client may use them but must tolerate those changes. See editors.md.
• Presentation. Error and diagnostic message text, DevTools panel HTML and styles, editor CodeLens, hover and zone titles, console output and log formatting.
• The repository. Examples, tests, benchmarks and scripts are not published to npm.
• Performance. Performance and size figures, which may improve or vary between versions.

Deprecation#

1. A public API is deprecated only in a minor release and always with a documented replacement, unless the functionality disappears completely; in that case, the reason is explained.
2. Deprecation is announced in the CHANGELOG, documentation and with @deprecated in JSDoc so the editor marks it.
3. Where feasible, deprecated use also emits a warning:
   • a meeko check or language server warning for syntax and conventions;
   • a development console warning, once per process, for runtime APIs.
4. Deprecated features keep working throughout 1.x and are only removed in the next major, whose migration guide covers them.

Deprecated APIs#

The theme system (theme, cookie, <head> script and icon rule, useTheme, useThemeToggle and POST /_meeko/theme) remains in core. Only the three tags are removed; the 1.8 guide explains their replacements.

The useSocket alias is the same function as useSocketClient, so it emits no console warning: the editor marks it through @deprecated. This does not affect the generated clients' useSocket("canal", opciones) auto-import, which is not deprecated. See framework.md.

byId segments construct the same requests as calling the segment and also emit no console warning: the editor strikes through each method called through them. The manifest's clientKey, createLocalCalls().api("users.byId", ...) and useApi do not change and are not deprecated. See framework.md.

An imported module or [módulo, opciones] in modules still loads the same way, with inline options merged after config[meta.configKey]; meeko dev, meeko build and meeko check write MEEK126 once per process and entry, and the editor marks it in meeko.config.*. A module without meta.configKey only receives options through [módulo, opciones]: its author must declare one before 2.0. @meekojs/i18n/module (and @meekojs/meeko/i18n/module) are not deprecated: they are the subpath resolved by '@meekojs/i18n'; only importing them in meeko.config.ts is deprecated. See Upgrade from 1.7 to 1.8.

A layer folder listed in modules still applies as a layer, in the same position as before, and meeko dev, meeko build and meeko check write a warning once per process. extends is not deprecated: it is an alias for layers. See framework.md.

MEEK128, MEEK129 and MEEK130 are only meeko check and editor warnings: in 1.x, they do not change SSR, hydration or generated code, and meeko check does not fail because of them. MEEK128 resolves names with the TypeScript checker (a local window variable is not the global) and does not warn if cleanup, or its registration, is guarded by typeof <global> or import.meta.env.SSR, or inside onMounted, an event handler or the continuation after the first browser await. In 2.0, all three will be errors.

MEEK122 is only a meeko check, meeko build and editor warning: in 1.x, it does not change SSR, hydration or generated code, and the value is written the same way. In 2.0, a literal outside AttributeValues<Tag, Name> in an attribute with a closed set of values will be an error; a computed string will remain accepted.

MEEK107 is only a meeko check, meeko build and language server warning: in 1.x, it does not change SSR, hydration or generated code, and an unbranded string is still inserted the same way. In 2.0, the html value will have to be assignable to TrustedHtml | null | undefined and the warning will become an error. Text literal types (html="'<br>'") remain accepted. See api.md.

MEEK109 is only a meeko check, meeko build and language server warning, and generated code does not change in 1.x. These uses compile and load in the browser, but do nothing (definePage outside <script server> and sidecars does not configure the route) or fail when called there (adapter, /password and /build functions need Node, Bun or Deno). What already failed before 1.3 is directly the MEEK108 error: a server auto-import did not resolve in the browser bundle, @meekojs/meeko/server and /cloudflare cannot load there (they create a node:async_hooks AsyncLocalStorage), a server/ import stopped meeko build, and macros and onMounted do not exist outside <script>. See framework.md.

HOST and PUBLIC_ORIGIN are read only when MEEKO_HOST or MEEKO_PUBLIC_ORIGIN is missing, and then meeko dev, start, preview and meeko build outputs write a warning once per process naming the new variable. See framework.md.

A vulnerability that cannot be fixed compatibly is the only exception. In that case, the minimum necessary change may ship in a patch or minor release, with its explanation and migration in the CHANGELOG.

Planned changes for 2.0#

Besides removing deprecated features, 2.0 will change these defaults. In 1.x, you can enable each early with its option.

With "matched", a class or attribute the script adds through the DOM API to an element without ref: or on: stops receiving scoped styles if that element was left without the attribute. See api.md.

Supported environments#

The table's Bun, Deno and workerd versions are the tested ones. They may be updated in a minor release and the CHANGELOG states it. Dropping Node 24 support requires a major.

Browsers#

The runtime is published compiled to ES2022, without polyfills. It uses, among others, Object.hasOwn, Array.prototype.at, MutationObserver, fetch with ReadableStream bodies (navigation to "stream" routes) and WebSocket (Socket). An application's client bundle uses Vite 8's default target, baseline-widely-available. Browsers meeting that target are supported.

E2E tests run with Chrome and Playwright's Chromium, Firefox and WebKit. Playwright WebKit is not equivalent to testing real Safari.

Security#

Report vulnerabilities privately through the Security tab of meekojs/meeko, never in a public issue. SECURITY.md details supported versions, what to include in the report and response timelines.

ESLint#

During Meeko 1.x, defineEslint sorts only imports by default, with perfectionist/sort-imports and perfectionist/sort-named-imports, warn level, autofix and ascending natural order. In 2.0, those two rules will become error. perfectionist: true also enables the recommended-natural set except sort-classes and sort-modules; that list is decided by the Perfectionist version the plugin pins. You can disable them all with perfectionist: false, turn one off with off or require error through rules; see Sort with Perfectionist, which also lists the cases where --fix changes behavior. Warnings can block CI using --max-warnings 0.