{ "schemaVersion": 1, "generatedAt": "canonical", "sources": [ { "id": "tavo-website", "kind": "website", "version": "workspace", "url": "https://tavojs.dev" }, { "id": "tavo-framework", "kind": "framework", "version": "1.0.2", "url": "https://github.com/tavojs/core" }, { "id": "tavo-cli", "kind": "cli", "version": "1.0.1", "url": "https://github.com/tavojs/core" }, { "id": "tavo-ui", "kind": "ui", "version": "1.0.1", "url": "https://github.com/tavojs/ui" } ], "documents": [ { "id": "getting-started:index", "section": "getting-started", "slug": "", "title": "Getting Started", "description": "Learn the Tavo.js application model from installation through production, one focused topic at a time.", "keywords": [ "getting started", "learn", "first app", "tutorial" ], "kind": "quickstart", "prerequisites": [ "HTML, CSS, TypeScript, and TSX fundamentals.", "Node.js 20.19+ or 22.12+, a terminal, an editor, and a modern browser." ], "outcomes": [ "Choose a task-first guide or follow the complete beginner learning path.", "Understand how Tavo.js separates routes, request data, local behavior, server work, and build output." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Build your first Tavo.js app", "href": "/docs/getting-started/first-app", "description": "Build one Project Dashboard from scaffold through CSR and SSR." } ], "canonicalPath": "/docs/getting-started", "sections": [ { "id": "prerequisites", "title": "Before you begin", "markdown": "These guides assume that you can read HTML, CSS, JavaScript or TypeScript, and TSX. You do not need previous Tavo.js experience. The examples use TypeScript, npm, and the generated project defaults.\n\n- Node.js 20.19+ or 22.12+ for development, builds, and server rendering.\n \n- A terminal and editor with TypeScript support.\n \n- A modern browser for the client application and development tools.\n \n\n**New to Tavo.js? Build one app first**\n\nFollow Build your first Tavo.js app for a cumulative path with a working checkpoint after every edit. The topic guides also stand alone when you need a specific answer." }, { "id": "application-model", "title": "The Tavo.js application model", "markdown": "Files define the route tree. Loaders and middleware prepare request-scoped data. Models and controllers own interactive behavior, while stores share client state. The same route tree can render on the server, in the browser, or as static output.\n\nTavo.js UI supplies accessible interface primitives and a project-owned theme. The framework CLI creates, inspects, validates, builds, and packages the application. The guides keep these responsibilities visible so convenience never hides the runtime boundary." }, { "id": "first-app-tutorial", "title": "Build one app from start to finish", "markdown": "Follow the dedicated first-app tutorial when you want one cumulative path with a checkpoint after every change. Its navigation stays focused on the app you are building.\n\n[\n\n## Build your first Tavo.js app\n\nBuild a Project Dashboard while learning routes, data, state, navigation, CSR, and SSR.Read guide →\n\n](/docs/getting-started/first-app)" }, { "id": "start", "title": "Start with a focused guide", "markdown": "[\n\n## Installation\n\nCreate an application, add Tavo.js UI, and run it locally.Read guide →\n\n](/docs/getting-started/installation)[\n\n## Project structure\n\nUnderstand the generated files and choose where feature code belongs.Read guide →\n\n](/docs/getting-started/project-structure)" }, { "id": "build", "title": "Build", "markdown": "[\n\n## Pages and layouts\n\nTurn files into typed routes, shared shells, and route-specific pending and error views.Read guide →\n\n](/docs/getting-started/pages-and-layouts)[\n\n## Linking and navigating\n\nMove through the route tree with responsive client navigation.Read guide →\n\n](/docs/getting-started/linking-and-navigating)[\n\n## Server and client execution\n\nChoose the correct runtime and keep hydration deterministic.Read guide →\n\n](/docs/getting-started/server-and-client-execution)[\n\n## Components, controllers, and stores\n\nStart with plain components, then add local behavior and shared state only when needed.Read guide →\n\n](/docs/getting-started/components-controllers-and-stores)" }, { "id": "data", "title": "Data", "markdown": "[\n\n## Fetching data\n\nLoad route-critical data with useful pending, error, and cancellation behavior.Read guide →\n\n](/docs/getting-started/fetching-data)[\n\n## Mutating data\n\nValidate, authorize, and commit server changes through actions.Read guide →\n\n](/docs/getting-started/mutating-data)[\n\n## Caching\n\nChoose static output and safe response-cache boundaries.Read guide →\n\n](/docs/getting-started/caching)[\n\n## Revalidating\n\nRefresh cached routes by time or application-owned tags.Read guide →\n\n](/docs/getting-started/revalidating)[\n\n## Error handling\n\nChoose route, global, and component-level recovery boundaries.Read guide →\n\n](/docs/getting-started/error-handling)" }, { "id": "interface", "title": "Interface", "markdown": "[\n\n## CSS and Tavo.js UI\n\nCombine local styles, design tokens, and accessible components.Read guide →\n\n](/docs/getting-started/css-and-tavo-ui)[\n\n## Image optimization\n\nDeliver stable, responsive local and remote images.Read guide →\n\n](/docs/getting-started/images)[\n\n## Font loading\n\nLoad local or external fonts without avoidable layout shift.Read guide →\n\n](/docs/getting-started/fonts)[\n\n## Metadata and social images\n\nDescribe routes for search engines, browsers, and social previews.Read guide →\n\n](/docs/getting-started/metadata-and-social-images)" }, { "id": "server", "title": "Server", "markdown": "[\n\n## Server routes\n\nExpose deliberate HTTP endpoints through the plugin boundary.Read guide →\n\n](/docs/getting-started/server-routes)[\n\n## Middleware\n\nRun request-aware checks before route resolution.Read guide →\n\n](/docs/getting-started/middleware)" }, { "id": "ship", "title": "Ship", "markdown": "[\n\n## Testing and diagnostics\n\nCatch failures at the fastest useful layer.Read guide →\n\n](/docs/getting-started/testing-and-diagnostics)[\n\n## Deploying\n\nMatch the build output to the runtime your application needs.Read guide →\n\n](/docs/getting-started/deploying)[\n\n## Upgrading\n\nUpdate the Tavo.js packages together and verify production behavior.Read guide →\n\n](/docs/getting-started/upgrading)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:first-app", "section": "getting-started", "slug": "first-app", "title": "Build your first Tavo.js app", "description": "Build a Project Dashboard while learning routes, loaders, local component state, controllers, Tavo.js UI, client navigation, CSR, and SSR.", "keywords": [ "first app", "quickstart", "project dashboard", "route loader", "createTavo", "TavoController" ], "kind": "quickstart", "prerequisites": [ "You can read HTML, CSS, TypeScript, and TSX; no Tavo.js experience is required.", "Node.js 20.19+ or 22.12+, npm, a terminal, and a code editor are available.", "Ports 5173 and 4174 are available, or you will use the URLs printed by the development servers." ], "outcomes": [ "Create a Tavo.js project and identify what the generated starter demonstrates.", "Add a file route with browser-safe loader data.", "Add local interactive state and named behavior with createTavo and TavoController.", "Verify the same route in client and server development modes." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Project structure", "href": "/docs/getting-started/project-structure", "description": "Learn which folders Tavo.js enforces and where application code belongs." }, { "title": "Server and client execution", "href": "/docs/getting-started/server-and-client-execution", "description": "Decide when data may run in both environments and when it must stay on the server." }, { "title": "Fetching data", "href": "/docs/getting-started/fetching-data", "description": "Replace local sample data with abortable network requests and explicit failure handling." } ], "canonicalPath": "/docs/getting-started/first-app", "sections": [ { "id": "before-you-begin", "title": "Before you begin", "markdown": "Quickstart · Runs in Browser, Server, Build\n\n### You will learn\n\n- Create a `Tavo.js` project and identify what the generated starter demonstrates.\n \n- Add a file route with browser-safe loader data.\n \n- Add local interactive state and named behavior with `createTavo` and `TavoController`.\n \n- Verify the same route in client and server development modes.\n \n\n### Starting point\n\n- You can read HTML, CSS, `TypeScript`, and TSX; no `Tavo.js` experience is required.\n \n- `Node.js 20.19+ or 22.12+`, `npm`, a terminal, and a code editor are available.\n \n- Ports 5173 and 4174 are available, or you will use the URLs printed by the development servers." }, { "id": "mental-model", "title": "Start with the application model", "markdown": "A `Tavo.js` application is a `TypeScript` program with a file-based route tree. A page file owns one URL, its loader prepares route data, and its TSX component renders that data. `createTavo` adds local reactive state when a view becomes interactive, while a `TavoController` gives that interaction named behavior.\n\nYou will build one feature in small working increments. Run the checkpoint after each increment before continuing; when something breaks, you then know which edit introduced it.\n\n**What this quickstart leaves for later**\n\nActions, authentication, caching, custom plugins, and deployment are separate guides. The first app stays focused on the route and rendering model you need before those topics." }, { "id": "create-project", "title": "1. Create and inspect the starter", "markdown": "Create a project named `project-dashboard`, install its declared dependencies, and start the client development server.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnode --version\nnpx @tavojs/cli create app project-dashboard\ncd project-dashboard\nnpm install\nnpm run dev\n```\n\n**Checkpoint**\n\n**Expected:** The URL printed by Vite opens the generated counter. Increment, decrement, reset, and theme controls update immediately.\n\n**If it does not work:** If Vite rejects the Node version, install Node.js 20.19+ or 22.12+, remove the incomplete node\\_modules directory, and run npm install again.\n\nThe starter already demonstrates `Tavo.js` local state: `src/pages/index.tsx` defines a model and updates it with `model.patch()`. Keep that page and `src/styles.css`; the next steps add a second route without discarding the working starter. After trying the controls, stop the server with Ctrl+C before installing the next dependency." }, { "id": "add-ui", "title": "2. Add Tavo.js UI through its plugin", "markdown": "Install the component package and ask its bundled `tavo-ui` command to create the project theme configuration. `@tavojs/ui-cli` is already a dependency of `@tavojs/ui`; do not install or version it separately.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpm install @tavojs/ui\nnpx tavo-ui web init\n```\n\nMerge `tavoUi()` into the configuration generated by the `Tavo.js` CLI. Keep `src/styles.css`, diagnostics, build settings, and every existing plugin. The UI plugin generates and injects theme variables during development and production builds, so this path does not add a generated theme file to `cssEntries`.\n\nMerge into `tavo.config.ts`\n\n**Merge tavo.config.ts**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\nimport { tavoUi } from \"@tavojs/ui/plugin\";\n\nexport default defineConfig({\n pagesDir: \"src/pages\",\n cssEntries: [\"src/styles.css\"],\n diagnostics: {\n devOverlay: true,\n traces: false,\n },\n plugins: [tavoUi()],\n});\n```\n\n**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpx tavo-ui web check\nnpm run typecheck\nnpm run dev\n```\n\n**Expected:** The theme check reports success, TypeScript completes without errors, and Vite starts the client application again.\n\n**If it does not work:** If tavo-ui cannot find a config, confirm that the init command created tavo-ui.config.ts in the project root. If the page loses its starter styling, restore src/styles.css in cssEntries." }, { "id": "create-route", "title": "3. Create the projects route", "markdown": "Create `src/pages/projects/index.tsx`. The path below is special: every non-underscore `TypeScript` or TSX module inside `src/pages` is treated as a route module. This file therefore creates `/projects`.\n\nStart with a plain TSX function. A page does not need a model, controller, store, or loader until its behavior requires one.\n\nCreate `src/pages/projects/index.tsx`\n\n**Create src/pages/projects/index.tsx**\n\n```tsx\nimport { Card, Page, Stack, Text } from \"@tavojs/ui\";\n\nexport default function ProjectsPage() {\n return (\n \n \n \n Project dashboard\n \n \n Make the learning path clear for a new Tavo.js developer.\n \n \n \n );\n}\n```\n\n**Checkpoint**\n\n**Expected:** With npm run dev still running, http://localhost:5173/projects shows the Project dashboard heading and one Documentation card.\n\n**If it does not work:** If Tavo.js reports that a page module has no default component, check the default export and confirm the file is named index.tsx inside src/pages/projects." }, { "id": "load-data", "title": "4. Load browser-safe route data", "markdown": "Create a normal source module for data that is safe to include in a browser bundle. This example contains public sample records—no database client, secret, session, or private API key.\n\nCreate `src/data/projects.ts`\n\n**Create src/data/projects.ts**\n\n```ts\nexport type Project = {\n id: string;\n name: string;\n summary: string;\n active: boolean;\n};\n\nexport const projects: Project[] = [\n {\n id: \"docs\",\n name: \"Documentation\",\n summary: \"Make the learning path clear for a new Tavo.js developer.\",\n active: true,\n },\n {\n id: \"website\",\n name: \"Website\",\n summary: \"Ship the next public release.\",\n active: true,\n },\n {\n id: \"mobile\",\n name: \"Mobile\",\n summary: \"Plan a later product experiment.\",\n active: false,\n },\n];\n```\n\nAdd a named `load` export to the functional route module. Its result becomes `data` for the default page component. Because this loader imports browser-safe data, it can run during both client navigation and SSR.\n\nReplace `src/pages/projects/index.tsx`\n\n**Replace src/pages/projects/index.tsx**\n\n```tsx\nimport type { PageProps } from \"@tavojs/core/router\";\nimport { Card, Grid, Page, Stack, Text } from \"@tavojs/ui\";\nimport { projects, type Project } from \"../../data/projects\";\n\ntype ProjectsData = { projects: Project[] };\n\nexport function load(): ProjectsData {\n return { projects };\n}\n\nexport default function ProjectsPage({ data }: PageProps) {\n return (\n \n \n \n Project dashboard\n \n \n {data?.projects.map((project) => (\n \n {project.summary}\n \n ))}\n \n \n \n );\n}\n```\n\n**Checkpoint**\n\n**Expected:** The projects route now shows Documentation, Website, and Mobile cards. A refresh keeps the same result.\n\n**If it does not work:** If the import cannot be resolved, check that projects.ts is under src/data and that the route uses the relative path ../../data/projects." }, { "id": "add-state", "title": "5. Add local state and a controller", "markdown": "The filter belongs only to the dashboard currently on screen, so local model state is the narrowest owner. The controller gives each transition a clear name: `showAll()` and `showActive()` patch the model, while the view reads `state.filter` and delegates button events to those methods.\n\nCreate the component below. Pass `ProjectDashboardController` as the third `createTavo` type argument and register it with the `controller` option. `Tavo.js` creates the controller with access to the component model and disposes it with the mounted component.\n\nCreate `src/components/ProjectDashboard.tsx`\n\n**Create src/components/ProjectDashboard.tsx**\n\n```tsx\nimport { createTavo, TavoController } from \"@tavojs/core\";\nimport { Button, Card, Grid, Inline, Stack, Text } from \"@tavojs/ui\";\nimport type { Project } from \"../data/projects\";\n\ntype ProjectFilter = \"all\" | \"active\";\ntype ProjectDashboardProps = { projects: Project[] };\ntype ProjectDashboardState = { filter: ProjectFilter };\n\nclass ProjectDashboardController extends TavoController {\n showAll() {\n this.model.patch({ filter: \"all\" });\n }\n\n showActive() {\n this.model.patch({ filter: \"active\" });\n }\n}\n\nexport const ProjectDashboard = createTavo<\n ProjectDashboardProps,\n ProjectDashboardState,\n ProjectDashboardController\n>({\n model: () => ({ filter: \"all\" }),\n controller: ProjectDashboardController,\n view: ({ props, state, controller }) => {\n const visibleProjects = props.projects.filter(\n (project) => state.filter === \"all\" || project.active,\n );\n\n return (\n \n \n controller?.showAll()}\n >\n All projects\n \n controller?.showActive()}\n >\n Active projects\n \n \n \n Showing {visibleProjects.length} of {props.projects.length} projects\n \n \n {visibleProjects.map((project) => (\n \n \n {project.summary}\n \n {project.active ? \"Active\" : \"Planned\"}\n \n \n \n ))}\n \n \n );\n },\n});\n```\n\nReplace the route one final time so the loader still owns project data, the dashboard model owns the current filter, and the controller owns the filter-changing behavior. This separation prevents request data from being copied into a global client store.\n\nReplace `src/pages/projects/index.tsx`\n\n**Replace src/pages/projects/index.tsx**\n\n```tsx\nimport type { PageProps } from \"@tavojs/core/router\";\nimport { Page, Stack, Text } from \"@tavojs/ui\";\nimport { ProjectDashboard } from \"../../components/ProjectDashboard\";\nimport { projects, type Project } from \"../../data/projects\";\n\ntype ProjectsData = { projects: Project[] };\n\nexport function load(): ProjectsData {\n return { projects };\n}\n\nexport default function ProjectsPage({ data }: PageProps) {\n return (\n \n \n \n Project dashboard\n \n \n Route data supplies the projects. Local model state controls the\n visible filter.\n \n \n \n \n );\n}\n```\n\n**Checkpoint**\n\n**Expected:** All projects shows three cards. Active projects shows two cards, updates the count, and marks the selected button with aria-pressed.\n\n**If it does not work:** If clicking does nothing, confirm the component registers ProjectDashboardController, passes it as the third createTavo type argument, and calls the controller methods from the button handlers." }, { "id": "add-navigation", "title": "6. Link the starter to the dashboard", "markdown": "Create a small navigation component with the `Tavo.js` router `Link`. A link represents a destination and lets the pages runtime coordinate history, focus, scroll, loaders, and cancellation.\n\nCreate `src/components/ProjectDashboardLink.tsx`\n\n**Create src/components/ProjectDashboardLink.tsx**\n\n```tsx\nimport { Link } from \"@tavojs/core/router\";\n\nexport function ProjectDashboardLink() {\n return Open the project dashboard;\n}\n```\n\nUpdate the generated home page in two small places while keeping the counter and its original styles intact. First, add this import beside the existing imports at the top of the file.\n\nUpdate `src/pages/index.tsx`\n\n**Patch src/pages/index.tsx**\n\n```tsx\nimport { ProjectDashboardLink } from \"../components/ProjectDashboardLink\";\n```\n\nNext, replace the existing one-line `app-footer` with this expanded footer.\n\nUpdate `src/pages/index.tsx`\n\n**Patch src/pages/index.tsx**\n\n```tsx\n
\n \n Built with Tavo.js\n src/pages/index.tsx\n
\n```\n\n**Checkpoint**\n\n**Expected:** Open http://localhost:5173, activate Open the project dashboard, and confirm the URL changes to /projects without a full document reload.\n\n**If it does not work:** If the link renders but navigation fails, verify that it imports Link from @tavojs/core/router and uses the to prop rather than href." }, { "id": "verify-rendering", "title": "7. Verify client and server rendering", "markdown": "You have been using client-side rendering (CSR): Vite serves the document shell and the browser resolves the route. Stop that server, then start `Tavo.js`'s server-side rendering (SSR) development mode.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\n# Stop the CSR server with Ctrl+C, then run:\nnpm run dev:ssr\n\n# In another terminal, inspect the server-rendered HTML:\ncurl http://localhost:4174/projects\n```\n\n**Checkpoint**\n\n**Expected:** The curl response contains Project dashboard, and http://localhost:4174/projects hydrates into the same interactive filter in the browser.\n\n**If it does not work:** If port 4174 is occupied, use the URL printed by the SSR server for both the browser and curl. A hydration warning usually means the first browser render differs from the server HTML." }, { "id": "result", "title": "What you built", "markdown": "Inspect `Final project tree`\n\n**Reference Final project tree**\n\n```text\nproject-dashboard/\n├── src/\n│ ├── components/\n│ │ ├── ProjectDashboard.tsx local filter model, controller, and UI\n│ │ └── ProjectDashboardLink.tsx client navigation\n│ ├── data/\n│ │ └── projects.ts browser-safe sample data\n│ ├── pages/\n│ │ ├── index.tsx generated starter plus dashboard link\n│ │ └── projects/\n│ │ └── index.tsx /projects route and loader\n│ └── styles.css preserved starter styles\n├── tavo-ui.config.ts project theme input\n└── tavo.config.ts framework and UI plugin configuration\n```\n\nThe route owns URL-level data and composition. The dashboard model owns state used only by that mounted view, and its controller owns named state transitions. The data module is ordinary browser-safe `TypeScript`. The UI plugin owns theme generation while the existing stylesheet remains part of the application." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Project structure\n\nLearn which folders Tavo.js enforces and where application code belongs.Read guide →\n\n](/docs/getting-started/project-structure)[\n\n## Server and client execution\n\nDecide when data may run in both environments and when it must stay on the server.Read guide →\n\n](/docs/getting-started/server-and-client-execution)[\n\n## Fetching data\n\nReplace local sample data with abortable network requests and explicit failure handling.Read guide →\n\n](/docs/getting-started/fetching-data)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:installation", "section": "getting-started", "slug": "installation", "title": "Installation", "description": "Create a Tavo.js application, add the integrated UI system, and run both client and server development modes.", "keywords": [ "install", "create app", "Node.js", "dev server" ], "kind": "guide", "prerequisites": [ "Node.js 20.19+ or 22.12+, npm, a terminal, and a TypeScript-capable editor.", "An empty parent directory in which the CLI may create project-dashboard." ], "outcomes": [ "Create and run the generated Tavo.js starter.", "Install @tavojs/ui and initialize its bundled theme CLI.", "Merge the UI plugin without removing starter styles or diagnostics.", "Start both client and server development modes." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Project structure", "href": "/docs/getting-started/project-structure", "description": "Learn what the generated files own." }, { "title": "Tavo.js UI installation", "href": "/docs/ui/installation", "description": "Review theme and package options in depth." } ], "canonicalPath": "/docs/getting-started/installation", "sections": [ { "id": "requirements", "title": "Check the development environment", "markdown": "Use `Node.js` 20.19 or newer (or 22.12 or newer) for `Tavo.js` development, builds, and server rendering. The application uses `TypeScript` and `npm` by default, but the CLI can record another package manager when your team has standardized on one.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnode --version\nnpm --version\n```" }, { "id": "create", "title": "Create the application", "markdown": "The create command writes the route directory, application entry, `TypeScript` and Vite configuration, development scripts, starter page, and agent-facing project guidance. Install dependencies after reviewing the target directory.\n\nOpen the URL printed by Vite and try the counter. Stop the development server with Ctrl+C before continuing to the installation commands below.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx @tavojs/cli create app project-dashboard\ncd project-dashboard\nnpm install\nnpm run dev\n```\n\n**Generated files are a starting point**\n\nThe CLI protects existing files by default. Use force only when you have deliberately reviewed the files that will be replaced.\n\n**Checkpoint**\n\n**Expected:** The URL printed by Vite opens the generated counter, and its counter and theme controls update immediately.\n\n**If it does not work:** If Vite rejects the Node version, install Node.js 20.19+ or 22.12+, reinstall the dependencies, and rerun npm run dev. Stop the working server with Ctrl+C before continuing." }, { "id": "package-managers", "title": "Use the team's package manager", "markdown": "The rest of this guide uses `npm` and runs project-local tools with `npx tavo` and `npx tavo-ui`. The equivalents are `pnpm exec tavo`, `yarn tavo`, or `bunx tavo` for the framework and `pnpm exec tavo-ui`, `yarn tavo-ui`, or `bunx tavo-ui` for UI tooling." }, { "id": "ui", "title": "Add Tavo.js UI", "markdown": "`Tavo.js` Framework owns routing, data, rendering, and application behavior. `Tavo.js` UI supplies interface components and project theme tooling. Install `@tavojs/ui`, then initialize its theme configuration.\n\nThe `tavo-ui` command comes with `@tavojs/ui` through its package dependencies. Do not install or independently version `@tavojs/ui-cli` in the application.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpm install @tavojs/ui\nnpx tavo-ui web init\n```" }, { "id": "configuration", "title": "Enable plugin-based theme generation", "markdown": "Merge `tavoUi()` into the generated configuration. Keep `src/styles.css`, diagnostics, build options, and every existing plugin. During development and production builds, the plugin reads the default `tavo-ui.config.ts` file and injects the generated theme variables; no generated theme file belongs in `cssEntries` for this setup.\n\nMerge into `tavo.config.ts`\n\n**Merge tavo.config.ts**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\nimport { tavoUi } from \"@tavojs/ui/plugin\";\n\nexport default defineConfig({\n pagesDir: \"src/pages\",\n cssEntries: [\"src/styles.css\"],\n diagnostics: {\n devOverlay: true,\n traces: false,\n },\n plugins: [tavoUi()],\n});\n```\n\n**Merge; do not replace**\n\nThe example repeats the generated pages, styles, and diagnostics to make the final shape clear. If your configuration already contains other settings or plugins, preserve them and add `tavoUi()` to the existing plugins array." }, { "id": "verify", "title": "Verify both rendering modes", "markdown": "The standard development command is the fastest client iteration loop. Use SSR development as soon as you add server loaders, actions, middleware, sessions, or request-time metadata.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpm run dev\n# Stop the CSR server, then start SSR development:\nnpm run dev:ssr\n```\n\n**Use the project-local CLI**\n\nKeep stable commands in package scripts or run them through `npx` so contributors and CI use the version declared by the application.\n\n**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpx tavo-ui web check\nnpm run typecheck\n```\n\n**Expected:** The theme check passes, TypeScript reports no errors, and both development modes print a local URL.\n\n**If it does not work:** If starter styling disappears, restore src/styles.css in cssEntries. If the theme config is missing, rerun the init command from the project root.\n\nLearn more\n\n- [Server and client execution](/docs/getting-started/server-and-client-execution) — Understand which code runs in each rendering mode and where private work belongs." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Project structure\n\nLearn what the generated files own.Read guide →\n\n](/docs/getting-started/project-structure)[\n\n## Tavo.js UI installation\n\nReview theme and package options in depth.Read guide →\n\n](/docs/ui/installation)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:project-structure", "section": "getting-started", "slug": "project-structure", "title": "Project structure", "description": "Understand the generated application shape and organize route, feature, server, and asset code deliberately.", "keywords": [ "folders", "files", "src", "pages", "configuration" ], "kind": "concept", "prerequisites": [ "A project created with `tavo create app`.", "The project is open in an editor so you can compare its tree with this guide." ], "outcomes": [ "Recognize the files created by the Tavo.js CLI.", "Know which files inside src/pages become public routes.", "Keep private modules inside the enforced src/server boundary.", "Choose simple shared and feature folders without inventing framework rules." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Pages and layouts", "href": "/docs/getting-started/pages-and-layouts", "description": "Turn the route tree into application UI." }, { "title": "Create and generate", "href": "/docs/cli/create-and-generate", "description": "Use the CLI to add files that follow these conventions." } ], "canonicalPath": "/docs/getting-started/project-structure", "sections": [ { "id": "generated-files", "title": "Read the generated project", "markdown": "The scaffold keeps configuration at the project root and application code under `src`. `Tavo.js` gives two source locations special safety or routing behavior: `src/pages` defines the route tree, and `src/server` is blocked from client bundles. Other source folders are application organization.\n\nInspect `Project tree`\n\n**Reference Project tree**\n\n```text\nproject-dashboard/\n├── public/ static browser assets\n├── src/\n│ ├── pages/ file-based routes and layouts\n│ ├── server/ enforced server-only modules, when needed\n│ ├── components/ reusable interface and behavior\n│ ├── store/ shared client state\n│ ├── main.tsx browser bootstrap\n│ └── styles.css application-wide styles\n├── index.html document shell\n├── tavo.config.ts framework and plugin settings\n├── tavo-ui.config.ts project theme input, after UI setup\n├── tsconfig.json TypeScript contract\n└── vite.config.ts build integration\n```" }, { "id": "route-conventions", "title": "Know which names affect routing", "markdown": "Every non-underscore `TypeScript` or TSX module inside `src/pages` is treated as a route module. Normal folders add URL segments. Brackets create parameters, three dots create catch-all parameters, and parentheses group files without adding a public segment. A `_layout.tsx` file wraps its descendants.\n\nDo not place ordinary helpers, services, stores, or components in `src/pages` with a normal filename: `Tavo.js` will try to load them as routes. Move them to another source folder, or use an underscore-prefixed private file only for a small route-local helper.\n\nInspect `src/pages`\n\n**Reference src/pages**\n\n```text\nindex.tsx → /\nprojects/index.tsx → /projects\nprojects/[id].tsx → /projects/:id\ndocs/[[...slug]].tsx → /docs/*?slug\n(marketing)/about.tsx → /about\nprojects/_layout.tsx → wraps /projects and descendants\nprojects/_format.ts → private helper; not a route\nprojects/format.ts → route module; do not use as a helper\n```\n\nLearn more\n\n- [Pages and layouts](/docs/getting-started/pages-and-layouts) — See these route conventions in typed page and layout examples." }, { "id": "organization", "title": "Decide where each file belongs", "markdown": "`src/pages` and `src/server` have framework meaning. Names such as `components` and `features` do not: they are folders you create to make browser-safe and shared code easy to find.\n\nStart with the simple structure below. A route file loads the data for its URL and assembles the page. Move code out of that file when it becomes reusable or when it must stay on the server.\n\n- Used by one route? Keep it next to that route until the file becomes hard to read.\n \n- Used by several routes? Move it to `src/components`, `src/features`, or another clearly named shared folder.\n \n- Uses a database, secret, session, or private API key? Put it in `src/server`. `Tavo.js` treats that directory as server-only and blocks imports that reach a client bundle.\n \n- Needed directly by the browser, such as an image or font? Put it in `public`; `public/logo.svg` is available at `/logo.svg`.\n \n- Found in `.tavo/build` or `.tavo/generated`? Do not edit it. `Tavo.js` recreates generated files.\n \n\nInspect `One possible structure`\n\n**Reference One possible structure**\n\n```text\nsrc/\n├── pages/\n│ └── projects/\n│ └── [id].tsx route for /projects/:id\n├── features/\n│ └── projects/\n│ └── ProjectCard.tsx UI used by project routes\n├── components/\n│ └── PageHeader.tsx UI reused across the app\n└── server/\n └── projects.ts database code; never imported by browser code\n\npublic/\n└── logo.svg available in the app as /logo.svg\n```\n\n**You do not need the final folder structure on day one**\n\nBegin with `src/pages`, a shared `src/components` folder, and `src/server` if the application has private server code. Add feature folders only when they make files easier to find.\n\nLearn more\n\n- [Server and client execution](/docs/getting-started/server-and-client-execution#server-boundary) — Learn what a server-only loader is and how to protect private dependencies.\n \n- [Fetching data](/docs/getting-started/fetching-data#route-loaders) — Learn how page and layout loaders provide route data.\n \n- [Mutating data](/docs/getting-started/mutating-data) — Learn how server actions validate, authorize, and commit changes.\n \n- [Middleware](/docs/getting-started/middleware#server-only) — Learn how server-only middleware handles sessions and private request checks." }, { "id": "verify-structure", "title": "Check the route boundary", "markdown": "Use the CLI to inspect the route tree after adding or moving page files. The output should contain only URLs that the application intentionally exposes.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tavo routes\nnpm run typecheck\n```\n\n**Checkpoint**\n\n**Expected:** The route list contains the intended pages and no helper filenames, and TypeScript reports no errors.\n\n**If it does not work:** If a helper appears as a route, move it outside src/pages or prefix its filename with an underscore. If a client build reports a server-only import, move the private call behind a server loader, action, middleware, or server route." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Pages and layouts\n\nTurn the route tree into application UI.Read guide →\n\n](/docs/getting-started/pages-and-layouts)[\n\n## Create and generate\n\nUse the CLI to add files that follow these conventions.Read guide →\n\n](/docs/cli/create-and-generate)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:pages-and-layouts", "section": "getting-started", "slug": "pages-and-layouts", "title": "Pages and layouts", "description": "Turn the file tree into typed routes, nested application shells, and route-specific loading and error states.", "keywords": [ "pages", "layouts", "dynamic routes", "file based route page", "defineRoutePage", "typed routes", "pending", "PagePendingProps", "PageErrorProps", "404", "error" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Turn the file tree into typed routes, nested application shells, and route-specific loading and error states." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Core pages and layouts", "href": "/docs/core/pages-and-layouts", "description": "Review the full route and layout contract." }, { "title": "Linking and navigating", "href": "/docs/getting-started/linking-and-navigating", "description": "Connect the routes with client navigation." } ], "canonicalPath": "/docs/getting-started/pages-and-layouts", "sections": [ { "id": "pages", "title": "Create a functional page", "markdown": "A page module describes one public route. The default function renders resolved page props, while optional named exports such as `load`, `pending`, `error`, `action`, `middleware`, `head`, and rendering or caching exports add route behavior. The file path remains the source of the public URL.\n\nCreate `src/pages/projects/[id].tsx`\n\n**Create src/pages/projects/[id].tsx**\n\n```tsx\nimport type { PageLoadContext, PageProps } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string };\ntype ProjectParams = { id: string };\n\nexport async function load({\n params,\n signal,\n url,\n}: PageLoadContext): Promise {\n const response = await fetch(\n new URL(`/api/projects/${encodeURIComponent(params.id)}`, url),\n { signal },\n );\n if (!response.ok) throw new Error(\"Project could not be loaded\");\n return response.json() as Promise;\n}\n\nexport default function ProjectPage({\n data,\n}: PageProps) {\n return (\n \n \n {data?.name}\n \n \n );\n}\n```\n\n**Keep route work abortable**\n\nNavigation supplies an `AbortSignal` to loaders. Pass it to `fetch` and downstream clients so an abandoned route cannot publish stale data." }, { "id": "route-aware-typing", "title": "Add route-aware typing when it helps", "markdown": "`defineRoutePage` is an optional helper for keeping the loader, page component, and other route behaviors in one typed object. Its path literal infers dynamic parameters such as `id` and connects the loader data type to the default page.\n\nThe file tree still owns routing. The helper does not register or rename a route, so keep its path literal aligned with the page filename and confirm the result with `npx tavo routes`.\n\nCreate `src/pages/projects/[id].tsx`\n\n**Create src/pages/projects/[id].tsx**\n\n```tsx\nimport { defineRoutePage } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string };\n\nexport default defineRoutePage<\"/projects/[id]\", Project>(\"/projects/[id]\", {\n load: async ({ params, signal, url }) => {\n const response = await fetch(\n new URL(`/api/projects/${encodeURIComponent(params.id)}`, url),\n { signal },\n );\n if (!response.ok) throw new Error(\"Project could not be loaded\");\n return response.json() as Promise;\n },\n\n default: function ProjectPage({ data }) {\n return (\n \n \n {data?.name}\n \n \n );\n },\n});\n```\n\n**The functional module remains the default**\n\nUse named exports for the clearest general-purpose page contract. Reach for `defineRoutePage` when its route-aware inference or grouped object form improves the page; the CLI offers it explicitly through `npx tavo generate page 'projects/[id]' --typed-route`." }, { "id": "layouts", "title": "Share UI with layouts", "markdown": "A `_layout.tsx` file wraps every descendant page. Layouts compose from the root toward the leaf, so the root can own global navigation while a projects layout owns project-specific navigation and shared data.\n\nCreate `src/pages/projects/_layout.tsx`\n\n**Create src/pages/projects/_layout.tsx**\n\n```tsx\nimport type { Child } from \"@tavojs/core\";\nimport { Link } from \"@tavojs/core/router\";\nimport { Box, Stack } from \"@tavojs/ui\";\n\nexport default function ProjectsLayout({ children }: { children?: Child }) {\n return (\n \n \n Projects\n {children}\n \n \n );\n}\n```" }, { "id": "route-loading-and-errors", "title": "Add route-specific loading and error UI", "markdown": "Export `pending` when a client navigation should replace the previous page with immediate route-specific feedback while the page loader runs. Export `error` when that page should own a contextual loader-failure view. Both exports are normal `Tavo.js` components and can be functions or components created with `createTavo()`.\n\nOn client navigation, `Tavo.js` resolves middleware and layout loaders first, renders `pending` inside the matched layouts, and then runs the page loader. The completed default page and its controller do not mount until the loader succeeds.\n\n- `PagePendingProps` provides the target pathname, params, resolved layout layers, and layer data. Page loader data is unavailable because it is still loading.\n \n- `PageErrorProps` adds `data` and `error` for the failed route. Present a safe message instead of rendering raw server details.\n \n- Use `aria-busy=\"true\"` and a useful accessible label for pending content. Use `role=\"alert\"` or an equivalent announcement strategy for errors.\n \n\nCreate `src/pages/dashboard.tsx`\n\n**Create src/pages/dashboard.tsx**\n\n```tsx\nimport type {\n PageErrorProps,\n PageLoadContext,\n PagePendingProps,\n PageProps,\n} from \"@tavojs/core/router\";\nimport { Page, Stack, Text } from \"@tavojs/ui\";\n\ntype DashboardData = {\n projects: Array<{ id: string; name: string }>;\n summary: { active: number };\n};\n\nexport function pending({ pathname }: PagePendingProps) {\n return (\n \n \n \n Loading dashboard…\n \n Preparing projects and their summary.\n \n \n );\n}\n\nexport function error({ pathname }: PageErrorProps) {\n return (\n \n \n \n Could not load the dashboard\n \n \n The data for {pathname} is unavailable. Try again.\n \n \n \n );\n}\n\nexport async function load({\n signal,\n url,\n}: PageLoadContext): Promise {\n const [projectsResponse, summaryResponse] = await Promise.all([\n fetch(new URL(\"/api/projects\", url), { signal }),\n fetch(new URL(\"/api/projects/summary\", url), { signal }),\n ]);\n if (!projectsResponse.ok || !summaryResponse.ok) {\n throw new Error(\"Dashboard data could not be loaded\");\n }\n return {\n projects: await projectsResponse.json(),\n summary: await summaryResponse.json(),\n } as DashboardData;\n}\n\nexport default function DashboardPage({ data }: PageProps) {\n return (\n \n \n Active projects: {data?.summary.active ?? 0}\n {data?.projects.map((project) => (\n {project.name}\n ))}\n \n \n );\n}\n```\n\n**Pending UI is a browser-navigation state**\n\nNormal SSR, static prerendering, prefetching, and navigation satisfied from a fresh route cache wait for or already have the completed route, so they do not render the `pending` export." }, { "id": "route-shapes", "title": "Use the route shape that matches the URL", "markdown": "Generate route types with a production build before relying on newly added dynamic paths throughout the application.\n\n- Use `[id]` for one required segment.\n \n- Use `[...slug]` for one-or-more catch-all segments.\n \n- Use `[[...slug]]` when the catch-all route also owns its base URL.\n \n- Use `(group)` folders to organize routes or apply alternate layouts without changing the URL." }, { "id": "failures", "title": "Provide route-level fallbacks", "markdown": "Add `src/pages/404.tsx` for URLs that do not match a route. Keep the message clear and provide a path back into the application.\n\nCreate `src/pages/404.tsx`\n\n**Create src/pages/404.tsx**\n\n```tsx\nimport { Link } from \"@tavojs/core/router\";\nimport { Page, Stack, Text } from \"@tavojs/ui\";\n\nexport const head = Page not found;\n\nexport default function NotFoundPage() {\n return (\n \n \n \n Page not found\n \n \n The page may have moved or the address may be incorrect.\n \n Return home\n \n \n );\n}\n```\n\nA page's `error` export is the first fallback for its page-loader failure. Add `src/pages/_error.tsx` as the application-wide fallback for routes that do not provide one. Show a stable recovery message without rendering server details, tokens, response bodies, or stack traces.\n\nCreate `src/pages/_error.tsx`\n\n**Create src/pages/_error.tsx**\n\n```tsx\nimport { Link } from \"@tavojs/core/router\";\nimport { Page, Stack, Text } from \"@tavojs/ui\";\n\nexport const head = Something went wrong;\n\nexport default function RouteErrorPage() {\n return (\n \n \n \n We could not load this page\n \n \n Try again, or return home if the problem continues.\n \n Return home\n \n \n );\n}\n```\n\n**Expected failures still belong in the page**\n\nA rejected form is normal application state. Use `notFound()` when route data is absent and should render `404.tsx`; it bypasses both route and global error views. Use a component `ErrorBoundary` for render-subtree failures." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Core pages and layouts\n\nReview the full route and layout contract.Read guide →\n\n](/docs/core/pages-and-layouts)[\n\n## Linking and navigating\n\nConnect the routes with client navigation.Read guide →\n\n](/docs/getting-started/linking-and-navigating)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:linking-and-navigating", "section": "getting-started", "slug": "linking-and-navigating", "title": "Linking and navigating", "description": "Move between routes while preserving browser history, focus, scroll position, and useful loading feedback.", "keywords": [ "Link", "router", "prefetch", "history", "scroll" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Move between routes while preserving browser history, focus, scroll position, and useful loading feedback." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Core routing", "href": "/docs/core/routing", "description": "See route status, prefetch, and standalone-router guidance." }, { "title": "Fetching data", "href": "/docs/getting-started/fetching-data", "description": "Understand the work that navigation owns." } ], "canonicalPath": "/docs/getting-started/linking-and-navigating", "sections": [ { "id": "links", "title": "Use links for application URLs", "markdown": "The Core Link component performs client navigation for internal destinations and keeps normal anchor behavior available to the browser. Use links for destinations and buttons for actions.\n\nCreate `src/components/ProjectNavigation.tsx`\n\n**Create src/components/ProjectNavigation.tsx**\n\n```tsx\nimport { Link } from \"@tavojs/core/router\";\nimport { Inline } from \"@tavojs/ui\";\n\nexport function ProjectNavigation() {\n return (\n \n All projects\n \n Active projects\n \n \n );\n}\n```" }, { "id": "navigation-behavior", "title": "Let the pages runtime own navigation behavior", "markdown": "The pages runtime matches the route, resolves middleware and loaders, updates metadata, announces the new page, restores focus, and coordinates scroll. When the target page exports `pending`, the URL changes first, middleware and layout loaders resolve, and the pending component renders inside those layouts while the page loader runs.\n\n- Use scroll={false} only when preserving the current position is part of the interaction.\n \n- Prefer route links over a second top-level standalone router.\n \n- Without a `pending` export, the previous page remains visible and the route content region is marked busy until the target resolves.\n \n- New routes start at the top, hashes target an element, and browser back or forward restores saved positions.\n \n\n**Navigation is interruptible**\n\nA later navigation aborts loader and middleware work from the route it replaces, removes its pending component, and prevents obsolete data or errors from replacing the active route. Treat `AbortError` as control flow rather than an application failure." }, { "id": "prefetching", "title": "Prefetch when intent is clear", "markdown": "`prefetchRoute` can resolve a likely destination before the click without changing the URL or rendering the route's `pending` component. Use it for focused or hovered high-probability links, not every route in the application. `getRouteStatus` exposes idle, loading, prefetching, ready, redirecting, and error states without duplicating the router state machine.\n\nCreate `src/navigation/prefetch-projects.ts`\n\n**Create src/navigation/prefetch-projects.ts**\n\n```ts\nimport { getRouteStatus, prefetchRoute } from \"@tavojs/core/router\";\n\nexport async function prefetchProjects() {\n await prefetchRoute(\"/projects\");\n return getRouteStatus(\"/projects\");\n}\n```" }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Core routing\n\nSee route status, prefetch, and standalone-router guidance.Read guide →\n\n](/docs/core/routing)[\n\n## Fetching data\n\nUnderstand the work that navigation owns.Read guide →\n\n](/docs/getting-started/fetching-data)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:server-and-client-execution", "section": "getting-started", "slug": "server-and-client-execution", "title": "Server and client execution", "description": "Choose where route work runs, protect private dependencies, and keep the first browser render consistent with server HTML.", "keywords": [ "SSR", "CSR", "hydration", "server-only", "SSG", "ISR" ], "kind": "concept", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Choose where route work runs, protect private dependencies, and keep the first browser render consistent with server HTML." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "SSR and hydration", "href": "/docs/core/ssr-and-hydration", "description": "Configure route output and debug hydration." }, { "title": "Security", "href": "/docs/core/security", "description": "Protect server modules, sessions, hosts, and redirects." } ], "canonicalPath": "/docs/getting-started/server-and-client-execution", "sections": [ { "id": "rendering-model", "title": "Understand the rendering model", "markdown": "`Tavo.js` renders the same TSX component model on the server and in the browser. In an SSR runtime, routes render on the server by default and hydrate in the browser. A route can opt into client-only rendering when its initial HTML is not important.\n\nCreate `src/pages/browser-only.tsx`\n\n**Create src/pages/browser-only.tsx**\n\n```tsx\nimport { Page } from \"@tavojs/ui\";\n\nexport const render = \"csr\";\n\nexport default function BrowserOnlyPage() {\n return Rendered in the browser;\n}\n```\n\nStage\n\nRoute component\n\nUniversal loader\n\nServer-only loader\n\nInitial CSR request\n\nBrowser\n\nBrowser\n\nSkipped\n\nInitial SSR request\n\nServer, then browser hydration\n\nServer; result is serialized\n\nServer; safe result is serialized\n\nLater client navigation\n\nBrowser\n\nBrowser\n\nSkipped\n\nSSG build\n\nBuild process\n\nBuild process\n\nBuild process\n\nISR refresh\n\nServer runtime\n\nServer runtime\n\nServer runtime\n\n- SSR renders for the current request.\n \n- CSR sends the document shell and resolves the route in the browser.\n \n- SSG prerenders selected static routes during the build.\n \n- ISR serves cached SSR output and refreshes it after a revalidation interval.\n \n- A route `pending` export can appear during browser route resolution, but normal SSR and static generation wait for the completed page or its error view." }, { "id": "server-boundary", "title": "Keep private work behind a server boundary", "markdown": "`defineServerLoader` marks route data that must only resolve on the server. `Tavo.js` also enforces `src/server/**` as a server-only module boundary: the client build fails if code from that directory reaches its module graph. Put databases, sessions, private API clients, and secret-bearing code there, then reach it through server loaders, actions, middleware, or server routes.\n\nA server-only loader is skipped during browser route resolution. Its SSR result is available during initial hydration, but a later client navigation needs safe client auth state or a server endpoint such as /api/me when it must refresh that data.\n\nCreate `src/pages/account.tsx`\n\n**Create src/pages/account.tsx**\n\n```tsx\nimport { defineServerLoader } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Account = { name: string };\n\nexport const load = defineServerLoader(async ({ request, signal }) => {\n const { getAccount, readSession } = await import(\"./session.server\");\n const session = await readSession(request);\n if (!session) throw new Error(\"Authentication required\");\n return getAccount(session.accountId, { signal });\n});\n\nexport default function AccountPage({ data }: { data?: Account }) {\n return (\n \n Welcome, {data?.name}\n \n );\n}\n```\n\n**Do not pass secrets through page data**\n\nLoader output is serialized for hydration. Return the minimum safe fields the interface needs, never session objects, credentials, private headers, or raw database records." }, { "id": "hydration", "title": "Keep hydration deterministic", "markdown": "The browser hydrates against the route data and HTML resolved by the server. A hydration warning means the initial client tree did not reproduce that output.\n\n- Guard browser-only globals such as window and `localStorage`.\n \n- Avoid time, randomness, and locale differences in the initial render.\n \n- Use deterministic IDs from framework helpers.\n \n- Test the production SSR build, not only the development server." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## SSR and hydration\n\nConfigure route output and debug hydration.Read guide →\n\n](/docs/core/ssr-and-hydration)[\n\n## Security\n\nProtect server modules, sessions, hosts, and redirects.Read guide →\n\n](/docs/core/security)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:components-controllers-and-stores", "section": "getting-started", "slug": "components-controllers-and-stores", "title": "Components, controllers, and stores", "description": "Give renderable state, application behavior, and shared client state one clear owner each.", "keywords": [ "createTavo", "controller", "model", "store", "state" ], "kind": "concept", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Give renderable state, application behavior, and shared client state one clear owner each." ], "runtime": [ "browser", "server" ], "related": [ { "title": "MVC components", "href": "/docs/core/mvc", "description": "Learn controller lifecycle and component ownership in depth." }, { "title": "Stores", "href": "/docs/core/stores", "description": "Choose store scope, subscriptions, and derived state." } ], "canonicalPath": "/docs/getting-started/components-controllers-and-stores", "sections": [ { "id": "plain-components", "title": "Begin with a plain component", "markdown": "A component that only transforms props into TSX should be a normal function. It is easier to read, test, and reuse because it owns no hidden behavior.\n\nCreate `src/components/ProjectList.tsx`\n\n**Create src/components/ProjectList.tsx**\n\n```tsx\nimport { Stack, Text } from \"@tavojs/ui\";\n\ntype ProjectSummary = { id: string; name: string };\n\nexport function ProjectList({ projects }: { projects: ProjectSummary[] }) {\n return (\n \n {projects.map((project) => (\n
  • \n {project.name}\n
    • \n ))}\n     \n );\n}\n```" }, { "id": "component-model", "title": "Add a local model for local interaction", "markdown": "When that mounted component needs renderable state, wrap it with `createTavo` and add a model. The filter below affects only this project list, so a global store would make ownership less clear.\n\nCreate `src/components/ProjectFilter.tsx`\n\n**Create src/components/ProjectFilter.tsx**\n\n```tsx\nimport { createTavo } from \"@tavojs/core\";\nimport { Button, Inline, Stack, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string; active: boolean };\ntype ProjectFilterProps = { projects: Project[] };\ntype ProjectFilterState = { filter: \"all\" | \"active\" };\n\nexport const ProjectFilter = createTavo(\n {\n model: () => ({ filter: \"all\" }),\n view: ({ props, state, model }) => {\n const visibleProjects = props.projects.filter(\n (project) => state.filter === \"all\" || project.active,\n );\n\n return (\n \n \n \n \n \n {visibleProjects.map((project) => (\n {project.name}\n ))}\n \n );\n },\n },\n);\n```" }, { "id": "controller", "title": "Add a controller only for coordinated behavior", "markdown": "A `Tavo.js` component has a required view and optional model and controller. Add a controller when behavior needs lifecycle, cleanup, services, routing, subscriptions, or side effects. Keep small event handlers that only patch local model state in the view." }, { "id": "shared-state", "title": "Share client state through named stores", "markdown": "A global store is appropriate when several mounted components or routes need the same client preference. Keep mutation methods beside the state so callers express intent rather than coordinating partial writes.\n\nCreate `src/components/ActiveProjectButton.tsx`\n\n**Create src/components/ActiveProjectButton.tsx**\n\n```tsx\nimport { createTavo, defineGlobalStore, TavoController } from \"@tavojs/core\";\nimport { Button } from \"@tavojs/ui\";\n\ntype FilterState = {\n status: \"all\" | \"active\";\n showActive(): void;\n};\n\nexport const projectFilters = defineGlobalStore(\n \"project-filters\",\n (set) => ({\n status: \"all\",\n showActive: () => set({ status: \"active\" }),\n }),\n);\n\nclass FilterController extends TavoController {\n showActive() {\n projectFilters.getState().showActive();\n }\n}\n\nexport const ActiveProjectButton = createTavo({\n controller: FilterController,\n view: ({ controller }) => (\n \n ),\n});\n```\n\n**Global does not mean request-scoped**\n\nGlobal stores are process-wide during SSR. Never put the current user, tenant, token, session, or permissions in them; return safe request data from a loader instead." }, { "id": "lifecycle", "title": "Make cleanup part of the behavior", "markdown": "Use `onInit` for subscriptions and initial model work, `onMount` or `onLayout` for DOM-dependent work, `afterRender` for post-commit behavior, and `onPropsChange` for explicit prop reactions. Return cleanup or register it with the controller so unmounting ends listeners and work.\n\n- Prefer controller helpers for events, store selection, resize, and intersection observation.\n \n- Subscribe to the smallest store value the component needs.\n \n- Keep request data in page or layout props instead of mirroring it into a process-wide store." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## MVC components\n\nLearn controller lifecycle and component ownership in depth.Read guide →\n\n](/docs/core/mvc)[\n\n## Stores\n\nChoose store scope, subscriptions, and derived state.Read guide →\n\n](/docs/core/stores)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:fetching-data", "section": "getting-started", "slug": "fetching-data", "title": "Fetching data", "description": "Load route-critical data, design pending and error views, stream secondary content, and cancel obsolete work.", "keywords": [ "loader", "pending", "PagePendingProps", "PageErrorProps", "fetch", "resource", "deferred", "AbortSignal" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Load route-critical data, design pending and error views, stream secondary content, and cancel obsolete work." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Data loading and middleware", "href": "/docs/core/data-and-middleware", "description": "Compare loaders, middleware, resources, and cancellation." }, { "title": "Streaming and async work", "href": "/docs/core/streaming-and-async", "description": "Design deferred boundaries and timeout behavior." }, { "title": "Error handling", "href": "/docs/getting-started/error-handling", "description": "Choose between route errors, the global error page, and component boundaries." } ], "canonicalPath": "/docs/getting-started/fetching-data", "sections": [ { "id": "route-loaders", "title": "Load data the route needs", "markdown": "A page or layout loader runs during route resolution. Its return value becomes page data and is serialized into SSR output, so the browser can hydrate without immediately repeating the request. The page's default component and controller do not mount until its loader completes.\n\nCreate `src/pages/dashboard.tsx`\n\n**Create src/pages/dashboard.tsx**\n\n```tsx\nimport type {\n PageErrorProps,\n PageLoadContext,\n PagePendingProps,\n PageProps,\n} from \"@tavojs/core/router\";\nimport { Page, Stack, Text } from \"@tavojs/ui\";\n\ntype DashboardData = {\n projects: Array<{ id: string; name: string }>;\n summary: { active: number };\n};\n\nexport function pending({ pathname }: PagePendingProps) {\n return (\n \n \n \n Loading dashboard…\n \n Preparing projects and their summary.\n \n \n );\n}\n\nexport function error({ pathname }: PageErrorProps) {\n return (\n \n \n \n Could not load the dashboard\n \n \n The data for {pathname} is unavailable. Try again.\n \n \n \n );\n}\n\nexport async function load({\n signal,\n url,\n}: PageLoadContext): Promise {\n const [projectsResponse, summaryResponse] = await Promise.all([\n fetch(new URL(\"/api/projects\", url), { signal }),\n fetch(new URL(\"/api/projects/summary\", url), { signal }),\n ]);\n if (!projectsResponse.ok || !summaryResponse.ok) {\n throw new Error(\"Dashboard data could not be loaded\");\n }\n return {\n projects: await projectsResponse.json(),\n summary: await summaryResponse.json(),\n } as DashboardData;\n}\n\nexport default function DashboardPage({ data }: PageProps) {\n return (\n \n \n Active projects: {data?.summary.active ?? 0}\n {data?.projects.map((project) => (\n {project.name}\n ))}\n \n \n );\n}\n```\n\n**Check every response**\n\nfetch resolves for HTTP error statuses. Check `response.ok` and turn expected failures into explicit page data before attempting to read a success shape." }, { "id": "route-pending-and-error", "title": "Design the route while its loader is unresolved", "markdown": "The example above exports `pending` for immediate feedback during active browser resolution and `error` for a contextual page-loader failure. `Tavo.js` renders either component inside the target route's resolved layouts.\n\nThe browser changes the URL, runs route middleware, resolves layout loaders, renders `pending`, and then runs the page loader. Success replaces it with the default page; failure replaces it with the page's `error` component.\n\nResolution path\n\nPending export\n\nVisible result\n\nInitial CSR resolution\n\nRendered while the page loader runs\n\nCompleted page or route error\n\nLater client navigation\n\nRendered after layout loaders resolve\n\nCompleted page or route error\n\nNormal SSR or static generation\n\nNot rendered\n\nServer waits for the completed page or error\n\nPrefetch or fresh route-cache hit\n\nNot rendered\n\nNo visible route replacement during prefetch\n\n- `PagePendingProps` contains `pathname`, `params`, `layers`, and `layerData`; page loader data is intentionally unavailable.\n \n- `PageErrorProps` contains those route fields plus `data` and `error`.\n \n- Layout data is available because `Tavo.js` resolves target layout loaders before showing the page pending component.\n \n- If the page has no `pending` export, the previous page remains visible and the route content region is marked busy.\n \n\n**Route pending or component resource?**\n\nUse a route `pending` export when the page cannot render meaningfully before its loader completes. Use `createResource()` when the page shell can render immediately and only one section owns the asynchronous work." }, { "id": "loader-execution", "title": "Know when the loader runs", "markdown": "A universal loader follows the route resolver. The table shows why its imports and return value must be safe in every environment that can execute or receive them.\n\nEntry path\n\nWhere load runs\n\nWhat the browser receives\n\nDirect CSR visit\n\nBrowser\n\nNo serialized loader result\n\nDirect SSR visit\n\nServer\n\nResult is serialized for hydration\n\nHydration\n\nBrowser reuses server data\n\nNo immediate repeat\n\nLater client navigation\n\nBrowser\n\nFresh result belongs to that navigation" }, { "id": "loader-ownership", "title": "Choose the narrowest data owner", "markdown": "Avoid copying loader results into global stores. Page props already keep request data scoped to the navigation that produced it.\n\n- Use a page loader when the route cannot render meaningfully without the data.\n \n- Use a layout loader for request data shared by its descendant routes.\n \n- Use `createResource` for component-scoped browser data that can load independently.\n \n- Use lazy when the asynchronous work is loading a component implementation." }, { "id": "streaming", "title": "Stream secondary server content", "markdown": "Resolve data required for navigation, SEO, and the primary shell in the loader. Put slower optional server work behind Deferred boundaries with a stable ID, useful fallback, timeout behavior, and an error fallback.\n\nPromise-backed Deferred content progressively patches an SSR stream. For browser-only asynchronous work, use a loader, resource, controller, or store instead." }, { "id": "cancellation", "title": "Pass cancellation through every layer", "markdown": "Navigation owns loader and middleware signals. Replacing a navigation aborts its route work, removes its pending component, and prevents obsolete data or errors from replacing the active route. A resource owns its current load. Deferred work belongs to its supplied signal or render lifecycle. Forward the signal to fetch, database wrappers that support it, and other cancellable clients.\n\n- Treat `AbortError` as normal control flow.\n \n- Do not publish results after their owner has been replaced.\n \n- Use transactions or idempotency for side effects because cancellation cannot undo a committed mutation." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Data loading and middleware\n\nCompare loaders, middleware, resources, and cancellation.Read guide →\n\n](/docs/core/data-and-middleware)[\n\n## Streaming and async work\n\nDesign deferred boundaries and timeout behavior.Read guide →\n\n](/docs/core/streaming-and-async)[\n\n## Error handling\n\nChoose between route errors, the global error page, and component boundaries.Read guide →\n\n](/docs/getting-started/error-handling)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:mutating-data", "section": "getting-started", "slug": "mutating-data", "title": "Mutating data", "description": "Handle server changes through validated, authorized route actions with explicit pending and failure states.", "keywords": [ "action", "form", "validation", "authorization", "idempotency" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Handle server changes through validated, authorized route actions with explicit pending and failure states." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Actions, forms, and validation", "href": "/docs/core/actions-and-forms", "description": "Review action responses, validation, and security order." }, { "title": "Revalidating", "href": "/docs/getting-started/revalidating", "description": "Refresh cached reads after a successful change." } ], "canonicalPath": "/docs/getting-started/mutating-data", "sections": [ { "id": "actions", "title": "Put server mutations in route actions", "markdown": "A route action handles non-GET requests in SSR mode. It receives a standard Request, so the handler can read JSON or form data, authorize the caller, perform the change, and return JSON, status, headers, or a redirect.\n\nCreate `src/pages/projects/new.tsx`\n\n**Create src/pages/projects/new.tsx**\n\n```ts\nimport {\n createServerFormAction,\n createTavo,\n TavoController,\n} from \"@tavojs/core\";\nimport { defineValidatedAction } from \"@tavojs/core/dev\";\nimport {\n Button,\n Field,\n FormControl,\n Page,\n Stack,\n Text,\n TextInput,\n} from \"@tavojs/ui\";\n\ntype ProjectInput = { name: string };\n\nconst projectSchema = {\n parse(input: unknown): ProjectInput {\n const name = String((input as { name?: unknown }).name ?? \"\").trim();\n if (!name) throw new Error(\"Project name is required\");\n return { name };\n },\n};\n\nexport const action = defineValidatedAction(\n projectSchema,\n async ({ input, request }) => {\n const { requireProjectPermission, saveProject } =\n await import(\"./project-store.server\");\n await requireProjectPermission(request);\n const project = await saveProject(input);\n return { redirect: `/projects/${project.id}` };\n },\n);\n\ntype ProjectFormState = { pending: boolean; error: string };\n\nclass ProjectFormController extends TavoController {\n formAction = createServerFormAction(\"/projects/new\");\n\n async submit(event: Event) {\n event.preventDefault();\n this.model.patch({ pending: true, error: \"\" });\n const result = await this.formAction.submit(\n event.currentTarget as HTMLFormElement,\n );\n this.model.patch({\n pending: false,\n error:\n result.status === \"error\"\n ? result.error instanceof Error\n ? result.error.message\n : \"Project could not be created\"\n : \"\",\n });\n }\n}\n\nexport default createTavo<{}, ProjectFormState, ProjectFormController>({\n model: () => ({ pending: false, error: \"\" }),\n controller: ProjectFormController,\n view: ({ state, controller }) => (\n \n \n \n New project\n \n void controller?.submit(event)}\n >\n \n \n \n \n \n {state.error ? (\n \n {state.error}\n \n ) : null}\n \n \n ),\n});\n```" }, { "id": "action-execution", "title": "Separate browser and server responsibilities", "markdown": "Phase\n\nRuntime\n\nResponsibility\n\nRender form\n\nBrowser and SSR\n\nShow fields, current errors, and pending state.\n\nSubmit\n\nBrowser\n\nSerialize input and send the non-GET request.\n\nRoute action\n\nServer\n\nValidate, authenticate, authorize, and commit.\n\nApply response\n\nBrowser\n\nShow field errors, success data, or follow a redirect.\n\nStatic-only deployment\n\nUnavailable\n\nUse a server runtime or external API for mutations." }, { "id": "validation", "title": "Validate before business logic", "markdown": "`defineValidatedAction` accepts Standard Schema and common parse-compatible validators. Invalid input receives a structured 400 response before the mutation handler runs.\n\n**Validation is not authorization**\n\nA valid payload can still come from the wrong user. Authenticate and verify permissions inside every server action before changing state." }, { "id": "safe-order", "title": "Keep the mutation order predictable", "markdown": "- Parse and validate the input shape.\n \n- Authenticate the request and authorize the specific resource operation.\n \n- Apply origin, CSRF, and idempotency rules appropriate to the endpoint.\n \n- Commit the database or external side effect.\n \n- Return only safe data, an explicit error shape, or a same-origin redirect." }, { "id": "form-state", "title": "Show pending and expected failures", "markdown": "Use `createServerFormAction` when a controller should own browser submission state for a route action. Disable duplicate submission while pending, associate validation messages with their fields, and announce the result without moving focus unexpectedly.\n\n**Design retries before enabling them**\n\nA network timeout does not prove that a server mutation failed. Use idempotency keys for operations that users or infrastructure may safely retry." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Actions, forms, and validation\n\nReview action responses, validation, and security order.Read guide →\n\n](/docs/core/actions-and-forms)[\n\n## Revalidating\n\nRefresh cached reads after a successful change.Read guide →\n\n](/docs/getting-started/revalidating)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:caching", "section": "getting-started", "slug": "caching", "title": "Caching", "description": "Prebuild stable routes and cache safe SSR responses without crossing user or request boundaries.", "keywords": [ "cache", "static", "SSG", "createTavo", "TavoController", "vary", "adapter" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Prebuild stable routes and cache safe SSR responses without crossing user or request boundaries." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "SSR and hydration", "href": "/docs/core/ssr-and-hydration", "description": "Compare SSR, CSR, SSG, and revalidated output." }, { "title": "Revalidating", "href": "/docs/getting-started/revalidating", "description": "Keep cached output fresh." } ], "canonicalPath": "/docs/getting-started/caching", "sections": [ { "id": "static-routes", "title": "Mark routes that can be static", "markdown": "Export prerender when a route can safely reuse its rendered output. For a dynamic path, `generateStaticParams` lists the concrete URLs the production build should prerender.\n\nStatic generation renders the initial `createTavo` view during the build; the browser can then hydrate it and let its controller own later interactions. In this example, every visitor receives the same safe article HTML while save state remains local to the hydrated component.\n\nCreate `src/pages/articles/[slug].tsx`\n\n**Create src/pages/articles/[slug].tsx**\n\n```tsx\nimport { createTavo, TavoController } from \"@tavojs/core\";\nimport type { PageLoadContext, PageProps } from \"@tavojs/core/router\";\nimport { Button, Page, Stack, Text } from \"@tavojs/ui\";\n\ntype Article = { title: string };\ntype ArticleParams = { slug: string };\ntype ArticlePageState = { saved: boolean };\n\nconst articles: Record = {\n \"getting-started\": { title: \"Getting started\" },\n \"release-notes\": { title: \"Release notes\" },\n};\n\nfunction getArticle(slug: string): Article {\n const article = articles[slug];\n if (!article) throw new Error(`Unknown article: ${slug}`);\n return article;\n}\n\nexport const prerender = true;\n\nexport function generateStaticParams(): ArticleParams[] {\n return [{ slug: \"getting-started\" }, { slug: \"release-notes\" }];\n}\n\nexport function load({ params }: PageLoadContext): Article {\n return getArticle(params.slug);\n}\n\nclass ArticlePageController extends TavoController {\n toggleSaved() {\n this.model.patch((state) => ({ saved: !state.saved }));\n }\n}\n\nexport default createTavo<\n PageProps,\n ArticlePageState,\n ArticlePageController\n>({\n model: () => ({ saved: false }),\n controller: ArticlePageController,\n view: ({ props, state, controller }) => (\n \n \n \n {props.data?.title}\n \n controller?.toggleSaved()}\n >\n {state.saved ? \"Saved for later\" : \"Save article\"}\n \n \n \n ),\n});\n```\n\n**Static does not mean non-interactive**\n\nKeep the initial model deterministic and safe to share. Browser-only controller behavior can begin after hydration, but request users, sessions, permissions, and personalized defaults must not enter the prerendered output." }, { "id": "cache-safety", "title": "Cache only shareable output", "markdown": "The route cache stores rendered HTML and resolved route data. Requests carrying Cookie or Authorization bypass static caching because their output may be user-specific.\n\n- Do not mark personalized pages static.\n \n- Use vary only for a small, deliberate set of request headers that genuinely change safe output.\n \n- Keep request users, sessions, tenants, and permissions out of global stores and module variables.\n \n\n**Static is a data contract**\n\nThe route must remain safe to share for every request that resolves to the same cache key. Treat that requirement as part of the route design, not only a performance switch." }, { "id": "cache-execution", "title": "Separate rendering from caching", "markdown": "Mode or request\n\nWhere rendering happens\n\nCache behavior\n\nCSR\n\nBrowser on each visit\n\nNormal HTTP asset caching only\n\nSSR\n\nServer for each request\n\nNone unless route or adapter enables it\n\nSSG\n\nBuild process\n\nGenerated HTML and route data\n\nISR\n\nServer after expiry\n\nServe cached output, then replace it\n\nCookie or Authorization request\n\nServer\n\nShared static cache is bypassed" }, { "id": "cache-adapters", "title": "Choose a production cache adapter", "markdown": "The Node runtime uses a bounded process-local memory cache by default. It is useful for one process, but it is not shared across replicas and disappears when the process restarts. Supply a cache adapter when the application needs shared persistence or coordinated invalidation." }, { "id": "inspect", "title": "Inspect what the build decided", "markdown": "`tavo` build prints each route render mode and static policy. Use the JSON report and generated route manifest in CI when static output is an application requirement.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\ntavo build --report-json\ntavo inspect route /articles/getting-started --json\n```" }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## SSR and hydration\n\nCompare SSR, CSR, SSG, and revalidated output.Read guide →\n\n](/docs/core/ssr-and-hydration)[\n\n## Revalidating\n\nKeep cached output fresh.Read guide →\n\n](/docs/getting-started/revalidating)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:revalidating", "section": "getting-started", "slug": "revalidating", "title": "Revalidating", "description": "Refresh cached routes by time or application-owned tags while keeping deployment behavior explicit.", "keywords": [ "revalidate", "cache tags", "invalidation", "ISR" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Refresh cached routes by time or application-owned tags while keeping deployment behavior explicit." ], "runtime": [ "server", "build" ], "related": [ { "title": "Deployment", "href": "/docs/core/deployment", "description": "Connect cache behavior to the selected runtime." }, { "title": "Testing and diagnostics", "href": "/docs/getting-started/testing-and-diagnostics", "description": "Verify cache hits, misses, and invalidation." } ], "canonicalPath": "/docs/getting-started/revalidating", "sections": [ { "id": "time-based", "title": "Refresh after a time interval", "markdown": "A numeric `revalidate` value automatically enables cached SSR and gives the cached output a lifetime in seconds. After it expires, the next resolution produces fresh output and replaces the stored entry.\n\nChoose the route-aware helper when you want typed path parameters and the route contract in one object. Choose named exports when you want each behavior visible at module scope. Both examples describe the same revalidated project route.\n\nCreate `src/pages/projects/[id].tsx`\n\n**Create src/pages/projects/[id].tsx**\n\n```tsx\nimport { defineRoutePage } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string };\n\nfunction getProject(id: string): Project {\n return { id, name: `Project ${id}` };\n}\n\nexport default defineRoutePage<\"/projects/[id]\", Project>(\"/projects/[id]\", {\n revalidate: 300,\n\n cacheTags: ({ params }) => [\"projects\", `project:${params.id}`],\n\n load: ({ params }) => getProject(params.id),\n\n default: function ProjectPage({ data }) {\n return (\n \n {data?.name}\n \n );\n },\n});\n```\n\n**Create src/pages/projects/[id].tsx**\n\n```tsx\nimport type { PageLoadContext, PageProps } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string };\ntype ProjectParams = { id: string };\n\nfunction getProject(id: string): Project {\n return { id, name: `Project ${id}` };\n}\n\nexport const revalidate = 300;\nexport const cacheTags = ({ params }: PageLoadContext) => [\n \"projects\",\n `project:${params.id}`,\n];\n\nexport function load({ params }: PageLoadContext): Project {\n return getProject(params.id);\n}\n\nexport default function ProjectPage({\n data,\n}: PageProps) {\n return (\n \n {data?.name}\n \n );\n}\n```\n\n**Revalidation already enables caching**\n\nDo not add `prerender = true` merely to enable cached SSR. Reserve `prerender = true` for build-time static HTML without timed revalidation; inside `defineRoutePage`, use its equivalent, `static: true`." }, { "id": "cache-tags", "title": "Name related cached output", "markdown": "`cacheTags` attaches application-owned names to a route entry. Tags can be static or derived from route parameters, which lets one mutation target a collection, one record, or both.\n\n- Use stable domain names such as projects and project:42.\n \n- Do not put secrets or personal data into a tag.\n \n- Keep tag production beside the route data contract so readers can see what invalidates it." }, { "id": "on-demand", "title": "Invalidate through the runtime boundary", "markdown": "`PagesRuntime` exposes synchronous tag invalidation for its resolved-route cache. The Node request handler exposes asynchronous `invalidateCache` for both runtime and static adapter entries. Custom cache adapters may also implement `invalidateTags`.\n\nCreate `src/server/invalidate-project.ts`\n\n**Create src/server/invalidate-project.ts**\n\n```ts\ntype CacheInvalidator = {\n invalidateCache(tags: string[]): Promise;\n};\n\nexport async function invalidateProjectCache(\n requestHandler: CacheInvalidator,\n projectId: string,\n) {\n return requestHandler.invalidateCache([\"projects\", `project:${projectId}`]);\n}\n```\n\n**Invalidation must reach every replica**\n\nProcess-local invalidation affects only that process. In a multi-instance deployment, connect tag invalidation to the shared cache or platform coordination mechanism." }, { "id": "after-mutation", "title": "Invalidate only after the mutation commits", "markdown": "Trigger invalidation after the database or external write succeeds. If the mutation and cache live in different systems, record enough information to retry failed invalidation without repeating the business change." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Deployment\n\nConnect cache behavior to the selected runtime.Read guide →\n\n](/docs/core/deployment)[\n\n## Testing and diagnostics\n\nVerify cache hits, misses, and invalidation.Read guide →\n\n](/docs/getting-started/testing-and-diagnostics)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:error-handling", "section": "getting-started", "slug": "error-handling", "title": "Error handling", "description": "Choose route and global error views, model normal failures as state, and contain exceptions at the nearest useful boundary.", "keywords": [ "errors", "PageErrorProps", "route error", "ErrorBoundary", "404", "retry", "diagnostics" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Choose route and global error views, model normal failures as state, and contain exceptions at the nearest useful boundary." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Testing and diagnostics", "href": "/docs/core/testing-and-diagnostics", "description": "Capture route, hydration, and runtime failures at the correct layer." }, { "title": "Streaming and async work", "href": "/docs/core/streaming-and-async", "description": "Add deferred error and timeout behavior." } ], "canonicalPath": "/docs/getting-started/error-handling", "sections": [ { "id": "expected-errors", "title": "Return expected failures explicitly", "markdown": "Validation failures, empty results, rejected permissions, and unavailable remote services can be normal application outcomes. Give them typed data or response shapes so the page can explain what happened and offer a useful next action.\n\n- Associate form errors with the field that needs attention.\n \n- Use status codes and JSON shapes consistently across route actions and server routes.\n \n- Call `notFound()` when missing route data should render `404.tsx`; unmatched URLs use the same page." }, { "id": "unexpected-errors", "title": "Contain unexpected render failures", "markdown": "`ErrorBoundary` protects a component subtree and renders fallback UI when rendering fails. Place boundaries around areas that can recover independently instead of replacing the entire application for one failed panel.\n\nCreate `src/components/ProjectPanel.tsx`\n\n**Create src/components/ProjectPanel.tsx**\n\n```tsx\nimport { ErrorBoundary, type Child } from \"@tavojs/core\";\nimport { Button, Stack, Text } from \"@tavojs/ui\";\n\nexport function ProjectPanel({ children }: { children?: Child }) {\n return (\n (\n \n Projects could not be displayed.\n \n \n )}\n >\n {children}\n \n );\n}\n```\n\n**Do not expose private error details**\n\nShow a stable user-facing message and send diagnostic details to controlled logging. Stack traces, request headers, loader data, and tokens do not belong in rendered fallback UI." }, { "id": "route-failures", "title": "Choose the closest route error view", "markdown": "A page can export an `error` component for its own loader failures. It receives `PageErrorProps`, including the target pathname, params, data and error fields, resolved layers, and layer data, and it renders inside the matched layout chain.\n\nIf the target page does not export `error`, `Tavo.js` uses `src/pages/_error.tsx` as the application-wide fallback. A layout-loader failure enters this error-resolution path instead of showing the page pending component with invalid layout data.\n\n- Use a page `error` export when the recovery message or next action is specific to that route.\n \n- Keep `_error.tsx` broad enough to handle any remaining page or layout loader failure.\n \n- `notFound()` bypasses both route and global error views and renders `404.tsx` with status 404.\n \n- Render failures belong in the nearest component `ErrorBoundary` because they happen after route resolution.\n \n\n**Treat the error value as sensitive**\n\nUse the `error` prop for safe classification and controlled diagnostics. Do not render stack traces, request headers, tokens, raw response bodies, or private loader data." }, { "id": "async-errors", "title": "Design asynchronous failure states", "markdown": "Resources expose idle, loading, success, and error states. Deferred boundaries accept error and timeout fallbacks. A retry should start a new owned operation and replace the old signal rather than reusing abandoned work.\n\n- Do not report deliberate cancellation as an error.\n \n- Set timeouts for optional dependencies that should not hold a stream open.\n \n- Instrument the route, loader, action, cache, or boundary phase without recording private payloads." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Testing and diagnostics\n\nCapture route, hydration, and runtime failures at the correct layer.Read guide →\n\n](/docs/core/testing-and-diagnostics)[\n\n## Streaming and async work\n\nAdd deferred error and timeout behavior.Read guide →\n\n](/docs/core/streaming-and-async)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:css-and-tavo-ui", "section": "getting-started", "slug": "css-and-tavo-ui", "title": "CSS and Tavo.js UI", "description": "Combine application styles, locally scoped CSS, design tokens, and accessible interface components.", "keywords": [ "CSS", "CSS Modules", "Tavo.js UI", "theme", "tokens" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Combine application styles, locally scoped CSS, design tokens, and accessible interface components." ], "runtime": [ "browser", "build" ], "related": [ { "title": "Tavo.js UI overview", "href": "/docs/ui", "description": "Choose theming, responsive, composition, and accessibility guides." }, { "title": "Design tokens", "href": "/docs/ui/tokens", "description": "Use generated tokens in product-specific styles." } ], "canonicalPath": "/docs/getting-started/css-and-tavo-ui", "sections": [ { "id": "style-boundaries", "title": "Give each style layer one job", "markdown": "Use application-wide CSS for document defaults and product-wide rules, CSS Modules for component-specific presentation, `Tavo.js` UI props for supported component behavior, and generated theme tokens for shared design decisions.\n\n- List deliberate global entry files in `tavo.config.ts` `cssEntries`.\n \n- Name local files \\*`.module.css` so class names remain scoped. Install sass-embedded before choosing \\*`.module.scss` for application code.\n \n- Keep third-party global styles in one documented application entry.\n \n- Use tokens instead of repeating product colors, spacing, radii, and typography values." }, { "id": "ui-components", "title": "Compose with Tavo.js UI", "markdown": "`Tavo.js` UI components provide semantic defaults, states, responsive props, and theme integration. They do not own your application data or business behavior; route modules, controllers, and stores remain responsible for those concerns.\n\nCreate `src/pages/projects/index.tsx`\n\n**Create src/pages/projects/index.tsx**\n\n```tsx\nimport { Button, Card, Grid, Page, Text } from \"@tavojs/ui\";\n\nexport default function ProjectsPage() {\n return (\n \n \n \n Refresh the getting started guide.\n \n \n \n \n );\n}\n```" }, { "id": "theme", "title": "Generate a project-owned theme", "markdown": "`tavo-ui.config.ts` describes the light and dark brand colors, default mode, numeric scale, typography, and token overrides the product needs. The `Tavo.js` UI plugin resolves that input and injects generated variables during development and production builds.\n\nMerge into `tavo-ui.config.ts`\n\n**Merge tavo-ui.config.ts**\n\n```ts\nimport type { TavoUiThemeConfig } from \"@tavojs/ui\";\n\nexport default {\n $schema: \"./node_modules/@tavojs/ui/schema.json\",\n defaultTheme: \"system\",\n color: {\n light: { primary: \"#3157d5\" },\n dark: { primary: \"#9bb1ff\" },\n },\n scale: { radius: 8 },\n} satisfies TavoUiThemeConfig;\n```\n\n**The application owns the theme**\n\nRegenerate theme output through the UI CLI instead of editing generated variables by hand. Commit the input configuration that expresses the product decision." }, { "id": "responsive-and-order", "title": "Keep responsive behavior and order predictable", "markdown": "Responsive values are mobile-first: base applies everywhere, then larger breakpoint values override it. Import order still controls global CSS, so keep one deliberate sequence and avoid relying on incidental module discovery.\n\n- Use component responsive props for supported layout behavior.\n \n- Use CSS Modules for product-specific selectors and states.\n \n- Use the exported breakpoint mixins when custom CSS must align with the UI system." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Tavo.js UI overview\n\nChoose theming, responsive, composition, and accessibility guides.Read guide →\n\n](/docs/ui)[\n\n## Design tokens\n\nUse generated tokens in product-specific styles.Read guide →\n\n](/docs/ui/tokens)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:images", "section": "getting-started", "slug": "images", "title": "Image optimization", "description": "Render stable responsive images and opt into tightly controlled server optimization for local or remote assets.", "keywords": [ "Image", "responsive", "sharp", "remote images", "assets" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Render stable responsive images and opt into tightly controlled server optimization for local or remote assets." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "SEO, assets, and styling", "href": "/docs/core/seo-assets-and-styling", "description": "Review Image, Font, Script, and metadata boundaries." }, { "title": "Security", "href": "/docs/core/security", "description": "Harden remote media and production SSR configuration." } ], "canonicalPath": "/docs/getting-started/images", "sections": [ { "id": "image-component", "title": "Describe the image layout", "markdown": "The Image component emits an img element with responsive optimizer URLs during SSR. Supply accurate dimensions to reserve space, a meaningful alt description, widths that match the design, and sizes that explain the rendered width to the browser.\n\nCreate `src/components/ProjectHero.tsx`\n\n**Create src/components/ProjectHero.tsx**\n\n```tsx\nimport { Image } from \"@tavojs/core\";\nimport { Page } from \"@tavojs/ui\";\n\nexport function ProjectHero() {\n return (\n \n \n \n );\n}\n```\n\n**Priority is exceptional**\n\nMark only an above-the-fold image that materially affects the initial view as priority. Lazy loading remains the better default for the rest of the page." }, { "id": "local-assets", "title": "Serve local assets from public", "markdown": "Files under public have root-relative browser URLs. Keep the source path inside that directory so the optimizer cannot read arbitrary server files. Use unoptimized when the source is already transformed or the deployment has no image optimizer." }, { "id": "remote-assets", "title": "Allow remote sources narrowly", "markdown": "Remote optimization is disabled until the application enables it and supplies an HTTPS allowlist. Restrict hostnames and paths to the product's actual media origins.\n\nMerge into `tavo.config.ts`\n\n**Merge tavo.config.ts**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\n\nexport default defineConfig({\n ssr: {\n images: {\n allowRemote: true,\n remotePatterns: [\n {\n protocol: \"https:\",\n hostname: \"media.example.com\",\n pathname: \"/projects/\",\n },\n ],\n },\n },\n});\n```\n\n**Remote media is a server security boundary**\n\nKeep the allowlist exact, preserve request-size and timeout limits, and do not enable insecure HTTP sources in production." }, { "id": "sharp", "title": "Install the production transformer when needed", "markdown": "The SSR optimizer uses the optional sharp dependency for transformations. Install it in the application that runs the server, then verify the /\\_tavo/image endpoint in production preview and on the selected platform.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpm install sharp\nnpm run build\nnpm run preview:ssr\n```" }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## SEO, assets, and styling\n\nReview Image, Font, Script, and metadata boundaries.Read guide →\n\n](/docs/core/seo-assets-and-styling)[\n\n## Security\n\nHarden remote media and production SSR configuration.Read guide →\n\n](/docs/core/security)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:fonts", "section": "getting-started", "slug": "fonts", "title": "Font loading", "description": "Load self-hosted or external fonts deliberately while controlling privacy, fallback behavior, and layout stability.", "keywords": [ "Font", "woff2", "preload", "preconnect", "font-display" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Load self-hosted or external fonts deliberately while controlling privacy, fallback behavior, and layout stability." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "SEO, assets, and styling", "href": "/docs/core/seo-assets-and-styling", "description": "See the complete document-asset model." }, { "title": "Theming", "href": "/docs/ui/theming", "description": "Connect the font variable to the product theme." } ], "canonicalPath": "/docs/getting-started/fonts", "sections": [ { "id": "local-fonts", "title": "Prefer a self-hosted font when possible", "markdown": "Place licensed font files under public and render Font from a root layout head export. The component creates the preload and @font-face rules for SSR and CSR, while a CSS variable makes the family available to the theme or application styles.\n\nCreate `src/pages/_layout.tsx`\n\n**Create src/pages/_layout.tsx**\n\n```tsx\nimport { Font, type Child } from \"@tavojs/core\";\n\nexport const head = (\n \n);\n\nexport default function RootLayout({ children }: { children?: Child }) {\n return <>{children};\n}\n```\n\n**Use the smallest useful font set**\n\nA variable WOFF2 file often replaces several individual weights. Preload only fonts required by the initial view; extra preloads compete with more important resources." }, { "id": "display-and-fallback", "title": "Choose a visible fallback strategy", "markdown": "font-display controls whether text waits for the custom file. swap keeps content visible immediately, while optional lets the browser retain the fallback on slow connections. Choose a fallback family with similar metrics to reduce movement when the custom font appears." }, { "id": "external-fonts", "title": "Treat external fonts as third-party requests", "markdown": "Font can emit stylesheet and preconnect links for an external provider. That request exposes the visitor's network metadata to another origin and adds a runtime dependency, so confirm the privacy and availability tradeoff before using it.\n\n- Preconnect only to origins used by the selected stylesheet.\n \n- Keep integrity and CSP requirements aligned with the provider.\n \n- Prefer self-hosting when privacy, reliability, or offline behavior matters." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## SEO, assets, and styling\n\nSee the complete document-asset model.Read guide →\n\n](/docs/core/seo-assets-and-styling)[\n\n## Theming\n\nConnect the font variable to the product theme.Read guide →\n\n](/docs/ui/theming)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:metadata-and-social-images", "section": "getting-started", "slug": "metadata-and-social-images", "title": "Metadata and social images", "description": "Describe each route for browsers, search engines, link previews, and assistive navigation.", "keywords": [ "Seo", "metadata", "Open Graph", "Twitter", "canonical" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Describe each route for browsers, search engines, link previews, and assistive navigation." ], "runtime": [ "server", "build" ], "related": [ { "title": "SEO, assets, and styling", "href": "/docs/core/seo-assets-and-styling", "description": "Review head exports, Seo, and document assets." }, { "title": "Deploying", "href": "/docs/getting-started/deploying", "description": "Confirm canonical origins and metadata in production." } ], "canonicalPath": "/docs/getting-started/metadata-and-social-images", "sections": [ { "id": "route-head", "title": "Keep metadata beside the route", "markdown": "Export a static head value when every visit shares the same metadata. Use a head function when the title, description, status, or social image depends on route parameters or loader data.\n\nCreate `src/pages/projects/[id].tsx`\n\n**Create src/pages/projects/[id].tsx**\n\n```tsx\nimport { Seo } from \"@tavojs/core\";\nimport type { PageLoadContext, PageProps } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { name: string; summary: string; image: string };\ntype ProjectParams = { id: string };\n\nexport function load({ params }: PageLoadContext): Promise {\n return getProject(params.id);\n}\n\nexport function head({ data, params }: PageLoadContext & { data?: Project }) {\n return (\n \n );\n}\n\nexport default function ProjectPage({\n data,\n}: PageProps) {\n return (\n \n \n {data?.name}\n \n \n );\n}\n\nasync function getProject(id: string): Promise {\n return {\n name: `Project ${id}`,\n summary: \"A project managed with Tavo.js.\",\n image: \"https://media.example.com/projects/social.png\",\n };\n}\n```" }, { "id": "seo-fields", "title": "Publish the fields consumers need", "markdown": "- Use one specific title and plain-language description per public route.\n \n- Set a canonical URL when multiple URLs can expose equivalent content.\n \n- Use robots, `noIndex`, and `noFollow` intentionally for non-public routes.\n \n- Provide Open Graph and Twitter images with stable HTTPS URLs and useful source dimensions.\n \n- Set theme-color when the browser chrome should follow the product theme." }, { "id": "social-images", "title": "Serve social images as public assets", "markdown": "Store static share images under public or point Seo at a trusted media origin. `Tavo.js` does not generate Open Graph artwork from route code; create the image through your asset pipeline and publish the final URL.\n\n**Metadata is server output**\n\nRequest-time metadata can use safe loader data, but it must not expose session values, private record fields, internal hostnames, or untrusted raw HTML." }, { "id": "verify", "title": "Verify the rendered document", "markdown": "Inspect the production SSR HTML, not only the browser DOM after navigation. Confirm the title, canonical URL, description, robots policy, and social tags for static, dynamic, success, and not-found routes." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## SEO, assets, and styling\n\nReview head exports, Seo, and document assets.Read guide →\n\n](/docs/core/seo-assets-and-styling)[\n\n## Deploying\n\nConfirm canonical origins and metadata in production.Read guide →\n\n](/docs/getting-started/deploying)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:server-routes", "section": "getting-started", "slug": "server-routes", "title": "Server routes", "description": "Expose deliberate HTTP endpoints through the plugin server boundary using standard web requests and responses.", "keywords": [ "server route", "plugin", "Request", "Response", "API" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Expose deliberate HTTP endpoints through the plugin server boundary using standard web requests and responses." ], "runtime": [ "server" ], "related": [ { "title": "Plugins and localization", "href": "/docs/core/plugins-and-localization", "description": "Understand plugin services, ordering, routes, and request scope." }, { "title": "Security", "href": "/docs/core/security", "description": "Configure origins, hosts, redirects, bodies, and secrets." } ], "canonicalPath": "/docs/getting-started/server-routes", "sections": [ { "id": "when-to-use", "title": "Choose a server route for an HTTP endpoint", "markdown": "Use a page action when a mutation belongs to one application route. Use a plugin server route for a reusable API, webhook, health check, or integration endpoint that should respond before page rendering.\n\n**Server routes require an SSR runtime**\n\nStatic hosting and a client-only Vite server cannot execute these handlers. Run the generated `.tavo/build/server/start.mjs` entry with Node." }, { "id": "register", "title": "Register methods in a plugin", "markdown": "Declare every endpoint in the plugin manifest, then implement the same endpoint keys in a lazy server phase. Handlers receive a standard Request and return a terminal Response.\n\nCreate `project-api.ts`\n\n**Create project-api.ts**\n\n```ts\nimport { definePlugin, definePluginPhase } from \"@tavojs/core/plugin\";\n\nexport const projectApi = definePlugin({\n id: \"@project/api\",\n version: \"1.0.0\",\n apiVersion: 1,\n manifest: {\n endpoints: [\n {\n id: \"summary\",\n methods: [\"GET\"],\n match: { kind: \"exact\", path: \"/api/projects/summary\" },\n },\n {\n id: \"collection\",\n methods: [\"GET\", \"POST\"],\n match: { kind: \"exact\", path: \"/api/projects\" },\n },\n {\n id: \"project\",\n methods: [\"GET\"],\n match: { kind: \"subtree\", path: \"/api/projects\" },\n },\n ],\n exposure: [\n {\n target: \"server\",\n from: \"/api/projects\",\n to: \"/api/projects\",\n reason: \"Expose the documented project API.\",\n },\n ],\n },\n server: () =>\n definePluginPhase({\n endpoints: {\n summary: async () => {\n const { projectSummary } = await import(\"./project-store.server\");\n return Response.json(await projectSummary());\n },\n collection: async ({ request }) => {\n const store = await import(\"./project-store.server\");\n if (request.method === \"POST\") {\n await store.requireProjectPermission(request);\n const input = store.parseProjectInput(await request.json());\n return Response.json(await store.createProject(input), {\n status: 201,\n });\n }\n\n const status =\n new URL(request.url).searchParams.get(\"status\") ?? \"all\";\n return Response.json(await store.listProjects(status));\n },\n project: async ({ request }) => {\n const { getProject } = await import(\"./project-store.server\");\n const id = decodeURIComponent(\n new URL(request.url).pathname.split(\"/\").at(-1)!,\n );\n const project = await getProject(id);\n return project\n ? Response.json(project)\n : Response.json({ error: \"Project not found\" }, { status: 404 });\n },\n },\n }),\n});\n```" }, { "id": "enable-plugin", "title": "Enable the plugin", "markdown": "Defining a plugin does not expose it by itself. Add it to the top-level plugins array in `tavo.config.ts`; the manifest exposure maps its declared server path onto the application's public URL tree.\n\nMerge into `tavo.config.ts`\n\n**Merge tavo.config.ts**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\nimport { projectApi } from \"./project-api\";\n\nexport default defineConfig({\n pagesDir: \"src/pages\",\n plugins: [projectApi],\n});\n```" }, { "id": "matching", "title": "Keep route matching explicit", "markdown": "Use exact matchers for individual URLs and subtree matchers for a deliberate route tree. Read query values and dynamic path pieces from `request.url`, validate them before use, and keep response formats stable for clients.\n\n- Return 405 when an endpoint does not support the incoming method.\n \n- Return deliberate content-type and cache headers.\n \n- Keep database and secret-bearing clients in server-only modules.\n \n- Bound request bodies and remote work with deployment-appropriate limits." }, { "id": "security", "title": "Preserve the request security boundary", "markdown": "Unsafe methods validate their origin by default. Disable that check only for independently authenticated endpoints such as verified webhooks, and authenticate and authorize every protected operation inside the handler.\n\n**A route is reachable without your UI**\n\nTreat every server route and page action as a public network surface. Client-side visibility and button state are not access control." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Plugins and localization\n\nUnderstand plugin services, ordering, routes, and request scope.Read guide →\n\n](/docs/core/plugins-and-localization)[\n\n## Security\n\nConfigure origins, hosts, redirects, bodies, and secrets.Read guide →\n\n](/docs/core/security)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:middleware", "section": "getting-started", "slug": "middleware", "title": "Middleware", "description": "Run fast request-aware checks before route loading and keep authentication data scoped to the active request.", "keywords": [ "middleware", "redirect", "authentication", "request", "server" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Run fast request-aware checks before route loading and keep authentication data scoped to the active request." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Data loading and middleware", "href": "/docs/core/data-and-middleware", "description": "Compare loader, resource, and middleware responsibilities." }, { "title": "Mutating data", "href": "/docs/getting-started/mutating-data", "description": "Enforce authorization again at the mutation boundary." } ], "canonicalPath": "/docs/getting-started/middleware", "sections": [ { "id": "role", "title": "Use middleware to control route flow", "markdown": "Middleware runs before loaders and rendering. It can allow navigation or redirect to another same-origin path with an optional redirect status. Use it for fast routing decisions rather than slow page data.\n\n- Use page middleware when the check belongs to one route.\n \n- Use layout middleware when descendants share the check.\n \n- Register plugin middleware for application-wide integration behavior.\n \n- Prefer hosting or platform redirect rules for unconditional redirects that do not need application request data." }, { "id": "server-only", "title": "Keep session checks on the server", "markdown": "`defineServerMiddleware` prevents the check from running during browser navigation. It is the right boundary for `HttpOnly` cookies, server sessions, private clients, and permission prechecks.\n\nBecause it is skipped during SPA navigation, server-only middleware is not a client navigation gate. Pair it with safe hydrated auth state or client navigation handling, and keep the real authorization check in every protected loader, action, and server route.\n\nCreate `src/pages/account.tsx`\n\n**Create src/pages/account.tsx**\n\n```tsx\nimport { defineServerMiddleware } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\nexport const middleware = defineServerMiddleware(async ({ request }) => {\n const { readSession } = await import(\"./session.server\");\n const session = await readSession(request);\n if (!session) return { redirect: \"/login\" };\n});\n\nexport default function AccountPage() {\n return (\n \n Account\n \n );\n}\n```\n\n**Prechecks are not complete authorization**\n\nRepeat resource-specific authorization inside the loader, action, or server route that reads or changes protected data. Middleware redirects improve flow; they do not make downstream code trusted." }, { "id": "middleware-execution", "title": "Know which middleware guards each entry path", "markdown": "Entry path\n\nPage middleware\n\nServer-only middleware\n\nFinal authorization\n\nDirect SSR request\n\nRuns\n\nRuns\n\nRepeat in loader or action\n\nHydration\n\nUses resolved route state\n\nDoes not rerun\n\nUse only safe serialized identity\n\nLater SPA navigation\n\nRuns\n\nSkipped\n\nProtected loader or endpoint decides\n\nDirect action or API request\n\nNot a security boundary\n\nDepends on registered request pipeline\n\nAction or handler must enforce it" }, { "id": "request-scope", "title": "Keep request data request-scoped", "markdown": "Read headers, cookies, and the URL from the supplied context. Pass only safe derived values through loader results or server services designed for the active request. Do not write the current user into a global store or module variable." }, { "id": "cancellation", "title": "Keep middleware fast and abortable", "markdown": "Middleware receives the navigation `AbortSignal`. Pass it to downstream work and stop promptly when navigation changes. Move route-critical data into a loader and avoid remote calls in middleware when a local cookie or claim is enough for the routing decision." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Data loading and middleware\n\nCompare loader, resource, and middleware responsibilities.Read guide →\n\n](/docs/core/data-and-middleware)[\n\n## Mutating data\n\nEnforce authorization again at the mutation boundary.Read guide →\n\n](/docs/getting-started/mutating-data)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:testing-and-diagnostics", "section": "getting-started", "slug": "testing-and-diagnostics", "title": "Testing and diagnostics", "description": "Check route behavior, project health, production rendering, and browser flows before a change reaches users.", "keywords": [ "testing", "doctor", "check", "routes", "bundle report", "browser tests" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Check route behavior, project health, production rendering, and browser flows before a change reaches users." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Testing and diagnostics", "href": "/docs/core/testing-and-diagnostics", "description": "Configure framework diagnostics, instrumentation, and test helpers." }, { "title": "Build and preview", "href": "/docs/cli/build-and-preview", "description": "Inspect build reports, bundle budgets, and production previews." } ], "canonicalPath": "/docs/getting-started/testing-and-diagnostics", "sections": [ { "id": "feedback-loop", "title": "Run the narrowest useful check", "markdown": "Use `TypeScript` and focused tests while editing, then widen the feedback loop as a change approaches release. `Tavo.js` diagnostics check the application shape and generated route contract without replacing tests for your product behavior.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tsc --noEmit\nnpx tavo doctor\nnpx tavo check\nnpx tavo routes\n```\n\n**Read the first useful failure**\n\nLater failures often follow from one invalid import, route, or configuration value. Fix the earliest actionable diagnostic, then run the checks again instead of treating the output as independent errors." }, { "id": "route-tests", "title": "Test routes without a browser", "markdown": "`createPagesTestHarness` resolves an in-memory page map with the same route conventions used by the application. Use it for fast route, loader, middleware, and error-path tests; keep DOM interaction and hydration assertions in a real browser.\n\nCreate `tests/pages/index.test.tsx`\n\n**Create tests/pages/index.test.tsx**\n\n```tsx\nimport { createPagesTestHarness } from \"@tavojs/core/dev\";\nimport { Text } from \"@tavojs/ui\";\n\nconst app = createPagesTestHarness({\n \"/src/pages/index.tsx\": {\n default: () => Project dashboard,\n },\n});\n\nexport async function homePageResolves() {\n const result = await app.runtime.resolvePathAsync(\"/\");\n if (\n result.status !== 200 ||\n result.pathname !== \"/\" ||\n result.route?.path !== \"/\"\n ) {\n throw new Error(\"Home page did not resolve successfully\");\n }\n}\n```" }, { "id": "production-checks", "title": "Test the production shape", "markdown": "A production build discovers routes, compiles client and server output, prerenders static pages, and reports `JavaScript` cost. SSR preview exercises the generated server entry rather than the development transform pipeline.\n\n- Exercise direct requests, client navigation, actions, 404 and error pages, and hydration in browser tests.\n \n- Start `npx` `tavo` preview `--ssr` in a separate terminal for manual SSR checks, or configure it as Playwright's `webServer`.\n \n- Inspect `.tavo/generated/build-report.json` when a route or shared first load grows unexpectedly.\n \n- Add `--max-first-load-js` and `--max-route-js` limits when CI should enforce bundle budgets.\n \n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tavo build --report-json\nnpx playwright test\n```" }, { "id": "diagnose-runtime", "title": "Keep runtime evidence actionable", "markdown": "Development diagnostics identify route, mount, patch, and hydration phases. Start with the first server-client divergence and its DOM path; suppressing the warning leaves the underlying ownership or rendering mismatch in place.\n\nProduction logs and instrumentation should record route patterns, phases, timing, and stable diagnostic codes. Exclude request bodies, cookies, tokens, and loader results unless the application has an explicit redaction policy." }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Testing and diagnostics\n\nConfigure framework diagnostics, instrumentation, and test helpers.Read guide →\n\n](/docs/core/testing-and-diagnostics)[\n\n## Build and preview\n\nInspect build reports, bundle budgets, and production previews.Read guide →\n\n](/docs/cli/build-and-preview)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:deploying", "section": "getting-started", "slug": "deploying", "title": "Deploying", "description": "Choose a runtime that matches the route contract, inspect generated output, and verify the real hosting boundary.", "keywords": [ "deployment", "static hosting", "Node" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Choose a runtime that matches the route contract, inspect generated output, and verify the real hosting boundary." ], "runtime": [ "server", "build" ], "related": [ { "title": "Deployment", "href": "/docs/core/deployment", "description": "Review artifacts, cache boundaries, security, and runtime requirements." }, { "title": "Deploy and monitor", "href": "/docs/cli/deploy-and-monitor", "description": "Build provider-neutral output and protect production monitoring endpoints." } ], "canonicalPath": "/docs/getting-started/deploying", "sections": [ { "id": "runtime-contract", "title": "Choose the runtime from application behavior", "markdown": "Static hosting can serve client-rendered assets and prerendered routes. Request-time features need a server runtime that can execute `Tavo.js`'s generated handler.\n\n- Use static hosting for CSR and fully prerendered output that has no request-time loader, action, session, or middleware work.\n \n- Use the generated Node production server for SSR, server loaders, route actions, sessions, and server routes.\n \n- Treat revalidation and shared cache invalidation as deployment capabilities; the process-local default is neither durable nor coordinated across replicas.\n \n\n**Static hosting cannot run server features**\n\nA successful static upload does not make loaders or actions available. Select a server target whenever correctness depends on work performed for each request." }, { "id": "build-output", "title": "Build once and inspect the artifacts", "markdown": "`tavo` build produces provider-neutral static and Node outputs. Do not edit generated files by hand or deploy stale artifacts.\n\nInspect `Generated output`\n\n**Reference Generated output**\n\n```text\n.tavo/build/client/ static assets and prerendered HTML\n.tavo/build/server/start.mjs generated Node production server\n```" }, { "id": "run-node-output", "title": "Run the Node output", "markdown": "Start the generated server directly when request-time behavior is required. Static-only applications can publish the client directory to any static host.\n\n- Keep authentication, loaders, actions, and business rules in application modules.\n \n- Rebuild after every application change.\n \n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tavo build\nPORT=4174 node .tavo/build/server/start.mjs\n```" }, { "id": "production-boundary", "title": "Verify the production boundary", "markdown": "Configure secrets, trusted hosts, canonical origin, request limits, cookies, CSP, remote image allowlists, and cache storage in the actual platform. Then smoke-test a direct SSR request, client navigation, mutation, error response, and static or revalidated route as applicable.\n\nProtect runtime monitoring with `TAVO_MONITOR_TOKEN` and send the token through the Authorization header. Use `tavo` monitor against the deployed URL to inspect a snapshot or watch the application after release.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tavo monitor --url https://app.example.com --token $MONITOR_TOKEN --once\n```" }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Deployment\n\nReview artifacts, cache boundaries, security, and runtime requirements.Read guide →\n\n](/docs/core/deployment)[\n\n## Deploy and monitor\n\nBuild provider-neutral output and protect production monitoring endpoints.Read guide →\n\n](/docs/cli/deploy-and-monitor)" } ], "sourceId": "tavo-website" }, { "id": "getting-started:upgrading", "section": "getting-started", "slug": "upgrading", "title": "Upgrading", "description": "Update the framework, framework CLI, and UI as one reviewed change, then validate production behavior.", "keywords": [ "upgrade", "dependencies", "release notes", "stability", "migration" ], "kind": "guide", "prerequisites": [ "A Tavo.js application created with the current CLI.", "Node.js 20.19+ or 22.12+ and the project dependencies installed." ], "outcomes": [ "Update the framework, framework CLI, and UI as one reviewed change, then validate production behavior." ], "runtime": [ "build" ], "related": [ { "title": "Core API reference", "href": "/docs/core/api", "description": "Review public entry points and the stability contract used by the application." }, { "title": "Web UI CLI", "href": "/docs/ui/cli", "description": "Validate theme configuration and inspect the installed UI tooling." } ], "canonicalPath": "/docs/getting-started/upgrading", "sections": [ { "id": "review-release", "title": "Review compatibility before changing versions", "markdown": "`Tavo.js` Framework 1.0 establishes the stable baseline. Read the Core and UI release notes for every version crossed, including configuration, generated-artifact, runtime, and experimental-API changes.\n\nCore publishes machine-readable stable and experimental labels from `@tavojs/core`. Stable entry points follow semantic versioning from 1.0 onward; experimental entry points may evolve more quickly.\n\n**Review experimental boundaries**\n\nCheck the release notes and every experimental entry point the application imports before updating the lockfile." }, { "id": "update-packages", "title": "Update the application packages together", "markdown": "Keep `@tavojs/core`, `@tavojs/cli`, and `@tavojs/ui` on compatible releases. The generated application installs `@tavojs/cli` as a development dependency and exposes its project-local `tavo` binary. The `tavo-ui` command is supplied through `@tavojs/ui`; do not install or upgrade `@tavojs/ui-cli` separately.\n\n- With `pnpm`, add `@tavojs/core` and `@tavojs/ui`, then add `@tavojs/cli` with `--save-dev`.\n \n- With Yarn, add the same three package names and keep `@tavojs/cli` in `devDependencies`.\n \n- With Bun, add the same three package names and keep `@tavojs/cli` in `devDependencies`.\n \n- Commit the manifest and lockfile together so CI and contributors install the reviewed dependency graph.\n \n\nRun in `Terminal — npm`\n\n**Run Terminal — npm**\n\n```bash\nnpm install @tavojs/core@latest @tavojs/ui@latest\nnpm install --save-dev @tavojs/cli@latest\n```" }, { "id": "diagnose-upgrade", "title": "Regenerate, then diagnose the project", "markdown": "Build once with the project-local CLI after installation so generated route types and manifests use the same version that will ship. Then diagnose the result. Treat doctor suggestions as reviewable changes; doctor `--fix-dry-run` reports proposed low-risk fixes without editing files.\n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tavo build\nnpx tavo doctor --fix-dry-run\nnpx tavo check\nnpx tavo routes\nnpx tavo-ui web check\n```" }, { "id": "release-gate", "title": "Run the full release gate", "markdown": "Typecheck and test the application, then create a production report and exercise the SSR output in a browser. Give extra attention to routing, hydration, actions, caching, error boundaries, theme output, and any API called out by the release notes.\n\n- Compare bundle reports and route manifests with the previous release when performance or static output is contractual.\n \n- Run `npx` `tavo` preview `--ssr` in a separate terminal and smoke-test direct production-rendered requests before release.\n \n- Deploy through the normal staging path and verify the generated output, secrets, caches, sessions, and monitor endpoint.\n \n- Keep the previous lockfile and deploy artifact available until the new release passes production smoke checks.\n \n\nRun in `Terminal`\n\n**Run Terminal**\n\n```bash\nnpx tsc --noEmit\nnpx tavo build --report-json\nnpx tavo verify --smoke --json\nnpx playwright test\n```" }, { "id": "checkpoint", "title": "Checkpoint", "markdown": "**Checkpoint**\n\n**Run Terminal**\n\n```bash\nnpm run typecheck\n```\n\n**Expected:** TypeScript completes without errors. The route or component reproduces the behavior described in this guide.\n\n**If it does not work:** Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration." }, { "id": "next-steps", "title": "Next steps", "markdown": "[\n\n## Core API reference\n\nReview public entry points and the stability contract used by the application.Read guide →\n\n](/docs/core/api)[\n\n## Web UI CLI\n\nValidate theme configuration and inspect the installed UI tooling.Read guide →\n\n](/docs/ui/cli)" } ], "sourceId": "tavo-website" }, { "id": "mcp:index", "section": "mcp", "slug": "", "title": "Use Tavo.js with AI coding agents", "description": "Connect MCP-compatible AI agents to versioned Tavo.js documentation, API metadata, component guidance, and optional read-only project inspection.", "keywords": [ "MCP", "AI agents", "Codex", "documentation", "project inspection", "@tavojs/mcp" ], "kind": "guide", "prerequisites": [ "Node.js 20.19+ or 22.12+.", "An MCP-compatible AI client.", "A Tavo.js application with a project-local @tavojs/cli package when project inspection is enabled." ], "outcomes": [ "Connect an AI client to @tavojs/mcp over local stdio.", "Choose between documentation-only and project-aware operation.", "Use Tavo.js knowledge and project tools within their read-only safety boundary." ], "runtime": [ "server" ], "related": [ { "title": "Framework CLI", "href": "/docs/cli", "description": "Understand the project-local inspection and verification commands used by MCP." }, { "title": "Tavo.js Framework overview", "href": "/docs/core", "description": "Learn the application model exposed through Tavo.js docs." } ], "canonicalPath": "/docs/mcp", "sections": [ { "id": "overview", "title": "Give agents exact Tavo.js context", "markdown": "Tavo.js MCP gives an AI coding agent a structured, searchable view of Tavo.js. The agent can discover Framework APIs, Tavo.js UI components, semantic tokens, and task-oriented guides instead of relying on generic framework assumptions.\n\nLocal mode can also inspect and verify a Tavo.js application through its project-local CLI. Model Context Protocol (MCP) is the connection between the AI client and Tavo.js; it does not replace the AI client or edit source code itself.\n\n**Read-only by design**\n\nEvery Tavo.js MCP capability is read-only. The AI host remains responsible for proposed code changes and user approval." }, { "id": "connect-locally", "title": "Connect locally", "markdown": "Tavo.js MCP runs through npm without a global installation. Add the following server definition to the configuration used by your MCP client:\n\n**Reference mcp.json**\n\n```json\n{\n \"mcpServers\": {\n \"tavo\": {\n \"command\": \"npx\",\n \"args\": [\n \"--yes\",\n \"@tavojs/mcp\",\n \"--project\",\n \"/absolute/path/to/tavo-app\"\n ]\n }\n }\n}\n```\n\nMCP client configuration formats differ, but the command and arguments are portable. Replace the example path with an absolute path to the target application. The application must provide a project-local `@tavojs/cli` package, which exposes the `tavo` binary.\n\nOmit `--project` and its path to keep the local server documentation-only.\n\n[View @tavojs/mcp on npm](https://www.npmjs.com/package/@tavojs/mcp)\n\n**Try the connection**\n\nAsk your agent: “Use the Tavo.js MCP server to inspect this project, find the documented pattern for a settings page, and tell me which files you would change. Do not edit anything.”" }, { "id": "connection-modes", "title": "Choose a connection mode", "markdown": "Mode\n\nBest for\n\nProject data\n\nCapabilities\n\nLocal stdio\n\nWorking inside a Tavo.js application\n\nRemains on the developer's machine\n\nPublic knowledge plus project context, inspection, and verification\n\nSelf-hosted Streamable HTTP\n\nServing public Tavo.js knowledge to remote clients\n\nNo project data accepted\n\nPublic documentation, APIs, components, and prompts\n\nUse local stdio for coding work because it can align guidance with the installed Tavo.js version and actual project structure. The npm package also includes a stateless HTTP transport for operators who want to host public documentation access. HTTP mode never accepts a project path or exposes project tools." }, { "id": "capabilities", "title": "What agents can use", "markdown": "### Public Tavo.js knowledge\n\nTool\n\nPurpose\n\n`search_tavo`\n\nSearch guides, APIs, components, and tokens by task.\n\n`get_tavo_document`\n\nRead one documentation record by stable ID.\n\n`find_tavo_components`\n\nFind UI components by intent, behavior, or accessibility need.\n\n`lookup_tavo_api`\n\nFind public Framework or Tavo.js UI symbols and package entry points.\n\n### Local project context\n\nTool\n\nPurpose\n\nSafety boundary\n\n`get_tavo_project_context`\n\nRead compact, task-bounded project conventions.\n\nAllowlisted agent-context CLI command\n\n`inspect_tavo_project`\n\nInspect a route, component, store, file, plugin, or API.\n\nAllowlisted inspect command and path validation\n\n`verify_tavo_project`\n\nRun diagnostics for the project or selected changed files.\n\nRestricted verification without project scripts\n\nThe server also exposes versioned resources under `tavo://` and reusable prompts for building features, choosing UI components, and diagnosing projects. Tool responses default to 2,048 tokens and accept a `maxTokens` budget from 256 to 8,192." }, { "id": "verification-safety", "title": "Keep project verification read-only", "markdown": "A normal project typecheck script is arbitrary project code: despite its name, it can write files, access the network, or perform another side effect.\n\n**Restricted verification**\n\nTavo.js MCP delegates project verification only to `tavo verify --no-project-scripts --json`. This performs Tavo.js diagnostics without invoking package scripts and reports that project scripts were disabled.\n\nThe adapter rejects incompatible Framework CLI versions rather than silently falling back to verification that could execute project scripts. Documentation compatibility is reported alongside project tool results." }, { "id": "documentation-sync", "title": "How documentation reaches the server", "markdown": "The server bundles a validated public documentation snapshot and never reads the Tavo.js Website repository at runtime:\n\n**Reference Reference snippet**\n\n```text\nTavo.js Website editorial source\n → export a validated public documentation manifest\n → bundle and index the snapshot in @tavojs/mcp\n → expose version and content hash to the MCP client\n```\n\nDocumentation updates require a new validated snapshot and MCP release. The runtime needs neither Website source nor Website credentials." }, { "id": "safety-and-privacy", "title": "Safety and privacy", "markdown": "- All MCP tools are read-only; the AI host remains responsible for changes and user approval.\n \n- HTTP mode never accepts --project and cannot inspect a developer's application.\n \n- Local inspection uses validated project-relative paths and only the allowlisted agent-context, inspect, and verify CLI machine commands.\n \n- Internal documentation and credentials are excluded from the bundled public content manifest.\n \n- Custom content manifests must pass schema and size validation before indexing.\n \n- The server cannot generate, change, build, or install project code." }, { "id": "troubleshooting", "title": "Troubleshooting", "markdown": "Problem\n\nWhat to check\n\nNo project tools\n\nUse local stdio and pass an absolute application path with --project.\n\nProject configuration fails\n\nConfirm the application has a compatible project-local @tavojs/cli package and can run its tavo machine commands.\n\nGuidance looks stale\n\nRead tavo://status and compare the content hash and package compatibility report.\n\nA response is truncated\n\nFollow its continuation resource or request a larger maxTokens value." }, { "id": "resources", "title": "Resources", "markdown": "- [@tavojs/mcp on npm](https://www.npmjs.com/package/@tavojs/mcp)\n- [Tavo.js MCP source](https://github.com/tavojs/tavo-mcp)\n- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)\n- [Tavo.js Framework documentation](/docs/core)\n- [Tavo.js UI documentation](/docs/ui)" } ], "sourceId": "tavo-website" }, { "id": "core:index", "section": "core", "slug": "", "title": "Tavo.js Framework documentation", "description": "The complete source of truth for building, rendering, extending, securing, testing, and operating a Tavo.js application.", "keywords": [ "framework", "runtime", "core", "architecture" ], "kind": "concept", "prerequisites": [ "Familiarity with TypeScript, TSX, and browser application development." ], "outcomes": [ "Explain how Tavo.js, its TSX runtime, Vite, file routes, loaders, rendering, and hydration fit together.", "Choose the correct Framework guide or exact API reference for a concrete development task." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Build your first Tavo.js app", "href": "/docs/getting-started/first-app", "description": "Apply the mental model in a cumulative project." }, { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up Tavo.js-specific terms and rendering acronyms." } ], "canonicalPath": "/docs/core", "sections": [ { "id": "choose-documentation-flow", "title": "Choose the documentation flow", "markdown": "[\n\n## Learn by building\n\nBuild your first Tavo.js application as one cumulative project. Use this when you are new to the Framework.Read guide →\n\n](/docs/getting-started/first-app)[\n\n## Understand a subsystem\n\nUse the Framework guides for mental models, complete workflows, defaults, lifecycle, cleanup, security, and production behavior.Read guide →\n\n](/docs/core/pages-and-layouts)[\n\n## Look up an exact API\n\nUse the generated reference for canonical imports, TypeScript signatures, runtime boundaries, stability, and owning guides.Read guide →\n\n](/docs/core/api)" }, { "id": "mental-model", "title": "How a Tavo.js application fits together", "markdown": "Tavo.js is a TypeScript and TSX framework with its own component runtime; it is not a React wrapper. Vite supplies the development server and bundling pipeline, while Tavo.js adds file routes, request data, server rendering, hydration, state, and production output.\n\nFiles in src/pages define the route tree. Middleware decides whether resolution continues, loaders prepare route data, and layouts compose the visible shell. Plain TSX components render interface; createTavo adds component-local state and controller behavior; stores share client state between consumers." }, { "id": "request-lifecycle", "title": "Follow one URL through Tavo.js", "markdown": "**Reference Reference snippet**\n\n```text\nURL\n → match a file route\n → run global, layout, and page middleware\n → load layout data from root to leaf, then page data\n → resolve route metadata\n → render or reuse SSR/static output, optionally stream deferred sections\n → send HTML and serialized route state\n → hydrate the same tree in the browser\n → handle later client navigation or server actions\n```\n\nThe exact work depends on the route mode. A CSR route sends a server shell and resolves in the browser. An SSR route renders for the request. Static and revalidated routes reuse SSR output according to their cache policy.\n\n**Keep request state inside the request**\n\nLoader results, sessions, users, and deferred work belong to one route resolution. Module variables, global stores, and runtime plugin capabilities may be shared by concurrent SSR requests." }, { "id": "choose", "title": "Browse the Framework by system", "markdown": "[\n\n## Fundamentals\n\nApplication configuration, environment boundaries, TSX components, DOM behavior, and the public package map.Read guide →\n\n](/docs/core/configuration)[\n\n## Routing and data\n\nFile routes, layouts, navigation, loaders, middleware, actions, forms, cancellation, pending UI, and route failures.Read guide →\n\n](/docs/core/pages-and-layouts)[\n\n## Application model\n\ncreateTavo, controllers, Stores, services, resources, async ownership, and shared application state.Read guide →\n\n](/docs/core/mvc)[\n\n## Rendering\n\nSSR, CSR, hydration, streaming, cache policy, metadata, styling, images, fonts, scripts, and localization.Read guide →\n\n](/docs/core/ssr-and-hydration)[\n\n## Server and security\n\nNode request handling, sessions, origins, trusted hosts, CSP, hydration exposure, remote assets, and failure containment.Read guide →\n\n](/docs/core/security)[\n\n## Extensions\n\nPlugin API v1, manifests, permissions, capabilities, installation instances, lifecycle phases, collisions, and inspection.Read guide →\n\n](/docs/core/plugins)[\n\n## Quality and tooling\n\nTesting, validation, diagnostics, scheduling, instrumentation, devtools, and development inspection.Read guide →\n\n](/docs/core/testing-and-diagnostics)[\n\n## Production\n\nBuild artifacts, static and Node delivery, monitoring, verification, and production troubleshooting.Read guide →\n\n](/docs/core/deployment)[\n\n## Reference\n\nRoute-module, configuration, runtime, diagnostic, stability, and canonical package API contracts.Read guide →\n\n](/docs/core/api)" }, { "id": "source-of-truth-contract", "title": "How to read this reference", "markdown": "Each focused guide explains ownership and lifecycle, provides a complete example, states defaults and failure behavior, and ends with a way to verify the result. Reference pages describe the exact public contract; the generated API inventory mirrors the declarations in the connected Framework checkout.\n\n**Public imports are the compatibility boundary**\n\nImport only from @tavojs/core, /router, /server, /config, /plugin, or the experimental /dev entry point. The /server-only and JSX runtime paths exist for their technical boundaries. Source implementation paths are not public APIs." }, { "id": "first-production-loop", "title": "Use the production loop early", "markdown": "Development mode optimizes iteration. A production build verifies route discovery, generated types, SSR output, static generation, and bundle boundaries.\n\n**Run Terminal**\n\n```bash\nnpx tavo check\nnpx tavo build --report-json\nnpx tavo preview --ssr\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:configuration", "section": "core", "slug": "configuration", "title": "Application configuration", "description": "Understand what belongs in tavo.config.ts, what belongs in vite.config.ts, and how to extend either file without discarding existing behavior.", "keywords": [ "configuration", "tavo.config", "vite.config", "plugins" ], "kind": "guide", "prerequisites": [ "A Tavo.js project created by the current CLI.", "Node.js 20.19+ or 22.12+ with project dependencies installed." ], "outcomes": [ "Place Framework and Vite settings in the correct file.", "Merge plugins and build settings without deleting generated configuration.", "Verify configuration with the local CLI and a production build." ], "runtime": [ "build" ], "related": [ { "title": "Environment variables", "href": "/docs/core/environment-variables", "description": "Separate server secrets from browser-safe configuration." }, { "title": "Runtime configuration reference", "href": "/docs/core/runtime-configuration", "description": "Inspect detailed SSR and handler defaults." }, { "title": "Plugins", "href": "/docs/core/plugins", "description": "Install and configure Plugin API v1 integrations." } ], "canonicalPath": "/docs/core/configuration", "sections": [ { "id": "starting-state", "title": "Start from the generated configuration", "markdown": "Use `Node.js 20.19+ or 22.12+` and run commands from the project root. A generated project already contains both configuration files. Edit those files in place instead of replacing them with an example from another project.\n\nFile\n\nRead by\n\nResponsibility\n\n`tavo.config.ts`\n\nTavo.js\n\nRoutes, CSS entries, plugins, diagnostics, build policy, and SSR behavior.\n\n`vite.config.ts`\n\nVite through Tavo.js\n\nVite server, resolve, dependency, and bundler settings while preserving Tavo.js's TSX and build plugins.\n\n`tsconfig.json`\n\nTypeScript\n\nTypechecking and Tavo.js's automatic TSX runtime configuration." }, { "id": "tavo-config", "title": "Configure framework behavior in tavo.config.ts", "markdown": "`defineConfig` preserves literal types and catches unsupported top-level fields. Paths are relative to the project root. Keep every existing plugin and CSS entry when adding another integration. `Tavo.js` has one framework configuration file at the project root; imported and computed values are evaluated consistently by development, build, inspection, and production.\n\n**Merge tavo.config.ts — merge with the existing file**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\nimport { tavoUi } from \"@tavojs/ui/plugin\";\n\nexport default defineConfig({\n pagesDir: \"src/pages\",\n cssEntries: [\"src/styles.css\"],\n diagnostics: {\n devOverlay: true,\n traces: false\n },\n build: {\n prerenderStyles: \"inline\",\n budgets: {\n firstLoadJs: \"150kb\",\n routeJs: \"40kb\"\n }\n },\n ssr: {\n trustedHosts: [\"example.com\"],\n canonicalOrigin: \"https://example.com\"\n },\n plugins: [tavoUi()]\n});\n```\n\n**Route modules have a separate contract**\n\nRendering mode, loaders, metadata, static output, and revalidation belong to page and layout modules. Do not move route-specific exports into tavo.config.ts.\n\n**Keep configuration in one file**\n\nExport defineConfig as the default from root tavo.config.ts. Plugins stay at the top level and server options stay inside the nested ssr object. Configuration load errors are reported instead of silently ignored." }, { "id": "top-level-reference", "title": "Top-level TavoConfig reference", "markdown": "These are all accepted top-level `TavoConfig` properties in `tavo.config.ts`. `defineConfig` rejects any other top-level key at typecheck time. Every property is optional, but the file and its default `defineConfig` export are required.\n\n**Reference tavo.config.ts**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\n\nexport default defineConfig({\n pagesDir: \"src/pages\",\n cssEntries: [\"src/styles/app.scss\"],\n diagnostics: {\n devOverlay: true,\n traces: false\n },\n ssr: {\n canonicalOrigin: \"https://example.com\"\n }\n});\n```\n\nProperty\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`pagesDir`\n\n`string`\n\nsrc/pages\n\nSets the project-root-relative directory scanned for pages, layouts, route groups, and special route modules.\n\n`cssEntries`\n\n`string[]`\n\nExisting files among src/styles.css, src/styles.scss, src/app.css, and src/app.scss\n\nSets project-root-relative global CSS or Sass entries loaded by development, client build, and SSR.\n\n`plugins`\n\n[`PluginUse`](/docs/core/api/plugin#api-tavojs-core-plugin--pluginuse)`[``]` `|` `{` `use``:` [`PluginUse`](/docs/core/api/plugin#api-tavojs-core-plugin--pluginuse)`[``]``;` `overrides``?``:` [`PluginOverride`](/docs/core/api/plugin#api-tavojs-core-plugin--pluginoverride)`[``]` `}`\n\nNo app plugins\n\nInstalls Plugin API v1 integrations. Use the array form for normal installs and the object form only when public overrides are needed.\n\n`diagnostics`\n\n`{ devOverlay?: boolean; traces?: boolean }`\n\nOmitted; generated apps set { devOverlay: true, traces: false }\n\nSets development error-overlay and framework trace preferences.\n\n`build`\n\n`{ prerenderStyles?: \"inline\" | \"external\"; budgets?: { … } }`\n\n{ prerenderStyles: \"inline\", budgets: {} }\n\nControls prerendered CSS delivery and JavaScript budget enforcement.\n\n`ssr`\n\n`Tavo.js SSR options`\n\nRuntime defaults shown below\n\nConfigures page-runtime behavior, Node requests, response caching, the HTML document, and image optimization.\n\n**Paths are project-root relative**\n\npagesDir, cssEntries, ssr.images.publicDir, and the root used by normal build commands resolve from the application root. A configured CSS entry that does not exist is skipped by the production build; npx tavo check reports missing entries before release." }, { "id": "diagnostics-build-reference", "title": "Diagnostics and build properties", "markdown": "Property\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`diagnostics.devOverlay`\n\n`boolean`\n\nGenerated apps: true\n\nEnables or disables the development error-overlay preference.\n\n`diagnostics.traces`\n\n`boolean`\n\nGenerated apps: false\n\nEnables or disables detailed framework diagnostic traces.\n\n`build.prerenderStyles`\n\n`\"inline\" | \"external\"`\n\ninline\n\nInlines collected route styles into prerendered HTML or writes references to external build assets.\n\n`build.budgets.firstLoadJs`\n\n`number | byte-size string`\n\nNo limit\n\nFails the production build when JavaScript needed for a route's first load exceeds this number of bytes.\n\n`build.budgets.routeJs`\n\n`number | byte-size string`\n\nNo limit\n\nFails the production build when JavaScript attributed to one route exceeds this number of bytes.\n\nBudget strings accept bytes or the case-insensitive units b, kb, kib, mb, and mib; decimal strings such as 1.5mb are valid. Numeric values are bytes. CLI flags override the file for one build.\n\n**Run Terminal**\n\n```bash\nnpx tavo build --max-first-load-js 150kb --max-route-js 40kb\nnpx tavo build --prerender-styles external\n```" }, { "id": "ssr-reference", "title": "SSR and page-runtime properties", "markdown": "The ssr object accepts the following properties. The CLI supplies discovered route modules and compiles top-level plugins, so most applications configure only origin security, rendering, caches, or images here.\n\nProperty\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`ssr.canonicalOrigin`\n\n`absolute HTTP(S) origin string`\n\nOrigin derived from the request Host over HTTP\n\nSets the public origin behind TLS termination. Credentials, paths, queries, and fragments are rejected; its host is also trusted for actions.\n\n`ssr.trustedHosts`\n\n`string[]`\n\nLocalhost variants, plus canonicalOrigin when configured\n\nAllows Host values used to validate Node action and plugin mutation requests. Entries may include a hostname or host with port.\n\n`ssr.allowExternalRedirects`\n\n`boolean`\n\nfalse\n\nAllows route and middleware redirects to absolute HTTP(S) URLs. Relative same-origin paths remain allowed without it.\n\n`ssr.stream`\n\n`boolean`\n\nfalse\n\nStreams the SSR response instead of buffering the completed document.\n\n`ssr.maxRequestBodyBytes`\n\n`number`\n\n10 MiB\n\nLimits buffered non-GET request bodies in the Node handler. Requests above the limit receive 413.\n\n`ssr.maxResolvedCacheEntries`\n\n`finite non-negative number`\n\n1,024\n\nLimits the process-local route-resolution data cache. Values are floored; 0 disables reuse.\n\n`ssr.staticCache`\n\n[`SsrStaticCache`](#ssr-static-cache)\n\nProcess-local memory cache with 1,024 entries\n\nStores rendered responses for static and revalidated routes. Supply an adapter for shared or durable caching.\n\n`ssr.document`\n\n[`RenderDocumentOptions`](#render-document-options)\n\nDocument defaults shown below\n\nSets the shared HTML shell, attributes, serialized initial state, CSP nonce, and style registry.\n\n`ssr.images`\n\n[`ImageOptimizerOptions`](#image-optimizer-options)\n\nOptimizer defaults shown below\n\nConfigures /\\_tavo/image, local and remote sources, transform limits, formats, and memory caching.\n\n`ssr.getPageProps`\n\n`() => Record`\n\nNo extra props\n\nAdds application-owned props to page components on each runtime render.\n\n`ssr.notFound`\n\n[`Component`](/docs/core/api/components-and-dom#api-tavojs-core--component)`<``{` `pathname``:` `string` `}``>`\n\nDiscovered src/pages/404 module\n\nOverrides the application-wide not-found component supplied by file routing.\n\n`ssr.csrFallback`\n\n[`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child) `|` `(``{` `pathname``,` `params` `}``)` `=>` [`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child)\n\nnull\n\nRenders fallback content when a CSR route is resolved by the browser before its route module is ready.\n\n`ssr.csrActions`\n\n[`CsrActionsOptions`](#csr-actions-options)\n\nDisabled\n\nMaps browser form submissions for static CSR delivery to an action backend. Nested properties are listed below.\n\n`ssr.middleware`\n\n[`PageMiddleware`](/docs/core/api/router#api-tavojs-core-router--pagemiddleware)`[``]`\n\n\\[\\]\n\nRuns application-wide middleware around every route in addition to discovered layout and page middleware.\n\n`ssr.i18n`\n\n[`I18nService`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--i18nservice)\n\nRegistered default i18n service, otherwise none\n\nSupplies locale detection, localized path resolution, and locale state to the pages runtime.\n\n`ssr.instrumentation`\n\n[`{ emit(event: TavoInstrumentationEvent): void }`](/docs/core/scheduling-and-instrumentation#event-contract)\n\nNone\n\nReceives route resolve, middleware, loader, action, and cache lifecycle events. Listener failures do not interrupt framework work.\n\n`ssr.modules`\n\n`PageModules`\n\nGenerated route-module map\n\nOverrides file-discovered modules. This is an advanced manual-runtime hook; normal applications leave it unset.\n\n**Plugins do not belong under ssr**\n\nssr.plugins is intentionally not part of TavoConfig. Install plugins with the top-level plugins array or the public { use, overrides } form. Plugin graph compilation and runtime construction are framework host responsibilities." }, { "id": "csr-actions-options", "title": "CSR action properties", "markdown": "Configure ssr.csrActions when a statically hosted CSR application should submit Tavo.js forms to a separate action server. resolveUrl takes precedence over baseUrl.\n\nProperty\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`ssr.csrActions.enabled`\n\n`boolean`\n\nfalse\n\nIntercepts eligible non-GET forms and enables action URL mapping.\n\n`ssr.csrActions.baseUrl`\n\n`string`\n\nCurrent origin and route path\n\nResolves the route pathname and query against a separate action-server base URL.\n\n`ssr.csrActions.resolveUrl`\n\n`({ pathname, search, form? }) => string`\n\nUses baseUrl, then the route path\n\nComputes the complete action request URL for each route or form.\n\n`ssr.csrActions.credentials`\n\n`RequestCredentials`\n\ninclude\n\nSets the Fetch credentials mode used for intercepted form submissions.\n\n`ssr.csrActions.headers`\n\n`HeadersInit | ({ pathname, form }) => HeadersInit`\n\nNo additional headers\n\nAdds fixed or per-form request headers to the action fetch.\n\n**Reference tavo.config.ts — send static-site forms to an action service**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\n\nexport default defineConfig({\n ssr: {\n csrActions: {\n enabled: true,\n baseUrl: \"https://actions.example.com\",\n credentials: \"include\",\n headers: ({ pathname }) => ({\n \"X-Tavo.js-Route\": pathname\n })\n }\n }\n});\n```" }, { "id": "render-document-options", "title": "HTML document properties", "markdown": "ssr.document sets defaults for the server-rendered document shell. Route head exports and Tavo.js SEO components can refine metadata per route.\n\nProperty\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`ssr.document.lang`\n\n`string`\n\nen\n\nSets the escaped html lang attribute.\n\n`ssr.document.title`\n\n`string`\n\nNo title\n\nSets the escaped fallback document title. Route SEO metadata takes precedence.\n\n`ssr.document.unsafeHeadHtml`\n\n`string`\n\nEmpty\n\nAppends trusted raw HTML to head. It is not escaped; prefer TSX metadata for all structured head content.\n\n`ssr.document.htmlAttributes`\n\n`Record`\n\n{}\n\nAdds escaped safe-name attributes to html. false omits an attribute and true renders a boolean attribute.\n\n`ssr.document.bodyAttributes`\n\n`Record`\n\n{}\n\nAdds escaped attributes to body.\n\n`ssr.document.appAttributes`\n\n`Record`\n\n{}\n\nAdds escaped attributes to the application container.\n\n`ssr.document.doctype`\n\n`string`\n\n\n\nSets the exact doctype prefix written before the html element.\n\n`ssr.document.appContainerId`\n\n`string`\n\napp\n\nSets the escaped id of the application container used by hydration.\n\n`ssr.document.initialState`\n\n`unknown`\n\nOmitted\n\nSerializes JSON into a protected application/json script after the app container.\n\n`ssr.document.stateScriptId`\n\n`string`\n\n\\_\\_TAVO\\_STATE\\_\\_\n\nSets the escaped id of the serialized initial-state script.\n\n`ssr.document.nonce`\n\n`string`\n\nNone\n\nAdds a CSP nonce to generated state and style elements.\n\n`ssr.document.beforeRender`\n\n`() => void`\n\nNone\n\nRuns immediately before server rendering. Use only for request-safe setup.\n\n`ssr.document.styleRegistry`\n\n[`StyleRegistry`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--styleregistry)\n\nA new registry for each render\n\nSupplies a custom style collector with add, has, and entries methods.\n\n**Raw HTML is always explicit**\n\nThere is no head string alias. Use escaped TSX metadata first, and use unsafeHeadHtml only when an integration truly requires trusted raw markup." }, { "id": "image-optimizer-options", "title": "Image optimizer properties", "markdown": "Property\n\nAccepted value\n\nDefault\n\nWhat it changes\n\n`ssr.images.enabled`\n\n`boolean`\n\ntrue\n\nEnables the /\\_tavo/image optimization endpoint.\n\n`ssr.images.allowRemote`\n\n`boolean`\n\nfalse\n\nAllows remote HTTP(S) image sources, still subject to remotePatterns and network safety checks.\n\n`ssr.images.remotePatterns`\n\n`Array`\n\n\\[\\]\n\nAllowlists remote origins or host/path patterns. A hostname beginning with \\*. matches subdomains only.\n\n`ssr.images.publicDir`\n\n`string`\n\npublic\n\nSets the project-root-relative source directory for local images.\n\n`ssr.images.quality`\n\n`number`\n\n75\n\nSets fallback output quality; request values are clamped from 1 through 100.\n\n`ssr.images.cacheMaxAge`\n\n`number`\n\n31,536,000 seconds\n\nSets the Cache-Control max-age of transformed image responses.\n\n`ssr.images.defaultFormat`\n\n`\"webp\" | \"avif\" | \"jpeg\" | \"png\" | \"original\"`\n\nwebp\n\nSets the output format when the optimization URL does not request one.\n\n`ssr.images.sizes`\n\n`number[]`\n\n\\[320, 640, 960, 1280, 1600\\]\n\nSets the candidate widths and supplies the fallback width for an optimization request.\n\n`ssr.images.timeoutMs`\n\n`number`\n\n5,000\n\nLimits remote fetch duration.\n\n`ssr.images.maxBytes`\n\n`number`\n\n10 MiB\n\nRejects local or remote source images larger than this byte limit.\n\n`ssr.images.memoryCacheMaxEntries`\n\n`number`\n\n128\n\nLimits transformed images stored in process memory. Values are floored; 0 disables storage.\n\n`ssr.images.maxConcurrentTransforms`\n\n`number`\n\n4\n\nLimits simultaneous Sharp transforms; values are floored with a minimum of 1.\n\n`ssr.images.maxPendingTransforms`\n\n`number`\n\n64\n\nLimits queued transforms before the optimizer returns a busy error.\n\n`ssr.images.allowInsecureRemote`\n\n`boolean`\n\nfalse\n\nAllows HTTP remote image URLs. Keep disabled unless the transport risk is explicitly accepted.\n\n`ssr.images.resolveHostname`\n\n`(hostname: string) => Promise>`\n\nNode DNS lookup\n\nOverrides DNS resolution used by private-network protection. Intended for adapters and controlled tests.\n\n**Reference tavo.config.ts — allow a narrow remote image source**\n\n```ts\nimport { defineConfig } from \"@tavojs/core/config\";\n\nexport default defineConfig({\n ssr: {\n images: {\n allowRemote: true,\n remotePatterns: [\n {\n protocol: \"https:\",\n hostname: \"images.example.com\",\n pathname: \"/products\"\n }\n ],\n defaultFormat: \"avif\",\n quality: 80\n }\n }\n});\n```\n\nServer image transforms require the optional sharp dependency in the application that runs SSR. Remote requests are checked against the allowlist, redirects, DNS results, private-network addresses, timeout, and byte limit." }, { "id": "ssr-static-cache", "title": "SsrStaticCache adapter", "markdown": "Use the public SsrStaticCache interface from @tavojs/core/server when rendered static and revalidated responses must be shared across processes or persisted outside Node memory. Methods may return values directly or through promises.\n\n**Reference src/server/static-cache.ts — minimal adapter**\n\n```ts\nimport type {\n SsrStaticCache,\n SsrStaticCacheEntry\n} from \"@tavojs/core/server\";\n\nconst entries = new Map();\n\nexport const staticCache: SsrStaticCache = {\n get(key) {\n return entries.get(key) ?? null;\n },\n\n set(key, entry) {\n entries.set(key, entry);\n },\n\n delete(key) {\n entries.delete(key);\n },\n\n invalidateTags(tags) {\n const requested = new Set(tags);\n let deleted = 0;\n\n for (const [key, entry] of entries) {\n if (entry.tags.some((tag) => requested.has(tag))) {\n entries.delete(key);\n deleted += 1;\n }\n }\n\n return deleted;\n },\n\n clear() {\n entries.clear();\n }\n};\n```\n\n`SsrStaticCacheEntry` contains the rendered response, an absolute `expiresAt` timestamp or null, and its cache tags. The built-in `createMemoryStaticCache` is available from `@tavojs/core/server`. The Map above illustrates the contract; use a shared cache implementation for multi-process production deployments.\n\n**Tag invalidation is optional but operationally important**\n\nWithout invalidateTags, cache-tag invalidation returns zero and cannot remove matching entries. Maintain a tag index in production adapters when invalidation volume makes a full scan inappropriate." }, { "id": "loading-behavior", "title": "Configuration loading behavior", "markdown": "**Reference scripts/read-config.ts**\n\n```ts\nimport { loadTavoConfig } from \"@tavojs/core/dev\";\n\nconst config = await loadTavoConfig(process.cwd(), {\n mode: \"development\"\n});\n\nconsole.log(config.pagesDir);\n```\n\nConcern\n\nContract\n\nLocation\n\nExactly one tavo.config.ts at the project root.\n\nExport\n\nA default export returned by defineConfig({ … }). A plain object is rejected.\n\nEvaluation\n\nImported and computed values are supported. The file is evaluated once per project root and process.\n\nEnvironment\n\n.env files are loaded before evaluation. The explicit mode wins, then NODE\\_ENV, then production.\n\nMode safety\n\nOne project root cannot be reevaluated in a different mode in the same process.\n\nFailure\n\nA failed load is not cached, so the next command or retry can load a corrected file." }, { "id": "vite-config", "title": "Keep Tavo.js's Vite wrapper", "markdown": "defineTavoViteConfig installs Tavo.js's TSX transform, file-route build guards, SVG support, localization splitting, and plugin build contributions. Pass your Vite settings into the wrapper rather than replacing it with Vite's defineConfig.\n\n**Replace vite.config.ts — replace only the empty wrapper call**\n\n```ts\nimport { defineTavoViteConfig } from \"@tavojs/core/config\";\n\nexport default defineTavoViteConfig(({ mode }) => ({\n server: {\n port: mode === \"development\" ? 4174 : undefined\n },\n build: {\n sourcemap: mode !== \"production\"\n }\n}));\n```" }, { "id": "verify-configuration", "title": "Verify the result", "markdown": "**Run Terminal**\n\n```bash\nnpx tavo info\nnpx tavo check\nnpm run build\n```\n\ninfo shows the resolved pages and CSS configuration, check reports route and project-shape problems, and the production build exercises both client and server configuration. If a plugin was added, run `npx tavo inspect plugins` as well." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:environment-variables", "section": "core", "slug": "environment-variables", "title": "Environment variables", "description": "Load server configuration safely, expose only deliberate public values to browser code, and understand mode-specific .env files.", "keywords": [ "environment", ".env", "VITE_", "secrets", "server-only" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with server rendering or build-time configuration." ], "outcomes": [ "Choose a server, browser, or build boundary for each environment value.", "Understand Tavo.js's .env file precedence.", "Keep secrets behind an enforced server-only module boundary." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Application configuration", "href": "/docs/core/configuration", "description": "Configure Framework and Vite behavior." }, { "title": "Security", "href": "/docs/core/security", "description": "Harden secrets, sessions, and request boundaries." } ], "canonicalPath": "/docs/core/environment-variables", "sections": [ { "id": "server-and-browser", "title": "Choose the boundary before naming the variable", "markdown": "Boundary\n\nExample\n\nRead it from\n\nServer only\n\n`process.env.DATABASE_URL`\n\nsrc/server, a server loader, action, middleware, or server plugin phase\n\nBrowser safe\n\n`import.meta.env.VITE_PUBLIC_API_ORIGIN`\n\nA normal source module used by browser code\n\nBuild/configuration\n\n`process.env.TAVO_SITE_URL`\n\ntavo.config.ts or server-side build tooling\n\n**VITE\\_ means public**\n\nVite replaces VITE\\_-prefixed values in browser bundles. Never use that prefix for passwords, signing keys, database URLs, private tokens, or any value that must remain secret." }, { "id": "env-files", "title": "Use mode-specific files deliberately", "markdown": "Tavo.js's server runtime reads these files from the project root. Later files override earlier files, while an environment variable already supplied by the shell or hosting platform wins over every file.\n\n**Reference Environment load order**\n\n```text\n.env\n.env.local\n.env.development\n.env.development.local\n\n# A production run uses .env.production and .env.production.local instead.\n```\n\nCommit non-secret defaults in .env when appropriate. Keep .env.local and mode-local files out of source control. Commit an .env.example containing names and safe placeholders so new developers know what the application requires." }, { "id": "server-example", "title": "Read secrets behind a server-only boundary", "markdown": "**Create src/server/projects.ts — create this server-only module**\n\n```ts\nimport \"@tavojs/core/server-only\";\n\nconst databaseUrl = process.env.DATABASE_URL;\n\nif (!databaseUrl) {\n throw new Error(\"DATABASE_URL is required\");\n}\n\nexport function getProjectsDatabaseUrl(): string {\n return databaseUrl;\n}\n```\n\nFiles under src/server and modules importing the server-only marker are framework-enforced client-build boundaries. Import them from a server loader, action, middleware, or server plugin phase. Do not statically import them into a component or universal loader." }, { "id": "public-example", "title": "Expose only browser-safe configuration", "markdown": "**Run .env.example — add the required public name**\n\n```bash\nVITE_PUBLIC_API_ORIGIN=https://api.example.com\n```\n\n**Create src/config/public.ts — create this shared module**\n\n```ts\nexport const publicConfig = {\n apiOrigin: import.meta.env.VITE_PUBLIC_API_ORIGIN\n};\n```\n\nRestart the development server after changing an environment file. Verify a server value through the route or handler that consumes it; verify a public value in the browser without printing unrelated environment data." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:components-and-jsx", "section": "core", "slug": "components-and-jsx", "title": "Components and JSX", "description": "Build functional Tavo.js components, understand the JSX contract, and choose when local behavior belongs in createTavo.", "keywords": [ "component", "JSX", "TSX", "Fragment", "children", "events", "controlled input" ], "kind": "guide", "prerequisites": [ "A Tavo.js application configured for the automatic JSX runtime.", "Familiarity with TypeScript functions and HTML attributes." ], "outcomes": [ "Write plain functional components with typed props and children.", "Use intrinsic attributes, events, class names, and controlled values correctly.", "Choose a function component, createTavo model, controller, or shared Store deliberately." ], "runtime": [ "browser", "server" ], "related": [ { "title": "MVC components", "href": "/docs/core/mvc", "description": "Add component-local state, controller behavior, and managed lifecycle work." }, { "title": "DOM and accessibility", "href": "/docs/core/dom-and-accessibility", "description": "Use refs, directives, focus management, transitions, and observers." }, { "title": "SSR and hydration", "href": "/docs/core/ssr-and-hydration", "description": "Keep the first browser render aligned with server output." } ], "canonicalPath": "/docs/core/components-and-jsx", "sections": [ { "id": "functional-components", "title": "Start with a function component", "markdown": "A Tavo.js component is a function that receives props and returns a renderable [`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child \"View Child in the Core API reference\"). Use a plain function when output depends only on props, children, or application services that are already reactive.\n\nThe automatic JSX runtime compiles TSX for you. Import runtime values such as [`Fragment`](/docs/core/api/components-and-dom#api-tavojs-core--fragment \"View Fragment in the Core API reference\") only when you reference them explicitly.\n\n- Strings, numbers, elements, nested child arrays, null, undefined, and booleans are valid children. Nullish and boolean children do not produce HTML.\n \n- [`Fragment`](/docs/core/api/components-and-dom#api-tavojs-core--fragment \"View Fragment in the Core API reference\") groups siblings without adding a DOM element.\n \n- Explicit children passed between component tags are available through `props.children`.\n \n- A `className` may be one string or an array of strings; arrays are joined with spaces.\n \n- A style value may be a CSS string or an object. Object keys written in camel case become kebab-case CSS properties during SSR.\n \n\n**Reference src/components/StatusBadge.tsx**\n\n```tsx\nimport type { PropsWithChildren } from \"@tavojs/core\";\n\ntype StatusBadgeProps = PropsWithChildren<{\n tone: \"neutral\" | \"success\" | \"danger\";\n}>;\n\nexport function StatusBadge({\n tone,\n children,\n}: StatusBadgeProps) {\n return (\n \n {children}\n \n );\n}\n```" }, { "id": "choose-state-owner", "title": "Choose the smallest state owner", "markdown": "Rendering and state ownership are separate decisions. Keep a component functional until it needs local reactive state, behavior, lifecycle, or cleanup.\n\n- Use a plain function component for render-only output.\n \n- Use [`createTavo`](/docs/core/api/application#api-tavojs-core--createtavo \"View createTavo in the Core API reference\") with a model for state owned by one mounted component.\n \n- Add a [`TavoController`](/docs/core/api/application#api-tavojs-core--tavocontroller \"View TavoController in the Core API reference\") for behavior, routing, services, refs, async actions, or managed side effects.\n \n- Use a global [`Store`](/docs/core/api/application#api-tavojs-core--store \"View Store in the Core API reference\") for browser state intentionally shared by multiple routes or component owners.\n \n- Use a route loader for request-specific and route-critical data; do not place request identity in global state.\n \n\n**Reference src/components/NameField.tsx**\n\n```tsx\nimport { createTavo, TavoController } from \"@tavojs/core\";\n\ntype NameFieldState = {\n name: string;\n};\n\nclass NameFieldController extends TavoController {\n updateName(event: Event) {\n const input = event.currentTarget as HTMLInputElement;\n this.model.patch({ name: input.value });\n }\n}\n\nexport const NameField = createTavo<\n Record,\n NameFieldState,\n NameFieldController\n>({\n model() {\n return { name: \"\" };\n },\n controller: NameFieldController,\n view({ state, controller }) {\n return (\n \n );\n },\n});\n```" }, { "id": "intrinsic-runtime", "title": "Understand intrinsic element behavior", "markdown": "- Text and attribute values are escaped. Unsafe attribute names and javascript-style URL protocols are rejected.\n \n- Event props begin with on and are attached by the browser runtime; they are not serialized into server HTML.\n \n- ref, use, transition, and key are runtime instructions rather than HTML attributes.\n \n- Boolean true emits a boolean attribute; false, null, and undefined omit the attribute.\n \n- HTML void elements such as input, img, and br render without closing tags.\n \n- Unknown safe intrinsic attributes pass through, which keeps data-\\* and aria-\\* attributes available.\n \n\n**Reference src/components/ProfileLink.tsx**\n\n```tsx\nexport function ProfileLink({\n active,\n userId,\n}: {\n active: boolean;\n userId: string;\n}) {\n return (\n \n View profile\n \n );\n}\n```\n\n**Render purity keeps hydration predictable**\n\nA component may render on the server and again in the browser. Do not read window, document, time, randomness, or browser storage while producing initial output. Move browser work to a controller lifecycle hook." }, { "id": "manual-rendering", "title": "Mount outside the Pages runtime", "markdown": "Most applications let Auto Pages create and hydrate the root. Use [`createRoot`](/docs/core/api/components-and-dom#api-tavojs-core--createroot \"View createRoot in the Core API reference\") when Tavo.js is embedded in an existing page, widget host, test shell, or other manually owned DOM container.\n\n- `root.render`(node) owns repeat renders; `root.unmount`() removes the tree and releases refs, directives, listeners, and controller cleanup.\n \n- Use `root.hydrate`(node) only when the container already holds matching server-rendered `Tavo.js` markup.\n \n- render(node, container) is the convenience form for a one-off browser mount when you do not need the [`Root`](/docs/core/api/components-and-dom#api-tavojs-core--root \"View Root in the Core API reference\") handle.\n \n- `renderToString`(node) returns escaped static HTML. Use the server rendering APIs instead when you need a complete document, route resolution, status, headers, head output, streaming, or hydration state.\n \n- The automatic JSX transform normally creates [`VNode`](/docs/core/api/components-and-dom#api-tavojs-core--vnode \"View VNode in the Core API reference\") values. [`h`](/docs/core/api/components-and-dom#api-tavojs-core--h \"View h in the Core API reference\") is the lower-level explicit constructor for tooling or non-JSX integrations.\n \n\n**Reference src/widget.tsx**\n\n```tsx\nimport { createRoot } from \"@tavojs/core\";\nimport { SupportWidget } from \"./SupportWidget\";\n\nconst container = document.querySelector(\"#support-widget\");\n\nif (!(container instanceof HTMLElement)) {\n throw new Error(\"Missing #support-widget container.\");\n}\n\nconst root = createRoot(container);\nroot.render();\n\n// Call this when the host removes the widget.\nexport function unmountSupportWidget() {\n root.unmount();\n}\n```\n\n**Reference src/render-card.tsx**\n\n```tsx\nimport { renderToString } from \"@tavojs/core\";\nimport { ReceiptCard } from \"./ReceiptCard\";\n\nexport function renderReceiptCard(total: string) {\n return renderToString();\n}\n```\n\n**Do not create a second application root**\n\nInside an Auto Pages application, render normal components from the route tree. A manual root is for a separately owned DOM container, not for replacing the route runtime." }, { "id": "controlled-fields", "title": "Treat value and checked as controlled", "markdown": "When value or checked comes from model state, update that same state from the corresponding event. The browser runtime restores the rendered value after an input event, so a static controlled value intentionally remains pinned.\n\n- Use `onChange` for live text-entry updates; `Tavo.js` maps the browser input event into the controlled-field flow.\n \n- Read `event.currentTarget` or `event.target` as the correct input element before updating the model.\n \n- Give every field an accessible label and expose validation with normal HTML constraints and `aria-describedby` where needed.\n \n- Use [`focusFirstInvalid`](/docs/core/api/components-and-dom#api-tavojs-core--focusfirstinvalid \"View focusFirstInvalid in the Core API reference\") after a failed client validation pass when moving focus is helpful and expected." }, { "id": "component-verification", "title": "Verify both render environments", "markdown": "- Render the component to HTML and confirm text, escaping, boolean attributes, class names, styles, and void elements.\n \n- Mount it in a browser test and confirm event updates, controlled values, focus, and cleanup.\n \n- Hydrate server markup and check that the first browser output matches without a hydration diagnostic.\n \n- Typecheck public props and event targets; do not rely on casts hidden inside application callers." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:dom-and-accessibility", "section": "core", "slug": "dom-and-accessibility", "title": "DOM and accessibility", "description": "Own DOM handles safely with refs, directives, focus utilities, transitions, observers, and explicit cleanup.", "keywords": [ "ref", "directive", "focus", "accessibility", "transition", "observer", "cleanup" ], "kind": "guide", "prerequisites": [ "A client-rendered or hydrated Tavo.js component.", "A DOM behavior that cannot be expressed through declarative props alone." ], "outcomes": [ "Use object, callback, merged, and keyed-list refs.", "Attach reusable directives and understand their cleanup timing.", "Build accessible focus ownership and managed observation." ], "runtime": [ "browser" ], "related": [ { "title": "Components and JSX", "href": "/docs/core/components-and-jsx", "description": "Review intrinsic props and client-only runtime behavior." }, { "title": "MVC components", "href": "/docs/core/mvc", "description": "Use controller lifecycle and managed side-effect helpers." }, { "title": "Routing and navigation", "href": "/docs/core/routing", "description": "Understand route focus restoration and accessible navigation." } ], "canonicalPath": "/docs/core/dom-and-accessibility", "sections": [ { "id": "ref-lifecycle", "title": "Use refs for direct DOM ownership", "markdown": "[`createRef`](/docs/core/api/components-and-dom#api-tavojs-core--createref \"View createRef in the Core API reference\") returns a mutable object whose current value follows one intrinsic element. Tavo.js assigns it on mount and hydration, moves it when the backing node changes, and clears it on replacement or unmount.\n\n- Object refs are convenient controller fields. Callback refs receive the node and later receive null during cleanup.\n \n- [`mergeRefs`](/docs/core/api/components-and-dom#api-tavojs-core--mergerefs \"View mergeRefs in the Core API reference\") combines multiple ref owners into one callback ref.\n \n- [`createListRefs`](/docs/core/api/components-and-dom#api-tavojs-core--createlistrefs \"View createListRefs in the Core API reference\") creates stable object refs by a string or numeric key; delete removed keys and clear the collection when its owner is disposed.\n \n- [`setRef`](/docs/core/api/components-and-dom#api-tavojs-core--setref \"View setRef in the Core API reference\") is useful when composing a higher-level component or adapter that forwards a DOM node.\n \n- Refs are never serialized into server HTML and remain null during server rendering.\n \n\n**Reference src/components/SearchField.tsx**\n\n```tsx\nimport {\n createRef,\n createTavo,\n TavoController,\n} from \"@tavojs/core\";\n\nclass SearchFieldController extends TavoController {\n input = createRef();\n\n onMount() {\n this.input.current?.select();\n }\n}\n\nexport const SearchField = createTavo({\n controller: SearchFieldController,\n view({ controller }) {\n return (\n \n );\n },\n});\n```\n\n**Reference src/components/ResultList.tsx**\n\n```tsx\nimport {\n createListRefs,\n createRef,\n createTavo,\n mergeRefs,\n TavoController,\n} from \"@tavojs/core\";\n\ntype Result = { id: string; label: string };\n\nclass ResultListController extends TavoController {\n items = createListRefs();\n measuredItem = createRef();\n featuredItem = mergeRefs(\n this.items.get(\"featured\"),\n this.measuredItem,\n );\n\n onUnmount() {\n this.items.clear();\n }\n}\n\nexport const ResultList = createTavo<\n { results: Result[] },\n Record,\n ResultListController\n>({\n controller: ResultListController,\n view({ props, controller }) {\n return (\n
      \n {props.results.map((result) => (\n \n {result.label}\n \n ))}\n
    \n );\n },\n});\n```" }, { "id": "directives", "title": "Attach reusable behavior with directives", "markdown": "An [`ElementDirective`](/docs/core/api/components-and-dom#api-tavojs-core--elementdirective \"View ElementDirective in the Core API reference\") receives an HTMLElement after it mounts and may return cleanup. Pass one directive or an array through the intrinsic use prop. When the directive value changes, Tavo.js cleans up the old value before applying the new one; unmount also runs cleanup.\n\n- [`autoFocus`](/docs/core/api/components-and-dom#api-tavojs-core--autofocus \"View autoFocus in the Core API reference\") queues focus after mount and accepts normal FocusOptions.\n \n- [`transition`](/docs/core/api/components-and-dom#api-tavojs-core--transition \"View transition in the Core API reference\") applies enter immediately, enterActive in a microtask, and leave classes/callbacks during cleanup.\n \n- transition does not wait for a CSS duration before removing a node. Use it for state classes and callbacks, not as an exit-animation coordinator.\n \n- Create reusable behavior with `createDirective` and attach it through the intrinsic use prop. Use `setRef` when a component or adapter must forward a DOM node to another ref owner.\n \n\n**Reference src/components/LiveNotice.tsx**\n\n```tsx\nimport {\n autoFocus,\n createDirective,\n transition,\n} from \"@tavojs/core\";\n\nconst announce = createDirective((element) => {\n element.setAttribute(\"aria-live\", \"polite\");\n\n return () => {\n element.removeAttribute(\"aria-live\");\n };\n});\n\nconst focusNotice = autoFocus();\nconst revealNotice = transition({\n classes: {\n enter: \"notice--enter\",\n enterActive: \"notice--visible\",\n leave: \"notice--leave\",\n },\n});\n\nexport function LiveNotice({ message }: { message: string }) {\n return (\n \n {message}\n \n );\n}\n```" }, { "id": "focus-ownership", "title": "Give dialogs explicit focus ownership", "markdown": "Accessible overlays need an initial focus target, contained Tab navigation, and restoration when the overlay closes. Keep every listener and restoration function under the same component owner.\n\n- [`getFocusableElements`](/docs/core/api/components-and-dom#api-tavojs-core--getfocusableelements \"View getFocusableElements in the Core API reference\") returns visible links, buttons, enabled form controls, and eligible tabindex elements in DOM order.\n \n- [`focusFirst`](/docs/core/api/components-and-dom#api-tavojs-core--focusfirst \"View focusFirst in the Core API reference\") returns the focused element or null. [`focusFirstInvalid`](/docs/core/api/components-and-dom#api-tavojs-core--focusfirstinvalid \"View focusFirstInvalid in the Core API reference\") targets the first control matching :invalid.\n \n- [`trapFocus`](/docs/core/api/components-and-dom#api-tavojs-core--trapfocus \"View trapFocus in the Core API reference\") returns the keydown-listener cleanup. If no child is focusable, the container itself must be focusable.\n \n- Focus trapping alone does not provide a complete modal: also label the dialog, prevent background interaction, support Escape where appropriate, and restore focus.\n \n\n**Reference src/components/Dialog.tsx**\n\n```tsx\nimport {\n captureFocusRestore,\n createRef,\n createTavo,\n focusFirst,\n TavoController,\n trapFocus,\n} from \"@tavojs/core\";\nimport type { PropsWithChildren } from \"@tavojs/core\";\n\nclass DialogController extends TavoController {\n dialog = createRef();\n\n onMount() {\n const restoreFocus = captureFocusRestore();\n const dialog = this.dialog.current;\n\n if (!dialog) {\n return restoreFocus;\n }\n\n focusFirst(dialog);\n const stopTrap = trapFocus(dialog);\n\n return () => {\n stopTrap();\n restoreFocus();\n };\n }\n}\n\nexport const Dialog = createTavo<\n PropsWithChildren<{ label: string }>,\n Record,\n DialogController\n>({\n controller: DialogController,\n view({ props, controller }) {\n return (\n \n {props.children}\n \n );\n },\n});\n```" }, { "id": "managed-observers", "title": "Observe elements with a managed owner", "markdown": "The standalone observer helpers [`observeResize`](/docs/core/api/components-and-dom#api-tavojs-core--observeresize \"View observeResize in the Core API reference\"), [`observeIntersection`](/docs/core/api/components-and-dom#api-tavojs-core--observeintersection \"View observeIntersection in the Core API reference\"), and [`observeMutation`](/docs/core/api/components-and-dom#api-tavojs-core--observemutation \"View observeMutation in the Core API reference\") accept an element or ref and return a disconnect function. Inside a [`TavoController`](/docs/core/api/application#api-tavojs-core--tavocontroller \"View TavoController in the Core API reference\"), the matching methods automatically register that disconnect function for component teardown.\n\n- `observeResize` and `observeIntersection` accept an Element or `DomRefObject`.\n \n- `observeMutation` accepts a Node or a ref object.\n \n- Browser support failures surface from the platform constructors; add a feature check or polyfill when supporting older environments.\n \n- Do not start observers during model creation, controller construction, or SSR.\n \n\n**Reference Reference snippet**\n\n```tsx\nclass ChartController extends TavoController {\n chart = createRef();\n\n onMount() {\n this.observeResize(this.chart, () => {\n this.measureChart();\n });\n\n this.observeIntersection(this.chart, (entries) => {\n this.model.patch({ visible: entries[0]?.isIntersecting ?? false });\n });\n }\n\n measureChart() {\n // Read the committed chart dimensions.\n }\n}\n```" }, { "id": "dom-verification", "title": "Verify cleanup and keyboard behavior", "markdown": "- Mount, replace, and unmount the element; assert object refs and callback refs are cleared.\n \n- Change a use prop and confirm the previous directive cleanup runs before the new directive.\n \n- Tab forward and backward through a focus trap, test an empty trap, and confirm focus restoration.\n \n- Unmount an observed component and assert the observer disconnects.\n \n- Run the same component through SSR and confirm ref, use, transition, and event instructions do not become HTML attributes." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:pages-and-layouts", "section": "core", "slug": "pages-and-layouts", "title": "Pages and layouts", "description": "Turn files into routes, compose nested application shells, and provide route-specific pending and error views.", "keywords": [ "pages", "layouts", "route groups", "pending", "PagePendingProps", "PageErrorProps", "404" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Turn files into routes, compose nested application shells, and provide route-specific pending and error views." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/pages-and-layouts", "sections": [ { "id": "route-files", "title": "Start with the route tree", "markdown": "`Tavo.js` derives application routes from src/pages. Keep route modules focused on route concerns: loader data, metadata, render mode, and the page component. Move reusable interface and business behavior into components, controllers, and stores.\n\nDynamic segments use brackets, catch-all segments use three dots, and folders wrapped in parentheses organize files without changing the public URL.\n\n**Reference src/pages/ — example route tree**\n\n```text\nsrc/pages/index.tsx → /\nsrc/pages/dashboard/index.tsx → /dashboard\nsrc/pages/blog/[id].tsx → /blog/:id\nsrc/pages/docs/[[...slug]].tsx → /docs/*?slug\nsrc/pages/(marketing)/about.tsx → /about\n```" }, { "id": "functional-page", "title": "Define a functional page", "markdown": "Export route behavior as named functions and render the completed result from the default component. The filename determines the URL; `PageProps`, `PagePendingProps`, `PageErrorProps`, and `PageLoadContext` provide explicit data and parameter types without wrapping the module.\n\n**Create src/pages/projects/[id].tsx — create this route module**\n\n```tsx\nimport type {\n PageErrorProps,\n PageLoadContext,\n PagePendingProps,\n PageProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { name: string };\ntype ProjectParams = { id: string };\n\nexport async function load({ params, signal, url }: PageLoadContext): Promise {\n const endpoint = new URL(`/api/projects/${params.id}`, url);\n const response = await fetch(endpoint, { signal });\n if (!response.ok) throw new Error(\"Project could not be loaded\");\n return response.json();\n}\n\nexport function pending({ params }: PagePendingProps) {\n return Loading project {params.id}…;\n}\n\nexport function error({ pathname }: PageErrorProps) {\n return Could not load {pathname}.;\n}\n\nexport default function ProjectPage({ data }: PageProps) {\n return {data?.name};\n}\n```" }, { "id": "layout-boundaries", "title": "Compose layouts and failures", "markdown": "A `_layout.tsx` file wraps every descendant route. Layouts compose from root to leaf, so the root can own global navigation while a dashboard layout owns its sidebar and shared loader data. Each layout receives its own loader result as data and its own loader failure as error.\n\n- Use route groups for alternate shells without adding a URL segment.\n \n- Add `src/pages/404.tsx` for unmatched URLs.\n \n- Export pending from a page for active client-navigation feedback after its layout loaders resolve.\n \n- Export error from a page for its contextual loader-failure view; otherwise `src/pages/_error.tsx` is the application-wide fallback.\n \n- A `notFound`() signal bypasses both error views and renders `src/pages/404.tsx`.\n \n- Handle a layout-loader failure from that layout's error prop; descendant loaders continue unless the loader signals not found.\n \n- Keep request-specific data in layout loader results, not process-wide stores during SSR." }, { "id": "page-module-reference", "title": "Page module reference", "markdown": "A page or layout is a functional default export with optional named route exports. The filename determines the public route, while load, action, middleware, head, render, prerender, revalidate, vary, `cacheTags`, and `generateStaticParams` add route behavior. Page modules can additionally export pending and error components.\n\nPage and layout components receive the resolved URL params and their own loader data. The layers array preserves every layout and page result, while `layerData` exposes those results by layer ID.\n\n**Reference Reference snippet**\n\n```ts\ntype PageModuleRecord = {\n default: Component>;\n pending?: Component;\n error?: Component;\n load?: PageLoader;\n action?: PageAction;\n head?: PageHeadExport | ((context: PageLoadContext & {\n data: unknown; error: unknown;\n }) => PageHeadExport);\n middleware?: PageMiddleware | PageMiddleware[];\n render?: \"csr\";\n prerender?: boolean;\n static?: boolean;\n revalidate?: number | false;\n vary?: string | string[];\n cacheTags?: string | string[] | ((context: PageLoadContext) => MaybePromise);\n generateStaticParams?: () => MaybePromise[]>;\n};\n\ntype PageProps> = {\n pathname?: string;\n params: TParams;\n data?: TData;\n error?: unknown;\n layers?: Array<{ id: string; kind: \"layout\" | \"page\"; data: unknown; error: unknown }>;\n layerData?: Record;\n};\n\ntype PagePendingProps> = {\n pathname: string;\n params: TParams;\n layers: RouteDataLayer[];\n layerData: Record;\n};\n\ntype PageErrorProps> =\n PagePendingProps & {\n data: unknown;\n error: unknown;\n};\n```" }, { "id": "route-conventions-reference", "title": "Route conventions and matching", "markdown": "- `index.tsx` maps to its folder path; `_layout.tsx` wraps descendants; `404.tsx` handles unmatched paths; a page error export handles its loader failure before the global `_error.tsx` fallback.\n \n- \\[id\\] is a required dynamic segment, \\[\\[id\\]\\] is optional, \\[...all\\] is a required catch-all, and \\[\\[...all\\]\\] is an optional catch-all.\n \n- Folders in parentheses are route groups: they organize files and select layouts without adding a URL segment.\n \n- `RouteParamsFromPath` derives string parameters. Optional parameters are string | undefined. `LoaderData` unwraps the loader's awaited return type.\n \n- [`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\") is optional route-aware typing assistance. It does not register or rename a route; keep its path literal aligned with the filename and confirm the result with tavo routes.\n \n- `defineRoutePage` also infers route params for pending and error components when the helper form is useful.\n \n- The CLI generates functional modules by default. Use `tavo` generate page `--typed-route` only when the helper form is useful.\n \n- Routes are sorted by segment specificity before matching: static segments win over dynamic segments, required parameters win over optional ones, and catch-all segments come last. Equivalent patterns use a lexical path tie-break, so filesystem discovery order never changes the result.\n \n\n**Reference Reference snippet**\n\n```tsx\n// src/pages/projects/[projectId]/tasks/[[taskId]].tsx\nimport type { PageProps } from \"@tavojs/core/router\";\n\ntype Params = {\n projectId: string;\n taskId?: string;\n};\n\nexport default function TaskPage({ params }: PageProps) {\n return (\n
    \n Project {params.projectId}; task {params.taskId ?? \"overview\"}\n
    \n );\n}\n```\n\n**Inspect the generated route graph**\n\nRoute collisions, invalid files, CSR-incompatible static options, and dynamic head on CSR routes become manifest diagnostics. Run tavo routes and tavo check before relying on route order." }, { "id": "route-pending-error-reference", "title": "Route pending and error reference", "markdown": "A page can export pending for unresolved browser navigation and error for a contextual page-loader failure. Both exports are normal `Tavo.js` components: use a function component for render-only feedback or `createTavo` when the state needs a model, controller, lifecycle, or cleanup.\n\n- Client navigation changes the URL, runs middleware, resolves target layout loaders, renders pending inside those layouts, runs the page loader, and then renders the completed page or route error.\n \n- The default page component and controller do not mount until the page loader completes. Pending props intentionally omit page loader data but include resolved layout layers and `layerData`.\n \n- A `createTavo` pending component's controller receives the target route through `this.page`, including pathname, route, status, params, layers, and `layerData`; `this.page.data` is unavailable while the loader is unresolved.\n \n- Without pending, the previous page stays visible while the target content region is marked busy.\n \n- The target page error export wins for its loader failure; otherwise `Tavo.js` renders `src/pages/_error.tsx`. `notFound`() bypasses both and renders `src/pages/404.tsx` with status 404.\n \n- A layout-loader failure enters error handling instead of rendering pending with invalid layout data.\n \n- Normal SSR, static prerendering, prefetching, and fresh route-cache hits do not render pending.\n \n- A replaced navigation aborts obsolete resolution, removes its pending view, and prevents stale data or errors from becoming active.\n \n- Use `aria-busy` and an accessible label for pending UI, avoid moving focus into a skeleton, and announce route errors without exposing private diagnostic details.\n \n\n**Reference Reference snippet**\n\n```tsx\nimport type {\n PageErrorProps,\n PagePendingProps\n} from \"@tavojs/core/router\";\n\nexport function pending({ params }: PagePendingProps<{ id: string }>) {\n return
    Loading report {params.id}…
    ;\n}\n\nexport function error({ pathname }: PageErrorProps<{ id: string }>) {\n return
    Could not load {pathname}.
    ;\n}\n```" }, { "id": "route-output-reference", "title": "Rendering, static output, and cache options", "markdown": "SSR is the normal server render mode. A route becomes CSR when its module chain selects render: \"csr\". Static and revalidation policy composes across root, layouts, and page rather than belonging only to the leaf page.\n\n- In functional modules, export const prerender = true enables static output. false or revalidate = false disables an inherited static policy.\n \n- revalidate is measured in seconds, rounded down, clamped to zero, and the shortest finite value in the module chain wins.\n \n- vary header names are lowercased and deduplicated. Localization also varies cached output by Accept-Language.\n \n- `cacheTags` can be static strings or request-aware resolvers. Tags support targeted invalidation in runtimes that expose it.\n \n- CSR routes ignore static, revalidate, vary, cache tags, and `generateStaticParams`. The manifest reports incompatible declarations.\n \n- `generateStaticParams` is required to enumerate build-time paths for a dynamic static route.\n \n\n**Reference Reference snippet**\n\n```tsx\nimport { defineRoutePage } from \"@tavojs/core/router\";\n\nexport default defineRoutePage(\"/catalog/[id]\", {\n static: true,\n revalidate: 300,\n vary: \"accept-language\",\n cacheTags: ({ params }) => [\"catalog\", `product:${params.id}`],\n generateStaticParams: async () => [{ id: \"starter\" }],\n load: ({ params, signal }) => getProduct(params.id, { signal }),\n default: ({ data }) => \n});\n```\n\n**Choose one static form**\n\nUse named prerender in a functional module or static inside defineRoutePage. Declaring both forms in one route is rejected." }, { "id": "pages-runtime-reference", "title": "Configure shared route behavior", "markdown": "- Put application-wide page props, not-found UI, CSR fallback content, middleware, localization, redirect policy, trusted hosts, and cache limits under ssr in `tavo.config.ts`.\n \n- Configure `ssr.csrFallback` through `defineConfig`; normal applications use the framework boot flow and do not construct a pages runtime.\n \n- Install plugins through the top-level plugins configuration. Plugin graph compilation and runtime construction are framework host responsibilities.\n \n- Use `tavo` routes and `tavo` inspect route `--json` for route inspection. Experimental tooling can use the supported `@tavojs/core/dev` inspection exports.\n \n\n**Reference Reference snippet**\n\n```ts\n// tavo.config.ts\nimport { defineConfig } from \"@tavojs/core/config\";\n\nexport default defineConfig({\n ssr: {\n csrFallback: \"Loading application…\",\n maxResolvedCacheEntries: 512\n }\n});\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:route-files-and-matching", "section": "core", "slug": "route-files-and-matching", "title": "Route files and matching", "description": "Use the exact src/pages conventions, understand deterministic route precedence, and place route-level failure UI correctly.", "keywords": [ "routes", "pages", "layouts", "dynamic segments", "route groups", "404", "error", "precedence" ], "kind": "reference", "prerequisites": [ "A Tavo.js application with its route modules under src/pages.", "Familiarity with functional TSX components." ], "outcomes": [ "Map files and folders to public paths without route collisions.", "Predict which route wins when several patterns could match.", "Choose page error, global error, or 404 UI for each failure." ], "runtime": [ "build", "server", "browser" ], "related": [ { "title": "Pages and layouts", "href": "/docs/core/pages-and-layouts", "description": "Learn the route-module composition model." }, { "title": "Route data lifecycle", "href": "/docs/core/route-data-lifecycle", "description": "Follow middleware and loaders after a route matches." } ], "canonicalPath": "/docs/core/route-files-and-matching", "sections": [ { "id": "file-to-url", "title": "Map src/pages to URLs", "markdown": "Tavo.js discovers route modules below src/pages. A normal page file contributes a URL; a special module changes how matching, layout, or failure rendering works. Route groups organize files and select layouts without adding a path segment.\n\n**Reference src/pages — route map**\n\n```text\nsrc/pages/\n index.tsx → /\n about.tsx → /about\n projects/\n _layout.tsx → wraps project descendants\n index.tsx → /projects\n new.tsx → /projects/new\n [id].tsx → /projects/:id\n [[tab]].tsx → /projects/:?tab\n [...path].tsx → /projects/*path\n (account)/\n _layout.tsx → selects a layout; no URL segment\n settings.tsx → /settings\n 404.tsx → unmatched and notFound() UI\n _error.tsx → fallback for page-loader errors\n```\n\nFile syntax\n\nWhat it matches\n\nResult\n\n`[id]`\n\nExactly one required segment.\n\nparams.id is a decoded string.\n\n`[[tab]]`\n\nZero or one segment.\n\nparams.tab is string | undefined.\n\n`[...path]`\n\nOne or more remaining segments.\n\nparams.path contains the decoded slash-joined value.\n\n`[[...path]]`\n\nZero or more remaining segments.\n\nparams.path is string | undefined.\n\n`(account)`\n\nNo URL segment.\n\nThe group remains part of layout identity.\n\n**Malformed encoded paths do not match**\n\nRoute parameters are decoded before they are published. If a path segment cannot be decoded, that candidate does not match. Do not decode params a second time in application code." }, { "id": "module-shape", "title": "Keep route modules functional and explicit", "markdown": "The default export renders the page. Named exports add behavior without changing the route path. [`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\") is optional route-aware typing; it does not register the route or override its filename. Its path literal is checked with [`RouteParamsFromPath`](/docs/core/api/router#api-tavojs-core-router--routeparamsfrompath \"View RouteParamsFromPath in the Core API reference\"), while the filesystem remains authoritative.\n\n**Reference src/pages/projects/[id].tsx**\n\n```tsx\nimport type {\n PageLoadContext,\n PageProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { id: string; name: string };\ntype ProjectParams = { id: string };\n\nexport async function load({\n params,\n signal,\n url\n}: PageLoadContext): Promise {\n const response = await fetch(\n new URL(`/api/projects/${params.id}`, url),\n { signal }\n );\n if (!response.ok) {\n throw new Error(\"Could not load project\");\n }\n return response.json() as Promise;\n}\n\nexport function head({ data }: { data: Project | null }) {\n return {data ? data.name : \"Project\"};\n}\n\nexport default function ProjectPage({\n data\n}: PageProps) {\n return (\n \n \n {data?.name}\n \n \n );\n}\n```\n\n- Page modules may export load, action, middleware, head, pending, error, render, prerender, revalidate, vary, `cacheTags`, and `generateStaticParams`.\n \n- Layout modules use the same data, middleware, head, and rendering exports and receive children from the route beneath them.\n \n- Use [`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\") from @tavojs/core/router later when path-derived params and one object are clearer for a complex route.\n \n- Keep the helper path literal aligned with the file path and inspect the generated manifest; the filesystem remains authoritative." }, { "id": "precedence", "title": "Predict deterministic route precedence", "markdown": "Matching is independent of filesystem discovery order. Tavo.js compares each segment from left to right and tries the more specific pattern first.\n\n**Reference Matching precedence — highest to lowest**\n\n```text\nstatic\n → required dynamic [id]\n → optional dynamic [[id]]\n → required catch-all [...path]\n → optional catch-all [[...path]]\n\n/projects/new wins over /projects/[id]\n/docs/[version] wins over /docs/[...path]\n/files/[...path] wins over /files/[[...path]]\n```\n\nWhen two compiled patterns have identical specificity, Tavo.js uses a lexical path tie-break. Treat equivalent patterns as a collision to fix, not as a way to choose behavior by declaration order.\n\n**Inspect collisions before deployment**\n\nRun tavo routes and tavo check after adding or renaming route files. The generated route order is the behavior that development, build, and production share." }, { "id": "special-modules", "title": "Place 404 and error UI at the correct boundary", "markdown": "- src/pages/404.tsx renders when no route matches and when a loader or middleware calls [`notFound()`](/docs/core/api/router#api-tavojs-core-router--notfound \"View notFound in the Core API reference\"). The response status is 404.\n \n- A page-local error export handles that page loader's failure and implements the [`PageErrorProps`](/docs/core/api/router#api-tavojs-core-router--pageerrorprops \"View PageErrorProps in the Core API reference\") contract: pathname, params, route layers, page data, and the error.\n \n- `src/pages/_error.tsx` is the fallback when a page loader fails and the page has no local error export.\n \n- A layout receives its own loader error through its error prop. Descendant loaders still run unless the failure is `notFound`(), and page pending UI is skipped while a layout error exists.\n \n- Files whose stem begins with an underscore are not public routes. Only documented special filenames receive special behavior.\n \n\n**Reference src/pages/404.tsx**\n\n```tsx\nimport { Page, Text } from \"@tavojs/ui\";\n\nexport default function NotFoundPage({\n pathname\n}: {\n pathname?: string;\n}) {\n return (\n \n \n Page not found\n \n The path {pathname ?? \"you requested\"} does not exist.\n \n );\n}\n```\n\n**Do not expose private failure details**\n\nRender a stable user-facing message and report the original error through server diagnostics or instrumentation. Serialized hydration errors are redacted, but route data and custom error UI still require deliberate privacy review." }, { "id": "advanced-status", "title": "Treat two implemented conventions as contract work in progress", "markdown": "Current Core source and tests recognize a top-level \\_root.tsx and a page-level layout = false export. Their final public 1.0 semantics are not yet ratified.\n\n- `_root.tsx` currently wraps every matched route before directory layouts and uses the layer ID \\_root.\n \n- layout = false currently skips directory `_layout.tsx` modules for that page while retaining `_root.tsx`.\n \n- Do not make reusable application architecture depend on either convention until Core publishes its stable contract, inheritance rules, and migration guarantees.\n \n- Use explicit directory layouts for production documentation and examples in the meantime." }, { "id": "verification", "title": "Verify the route graph", "markdown": "**Run Terminal**\n\n```bash\nnpx tavo routes\nnpx tavo inspect route /projects/new --json\nnpx tavo inspect route /projects/example --json\nnpx tavo check\n```\n\nVerify both the static and dynamic examples so precedence is observable. Also request an unknown path and a loader path that calls `notFound`() to confirm the same 404 module and status are used." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:routing", "section": "core", "slug": "routing", "title": "Routing and navigation", "description": "Navigate between typed file routes while preserving browser history, focus, scroll, and pending state.", "keywords": [ "router", "navigation", "Link", "prefetch" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Navigate between typed file routes while preserving browser history, focus, scroll, and pending state." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/routing", "sections": [ { "id": "navigation-model", "title": "Use Auto Pages for application routes", "markdown": "Auto Pages discovers application routes from src/pages and owns matching, layouts, loaders, route pending and error views, metadata, focus restoration, accessibility announcements, and scroll restoration. Route folders, dynamic segments, groups, 404 pages, and error pages all participate in the same generated route graph.\n\n**Standalone router**\n\nThe router entry point also exposes createRouter for small client-only or embedded flows. Most file-routed applications should use Auto Pages instead of creating a second top-level router." }, { "id": "links-and-scroll", "title": "Link and scroll behavior", "markdown": "The Core [`Link`](/docs/core/api/router#api-tavojs-core-router--link \"View Link in the Core API reference\") performs SPA navigation and sets `aria-current` on the active destination. New routes begin at the top, hashes scroll into view, and browser back or forward restores saved positions.\n\n**Create src/components/AccountNavigation.tsx — create this component**\n\n```tsx\nimport { Link } from \"@tavojs/core/router\";\nimport { Inline } from \"@tavojs/ui\";\n\nexport function AccountNavigation() {\n return \n Profile\n Security\n ;\n}\n```" }, { "id": "prefetch-and-status", "title": "Prefetch intentionally", "markdown": "Prefetch routes when intent is clear, such as pointer hover or focus on a high-probability destination. Prefetching resolves work without changing the URL or rendering the target page's pending component. Route status APIs let interface code show loading, prefetching, ready, or error states without duplicating the router state machine.\n\n**Create src/navigation/reports.ts — create this browser-safe helper**\n\n```ts\nimport { getRouteStatus, prefetchRoute } from \"@tavojs/core/router\";\n\nexport async function prepareReports() {\n await prefetchRoute(\"/reports\");\n return getRouteStatus(\"/reports\");\n}\n```" }, { "id": "subscriptions-and-inspection", "title": "Subscribe and inspect responsibly", "markdown": "Auto Pages exposes synchronous route state and disposable subscriptions from `@tavojs/core/router`. Development inspection lives under `@tavojs/core/dev`, while `tavo` routes and `tavo` inspect route show the generated graph without adding application code.\n\n- Use `getResolvedRoute` and `getRouteStatus` for current resolution state.\n \n- Use `subscribeAvailableRoutes` and `subscribeRouteStatus` when interface state must react to route changes.\n \n- Run `tavo` routes, `tavo` inspect route `--json`, or import `getAutoPagesInspection` from `@tavojs/core/dev` during development.\n \n\n**Reference src/navigation/route-observer.ts**\n\n```ts\nimport {\n getAvailableRoutes,\n getCurrentPathname,\n subscribePathname\n} from \"@tavojs/core/router\";\n\nconsole.log(getCurrentPathname(), getAvailableRoutes());\n\nconst unsubscribe = subscribePathname((pathname) => {\n console.log(\"Route changed:\", pathname);\n});\n\n// Call when this observer's owner is disposed.\nunsubscribe();\n```" }, { "id": "auto-pages-navigation-reference", "title": "File-router navigation API", "markdown": "Auto Pages discovers application routes from src/pages. Import its navigation and route-state APIs from `@tavojs/core/router`. Reads are synchronous; subscribe functions return an unsubscribe callback; `prefetchRoute` resolves route middleware and loaders without changing browser history.\n\n- Route status is idle, loading, prefetching, ready, redirecting, or error.\n \n- A page pending export is visible only during active client-side route resolution; `prefetchRoute` never renders it.\n \n- Without an active resolver, `prefetchRoute` leaves the route idle rather than throwing.\n \n- Pass an `AbortSignal` when hover, focus, or another owner should be able to cancel a prefetch.\n \n- Call every returned unsubscribe function when its component, controller, or external owner is disposed.\n \n- Import `getAutoPagesInspection` from `@tavojs/core/dev` for development inspection, or use `tavo` routes and `tavo` inspect route `--json`.\n \n\n**Reference Reference snippet**\n\n```ts\nnavigate(to: string, options?: { replace?: boolean; scroll?: boolean }): void\nprefetchRoute(pathname: string, options?: { signal?: AbortSignal }): Promise\ngetCurrentPathname(): string\nsubscribePathname(listener: (pathname: string) => void): () => void\ngetAvailableRoutes(): PageRouteDefinition[]\nsubscribeAvailableRoutes(listener: (routes: PageRouteDefinition[]) => void): () => void\ngetResolvedRoute(pathname?: string)\ngetRouteStatus(pathname?: string): RouteStatus\nsubscribeRouteStatus(listener: (status: RouteStatus, all: RouteStatusState) => void, pathname?: string): () => void\n```" }, { "id": "link-reference", "title": "Link behavior and accessibility", "markdown": "- [`Link`](/docs/core/api/router#api-tavojs-core-router--link \"View Link in the Core API reference\") renders a real anchor and adds `aria-current`\\=\"page\" when its resolved route is active.\n \n- Only an unmodified primary click to the same origin is intercepted. External URLs, downloads, modified clicks, new-window targets, and same-page hashes keep browser behavior.\n \n- replace defaults to false. Navigation scrolls to the top or hash by default; scroll: false preserves the current position. Back and forward restore saved positions.\n \n- When an i18n service is registered, internal destinations are localized and active matching ignores the locale prefix.\n \n\n**Reference Reference snippet**\n\n```ts\ntype LinkProps = {\n to: string;\n replace?: boolean;\n scroll?: boolean;\n className?: string;\n children?: Child;\n};\n```" }, { "id": "standalone-router-reference", "title": "Standalone router reference", "markdown": "The standalone router is intended for embedded or client-only route areas. Do not create a second top-level router inside a file-routed application.\n\n- `RouterProvider` can render explicit children or the matched route component.\n \n- After navigation it announces status, focuses `data-tavo-route-focus`, main, h1, or role=main, and restores scroll.\n \n- [`navigate`](/docs/core/api/router#api-tavojs-core-router--navigate \"View navigate in the Core API reference\") is a no-op during server rendering. [`Router`](/docs/core/api/router#api-tavojs-core-router--router \"View Router in the Core API reference\") params are decoded strings.\n \n\n**Reference Reference snippet**\n\n```tsx\nconst router = createRouter([\n { path: \"/\", component: Home },\n { path: \"/teams/:id\", component: Team }\n]);\n\nrouter.navigate(\"/teams/core\", { replace: false, scroll: true });\nrouter.getPathname();\nrouter.match(\"/teams/core\"); // { route, params: { id: \"core\" } }\n\n}\n busy={false}\n contentId=\"route-content\"\n/>\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:navigation-and-route-state", "section": "core", "slug": "navigation-and-route-state", "title": "Navigation and route state", "description": "Navigate, prefetch, inspect route resolution, and own route subscriptions without leaking browser listeners.", "keywords": [ "navigation", "Link", "prefetch", "route status", "subscriptions", "pathname" ], "kind": "reference", "prerequisites": [ "A file-routed Tavo.js application.", "Client-side code that needs navigation or route progress." ], "outcomes": [ "Choose Link or navigate without breaking browser behavior.", "Interpret every route status and prefetch outcome.", "Read initial state and clean up every route subscription." ], "runtime": [ "browser" ], "related": [ { "title": "Route files and matching", "href": "/docs/core/route-files-and-matching", "description": "Understand the route catalog exposed to navigation." }, { "title": "MVC and controllers", "href": "/docs/core/mvc", "description": "Own subscriptions and async work with createTavo." } ], "canonicalPath": "/docs/core/navigation-and-route-state", "sections": [ { "id": "navigation", "title": "Use anchors first and navigate for imperative transitions", "markdown": "**Reference src/components/ProjectNavigation.tsx**\n\n```tsx\nimport { Link, navigate } from \"@tavojs/core/router\";\nimport { Button, Stack } from \"@tavojs/ui\";\n\nexport function ProjectNavigation() {\n function openLatestProject() {\n navigate(\"/projects/latest\");\n }\n\n return (\n \n All projects\n \n \n );\n}\n```\n\n- [`Link`](/docs/core/api/router#api-tavojs-core-router--link \"View Link in the Core API reference\") renders a real anchor, supports keyboard and assistive technology behavior, and marks the active route with aria-current.\n \n- Same-origin, unmodified primary clicks become client navigation. External links, downloads, modified clicks, new-window targets, and same-page hashes retain native browser behavior.\n \n- [`navigate`](/docs/core/api/router#api-tavojs-core-router--navigate)`(``to``,` `{` `replace``,` `scroll` `}``)` is for event-driven transitions. replace defaults to false and scroll defaults to true.\n \n- Back and forward navigation follows browser history and restores recorded scroll positions." }, { "id": "status", "title": "Read route status as a state machine", "markdown": "**Reference src/navigation/progress.ts**\n\n```ts\nimport {\n getRouteStatus,\n subscribeRouteStatus,\n} from \"@tavojs/core/router\";\n\nconsole.debug(getRouteStatus(\"/reports\").status);\n\nconst stop = subscribeRouteStatus((status) => {\n document.documentElement.dataset.routeStatus = status.status;\n}, \"/reports\");\n\n// Return stop from the lifecycle owner.\n```\n\nStatus\n\nMeaning\n\n`idle`\n\nNo active or reusable resolution is recorded for the path.\n\n`loading`\n\nAn active navigation is running middleware and loaders.\n\n`prefetching`\n\nBackground resolution is running without changing history.\n\n`ready`\n\nA resolved result is available for the path.\n\n`redirecting`\n\nMiddleware or route resolution selected another location.\n\n`error`\n\nResolution failed; inspect the status error for reporting.\n\nEach record follows [`RouteStatus`](/docs/core/api/router#api-tavojs-core-router--routestatus \"View RouteStatus in the Core API reference\"). Read a path with [`getRouteStatus`](/docs/core/api/router#api-tavojs-core-router--getroutestatus)`(``pathname``)` and observe future transitions with [`subscribeRouteStatus`](/docs/core/api/router#api-tavojs-core-router--subscriberoutestatus)`(``listener``,` `pathname``?``)`.\n\n- [`getCurrentPathname`](/docs/core/api/router#api-tavojs-core-router--getcurrentpathname)`(``)` reads the current browser path.\n \n- [`getAvailableRoutes`](/docs/core/api/router#api-tavojs-core-router--getavailableroutes)`(``)` returns discovered [`PageRouteDefinition`](/docs/core/api/router#api-tavojs-core-router--pageroutedefinition \"View PageRouteDefinition in the Core API reference\") records; the catalog is not an authorization boundary.\n \n- [`getResolvedRoute`](/docs/core/api/router#api-tavojs-core-router--getresolvedroute)`(``pathname``)` returns the current resolved route snapshot when available. Pass the path explicitly when inspecting anything other than the active route. The renderer-state shape is intentionally not a separately importable route-author contract." }, { "id": "subscriptions", "title": "Read once, subscribe, and return cleanup", "markdown": "[`subscribePathname`](/docs/core/api/router#api-tavojs-core-router--subscribepathname \"View subscribePathname in the Core API reference\"), [`subscribeAvailableRoutes`](/docs/core/api/router#api-tavojs-core-router--subscribeavailableroutes \"View subscribeAvailableRoutes in the Core API reference\"), and [`subscribeRouteStatus`](/docs/core/api/router#api-tavojs-core-router--subscriberoutestatus \"View subscribeRouteStatus in the Core API reference\") publish future changes; they do not replace the initial synchronous read. A [`createTavo`](/docs/core/api/application#api-tavojs-core--createtavo \"View createTavo in the Core API reference\") controller is a natural owner because onMount can return one cleanup that releases every subscription.\n\n**Reference src/components/RouteProgress.tsx**\n\n```tsx\nimport {\n createTavo,\n TavoController\n} from \"@tavojs/core\";\nimport {\n getCurrentPathname,\n getRouteStatus,\n subscribePathname,\n subscribeRouteStatus,\n type RouteStatus\n} from \"@tavojs/core/router\";\nimport { Text } from \"@tavojs/ui\";\n\ntype RouteProgressState = {\n pathname: string;\n status: RouteStatus[\"status\"];\n};\n\nclass RouteProgressController extends TavoController {\n sync(pathname = getCurrentPathname()) {\n this.model.patch({\n pathname,\n status: getRouteStatus(pathname).status\n });\n }\n\n onMount() {\n this.sync();\n const stopPathname = subscribePathname((pathname) => {\n this.sync(pathname);\n });\n const stopStatus = subscribeRouteStatus((status) => {\n this.model.patch({\n pathname: status.pathname,\n status: status.status\n });\n });\n\n return function cleanupRouteProgress() {\n stopPathname();\n stopStatus();\n };\n }\n}\n\nexport const RouteProgress = createTavo<\n Record,\n RouteProgressState,\n RouteProgressController\n>({\n model: () => ({\n pathname: \"/\",\n status: \"idle\"\n }),\n controller: RouteProgressController,\n view: ({ state }) => {\n return (\n \n {state.pathname}: {state.status}\n \n );\n }\n});\n```\n\n**Scope status subscriptions when possible**\n\nPass a pathname to [`subscribeRouteStatus`](/docs/core/api/router#api-tavojs-core-router--subscriberoutestatus \"View subscribeRouteStatus in the Core API reference\") when one component owns one destination. An unscoped subscription receives all route transitions and should be reserved for global progress or diagnostics UI." }, { "id": "prefetch", "title": "Prefetch without navigating", "markdown": "**Reference src/components/ProjectLink.tsx**\n\n```tsx\nimport { Link, prefetchRoute } from \"@tavojs/core/router\";\n\nexport function ProjectLink({ id }: { id: string }) {\n const pathname = `/projects/${id}`;\n let prefetch: AbortController | null = null;\n\n function startPrefetch() {\n prefetch?.abort();\n prefetch = new AbortController();\n void prefetchRoute(pathname, {\n signal: prefetch.signal\n });\n }\n\n function stopPrefetch() {\n prefetch?.abort();\n prefetch = null;\n }\n\n return (\n \n \n Open project {id}\n \n \n );\n}\n```\n\n- `prefetchRoute` runs the target's client-eligible middleware and loaders but does not change history or render the target pending component.\n \n- Status moves through prefetching and then ready or error. Cancellation returns the prefetch to idle.\n \n- Pass an `AbortSignal` when hover, focus, a controller, or another owner can stop needing the result.\n \n- Prefetch is an optimization. Navigation must still work when no prefetch ran, failed, or was evicted." }, { "id": "failure-and-verification", "title": "Verify navigation and cancellation", "markdown": "- Replace a slow navigation with a second destination and confirm the obsolete result never becomes active.\n \n- Abort a hover prefetch and confirm it neither changes the URL nor displays pending UI.\n \n- Mount and unmount subscription-owning components repeatedly while checking that each cleanup runs.\n \n- Test [`Link`](/docs/core/api/router#api-tavojs-core-router--link \"View Link in the Core API reference\") with keyboard activation, modifier keys, downloads, external URLs, hashes, and browser back/forward.\n \n\n**Run Terminal**\n\n```bash\nnpx tavo routes\nnpx tavo inspect route /projects/example --json\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:data-and-middleware", "section": "core", "slug": "data-and-middleware", "title": "Data loading and middleware", "description": "Load route data, provide route-specific pending and error states, redirect or gate navigation, and cancel obsolete work.", "keywords": [ "loader", "pending", "error", "middleware", "resource", "AbortSignal" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Load route data, provide route-specific pending and error states, redirect or gate navigation, and cancel obsolete work." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/data-and-middleware", "sections": [ { "id": "route-loaders", "title": "Load route-critical data", "markdown": "Page and layout loaders run during route resolution. Their result becomes page data and is available to route-aware controllers. A page can export pending for active browser resolution and error for its loader failure. Pass the provided `AbortSignal` to downstream work so superseded navigation cannot publish stale results.\n\n**Replace src/pages/projects/[id].tsx — replace the route module**\n\n```tsx\nimport type {\n PageErrorProps,\n PageLoadContext,\n PagePendingProps,\n PageProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Project = { name: string };\n\nexport async function load({ params, signal, url }: PageLoadContext): Promise {\n const endpoint = new URL(`/api/projects/${params.id}`, url);\n const response = await fetch(endpoint, { signal });\n if (!response.ok) throw new Error(\"Project could not be loaded\");\n return response.json();\n}\n\nexport function pending({ params }: PagePendingProps) {\n return Loading project {params.id}…;\n}\n\nexport function error({ pathname }: PageErrorProps) {\n return Could not load {pathname}.;\n}\n\nexport default function ProjectPage({ data }: PageProps) {\n return {data?.name};\n}\n```" }, { "id": "middleware-boundary", "title": "Keep middleware request-scoped", "markdown": "Middleware runs before loaders and can continue or redirect route resolution. Return nothing to continue, or return an object with redirect and an optional status. A status without redirect does not stop the route. This example normalizes a redundant query before the loader runs. Use `defineServerMiddleware` plus a server-only helper for sessions, secrets, or other policy that must never run during browser navigation.\n\n**Merge src/pages/projects/_layout.tsx — merge this middleware export**\n\n```ts\nimport { defineServerMiddleware } from \"@tavojs/core/router\";\n\nexport const middleware = defineServerMiddleware(({ request }) => {\n const url = new URL(request.url);\n if (url.searchParams.get(\"view\") === \"all\") {\n return { redirect: \"/projects\", status: 308 };\n }\n});\n```" }, { "id": "route-vs-resource", "title": "Route loader or resource?", "markdown": "Starting a new resource load aborts the previous one. Treat cancellation as expected control flow rather than an application error.\n\n- Use a loader when the route cannot render meaningfully without the data.\n \n- Use a layout loader for data shared by descendant routes.\n \n- Use `createResource` for component-scoped async data that can load independently.\n \n- Use lazy when the async work is loading a component implementation." }, { "id": "loader-contract-reference", "title": "Loader contract", "markdown": "- Loader runtime defaults to both. `defineServerLoader` is equivalent to a server-only loader and is skipped during browser resolution.\n \n- request, URL, Headers, and `AbortSignal` are portable Fetch APIs. Build application-relative fetch URLs with new URL(path, url) so the same loader works in Node and the browser. Use `rawRequest` only at an adapter integration boundary.\n \n- Pass signal to fetch and every abort-aware dependency. Superseded navigation is expected cancellation and must not publish stale data.\n \n- Layout loaders resolve from root to leaf, followed by the page loader. Later loader contexts receive successful earlier results through the optional keyed `context.layers` record. Rendered page, pending, and error props use a different shape: ordered layers plus keyed `layerData`.\n \n- A layout-loader failure stays on that layout layer and enters route error handling rather than rendering the page pending view with invalid layout data.\n \n- A page-loader failure renders the target page's error export when present, then falls back to `src/pages/_error.tsx`.\n \n- An aborted obsolete resolution returns to idle rather than rendering an error.\n \n\n**Reference Reference snippet**\n\n```ts\ntype PageLoadContext = {\n pathname: string;\n params: Record;\n request: Request;\n rawRequest?: unknown;\n url: URL;\n headers: Headers;\n method: string;\n signal: AbortSignal;\n layers?: Record;\n};\n\ndefineLoader(handler, { runtime?: \"server\" | \"client\" | \"both\" })\ndefineServerLoader(handler)\n```" }, { "id": "middleware-contract-reference", "title": "Middleware contract and order", "markdown": "- Middleware can be declared globally, by plugins, on layouts, and on pages. Runtime-wide middleware runs first, then layout middleware from root to leaf, then page middleware.\n \n- Return nothing to continue. Return redirect to stop normal resolution; status defaults to 302 and only has an effect when redirect is present. Returning status alone does not block a route.\n \n- Middleware runtime defaults to both. Use `defineServerMiddleware` for `HttpOnly` cookies, secrets, databases, and server sessions.\n \n- Redirect targets are same-origin by default. External redirects require an explicit runtime opt-in and application validation.\n \n\n**Reference Reference snippet**\n\n```ts\ntype PageMiddleware = ((context: {\n to: string;\n from?: string;\n params: Record;\n request: Request;\n rawRequest?: unknown;\n url: URL;\n headers: Headers;\n method: string;\n signal: AbortSignal;\n}) => void | { redirect?: string; status?: number } | Promise<...>) & {\n __tavo_middleware_options__?: { runtime?: \"server\" | \"client\" | \"both\" };\n};\n```" }, { "id": "resource-reference", "title": "Component resource reference", "markdown": "- A resource starts idle with null data, error, and `updatedAt`. A new load aborts the previous load.\n \n- preload deduplicates the current pending operation. load always starts a new one.\n \n- abort returns to idle, clears error and `updatedAt`, and preserves the last data. reset also clears data.\n \n- An aborted operation resolves to idle state even if the loader ignores its signal. Non-abort failures resolve to error state rather than throwing from load.\n \n\n**Reference Reference snippet**\n\n```ts\ntype ResourceState = {\n status: \"idle\" | \"loading\" | \"success\" | \"error\";\n data: T | null;\n error: unknown;\n updatedAt: number | null;\n};\n\ntype Resource = {\n store: Store>;\n read(): ResourceState;\n load(options?: { signal?: AbortSignal }): Promise>;\n preload(options?: { signal?: AbortSignal }): Promise>;\n abort(reason?: unknown): void;\n reset(): void;\n};\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:route-data-lifecycle", "section": "core", "slug": "route-data-lifecycle", "title": "Route data lifecycle", "description": "Follow middleware, layout loaders, page loaders, pending UI, cancellation, and layer data through one route resolution.", "keywords": [ "loaders", "middleware", "layers", "layerData", "pending", "AbortSignal", "notFound" ], "kind": "reference", "prerequisites": [ "A route with a page module and, optionally, directory layouts.", "Familiarity with Fetch Request, Response, URL, Headers, and AbortSignal." ], "outcomes": [ "Predict middleware and loader order.", "Use the exact layer names available to loaders and components.", "Handle cancellation and each loader failure at the correct boundary." ], "runtime": [ "server", "browser" ], "related": [ { "title": "Data and middleware", "href": "/docs/core/data-and-middleware", "description": "See the broader data-fetching guide." }, { "title": "Navigation and route state", "href": "/docs/core/navigation-and-route-state", "description": "Observe the client resolution state machine." } ], "canonicalPath": "/docs/core/route-data-lifecycle", "sections": [ { "id": "request-order", "title": "Follow the route resolution order", "markdown": "**Reference Reference snippet**\n\n```text\nmatched route\n → runtime-wide middleware\n → plugin middleware\n → root and layout middleware, outer to inner\n → page middleware\n → root and layout loaders, outer to inner\n → page pending UI, only for eligible client navigation\n → page loader\n → layout and page head\n → page or page error, wrapped by resolved layouts\n```\n\n- Middleware may continue or redirect before data work starts. A redirect stops normal route resolution.\n \n- Layout loaders run sequentially from outermost to innermost. The page loader runs last.\n \n- Pending renders only during an active client navigation with a client-eligible page loader and no layout-loader error.\n \n- SSR, static generation, prefetching, fresh resolved-cache hits, and routes without pending do not render page pending UI." }, { "id": "context", "title": "Use the portable request context", "markdown": "Loaders implement [`PageLoader`](/docs/core/api/router#api-tavojs-core-router--pageloader \"View PageLoader in the Core API reference\") and receive one [`PageLoadContext`](/docs/core/api/router#api-tavojs-core-router--pageloadcontext \"View PageLoadContext in the Core API reference\"). The same portable request fields are inherited by [`PageActionContext`](/docs/core/api/router#api-tavojs-core-router--pageactioncontext \"View PageActionContext in the Core API reference\").\n\n**Reference PageLoadContext**\n\n```ts\ntype PageLoadContext = {\n pathname: string;\n params: Record;\n request: Request;\n rawRequest?: unknown;\n url: URL;\n headers: Headers;\n method: string;\n signal: AbortSignal;\n layers?: Record;\n};\n```\n\n- request, url, headers, and signal are portable Fetch APIs and work across supported server and browser execution.\n \n- Build application-relative URLs with new URL(path, url), then pass signal to fetch and every abort-aware dependency.\n \n- Use `rawRequest` only at an adapter integration boundary. It is not portable application state.\n \n- A loader runs in both environments unless `defineLoader` selects another runtime. Use `defineServerLoader` for secrets, databases, server sessions, and `HttpOnly` cookies.\n \n- Treat params and request data as untrusted input even when the route pattern constrained their shape." }, { "id": "layer-names", "title": "Distinguish loader layers from component layers", "markdown": "The same resolved data is exposed in two shapes for different jobs. Loader context uses the property name layers for a keyed record of successful earlier layout results. Component props use layers for the ordered diagnostic list and layerData for the keyed record.\n\nPublic contract\n\nProperty\n\nShape\n\nContents\n\n[`PageLoadContext`](/docs/core/api/router#api-tavojs-core-router--pageloadcontext)\n\n`layers`\n\n`Record`\n\nSuccessful earlier layout results only.\n\n[`PageProps`](/docs/core/api/router#api-tavojs-core-router--pageprops) `/` [`PagePendingProps`](/docs/core/api/router#api-tavojs-core-router--pagependingprops) `/` [`PageErrorProps`](/docs/core/api/router#api-tavojs-core-router--pageerrorprops)\n\n`layers`\n\n`RouteDataLayer[]`\n\nOrdered layout layers and, after completion, the page layer; each has id, kind, data, and error.\n\n[`PageProps`](/docs/core/api/router#api-tavojs-core-router--pageprops) `/` [`PagePendingProps`](/docs/core/api/router#api-tavojs-core-router--pagependingprops) `/` [`PageErrorProps`](/docs/core/api/router#api-tavojs-core-router--pageerrorprops)\n\n`layerData`\n\n`Record`\n\nSuccessful results keyed by layer ID.\n\n- The current root layer ID is \\_root.\n \n- A directory layout ID is its src/pages-relative directory key. The root directory layout is /; `src/pages/projects/_layout.tsx` is projects; route-group names remain in the key.\n \n- The page layer ID is the compiled route path, such as /projects/:id.\n \n- A failed loader remains in the ordered layers array but is omitted from the successful `layerData` record.\n \n\n**Reference src/pages/projects/[id].tsx**\n\n```tsx\nimport type {\n PageLoadContext,\n PageProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Workspace = { id: string };\ntype Project = { id: string; name: string };\n\nexport async function load({\n params,\n layers,\n signal,\n url\n}: PageLoadContext): Promise {\n const workspace = layers?.projects as Workspace | undefined;\n const response = await fetch(\n new URL(\n `/api/workspaces/${workspace?.id}/projects/${params.id}`,\n url\n ),\n { signal }\n );\n if (!response.ok) {\n throw new Error(\"Could not load project\");\n }\n return response.json() as Promise;\n}\n\nexport default function ProjectPage({\n data,\n layerData\n}: PageProps) {\n const workspace = layerData?.projects as Workspace | undefined;\n return (\n \n {workspace?.id}: {data?.name}\n \n );\n}\n```\n\n**Layer IDs are framework identities**\n\nDirectory moves and route-group renames can change layout IDs. Keep cross-layout reads local and deliberate, and cover each expected key with route inspection and integration tests." }, { "id": "failure-cancellation", "title": "Handle failure and cancellation separately", "markdown": "- A layout-loader failure is stored on that layout layer. The failed value is not added to downstream `context.layers`, descendants continue, and the layout receives its own data and error props.\n \n- A page-loader failure renders the page's error export when present, then `src/pages/_error.tsx`. The response defaults to status 500 unless head selects another status.\n \n- `notFound`() from middleware or any loader stops normal output, renders `404.tsx`, and returns status 404.\n \n- A superseding navigation aborts obsolete work. Pass signal onward and do not translate `AbortError` into user-facing route failure UI.\n \n- A server-only loader is skipped during browser resolution; design the browser path so it already has the required hydrated or independently fetched data.\n \n\n**Reference src/pages/projects/[id].tsx — failure exports**\n\n```tsx\nimport {\n notFound,\n type PageErrorProps,\n type PagePendingProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype ProjectParams = { id: string };\n\nexport async function load({ params, signal, url }) {\n const response = await fetch(\n new URL(`/api/projects/${params.id}`, url),\n { signal }\n );\n if (response.status === 404) {\n notFound();\n }\n if (!response.ok) {\n throw new Error(\"Could not load project\");\n }\n return response.json();\n}\n\nexport function pending({\n params\n}: PagePendingProps) {\n return (\n \n Loading project {params.id}…\n \n );\n}\n\nexport function error({\n pathname\n}: PageErrorProps) {\n return (\n \n \n Could not load {pathname}.\n \n \n );\n}\n```" }, { "id": "middleware", "title": "Keep middleware decisions small and auditable", "markdown": "A route middleware export implements [`PageMiddleware`](/docs/core/api/router#api-tavojs-core-router--pagemiddleware \"View PageMiddleware in the Core API reference\"). Use [`defineMiddleware`](/docs/core/api/router#api-tavojs-core-router--definemiddleware \"View defineMiddleware in the Core API reference\") for portable work and [`defineServerMiddleware`](/docs/core/api/router#api-tavojs-core-router--defineservermiddleware \"View defineServerMiddleware in the Core API reference\") when the decision requires server-only state.\n\n**Reference src/pages/account/_layout.tsx — named export**\n\n```ts\nimport {\n defineServerMiddleware\n} from \"@tavojs/core/router\";\n\nexport const middleware = defineServerMiddleware(\n async ({ request, signal }) => {\n signal.throwIfAborted();\n const { readAuthenticatedUser } = await import(\"src/server/auth\");\n const user = await readAuthenticatedUser(request, { signal });\n if (!user) {\n return {\n redirect: \"/sign-in\",\n status: 302\n };\n }\n }\n);\n```\n\n- Middleware runtime defaults to both. Use `defineServerMiddleware` whenever the decision reads secrets or server-only credentials.\n \n- Return nothing to continue. Return redirect to stop resolution; its status defaults to 302.\n \n- A status without redirect does not block or replace the route.\n \n- External redirects are disabled by default. Keep them disabled for targets derived from request data." }, { "id": "verification", "title": "Verify order, layers, and cancellation", "markdown": "**Run Terminal**\n\n```bash\nnpx tavo inspect route /projects/example --json\nnpx tavo check\nnpx tavo build\n```\n\nTest successful layout and page loads, each loader failing independently, notFound(), a redirect, and an aborted slow navigation. Assert both response status and the exact visible boundary rather than checking only rendered text." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:actions-and-forms", "section": "core", "slug": "actions-and-forms", "title": "Actions, forms, and validation", "description": "Handle mutations with route actions, schema validation, explicit response shapes, and server-owned sessions.", "keywords": [ "action", "form", "validation", "session" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Handle mutations with route actions, schema validation, explicit response shapes, and server-owned sessions." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/actions-and-forms", "sections": [ { "id": "mutation-boundary", "title": "Put server mutations in actions", "markdown": "A route action handles non-GET requests in SSR mode. Parse the normalized Fetch Request, authorize the caller, perform the mutation, and return JSON, status, headers, or a redirect.\n\n**Merge src/pages/projects/index.tsx — merge this action export**\n\n```ts\nimport { defineAction } from \"@tavojs/core/router\";\n\nexport const action = defineAction(async ({ request }) => {\n const form = await request.formData();\n const name = String(form.get(\"name\") ?? \"\").trim();\n if (!name) {\n return { status: 400, json: { error: \"Project name is required\" } };\n }\n\n return {\n status: 201,\n json: { id: crypto.randomUUID(), name }\n };\n});\n```" }, { "id": "validated-actions", "title": "Validate input before business logic", "markdown": "`Tavo.js` accepts Standard Schema validators and common parse contracts. `defineValidatedAction` parses JSON or form input, returns HTTP 400 for invalid input, and passes typed input to the handler.\n\n**Merge src/pages/projects/new.tsx — merge this action export**\n\n```ts\nimport { defineValidatedAction } from \"@tavojs/core/dev\";\n\ntype ProjectInput = { name: string };\ntype ProjectParseResult =\n | { success: true; data: ProjectInput }\n | { success: false; error: { issues: Array<{ message: string; path: string[] }> } };\n\nconst projectSchema = {\n safeParse(value: unknown): ProjectParseResult {\n const name =\n value && typeof value === \"object\"\n ? (value as Record).name\n : undefined;\n if (typeof name !== \"string\" || name.trim().length < 2) {\n return {\n success: false,\n error: {\n issues: [{\n message: \"Project name must contain at least two characters\",\n path: [\"name\"]\n }]\n }\n };\n }\n return { success: true, data: { name: name.trim() } };\n }\n};\n\nexport const action = defineValidatedAction(projectSchema, async ({ input }) => {\n return {\n status: 201,\n json: { id: crypto.randomUUID(), name: input.name }\n };\n});\n```" }, { "id": "security-order", "title": "Use a safe mutation order", "markdown": "- Validate the input shape.\n \n- Authenticate and authorize the request.\n \n- Apply origin, CSRF, and idempotency rules appropriate to the endpoint.\n \n- Commit the database or external side effect.\n \n- Return only safe response data.\n \n\n**Validation is not authorization**\n\nA valid payload can still come from the wrong user. Keep permissions and session checks inside the server action before state changes." }, { "id": "route-action-reference", "title": "Route action contract", "markdown": "- Route actions handle non-GET requests during SSR route handling. The context is the same portable request context used by loaders.\n \n- Return a Response directly or an `ActionResult`. redirect creates a Location response; json serializes a JSON body; status and headers customize the response.\n \n- Unsafe methods validate browser Origin by default. Set `validateOrigin`: false only for endpoints with independent authentication such as signed webhooks.\n \n- When `contentType` is declared, a mismatched request receives 415 Unsupported Media Type before the handler runs.\n \n\n**Reference Reference snippet**\n\n```ts\ntype ActionResult = {\n body?: BodyInit | null;\n headers?: HeadersInit | Record;\n json?: unknown;\n redirect?: string;\n status?: number;\n};\n\ndefineAction(handler, {\n contentType?: \"form-data\" | \"json\";\n validateOrigin?: boolean;\n});\n```" }, { "id": "action-primitive-reference", "title": "Client action state", "markdown": "- run aborts an older run and resolves to the final `ActionState`. Handler failures become error state; run does not rethrow them.\n \n- abort returns to idle, clears error and `completedAt`, and preserves existing data. reset aborts and clears the complete state.\n \n- Subscribe through `action.store` or a controller's listen/select helpers.\n \n\n**Reference Reference snippet**\n\n```ts\ntype ActionState = {\n status: \"idle\" | \"running\" | \"success\" | \"error\";\n data: TResult | null;\n error: unknown;\n submittedAt: number | null;\n completedAt: number | null;\n};\n\nconst save = createAction(async ({ input, signal }) => saveProject(input, { signal }));\nsave.store; // observable Store>\nsave.getState();\nawait save.run(input);\nsave.abort();\nsave.reset();\n```" }, { "id": "form-action-reference", "title": "Form helpers and transport defaults", "markdown": "- Repeated `FormData` field names become arrays; single fields remain one `FormDataEntryValue`.\n \n- Server forms default to POST, multipart `FormData`, and same-origin credentials. JSON mode adds application/json unless a content type already exists.\n \n- The default parser throws for a non-ok response, otherwise returns JSON when declared by the response and text for other content types.\n \n- body and `contentType` may be selected by boot mode. A redirected browser response is followed with `window.location.assign`.\n \n\n**Reference Reference snippet**\n\n```ts\nformDataToObject(data: FormData): FormValues\ncreateFormAction(handler): FormAction\ncreateServerFormAction(url, {\n body?: \"form-data\" | \"json\" | ((values, context) => BodyInit);\n contentType?: \"form-data\" | \"json\";\n credentials?: RequestCredentials;\n fetch?: typeof fetch;\n headers?: HeadersInit;\n method?: string;\n parseResponse?: (response: Response) => MaybePromise;\n}): FormAction\n\ntype FormAction = {\n action: Action;\n store: Store>;\n submit(form: HTMLFormElement | FormData | FormValues): Promise>;\n reset(): void;\n};\n```" }, { "id": "validation-reference", "title": "Validation schemas and failures", "markdown": "`validateInput` accepts Standard Schema, `safeParse` or `safeParseAsync`, and parse or `parseAsync` contracts. `defineValidatedAction` reads JSON when Content-Type includes application/json and otherwise converts `FormData` while preserving repeated fields.\n\n**Reference Reference snippet**\n\n```ts\nconst result = await validateInput(schema, unknownInput);\n// { ok: true, value } | { ok: false, issues: [{ message, path? }] }\n\nexport const action = defineValidatedAction(schema, async ({ input, request }) => {\n await authorize(request, input);\n return { status: 201, json: await createRecord(input) };\n});\n\n// Invalid input response, status 400:\n// { error: \"validation_failed\", issues: [{ message, path? }] }\n```\n\n**Validation is not authorization**\n\nSchema validation proves the payload shape only. Authenticate, authorize, apply CSRF or idempotency rules, and then commit the mutation inside the server action." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:route-actions-and-csr-forms", "section": "core", "slug": "route-actions-and-csr-forms", "title": "Route actions and CSR forms", "description": "Handle mutations with route actions, predictable response defaults, origin checks, and explicit pure-CSR form transport.", "keywords": [ "actions", "forms", "CSR", "POST", "origin", "content type", "redirect" ], "kind": "reference", "prerequisites": [ "A route that accepts a non-GET request.", "Understanding of HTTP methods, status codes, origins, and form encoding." ], "outcomes": [ "Return the intended HTTP response from every action result form.", "Preserve origin, content-type, authentication, and authorization checks.", "Configure form transport for a pure CSR deployment without double handling." ], "runtime": [ "server", "browser" ], "related": [ { "title": "Actions and forms", "href": "/docs/core/actions-and-forms", "description": "Learn form state, validation, and reusable action helpers." }, { "title": "Security", "href": "/docs/core/security", "description": "Harden request origins, sessions, CSP, and output." } ], "canonicalPath": "/docs/core/route-actions-and-csr-forms", "sections": [ { "id": "server-action", "title": "Define the mutation beside its route", "markdown": "A route action implements [`PageAction`](/docs/core/api/router#api-tavojs-core-router--pageaction \"View PageAction in the Core API reference\"), receives [`PageActionContext`](/docs/core/api/router#api-tavojs-core-router--pageactioncontext \"View PageActionContext in the Core API reference\"), and may return a native Response or the documented data, redirect, or error object forms. [`defineAction`](/docs/core/api/router#api-tavojs-core-router--defineaction \"View defineAction in the Core API reference\") adds origin and content-type policy to that handler.\n\n**Reference src/pages/projects/new.tsx**\n\n```tsx\nimport {\n defineAction,\n type PageActionContext\n} from \"@tavojs/core/router\";\nimport { Button, Page, Stack, TextField } from \"@tavojs/ui\";\ntype NewProjectInput = { name: string };\n\nexport const action = defineAction(\n async ({ request }: PageActionContext) => {\n const {\n authorizeProjectCreation,\n createProject,\n requireUser\n } = await import(\"src/server/projects\");\n const form = await request.formData();\n const input: NewProjectInput = {\n name: String(form.get(\"name\") ?? \"\").trim()\n };\n\n const user = await requireUser(request);\n authorizeProjectCreation(user);\n const project = await createProject(input);\n\n return {\n redirect: `/projects/${project.id}`\n };\n },\n {\n contentType: \"form-data\"\n }\n);\n\nexport default function NewProjectPage() {\n return (\n \n
    \n \n \n \n \n
    \n     \n );\n}\n```\n\n- The Node route handler sends non-GET and non-HEAD requests to the matched page action before normal page rendering.\n \n- If the route has no action, the handler returns 405 Method Not Allowed with Allow: GET, HEAD.\n \n- A body above the configured request limit returns 413. An unhandled action failure becomes a generic 500 response.\n \n- Return a Response to control the full response, or return an `ActionResult` for `Tavo.js` to normalize and harden." }, { "id": "response-defaults", "title": "Know the action response defaults", "markdown": "Handler result\n\nDefault response\n\n`undefined`\n\n204 with an empty body\n\n`{ redirect }`\n\n303 with Location\n\n`{ json }`\n\n200 with application/json; charset=utf-8 and a serialized body\n\n`{ body }`\n\n200 when body is present; otherwise 204\n\n`Response`\n\nIts status, body, and headers are preserved; default security headers are added when absent\n\nAn explicit status or headers value in these object forms overrides the corresponding default. External redirect targets are rejected unless the runtime explicitly enables them; validate any user-derived redirect again at the application boundary." }, { "id": "request-safety", "title": "Apply transport checks before business logic", "markdown": "- Unsafe action methods validate Origin against the request origin by default. Node-like requests also require a local or configured trusted host.\n \n- Do not set `validateOrigin`: false for a browser form. Reserve it for endpoints with an independent authenticity mechanism, such as a verified webhook signature.\n \n- `contentType`: \"json\" accepts application/json and +json media types. `contentType`: \"form-data\" accepts multipart/form-data and application/x-www-form-urlencoded.\n \n- A declared content-type mismatch returns 415 before the handler runs.\n \n- Parsing or schema validation proves shape, not identity or permission. Authenticate, authorize, enforce CSRF or idempotency policy, and then commit the mutation.\n \n- Do not return secrets, private exception messages, or raw database failures in action bodies.\n \n\n**Trusted hosts are not user authorization**\n\ntrustedHosts establishes which request host is acceptable for origin comparison. It does not authenticate the caller or grant permission to mutate a record." }, { "id": "csr-transport", "title": "Configure delegated forms only for pure CSR boot", "markdown": "In a server-rendered document, a normal form posts to its matched route action. A pure CSR document can opt into delegated action transport through [`bootTavo`](/docs/core/api/application#api-tavojs-core--boottavo \"View bootTavo in the Core API reference\") and its `csrActions` option so the browser submits to an available backend endpoint.\n\n**Reference src/main.tsx — pure CSR entry**\n\n```tsx\nimport { bootTavo } from \"@tavojs/core\";\n\nvoid bootTavo({\n csrActions: {\n enabled: true,\n baseUrl: \"https://api.example.com\",\n credentials: \"include\",\n headers: {\n \"X-Requested-With\": \"Tavo.js\"\n }\n }\n});\n```\n\n**Reference CsrActionsOptions — developer-supplied callbacks**\n\n```ts\ntype CsrActionContext = {\n pathname: string;\n search: string;\n form?: HTMLFormElement;\n};\n\ntype CsrActionsOptions = {\n enabled?: boolean;\n baseUrl?: string;\n resolveUrl?: (context: CsrActionContext) => string;\n credentials?: RequestCredentials;\n headers?:\n | HeadersInit\n | ((context: {\n pathname: string;\n form: HTMLFormElement;\n }) => HeadersInit);\n};\n```\n\n- Delegation applies to non-GET, same-window forms that are not explicitly external.\n \n- The browser sends `FormData` with the form method. credentials defaults to include when not configured.\n \n- `data-tavo-native` opts one form out so the browser performs its native submission.\n \n- A same-origin redirect becomes replace navigation. Other redirect destinations use a full browser navigation.\n \n- CSR action delegation is not enabled during SSR hydration. This prevents the hydrated application from installing a competing form transport.\n \n- A pure CSR form without `csrActions` emits a development warning unless it is marked `data-tavo-native`.\n \n\n**CORS does not replace action security**\n\nA cross-origin CSR backend must deliberately allow the app origin and credentials. The action still needs origin or signature validation, authentication, authorization, and safe cookie settings." }, { "id": "verification", "title": "Verify the complete mutation path", "markdown": "- Submit valid multipart and URL-encoded forms, then test the wrong media type and expect 415.\n \n- Send a missing or cross-origin Origin header according to the deployment contract and verify 403 where required.\n \n- Verify no action returns 405, an oversized body returns 413, and internal failures return a generic 500.\n \n- Test redirect, JSON, body, empty, and direct Response results with their exact status and headers.\n \n- For pure CSR, verify endpoint mapping, credentials, native opt-out, same-origin replace navigation, and full external navigation.\n \n\n**Run Terminal**\n\n```bash\nnpx tavo inspect route /projects/new --json\nnpx tavo build\n```" }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:mvc", "section": "core", "slug": "mvc", "title": "MVC components", "description": "Separate local reactive state, business behavior, and TSX rendering with createTavo.", "keywords": [ "createTavo", "controller", "model", "lifecycle" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Separate local reactive state, business behavior, and TSX rendering with createTavo." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/mvc", "sections": [ { "id": "mental-model", "title": "Give each concern one home", "markdown": "A `Tavo.js` component has an optional model, an optional controller, and a required view. The model stores renderable local state, the controller coordinates behavior and side effects, and the view describes output from props and state.\n\n- Render-only components can provide only a view.\n \n- Small interactions can patch the model directly.\n \n- Use a controller when behavior needs lifecycle, services, stores, routing, refs, or managed cleanup." }, { "id": "controller-example", "title": "Build a controller-backed component", "markdown": "Controllers receive the component model and current props automatically. They also have access to page, router, stores, and services supplied by the runtime.\n\n**Create src/components/Counter.tsx — create this component**\n\n```tsx\nimport { createTavo, TavoController } from \"@tavojs/core\";\nimport { Button } from \"@tavojs/ui\";\n\nclass CounterController extends TavoController {\n increment() {\n this.model.patch((state) => ({ count: state.count + 1 }));\n }\n}\n\nexport const Counter = createTavo({\n model: () => ({ count: 0 }),\n controller: CounterController,\n view: ({ state, controller }) => (\n \n )\n});\n```" }, { "id": "lifecycle-and-cleanup", "title": "Own lifecycle work", "markdown": "Use `onInit` for subscriptions and initial model work, `onMount` or `onLayout` for DOM-dependent behavior, `afterRender` for post-commit work, and `onPropsChange` for explicit prop reactions.\n\n**Reference src/components/Clock/controller.ts**\n\n```ts\nimport { TavoController } from \"@tavojs/core\";\n\nexport class ClockController extends TavoController {\n onMount() {\n const timer = window.setInterval(() => {\n this.model.patch({ now: new Date() });\n }, 1000);\n\n return () => window.clearInterval(timer);\n }\n}\n```\n\n**Cleanup is part of the feature**\n\nReturn cleanup from mount methods or register it with this.cleanup(). Prefer controller helpers such as listen, select, observeResize, and observeIntersection so teardown follows the component lifecycle." }, { "id": "definition-contract", "title": "Understand the complete createTavo contract", "markdown": "[`createTavo`](/docs/core/api/application#api-tavojs-core--createtavo \"View createTavo in the Core API reference\") returns a typed component. Only view is required. A model owns reactive state, while a controller owns behavior and managed side effects. Each mounted component keeps one model and one controller instance across rerenders.\n\n**Reference Reference snippet**\n\n```ts\ncreateTavo({\n model?: (props: Props) => State | Store,\n controller?: new (ctx: MvcControllerContext) => Controller,\n createController?: (ctx: MvcControllerContext) => Controller,\n view: (ctx: {\n props: Props;\n state: State;\n model: Store;\n controller: Controller | null;\n }) => Child\n}): Component\n```\n\n## model\n\nRuns once for a mounted component, using its initial props. Return a plain object for Tavo.js to wrap with createStore, or return an existing Store. When omitted, Tavo.js creates an empty Store.\n\n## controller\n\nA class constructor that receives the complete controller context. Use it for reusable behavior, lifecycle methods, and managed work.\n\n## createController\n\nA factory alternative for functional or object-based controllers. If both controller fields are supplied, the class controller is used.\n\n## view\n\nReceives current props, the state snapshot, the model Store, and the controller instance. Without a controller, controller is null.\n\n**Reference Reference snippet**\n\n```tsx\nimport { createTavo } from \"@tavojs/core\";\nimport { Button } from \"@tavojs/ui\";\n\nexport const Counter = createTavo({\n model: ({ initial = 0 }: { initial?: number }) => ({ count: initial }),\n view: ({ state, model }) => (\n \n )\n});\n```\n\n**Initial props and current props are different concerns**\n\nmodel(props) runs only when the component instance is created. Use controller.props or onPropsChange when behavior must follow later prop updates." }, { "id": "controller-context", "title": "Use the context injected into every controller", "markdown": "[`TavoController`](/docs/core/api/application#api-tavojs-core--tavocontroller \"View TavoController in the Core API reference\") receives six developer-facing context groups. They are also available on the ctx constructor argument and on controllers returned by createController.\n\nProperty\n\nValue\n\nUse\n\n`model`\n\n[`Store`](/docs/core/api/application#api-tavojs-core--store)`<``State``>`\n\nRead and update the component-local reactive model.\n\n`props`\n\n`Props`\n\nRead the latest props; Tavo.js refreshes them before each view call.\n\n`router`\n\n[`Router`](/docs/core/api/router#api-tavojs-core-router--router) `helpers`\n\nNavigate, update the URL, prefetch, and inspect available routes.\n\n`stores`\n\n`Global store registry`\n\nGet, test, and list stores previously created with defineGlobalStore.\n\n`services`\n\n`Service registry`\n\nGet, optionally resolve, test, and list named or typed services.\n\n`page`\n\n`Current route state`\n\nRead pathname, status, params, data, errors, and layout-layer data.\n\n**Reference Reference snippet**\n\n```ts\nclass ProjectController extends TavoController {\n openSettings() {\n this.router.navigate(`/projects/${this.page.params.id}/settings`);\n }\n\n rememberTab(tab: string) {\n // Changes browser history without running route navigation or remounting.\n this.router.pushUrl(`?tab=${encodeURIComponent(tab)}`);\n }\n\n prefetchReports(signal?: AbortSignal) {\n return this.router.prefetch(\"/reports\", { signal });\n }\n}\n```\n\nContext\n\nAvailable members\n\n`router`\n\n[`navigate`](/docs/core/api/router#api-tavojs-core-router--navigate)`(``to``,` `options``?``)``,` `pushUrl``(``to``)``,` `replaceUrl``(``to``)``,` `prefetch``(``pathname``,` `{` `signal``?` `}``?``)``,` `routes`\n\n`stores`\n\n`get(name), has(name), list()`\n\n`services`\n\n`get(identifier), tryGet(identifier), has(identifier), list()`\n\n`page`\n\n`pathname, route, status, data, params, error, layers, layerData`\n\n**Lookup does not register**\n\nController stores and services expose lookup APIs only. Define a global store with defineGlobalStore and register a service before a controller resolves it. stores.get and services.get throw when a name is missing; services.tryGet returns undefined." }, { "id": "managed-methods", "title": "Let the controller manage side effects", "markdown": "Controller helpers return unsubscribe functions. You can call one early to cancel the work; otherwise Tavo.js disposes it when the component is destroyed.\n\nMethod\n\nBehavior\n\n`cleanup(fn)`\n\nRegister any cleanup and receive an idempotent wrapped unsubscribe.\n\n`createId(prefix?)`\n\nCreate an instance-scoped sequential ID. The default prefix is id.\n\n`setTimeout(fn, delay?)`\n\nSchedule a timeout that is removed after firing and cancelled on destroy.\n\n`setInterval(fn, delay?)`\n\nSchedule an interval that is cancelled on destroy.\n\n`scheduleLayoutEffect(fn)`\n\nQueue managed microtask work that may return cleanup.\n\n`scheduleAfterRender(fn)`\n\nQueue one-shot microtask work and unregister after it runs.\n\n`scheduleOnMount(fn)`\n\nQueue managed mount work that may return cleanup.\n\n`listen(store, listener, options?)`\n\nSubscribe to a complete Tavo.js Store snapshot.\n\n`select(store, selector, listener, options?)`\n\nSubscribe to a selected value with optional equality.\n\n`watch(store, target, listener, options?)`\n\nWatch a key, nested path, or selector.\n\n`listenExternal(store, listener, options?)`\n\nSubscribe to an ExternalStore snapshot with optional equality.\n\n[`observeResize`](/docs/core/api/components-and-dom#api-tavojs-core--observeresize)`(``target``,` `listener``,` `options``?``)`\n\nCreate a managed ResizeObserver.\n\n[`observeIntersection`](/docs/core/api/components-and-dom#api-tavojs-core--observeintersection)`(``target``,` `listener``,` `options``?``)`\n\nCreate a managed IntersectionObserver.\n\n[`observeMutation`](/docs/core/api/components-and-dom#api-tavojs-core--observemutation)`(``target``,` `listener``,` `options``?``)`\n\nCreate a managed MutationObserver for a Node or ref object.\n\n`action(fn)`\n\nWrap sync or async work with reactive pending, result, and error state.\n\n**Reference Reference snippet**\n\n```tsx\nclass PanelController extends TavoController {\n declare panel: { current: HTMLElement | null };\n\n onMount() {\n this.setInterval(() => this.refresh(), 30_000);\n this.observeResize(this.panel, () => this.measure());\n return this.listen(filters, (state) => this.applyFilters(state));\n }\n\n refresh() {}\n measure() {}\n applyFilters(_state: FilterState) {}\n}\n```" }, { "id": "lifecycle-reference", "title": "Choose the lifecycle hook by timing", "markdown": "Hook\n\nWhen it runs\n\nReturn\n\nSSR\n\n`onInit()`\n\nOnce in the first passive mount task, immediately before onMount.\n\nNo\n\nNo\n\n`onMount()`\n\nOnce in the first passive mount task.\n\nMay return cleanup\n\nNo\n\n`onLayout()`\n\nAfter every client commit, before passive hooks.\n\nMay return cleanup\n\nNo\n\n`afterRender()`\n\nAs a passive task after every client commit.\n\nNo\n\nNo\n\n`onPropsChange(props)`\n\nInitial client render and later shallowly changed props.\n\nNo\n\nNo\n\n`onDestroy()`\n\nOnce during teardown, before managed controller cleanups flush.\n\nNo\n\nNo\n\nonLayout cleanup follows layout rerenders and unmount. An onMount cleanup is registered with the controller automatically. Controller props are updated synchronously before view renders; onPropsChange is the later passive notification and uses top-level shallow equality.\n\n**Reference Reference snippet**\n\n```ts\nclass DialogController extends TavoController {\n onInit() {\n this.model.patch({ phase: \"ready\" });\n }\n\n onLayout() {\n const restore = captureFocusRestore();\n return () => restore();\n }\n\n onMount() {\n return this.listen(preferences, ({ reducedMotion }) => {\n this.model.patch({ reducedMotion });\n }, { immediate: true });\n }\n\n afterRender() {\n // Observe the committed client view.\n }\n\n onPropsChange(props: DialogProps) {\n if (!props.open) this.model.patch({ phase: \"closed\" });\n }\n\n onDestroy() {\n // Final controller-owned work. Managed helpers are cleaned next.\n }\n}\n```\n\n**What participates in server rendering**\n\nModel creation, controller construction, view rendering, and IDs created from the constructor context participate in SSR. Client lifecycle hooks, timers, observers, and DOM-dependent work do not." }, { "id": "controller-actions", "title": "Represent async work with controller actions", "markdown": "**Reference Reference snippet**\n\n```tsx\nclass ProfileController extends TavoController {\n save = this.action(async (name: string) => {\n const response = await fetch(\"/api/profile\", {\n method: \"POST\",\n body: JSON.stringify({ name })\n });\n if (!response.ok) throw new Error(\"Could not save profile\");\n return response.json() as Promise<{ name: string }>;\n });\n}\n\nexport const Profile = createTavo({\n controller: ProfileController,\n view: ({ controller }) => \n controller?.save.run(\"Ada\").catch(() => {})}\n >\n Save\n \n {controller?.save.error ? Save failed : null}\n {controller?.save.result ? Saved {controller.save.result.name} : null}\n \n});\n```\n\n- An action starts with pending false, error null, and result null.\n \n- run sets pending true and clears error. It resolves with the function result or rethrows the caught error.\n \n- Only the most recently started run may update action state, so an older response cannot overwrite a newer one.\n \n- Starting another run keeps the previous result visible while pending.\n \n- reset clears pending, error, and result and prevents in-flight completions from changing action state.\n \n- Every action-state transition rerenders the owning MVC component.\n \n\n**Actions are safe as class fields**\n\naction is the one TavoController helper designed to run from a class-field initializer before normal controller attachment. Await or catch run because rejected work is rethrown to its caller." }, { "id": "controller-construction", "title": "Use constructor context before attachment", "markdown": "Tavo.js constructs a class with the complete ctx argument, then attaches model, props, framework context, and managed methods to the instance. Use ctx for constructor-time IDs or reads. Use this.model, this.props, and the other instance helpers from lifecycle hooks and normal methods.\n\n**Reference Reference snippet**\n\n```tsx\nimport { Box, TextInput } from \"@tavojs/ui\";\n\nclass FieldController extends TavoController {\n id: string;\n\n constructor(ctx: { createId(prefix?: string): string }) {\n super();\n this.id = ctx.createId(\"field\");\n }\n}\n\nexport const Field = createTavo, Record, FieldController>({\n controller: FieldController,\n view: ({ controller }) => (\n \n Email\n \n \n )\n});\n```\n\n**Do not call most this helpers in the constructor**\n\nthis.createId, cleanup, timers, schedulers, listeners, and observers are unavailable until createTavo finishes attachment and will throw. Use ctx in the constructor, or move the work to a lifecycle hook." }, { "id": "mvc-common-mistakes", "title": "Avoid common MVC mistakes", "markdown": "## Recreating state from new props\n\nmodel runs once per component instance. React to later props through current controller.props or onPropsChange.\n\n## Leaking manual subscriptions\n\nPrefer listen, select, watch, listenExternal, and observer helpers. Otherwise pass the unsubscribe to cleanup.\n\n## Using URL updates as navigation\n\npushUrl and replaceUrl only change browser history. Use navigate when the application should resolve and render another route.\n\n## Ignoring action rejection\n\nAction error state is reactive, but run still rejects. Await it in a try/catch or attach a catch handler from an event callback.\n\n## Doing DOM work during SSR\n\nPut element measurement, focus, observers, and browser timers in onLayout or onMount rather than constructors or model factories.\n\n## Duplicating model state\n\nRead renderable state from view.state and mutate through view.model or controller.model instead of copying snapshots into controller fields." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:stores", "section": "core", "slug": "stores", "title": "Stores", "description": "Model shared state with explicit actions, precise subscriptions, derived values, and optional persistence.", "keywords": [ "state", "store", "computed", "persist" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Model shared state with explicit actions, precise subscriptions, derived values, and optional persistence." ], "runtime": [ "browser" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/stores", "sections": [ { "id": "store-shape", "title": "Keep state and mutations together", "markdown": "`createStore` accepts an object or an initializer. Prefer an initializer when the store owns actions: callers then express intent through methods instead of coordinating partial state writes throughout the application.\n\n**Create src/stores/filters.ts — create this store**\n\n```ts\nimport { createStore } from \"@tavojs/core\";\n\nexport const filters = createStore((set, get) => ({\n status: \"all\",\n setStatus(status: string) { set({ status }); },\n reset() { set({ status: \"all\" }); },\n isActive() { return get().status !== \"all\"; }\n}));\n```" }, { "id": "updates-and-subscriptions", "title": "Subscribe to the smallest useful value", "markdown": "Use patch for top-level partial updates, set for a key or nested path, and `setState` only when replacing the complete state value. `subscribeSelector` and watch prevent unrelated changes from waking application behavior.\n\n**Reference src/stores/filters.ts — append while learning subscriptions**\n\n```ts\nconst stop = filters.subscribeSelector(\n (state) => state.status,\n (nextStatus, previousStatus) => console.log({ nextStatus, previousStatus })\n);\n\nfilters.set(\"status\", \"active\");\nstop();\n```" }, { "id": "scope-and-derived-state", "title": "Choose the correct scope", "markdown": "Use a component model for state owned by one component, a global store for client state shared across routes, and a computed store for a derived value consumed by multiple subscribers.\n\n**SSR safety**\n\nGlobal stores are process-wide on the server. Never place the current request user, session, token, tenant, or permissions in them. Return safe request data from a server loader instead." }, { "id": "store-contract", "title": "Use the complete Store contract", "markdown": "**Reference Reference snippet**\n\n```ts\ntype Store = {\n getState(): State;\n setState(next: State | ((previous: State) => State)): State;\n set(path, valueOrUpdater): State;\n patch(partial: Partial | ((previous: State) => Partial)): State;\n subscribe(listener, options?): Unsubscribe;\n subscribeSelector(selector, listener, options?): Unsubscribe;\n watch(pathOrSelector, listener, options?): Unsubscribe;\n};\n```\n\nMethod\n\nUse it to\n\n`getState()`\n\nRead the current complete snapshot.\n\n`setState(next)`\n\nReplace the complete state with a value or updater result.\n\n`patch(partial)`\n\nShallow-merge a top-level partial value or updater result.\n\n`set(path, value)`\n\nImmutably update one key or nested path; the updater receives the previous value and whole state.\n\n`subscribe(listener)`\n\nObserve every emitted complete-state write.\n\n`subscribeSelector(selector, listener)`\n\nObserve a computed selection and ignore equal results.\n\n`watch(target, listener)`\n\nObserve a key, nested path, or selector with complete previous-state context.\n\n**Reference Reference snippet**\n\n```ts\nconst settings = createStore({\n theme: \"system\" as \"light\" | \"dark\" | \"system\",\n profile: { name: \"Ada\", notifications: true }\n});\n\nsettings.set(\"theme\", \"dark\");\nsettings.set(\"profile.notifications\", (enabled) => !enabled);\nsettings.patch((state) => ({\n profile: { ...state.profile, name: \"Grace\" }\n}));\nsettings.setState({\n theme: \"system\",\n profile: { name: \"Ada\", notifications: true }\n});\n```\n\n**Replacement and patching are not interchangeable**\n\nsetState replaces the entire state. patch merges only the top level. set clones the containers on one path. All update methods return the resulting snapshot." }, { "id": "store-initializers", "title": "Keep state and actions together", "markdown": "**Reference Reference snippet**\n\n```ts\nimport { createStore } from \"@tavojs/core\";\n\nexport const cart = createStore((set, get) => ({\n items: [] as Array<{ id: string; quantity: number }>,\n\n add(id: string) {\n const current = get().items;\n set({ items: [...current, { id, quantity: 1 }] });\n },\n\n clear() {\n set({ items: [] });\n }\n}));\n\ncart.getState().add(\"keyboard\");\n```\n\nIn an initializer, set is the Store's top-level patch function and get reads the complete snapshot. Capture them in action methods that run later. Action functions remain part of the Store state at runtime.\n\n**Do not call set or get while creating initial state**\n\nThe Store is not initialized until the initializer returns. Calling set() or get() synchronously inside the initializer throws. Defining methods that call them later is the intended pattern." }, { "id": "nested-store-paths", "title": "Update nested paths immutably", "markdown": "**Reference Reference snippet**\n\n```ts\nconst board = createStore({\n columns: [\n { title: \"Todo\", cards: [{ id: \"a\", done: false }] }\n ]\n});\n\nboard.set([\"columns\", 0, \"title\"], \"In progress\");\nboard.set([\"columns\", 0, \"cards\", 0, \"done\"], true);\nboard.set(\"columns.0.cards.0.done\", (done) => !done);\n```\n\n- set accepts a top-level key, a dot-separated path, a number, or a readonly segment array.\n \n- The updater receives the previous selected value and the complete state.\n \n- `Tavo.js` clones every ancestor on the path and preserves unrelated references.\n \n- Missing containers become arrays when the next segment is numeric and objects otherwise.\n \n- If the selected value is unchanged under `Object.is`, `Tavo.js` returns the original state and emits nothing.\n \n- A real top-level key containing dots takes precedence over interpreting that string as a path.\n \n\n**Unsafe path segments are rejected**\n\n\\_\\_proto\\_\\_, prototype, and constructor are not allowed in Store paths. This prevents nested writes from becoming prototype pollution." }, { "id": "store-subscriptions", "title": "Subscribe at the smallest useful level", "markdown": "API\n\nTarget\n\nListener\n\nNotification\n\n`subscribe`\n\nComplete state\n\n`(state, previousState)`\n\nEvery emitted write\n\n`subscribeSelector`\n\nSelector\n\n`(selected, previousSelected, state)`\n\nObject.is by default\n\n`watch`\n\nKey, path, or selector\n\n`(selected, previousSelected, state, previousState)`\n\nObject.is by default\n\n**Reference Reference snippet**\n\n```ts\nconst stopName = account.watch(\n \"user.profile.name\",\n (name, previousName, state, previousState) => {\n console.log({ name, previousName, state, previousState });\n },\n { immediate: true }\n);\n\nconst stopSummary = account.subscribeSelector(\n (state) => ({ name: state.user.profile.name, plan: state.plan }),\n (summary, previousSummary) => console.log(summary, previousSummary),\n { isEqual: shallowEqual }\n);\n\nstopName();\nstopSummary();\n```\n\nWith immediate enabled, Tavo.js invokes the listener at subscription time. Current and previous selected values are the same current value; state and previousState are also the same current snapshot where supplied.\n\n**Selectors that return objects need equality**\n\nObject.is treats each newly created object as different. Supply shallowEqual or a domain-specific comparator when a selector returns an object or array and unrelated writes should be ignored." }, { "id": "derived-and-persistent-stores", "title": "Derive and persist focused state", "markdown": "**Reference Reference snippet**\n\n```ts\nimport { computedStore, persistStore } from \"@tavojs/core\";\n\nconst account = createStore({ first: \"Ada\", last: \"Lovelace\", token: \"secret\" });\n\nexport const displayName = computedStore(account, (state) => ({\n value: `${state.first} ${state.last}`\n}));\n\nconst stopPersistence = persistStore(account, {\n key: \"account-preferences\",\n pick: ({ first, last }) => ({ first, last })\n});\n\n// Stop writing future changes when this persistence owner is disposed.\nstopPersistence();\n```\n\n## computedStore\n\nCreates a Store from the selector's current result and updates it when the source selection changes. Pass isEqual when the selection needs custom comparison.\n\n## persistStore\n\nReads an existing saved value immediately, patches it into the Store, and subscribes future writes. It defaults to localStorage and JSON.\n\n- `persistStore` requires key and accepts storage, serialize, deserialize, and pick overrides.\n \n- Without browser storage or a supplied storage adapter, it returns a no-op unsubscribe.\n \n- It does not save initial state until a [`Store`](/docs/core/api/application#api-tavojs-core--store \"View Store in the Core API reference\") write emits.\n \n- Storage and parse errors are not swallowed; handle them in a custom adapter when recovery is required.\n \n- `computedStore` returns the normal [`Store`](/docs/core/api/application#api-tavojs-core--store \"View Store in the Core API reference\") interface. Treat it as derived output and update its source instead.\n \n\n**Persist preferences, not secrets**\n\nBrowser storage is readable by client JavaScript. Use pick to exclude tokens, private server data, and fields that should expire with the session." }, { "id": "external-stores", "title": "Adapt state owned outside Tavo.js", "markdown": "**Reference Reference snippet**\n\n```ts\nimport { createExternalStore } from \"@tavojs/core\";\n\nexport const colorScheme = createExternalStore({\n getSnapshot: () => matchMedia(\"(prefers-color-scheme: dark)\").matches,\n getServerSnapshot: () => false,\n subscribe(listener) {\n const query = matchMedia(\"(prefers-color-scheme: dark)\");\n query.addEventListener(\"change\", listener);\n return () => query.removeEventListener(\"change\", listener);\n }\n});\n\nclass ThemeController extends TavoController {\n onMount() {\n return this.listenExternal(\n colorScheme,\n (dark) => this.model.patch({ dark }),\n { immediate: true }\n );\n }\n}\n```\n\nAn ExternalStore provides getSnapshot, subscribe, and an optional getServerSnapshot. createExternalStore returns that interface unchanged. Controller listenExternal reads getSnapshot, suppresses equal values with Object.is by default, and manages unsubscription." }, { "id": "global-stores", "title": "Share named client state across routes", "markdown": "**Reference Reference snippet**\n\n```ts\nimport {\n defineGlobalStore,\n getGlobalStore,\n hasGlobalStore,\n listGlobalStores\n} from \"@tavojs/core\";\n\nexport const preferences = defineGlobalStore(\"preferences\", (set) => ({\n density: \"comfortable\" as \"comfortable\" | \"compact\",\n setDensity(density: \"comfortable\" | \"compact\") {\n set({ density });\n }\n}));\n\nclass ToolbarController extends TavoController {\n compact() {\n this.stores.get>(\"preferences\")\n .getState()\n .setDensity(\"compact\");\n }\n}\n```\n\n- `defineGlobalStore` creates a name once. A later definition returns the existing [`Store`](/docs/core/api/application#api-tavojs-core--store \"View Store in the Core API reference\") and ignores the new initial state.\n \n- `getGlobalStore` throws for an unknown name; `hasGlobalStore` checks first and `listGlobalStores` returns registered names.\n \n- Controller `this.stores` exposes get, has, and list but does not define stores.\n \n- Use the `@tavojs/core` package root for the complete global-store API.\n \n\n**Global means process-wide during SSR**\n\nNever write the current user, session, token, tenant, or permissions into a global Store during server rendering. Tavo.js warns once per global Store name when setState, set, or patch writes during SSR, but the write can still leak request data. Return request-scoped values from loaders instead." }, { "id": "store-ssr-snapshots", "title": "Understand automatic Store hydration", "markdown": "Tavo.js serializes written Store state during SSR, embeds it in the page, and hydrates matching client Stores. Top-level function values are excluded from the serialized snapshot. This lifecycle is automatic; snapshot scopes and document-state hydration are framework internals, not application APIs.\n\n**Keep request values request-scoped**\n\nUse route loader data for the current user, session, token, tenant, permissions, and other request-specific values. Never write those values to a process-wide global Store during server rendering." }, { "id": "store-common-mistakes", "title": "Avoid common Store mistakes", "markdown": "## Mutating nested state\n\nUse set with a path or replace ancestors in patch. Direct mutation bypasses immutable comparison and notifications.\n\n## Replacing state with patch\n\npatch preserves unspecified top-level fields. Use setState only when the complete snapshot is intentionally replaced.\n\n## Object selectors without equality\n\nA new object fails Object.is on every write. Pass shallowEqual or a focused comparator.\n\n## Forgetting unsubscribe\n\nKeep the function returned by subscriptions and persistence. Inside controllers, prefer managed listen, select, and watch helpers.\n\n## Calling initializer helpers immediately\n\nDefine action functions that call set and get later. The Store is not readable or writable until its initializer returns.\n\n## Putting request data in a global Store\n\nGlobal Stores are process-wide on the server. Keep identity and authorization data in request-scoped loader results." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:services-and-dependencies", "section": "core", "slug": "services-and-dependencies", "title": "Services and dependency lifetimes", "description": "Register typed application dependencies, resolve them through controllers, and keep process-wide services free of request identity.", "keywords": [ "service", "dependency injection", "createServiceKey", "registerService", "lifetime", "SSR safety" ], "kind": "guide", "prerequisites": [ "An application dependency that is not component state or request data." ], "outcomes": [ "Register and resolve named or typed application services.", "Choose between models, Stores, services, and plugin capabilities.", "Keep server request state isolated from process-wide registries." ], "runtime": [ "browser", "server" ], "related": [ { "title": "MVC components", "href": "/docs/core/mvc", "description": "Resolve services and plugin capabilities in controllers." }, { "title": "Stores", "href": "/docs/core/stores", "description": "Use observable state instead of a service registry." }, { "title": "Security", "href": "/docs/core/security", "description": "Keep authentication and authorization request-scoped." } ], "canonicalPath": "/docs/core/services-and-dependencies", "sections": [ { "id": "selection", "title": "Choose the dependency owner first", "markdown": "- Use a [`createTavo`](/docs/core/api/application#api-tavojs-core--createtavo \"View createTavo in the Core API reference\") model for reactive state owned by one mounted component.\n \n- Use a global [`Store`](/docs/core/api/application#api-tavojs-core--store \"View Store in the Core API reference\") for observable browser state shared across multiple component or route owners.\n \n- Use an application service for a stable dependency such as a client SDK, stateless formatter, telemetry sink, or feature client.\n \n- Use a plugin capability for behavior owned and declared by a Plugin API v1 installation.\n \n- Use loader, middleware, action, endpoint, or session context for the current request, user, tenant, token, or permissions.\n \n\n**Reference src/services/clock.ts**\n\n```ts\nimport {\n createServiceKey,\n registerService,\n} from \"@tavojs/core\";\n\nexport type Clock = {\n now(): Date;\n};\n\nexport const clockKey = createServiceKey(\"app.clock\");\n\nregisterService(clockKey, {\n now: () => new Date(),\n});\n```" }, { "id": "typed-services", "title": "Register and resolve a typed service", "markdown": "[`createServiceKey`](/docs/core/api/application#api-tavojs-core--createservicekey \"View createServiceKey in the Core API reference\") carries the service type while retaining a stable string name. Register once in the runtime that owns the dependency with [`registerService`](/docs/core/api/application#api-tavojs-core--registerservice \"View registerService in the Core API reference\"), then resolve by the same key.\n\n- [`getService`](/docs/core/api/application#api-tavojs-core--getservice \"View getService in the Core API reference\") and controller services.get throw when the identifier is missing.\n \n- [`tryGetService`](/docs/core/api/application#api-tavojs-core--trygetservice \"View tryGetService in the Core API reference\") and controller services.tryGet return undefined for an optional dependency.\n \n- [`hasService`](/docs/core/api/application#api-tavojs-core--hasservice \"View hasService in the Core API reference\") checks one identifier; [`listServices`](/docs/core/api/application#api-tavojs-core--listservices \"View listServices in the Core API reference\") returns every registered name.\n \n- String names are supported, but a typed key keeps registration and lookup aligned without repeated generic arguments.\n \n\n**Reference src/services/metrics.ts**\n\n```ts\nimport {\n createServiceKey,\n getService,\n hasService,\n registerService,\n} from \"@tavojs/core\";\n\nexport type MetricsService = {\n increment(name: string): void;\n};\n\nexport const metricsKey =\n createServiceKey(\"app:metrics\");\n\nfunction createMetricsService(): MetricsService {\n return {\n increment(name) {\n navigator.sendBeacon(\n \"/api/metrics\",\n JSON.stringify({ name }),\n );\n },\n };\n}\n\nexport function installMetricsService(): MetricsService {\n if (!hasService(metricsKey)) {\n registerService(metricsKey, createMetricsService());\n }\n\n return getService(metricsKey);\n}\n```\n\n**Reference src/main.tsx**\n\n```tsx\nimport { bootTavo } from \"@tavojs/core\";\nimport { installMetricsService } from \"./services/metrics\";\n\ninstallMetricsService();\n\nvoid bootTavo().catch((error: unknown) => {\n console.error(\"Tavo.js failed to start.\", error);\n});\n```\n\n**Reference src/components/TrackedButton.tsx**\n\n```tsx\nimport {\n createTavo,\n TavoController,\n} from \"@tavojs/core\";\nimport { metricsKey } from \"../services/metrics\";\n\nclass TrackedButtonController extends TavoController {\n track() {\n this.services.get(metricsKey).increment(\"project_created\");\n }\n}\n\nexport const TrackedButton = createTavo({\n controller: TrackedButtonController,\n view({ controller }) {\n return (\n {\n controller?.track();\n }}\n >\n Create project\n \n );\n },\n});\n```" }, { "id": "registration", "title": "Make replacement intentional", "markdown": "- `registerService` returns the same service instance it registers.\n \n- A duplicate name still replaces the previous value. Core warns once unless { override: true } declares that replacement is intentional.\n \n- The default i18n service uses the reserved `tavo`:i18n name and participates in framework discovery.\n \n- `unregisterService` and `clearServices` are development/testing helpers from `@tavojs/core/dev`; use them to isolate tests rather than as normal application lifecycle.\n \n\n**Reference tests/metrics.test.ts**\n\n```ts\nimport {\n clearServices,\n unregisterService,\n} from \"@tavojs/core/dev\";\nimport {\n metricsKey,\n installMetricsService,\n} from \"../src/services/metrics\";\n\nexport function beforeEachServiceTest() {\n clearServices();\n installMetricsService();\n}\n\nexport function afterEachServiceTest() {\n unregisterService(metricsKey);\n}\n```" }, { "id": "server-lifetime", "title": "Treat the registry as process-wide during SSR", "markdown": "The service registry lives on `globalThis`. A Node process can serve concurrent requests through the same service instance, so registration during SSR emits a warning that asks you to audit the lifetime.\n\n- A shared service may be immutable or internally concurrency-safe, but it must not store the current request identity.\n \n- Never attach a user, tenant, session, token, cart, permissions, or request headers to a registered service.\n \n- Pass request values into stateless service methods, or create the request-bound client inside the loader/action/middleware that owns it.\n \n- Do not silence a duplicate or SSR warning with override until the replacement and lifetime are intentional.\n \n\n**A typed singleton is still a singleton**\n\ncreateServiceKey improves type safety; it does not make a service request-scoped. Authentication and authorization must remain in the server request path." }, { "id": "plugin-capabilities", "title": "Distinguish services from capabilities", "markdown": "Controllers expose both `this.services` and `this.capabilities`. Services are registered directly by the application. Capabilities are contracts contributed by installed plugins and resolved through the active Pages runtime.\n\n- Use `capabilities.resolve` for a required plugin capability and `tryResolve` for an optional one.\n \n- Required capability resolution without an active Pages runtime fails with `TAVO_PLUGIN_004`.\n \n- Keep plugin ownership, permissions, and replacement rules in the Plugin API v1 manifest instead of recreating them in the service registry." }, { "id": "service-verification", "title": "Verify registration and isolation", "markdown": "- Resolve the typed key after installation and assert the same instance is returned.\n \n- Verify get throws and `tryGet` returns undefined before installation.\n \n- Register a duplicate in a focused test and confirm intentional override behavior.\n \n- Clear services between tests that share a process.\n \n- Run concurrent SSR requests and confirm no request-specific value is retained by a service." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:async-ownership", "section": "core", "slug": "async-ownership", "title": "Async ownership and cancellation", "description": "Choose route loaders, resources, actions, forms, Deferred boundaries, and controller actions by lifetime and cancellation behavior.", "keywords": [ "async", "AbortSignal", "cancellation", "resource", "action", "Deferred", "stale result" ], "kind": "guide", "prerequisites": [ "An asynchronous read, mutation, component task, or streamed value." ], "outcomes": [ "Assign each asynchronous task to one clear owner.", "Propagate AbortSignal and prevent stale completions from publishing.", "Distinguish abort, failure, reset, and committed side effects." ], "runtime": [ "browser", "server" ], "related": [ { "title": "Data loading and middleware", "href": "/docs/core/data-and-middleware", "description": "Load route-critical data and use component resources." }, { "title": "Actions, forms, and validation", "href": "/docs/core/actions-and-forms", "description": "Handle mutations and form transport." }, { "title": "Streaming and async work", "href": "/docs/core/streaming-and-async", "description": "Stream secondary server values with Deferred." } ], "canonicalPath": "/docs/core/async-ownership", "sections": [ { "id": "choose-owner", "title": "Choose the owner before the primitive", "markdown": "- Use a route load export when navigation cannot render the route correctly without the data.\n \n- Use [`createResource`](/docs/core/api/data-actions-and-async#api-tavojs-core--createresource \"View createResource in the Core API reference\") when one mounted feature owns independently refreshable read data.\n \n- Use a route action for a server mutation and its HTTP response.\n \n- Use [`createAction`](/docs/core/api/data-actions-and-async#api-tavojs-core--createaction \"View createAction in the Core API reference\") or [`createFormAction`](/docs/core/api/data-actions-and-async#api-tavojs-core--createformaction \"View createFormAction in the Core API reference\") for observable client mutation state.\n \n- Use [`TavoController`](/docs/core/api/application#api-tavojs-core--tavocontroller \"View TavoController in the Core API reference\").action for controller-owned work whose pending/result/error state should rerender that component.\n \n- Use [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") when the server can send meaningful fallback HTML before a secondary value resolves." }, { "id": "resource-owner", "title": "Give a component resource explicit cleanup", "markdown": "- load always starts a new operation and aborts the previous one. preload deduplicates the current pending operation.\n \n- Forward the supplied signal to fetch and every abort-aware dependency.\n \n- A stale completion cannot overwrite a newer load.\n \n- An abort resolves the resource back to idle, clears error and `updatedAt`, and preserves the last data. reset also clears data.\n \n- [`Resource`](/docs/core/api/data-actions-and-async#api-tavojs-core--resource \"View Resource in the Core API reference\") failures become error state; load resolves to that state instead of rethrowing the loader error.\n \n\n**Reference src/components/ActivityPanel.tsx**\n\n```tsx\nimport {\n createResource,\n createTavo,\n TavoController,\n} from \"@tavojs/core\";\n\ntype Activity = {\n id: string;\n summary: string;\n};\n\nclass ActivityController extends TavoController {\n activity = createResource(async ({ signal }) => {\n const response = await fetch(\"/api/activity\", { signal });\n\n if (!response.ok) {\n throw new Error(\"Activity could not be loaded.\");\n }\n\n return response.json();\n });\n\n onMount() {\n this.listen(this.activity.store, () => {\n this.model.patch({});\n });\n this.cleanup(() => {\n this.activity.abort(\"Activity panel unmounted.\");\n });\n void this.activity.load();\n }\n\n reload() {\n void this.activity.load();\n }\n}\n\nexport const ActivityPanel = createTavo({\n controller: ActivityController,\n view({ controller }) {\n const activity = controller?.activity.read();\n\n if (!activity || activity.status === \"idle\") {\n return

    Activity is idle.

    ;\n }\n\n if (activity.status === \"loading\") {\n return

    Loading activity…

    ;\n }\n\n if (activity.status === \"error\") {\n return

    Activity failed to load.

    ;\n }\n\n return (\n
      \n {activity.data?.map((item) => {\n return
    • {item.summary}
      • ;\n })}\n
    \n );\n },\n});\n```" }, { "id": "mutation-semantics", "title": "Know whether a mutation rejects", "markdown": "The two client action primitives intentionally expose different caller behavior. Choose based on who owns control flow, then handle both the observable state and returned promise.\n\n- `createAction.run` resolves to `ActionState` on success or handler failure. The failure is stored with status error.\n \n- `TavoController.action.run` resolves with the handler result and rethrows a caught error while also exposing reactive error state.\n \n- `createFormAction` mirrors `createAction` state and also records submitted values.\n \n- Starting a newer run prevents an older completion from replacing the latest observable state.\n \n- reset invalidates an in-flight completion and clears the complete state.\n \n\n**Cancellation cannot undo a committed mutation**\n\nAbortSignal stops waiting and can prevent later publication, but a database, payment, email, or remote API may already have committed. Use authorization, idempotency keys, and a server-side transaction where the business operation requires them." }, { "id": "controller-action", "title": "Handle controller action rejection", "markdown": "- A controller action is safe to create as a class field.\n \n- Its pending, result, and error transitions rerender the owning `createTavo` component.\n \n- Catch or await run from event handlers so a handled UI failure does not become an unhandled rejection.\n \n\n**Reference Reference snippet**\n\n```tsx\nclass SaveController extends TavoController {\n save = this.action(async (name: string) => {\n const response = await fetch(\"/projects\", {\n method: \"POST\",\n headers: { \"content-type\": \"application/json\" },\n body: JSON.stringify({ name }),\n });\n\n if (!response.ok) {\n throw new Error(\"Project could not be saved.\");\n }\n\n return response.json() as Promise<{ id: string }>;\n });\n\n submit(name: string) {\n void this.save.run(name).catch(() => {\n // The view renders save.error.\n });\n }\n}\n```" }, { "id": "deferred-ownership", "title": "Propagate cancellation into Deferred work", "markdown": "[`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") owns rendering of a promise-backed value; it does not create the underlying request. Pass one `AbortSignal` through `createDeferredValue` or [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") and into the operation that produces the promise.\n\n- Give every [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") value a stable id when the server result should be serialized and reused during hydration.\n \n- Use `timeoutFallback` for the typed `TAVO_DEFERRED_TIMEOUT` case and `errorFallback` for other rejection.\n \n- A pure CSR document renders fallback for a promise-backed [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") value; progressive patching is an SSR capability.\n \n- Do not share request-specific promises through module variables or process-wide registries." }, { "id": "async-verification", "title": "Test race, abort, and cleanup paths", "markdown": "- Hold two operations pending, resolve the newer one first, and assert the older completion cannot replace state.\n \n- Abort before start, while pending, and during component unmount.\n \n- Assert the semantic difference between abort and reset, especially whether previous data remains.\n \n- Reject every action/resource path and verify both observable state and promise behavior.\n \n- For server mutations, retry with the same idempotency key and verify one committed effect." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:ssr-and-hydration", "section": "core", "slug": "ssr-and-hydration", "title": "SSR and hydration", "description": "Choose SSR, CSR, SSG, or revalidated output and keep the initial client tree consistent with server HTML.", "keywords": [ "server rendering", "hydration", "static", "ISR" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Choose SSR, CSR, SSG, or revalidated output and keep the initial client tree consistent with server HTML." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/ssr-and-hydration", "sections": [ { "id": "render-modes", "title": "Choose rendering per route", "markdown": "The same page and component code can render on the server or client. SSR is the default in SSR development, preview, and the generated Node server. Use CSR only when the route depends on browser-only behavior and its initial HTML is not important.\n\n- SSR renders for each request.\n \n- CSR sends the document shell and resolves the route in the browser.\n \n- SSG prerenders static routes during build.\n \n- ISR caches SSR output and refreshes it after a revalidation interval." }, { "id": "route-configuration", "title": "Configure route output", "markdown": "Static routes may provide `generateStaticParams` for dynamic paths. Revalidated output uses a runtime process-local cache by default, while Cookie or Authorization requests bypass static caching.\n\n**Create src/pages/blog/[id].tsx — create this static route**\n\n```tsx\nimport { notFound, type PageLoadContext, type PageProps } from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\nconst posts: Record = {\n hello: { title: \"Hello from Tavo.js\" },\n \"release-notes\": { title: \"Release notes\" }\n};\n\nexport const prerender = true;\nexport const generateStaticParams = () => [{ id: \"hello\" }, { id: \"release-notes\" }];\nexport const load = ({ params }: PageLoadContext) => posts[params.id] ?? notFound();\n\nexport default function BlogPost({ data }: PageProps<{ title: string }>) {\n return {data?.title};\n}\n```" }, { "id": "hydration-contract", "title": "Keep hydration deterministic", "markdown": "`Tavo.js` serializes resolved route data so the browser can hydrate against the same route tree without immediately loading it again. Hydration warnings mean server and client produced different initial output.\n\n- Do not read browser-only globals during the initial render without a guard.\n \n- Use deterministic IDs from controller helpers.\n \n- Avoid time, randomness, and locale differences between server and client output.\n \n- Test the production SSR build, not only development mode." }, { "id": "render-mode-reference", "title": "Rendering mode reference", "markdown": "Every route resolves to either SSR or CSR. SSR is the default. Static generation and revalidation are cache policies applied to SSR routes; they are not separate component runtimes.\n\n**Reference src/pages/account.tsx**\n\n```tsx\n// Browser-rendered route with a useful server shell.\nexport const render = \"csr\";\n\nexport default function AccountPage() {\n return
    Account settings
    ;\n}\n```\n\nAPI / option\n\nType\n\nDefault\n\nBehavior\n\n[`render`](/docs/core/api/components-and-dom#api-tavojs-core--render)\n\n`\"csr\"`\n\nSSR\n\nExport render = \"csr\" to opt the route subtree out of server body rendering.\n\n`prerender`\n\n`boolean`\n\nfalse\n\nMarks a functional SSR route for build-time prerendering or runtime static caching. false disables an inherited static policy.\n\n`revalidate`\n\n`number | false`\n\nunset\n\nEnables static SSR caching for the given number of seconds. Values are floored and clamped to zero; false disables inherited caching.\n\n`generateStaticParams`\n\n`() => params[] | Promise`\n\nunset\n\nLists build-time paths for a dynamic static route.\n\n`csrFallback`\n\n[`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child) `|` `(``context``)` `=>` [`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child)\n\nempty route node\n\nProvides meaningful server-shell content for a CSR route without executing its client loader.\n\n**CSR ignores static-only exports**\n\nOn a CSR route, Tavo.js ignores static, revalidate, vary, and generateStaticParams. A dynamic head function also runs only when the browser resolves the route, so it cannot change the initial response. The route manifest reports these combinations as diagnostics.\n\nLayout and page cache settings compose from root to leaf. Vary headers are trimmed, lowercased, and merged. Static cache tags are merged. If several layers provide numeric revalidation intervals, the shortest interval wins." }, { "id": "boot-and-hydration-reference", "title": "Boot and hydration reference", "markdown": "[](/docs/core/api/application#api-tavojs-core--boottavo \"View bootTavo in the Core API reference\")detects server, hydrated SSR, and browser-only documents. It returns a discriminated result so application entrypoints can inspect what actually started.\n\nAPI / option\n\nType\n\nDefault\n\nBehavior\n\n`root`\n\n`Element | null`\n\nunset\n\nUses a specific client mount element.\n\n`rootSelector`\n\n`string`\n\n\"#app\"\n\nLocates the client root when root is not provided.\n\n`hydrate`\n\n`boolean`\n\ndetected\n\nDefaults to true when \\_\\_`TAVO_SSR__` or \\_\\_`TAVO_STATE__` exists. A root marked `data-tavo-render-mode`\\=\"csr\" always renders instead.\n\n`serverFile`\n\n`string`\n\n\"server.mjs\"\n\nServer boot returns none when this file is absent.\n\n`modules / node.modules`\n\n`PageModules`\n\nrequired on server\n\nSupplies the server route module map. Missing modules throw `TAVO_PAGES_005`.\n\n[`getTavoBootMode`](/docs/core/api/application#api-tavojs-core--gettavobootmode)\n\n`() => \"server\" | \"ssr\" | \"csr\" | \"none\"`\n\n—\n\nReports the planned mode without starting the app.\n\n**Reference Reference snippet**\n\n```ts\nimport { bootTavo, getTavoBootMode } from \"@tavojs/core\";\n\nconsole.log(getTavoBootMode());\nconst result = await bootTavo();\n\nif (result.mode === \"client\") {\n // result.root exposes render, hydrate, and unmount.\n}\n```\n\n- A missing client root throws `TAVO_PAGES_002` and names the expected selector.\n \n- Hydration restores serialized page, layout, and store state instead of rerunning the initial loaders.\n \n- CSR boot resolves the initial loaders and same-origin redirects before mounting the route.\n \n- Initial redirect resolution stops after eight redirects and warns about a likely middleware loop." }, { "id": "server-rendering-methods", "title": "Server rendering methods", "markdown": "**Reference Reference snippet**\n\n```tsx\nimport {\n renderDocument,\n renderDocumentStream,\n} from \"@tavojs/core/server\";\n\nconst html = renderDocument(, {\n title: \"Dashboard\",\n initialState: { locale: \"en\" },\n});\n\nconst stream = renderDocumentStream(, {\n title: \"Dashboard\",\n});\n```\n\nAPI / option\n\nType\n\nDefault\n\nBehavior\n\n[`renderDocument`](/docs/core/api/server#api-tavojs-core-server--renderdocument)`(``node``,` `options``)`\n\n`string`\n\n—\n\nRenders the complete HTML document and serialized initial state.\n\n[`renderDocumentStream`](/docs/core/api/server#api-tavojs-core-server--renderdocumentstream)`(``node``,` `options``)`\n\n`ReadableStream`\n\n—\n\nStreams the shell followed by deferred patch chunks.\n\n[`createPagesRuntimeAsync`](/docs/core/api/server#api-tavojs-core-server--createpagesruntimeasync)`(``modules``,` `options``)`\n\n`Promise`\n\n—\n\nCreates the technical server runtime used by generated CLI SSR templates.\n\n[`renderPagesResponseFromRuntimeAsync`](/docs/core/api/server#api-tavojs-core-server--renderpagesresponsefromruntimeasync)`(``runtime``,` `pathname``,` `options``)`\n\n`Promise`\n\n—\n\nRenders a response from that server runtime. Import it only from `@tavojs/core/server`.\n\n**Use handlers for applications**\n\n[](/docs/core/api/server#api-tavojs-core-server--createnoderequesthandler \"View createNodeRequestHandler in the Core API reference\")adds actions, plugins, image optimization, security headers, static response caching, and contained HTTP failures. Low-level render functions are intended for custom Node integrations." }, { "id": "static-cache-contract", "title": "Static cache and invalidation contract", "markdown": "Tavo.js keeps a resolved route-data cache and a rendered-response cache. Both default to 1,024 process-local entries and evict the oldest entry when full. Set maxResolvedCacheEntries to 0 to disable route-data reuse, or provide a custom [`staticCache`](/docs/core/api/server#api-tavojs-core-server--ssrstaticcache \"View SsrStaticCache in the Core API reference\") for shared rendered output.\n\n- Cache keys include request origin, pathname, query string, and declared vary headers.\n \n- Localized routes also vary by Accept-Language automatically.\n \n- Requests with Cookie or Authorization bypass shared static response caching and do not evict an existing public entry.\n \n- Redirects and responses with status 500 or greater are not stored.\n \n- Concurrent public renders for the same cache key share one in-flight render.\n \n- Cache adapter read, write, and delete failures degrade to an uncached response instead of failing SSR.\n \n\n**Reference Reference snippet**\n\n```ts\nconst handler = createNodeRequestHandler({ modules, staticCache });\n\nawait handler.invalidateCache(\"post:hello\");\nawait handler.invalidateCache([\"posts\", \"homepage\"]);\nawait handler.clearCache();\n```\n\nFor process-local caching, use [](/docs/core/api/server#api-tavojs-core-server--creatememorystaticcache \"View createMemoryStaticCache in the Core API reference\"). A custom [](/docs/core/api/server#api-tavojs-core-server--ssrstaticcache \"View SsrStaticCache in the Core API reference\")adapter has the following complete contract, including optional tag invalidation and clearing:\n\n**Reference Reference snippet**\n\n```ts\nimport type {\n SsrStaticCache,\n SsrStaticCacheEntry,\n} from \"@tavojs/core/server\";\n\nexport function createInspectableStaticCache(): SsrStaticCache {\n const entries = new Map();\n\n return {\n get(key) {\n return entries.get(key) ?? null;\n },\n set(key, entry) {\n entries.set(key, entry);\n },\n delete(key) {\n entries.delete(key);\n },\n invalidateTags(tags) {\n const requested = new Set(tags);\n let deleted = 0;\n\n for (const [key, entry] of entries) {\n if (!entry.tags.some((tag) => requested.has(tag))) continue;\n entries.delete(key);\n deleted += 1;\n }\n\n return deleted;\n },\n clear() {\n entries.clear();\n },\n };\n}\n```\n\ninvalidateCache removes matching loader-resolution entries and rendered responses. clearCache clears both layers. A custom cache can implement invalidateTags and clear; otherwise the handler deletes the entries it has observed in the current process." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:rendering-head-and-hydration", "section": "core", "slug": "rendering-head-and-hydration", "title": "Rendering, head, and hydration", "description": "Choose SSR or CSR, compose escaped route metadata, understand head cleanup, and keep private values out of browser-readable hydration state.", "keywords": [ "SSR", "CSR", "head", "metadata", "hydration", "unsafeHeadHtml", "serialization" ], "kind": "reference", "prerequisites": [ "A route with functional page and layout modules.", "Understanding of server rendering and browser hydration." ], "outcomes": [ "Choose a rendering mode and predict where loaders and head functions run.", "Compose route metadata without introducing HTML injection.", "Audit every value serialized into the hydration document." ], "runtime": [ "server", "browser", "build" ], "related": [ { "title": "SSR and hydration", "href": "/docs/core/ssr-and-hydration", "description": "Configure the document and Node rendering pipeline." }, { "title": "SEO, assets, and styling", "href": "/docs/core/seo-assets-and-styling", "description": "Use Seo, Head, images, fonts, scripts, and styles." } ], "canonicalPath": "/docs/core/rendering-head-and-hydration", "sections": [ { "id": "render-mode", "title": "Treat SSR as the default", "markdown": "The route chain resolves to one [`PageRenderMode`](/docs/core/api/router#api-tavojs-core-router--pagerendermode \"View PageRenderMode in the Core API reference\"). Omitting the named render export selects SSR; only [`render`](/docs/core/api/components-and-dom#api-tavojs-core--render) `=` `\"csr\"` selects client-only route rendering.\n\nMode\n\nRoute declaration\n\nServer\n\nBrowser\n\nSSR\n\n`No render export`\n\nMiddleware, eligible loaders, head, layouts, and the page render for the request.\n\nThe same tree hydrates, then later navigation resolves in the browser.\n\nCSR\n\n`export const render = \"csr\"`\n\nTavo.js renders the configured CSR fallback and static head contributions only.\n\nThe route resolves and renders after client boot.\n\n- A CSR selection anywhere in the route module chain makes the resolved route CSR.\n \n- Static generation, revalidation, vary, cache tags, and static params are incompatible with CSR and are ignored with manifest diagnostics.\n \n- Use CSR only when the route cannot produce useful request HTML. Client interactivity does not require CSR; SSR pages hydrate into interactive components.\n \n- Dynamic head functions do not run on the server for CSR routes because route data is not resolved there." }, { "id": "head-contract", "title": "Return escaped TSX from head", "markdown": "A named head export returns [`PageHeadExport`](/docs/core/api/router#api-tavojs-core-router--pageheadexport \"View PageHeadExport in the Core API reference\"): escaped TSX for normal metadata or a [`PageHead`](/docs/core/api/router#api-tavojs-core-router--pagehead \"View PageHead in the Core API reference\") object for response status and document attributes.\n\n**Reference src/pages/projects/[id].tsx — named head export**\n\n```tsx\nimport { Seo } from \"@tavojs/core\";\n\ntype Project = {\n name: string;\n summary: string;\n};\n\nexport function head({\n data\n}: {\n data: Project | null;\n}) {\n const title = data ? `${data.name} · Projects` : \"Project\";\n return (\n <>\n {title}\n \n \n );\n}\n```\n\n- TSX children and attributes are escaped by the renderer. Prefer TSX and [`Seo`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--seo \"View Seo in the Core API reference\") for every normal metadata contribution.\n \n- The hard raw-string boundary is `unsafeHeadHtml` in a `PageHead` object or [`Head`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--head \"View Head in the Core API reference\") component. There is no raw head string alias.\n \n- `unsafeHeadHtml` is inserted without escaping. Never concatenate user, loader, request, database, translation, or CMS values into it unless a trusted sanitizer establishes the complete HTML policy.\n \n- head may also return title, status, `htmlAttributes`, and `bodyAttributes` in a `PageHead` object.\n \n\n**The unsafe name is the security review**\n\nTreat every [`PageHead`](/docs/core/api/router#api-tavojs-core-router--pagehead)`.``unsafeHeadHtml` occurrence like an HTML injection sink. Require a narrow owner, a documented sanitizer or trusted constant, and a test that prevents request data from reaching it." }, { "id": "head-precedence", "title": "Predict head precedence and browser cleanup", "markdown": "- [`Head`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--head \"View Head in the Core API reference\") contributions resolve from outer layouts to inner layouts, then the page.\n \n- A dynamic layout head receives that layout's own loader data and error. The page head receives page data and the page-loader error.\n \n- Later title, status, `htmlAttributes`, and `bodyAttributes` values win for the same field.\n \n- Managed [`Seo`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--seo \"View Seo in the Core API reference\") entries are deduplicated by their framework key with the later value winning. Unkeyed head nodes preserve contribution order.\n \n- On browser navigation, `Tavo.js` removes nodes owned by the previous route, applies the next route's nodes and attributes, and restores the document fallback title when the next route has no title.\n \n\n**Status belongs to the HTTP response**\n\nOn SSR, head.status becomes the route response status. Do not use a visual heading or client-only metadata update as a substitute for returning the correct server status." }, { "id": "hydration-exposure", "title": "Assume hydration state is public", "markdown": "SSR sends enough state for the browser to adopt the server-rendered tree. Anyone who receives the HTML can read this serialized state, including values that are not visibly rendered. Its ordered route data entries describe the resolved layout and page layers.\n\nState\n\nBrowser exposure\n\nPage data\n\nSerialized for the resolved page.\n\nlayers and layerData\n\nSerialized layout and page loader results, both ordered and keyed.\n\nStore snapshots\n\nSerialized when included in the document hydration state.\n\nPlugin state\n\nSerialized when a plugin contributes hydration state.\n\nErrors\n\nHydration error details are redacted to a generic internal-server message.\n\n- Return the minimum browser-safe shape from loaders. Keep tokens, session internals, credentials, private profile fields, and database records on the server.\n \n- Server-only execution does not make a returned loader value secret; SSR loader output can still be serialized.\n \n- Review nested layout data as carefully as page data because `layerData` exposes successful results by ID.\n \n- Redaction is a failure safeguard, not a reason to pass rich server exceptions into view props or custom error output." }, { "id": "hydration-failure", "title": "Keep the server and client trees compatible", "markdown": "- Render deterministic initial output from the same route data and serialized store state on both sides.\n \n- Move DOM reads, browser storage, timers, observers, and subscriptions into client lifecycle hooks.\n \n- Do not branch initial markup on `Date.now`(), `Math.random`(), locale defaults, viewport measurements, or undocumented globals.\n \n- A hydration mismatch is a correctness failure: fix the divergent input instead of suppressing the warning.\n \n- Clean up head ownership, controller work, and subscriptions when navigation replaces the route." }, { "id": "verification", "title": "Verify source HTML and hydrated behavior", "markdown": "**Run Terminal**\n\n```bash\nnpx tavo inspect route /projects/example --json\nnpx tavo build\nPORT=4174 node .tavo/build/server/start.mjs\n```\n\n- Inspect the raw document response to confirm SSR content, status, escaped metadata, and the absence of private values.\n \n- Inspect the live head before and after client navigation to confirm stale title, meta, html attributes, and body attributes are removed or replaced.\n \n- Hydrate with browser console errors treated as test failures.\n \n- Test a CSR route separately: the raw response should contain the chosen fallback and only static head contributions." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:static-output-and-cache", "section": "core", "slug": "static-output-and-cache", "title": "Static output and route cache", "description": "Use revalidated SSR, build-time parameter enumeration, vary keys, and cache tags while avoiding unresolved permanent-cache behavior.", "keywords": [ "prerender", "revalidate", "cache", "generateStaticParams", "vary", "cacheTags", "ISR" ], "kind": "reference", "prerequisites": [ "An SSR route whose output is safe to share between requests.", "A deployment that serves Tavo.js's generated client and Node output." ], "outcomes": [ "Enable cached SSR with the minimum non-redundant declaration.", "Enumerate dynamic paths and compose inherited cache policy.", "Verify cache headers, variation, privacy bypasses, and tags." ], "runtime": [ "build", "server" ], "related": [ { "title": "SSR and hydration", "href": "/docs/core/ssr-and-hydration", "description": "Understand the server-rendered response being cached." }, { "title": "Deployment", "href": "/docs/core/deployment", "description": "Serve the canonical client and Node build outputs." } ], "canonicalPath": "/docs/core/static-output-and-cache", "sections": [ { "id": "choose-policy", "title": "Choose one settled cache policy", "markdown": "**Reference src/pages/catalog.tsx**\n\n```tsx\nexport const revalidate = 300;\nexport const cacheTags = [\"catalog\"];\n\nexport default function CatalogPage() {\n return
    Catalog
    ;\n}\n```\n\nIntent\n\nFunctional module\n\n[`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\")\n\nBehavior\n\nCached SSR with regeneration\n\n`export const revalidate = 300`\n\n`revalidate: 300`\n\nNumeric revalidate automatically enables static caching.\n\nBuild-time static HTML without revalidation\n\n`export const prerender = true`\n\n`static: true`\n\nUse one form only; see the permanent-cache contract note below.\n\nDisable inherited static policy\n\n`export const revalidate = false`\n\n`revalidate: false`\n\nResets inherited static and revalidation policy.\n\n**Do not combine redundant static declarations**\n\nA numeric revalidate already enables cached SSR, so prerender = true is redundant. In [`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\"), static: true is the helper equivalent of the named prerender export. A route that declares both static and prerender forms is rejected." }, { "id": "revalidated-route", "title": "Declare revalidated dynamic output", "markdown": "For a dynamic cached route, `generateStaticParams()` returns [`PageStaticParams`](/docs/core/api/router#api-tavojs-core-router--pagestaticparams \"View PageStaticParams in the Core API reference\") for the paths the build should materialize. The loader and cache-tag resolver receive [`PageLoadContext`](/docs/core/api/router#api-tavojs-core-router--pageloadcontext \"View PageLoadContext in the Core API reference\").\n\n**Reference src/pages/catalog/[id].tsx**\n\n```tsx\nimport type {\n PageLoadContext,\n PageProps\n} from \"@tavojs/core/router\";\nimport { Page, Text } from \"@tavojs/ui\";\n\ntype Product = { id: string; name: string };\ntype ProductParams = { id: string };\n\nexport const revalidate = 300;\nexport const vary = \"accept-language\";\n\nexport function cacheTags({\n params\n}: PageLoadContext): string[] {\n return [\"catalog\", `product:${params.id}`];\n}\n\nexport function generateStaticParams(): ProductParams[] {\n return [{ id: \"starter\" }, { id: \"team\" }];\n}\n\nexport async function load({\n params,\n signal,\n url\n}: PageLoadContext): Promise {\n const response = await fetch(\n new URL(`/api/catalog/${params.id}`, url),\n { signal }\n );\n if (!response.ok) {\n throw new Error(\"Could not load product\");\n }\n return response.json() as Promise;\n}\n\nexport default function ProductPage({\n data\n}: PageProps) {\n return (\n \n \n {data?.name}\n \n \n );\n}\n```\n\n- `generateStaticParams` returns parameter records for dynamic paths the build must enumerate. Every record must provide values expected by that route pattern.\n \n- A numeric revalidate is measured in seconds, rounded down, and clamped to zero.\n \n- Static policy composes through the route chain. The shortest finite revalidate value wins.\n \n- vary names are lowercased and deduplicated. Localization also adds Accept-Language variation.\n \n- CSR routes ignore static policy and static params with a manifest diagnostic." }, { "id": "http-cache", "title": "Understand Node cache behavior", "markdown": "Inspection exposes the composed [`PageCachePolicy`](/docs/core/api/router#api-tavojs-core-router--pagecachepolicy \"View PageCachePolicy in the Core API reference\"). Each static or request-aware tag declaration follows [`PageCacheTags`](/docs/core/api/router#api-tavojs-core-router--pagecachetags \"View PageCacheTags in the Core API reference\").\n\n- A successful route with numeric revalidate emits Cache-Control: public, max-age=0, s-maxage=N.\n \n- `Tavo.js` uses the static cache only for responses eligible under the composed route policy.\n \n- Non-200 responses, resolved route errors, and requests with personal headers do not receive shared static cache headers.\n \n- Vary values must cover every request header that can change shared output. Missing variation can serve one user's representation to another.\n \n- Cache tags support targeted invalidation where the selected runtime exposes it. Attach tags to the page or documented directory layouts.\n \n\n**Root cache tags are not yet a settled contract**\n\nCurrent manifest composition does not reliably carry cacheTags from \\_root into route policy. Do not depend on root-level tags; place them on a documented layout or page and verify the inspected route until Core closes this gap." }, { "id": "permanent-cache-status", "title": "Keep permanent static caching behind verification", "markdown": "The public intent of both prerender = true and static: true in [`defineRoutePage`](/docs/core/api/router#api-tavojs-core-router--defineroutepage \"View defineRoutePage in the Core API reference\") is build-time static HTML without revalidation. Current Core also gives a non-revalidated static route a long-lived immutable runtime cache response. That permanent runtime behavior is still under contract review.\n\n- Use numeric revalidate when the Node runtime must refresh content; its cache behavior is explicit and settled.\n \n- Use prerender or helper static only when build-time output is the intended source and the deployed asset/cache layer has been verified.\n \n- Do not document the current immutable Node response as a permanent application guarantee until Core resolves the contract.\n \n- A change to this behavior may require a Core migration note even if the authored route export stays the same." }, { "id": "privacy-and-failure", "title": "Cache only shareable successful output", "markdown": "- Do not statically cache a route whose output depends on a session, authorization decision, private cookie, or user-specific request header.\n \n- A cache tag identifies related entries; it does not make private output safe to share.\n \n- Return the correct non-200 status for failures and not-found output so they are not mistaken for a successful reusable document.\n \n- Keep cache keys and tags bounded. Never place secret values in either one because operational tooling may expose them.\n \n- When variation or privacy is uncertain, prefer uncached SSR and add caching only after request-level tests prove isolation." }, { "id": "verification", "title": "Inspect generation and response headers", "markdown": "**Run Terminal**\n\n```bash\nnpx tavo inspect route /catalog/starter --json\nnpx tavo build\nPORT=4174 node .tavo/build/server/start.mjs\ncurl -i http://127.0.0.1:4174/catalog/starter\n```\n\n- Confirm the inspected route has the expected static, revalidate, vary, and tag policy.\n \n- Confirm every generated dynamic parameter produces output at the intended path.\n \n- Assert Cache-Control and Vary for a successful anonymous request.\n \n- Repeat with the deployment's personal headers and failure cases and confirm shared cache headers are absent.\n \n- Exercise tag invalidation only through a runtime that explicitly exposes and documents it." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:streaming-and-async", "section": "core", "slug": "streaming-and-async", "title": "Streaming and async work", "description": "Deliver the route shell first, defer secondary server content, and give every async operation an owner.", "keywords": [ "deferred", "async", "streaming", "cancellation" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Deliver the route shell first, defer secondary server content, and give every async operation an owner." ], "runtime": [ "server" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/streaming-and-async", "sections": [ { "id": "what-to-defer", "title": "Defer secondary content", "markdown": "Route loaders should resolve data required for navigation, SEO, and the primary shell. [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") boundaries are for slower, optional server content such as analytics summaries, recommendations, or below-the-fold panels.\n\n**SSR-only progression**\n\nPromise-backed Deferred boundaries progressively patch an SSR stream. For browser-only async work, use route loaders, resources, controllers, or stores." }, { "id": "deferred-boundary", "title": "Create a meaningful boundary", "markdown": "Give each boundary a stable ID, a lightweight fallback, and timeout behavior when the content is optional. Create the deferred value inside request-owned rendering work. A value created at module scope would be shared by every SSR request handled by that process.\n\n**Create src/components/Stats.tsx — create this component**\n\n```tsx\nimport { Deferred, createDeferredValue } from \"@tavojs/core\";\nimport { Card, Skeleton, Text } from \"@tavojs/ui\";\n\nasync function loadStats(): Promise<{ total: number }> {\n await new Promise((resolve) => setTimeout(resolve, 250));\n return { total: 12 };\n}\n\nexport function Stats() {\n const stats = createDeferredValue(loadStats(), {\n id: \"dashboard-stats\",\n timeoutMs: 1500\n });\n\n return }>\n {(value) => {value.total} active projects}\n ;\n}\n```" }, { "id": "cancellation", "title": "Give work an owner", "markdown": "Navigation owns loaders and middleware, a resource owns its current load, and deferred work belongs to its signal or render lifecycle. Pass `AbortSignal` through every supported layer and never publish results after the owner is gone.\n\n- Treat `AbortError` as control flow, not a user-facing failure.\n \n- Use transactions or idempotency keys for side effects; cancellation cannot undo a committed mutation.\n \n- Set timeouts for optional remote dependencies that should not hold a stream open." }, { "id": "deferred-api-reference", "title": "Deferred API reference", "markdown": "**Reference Reference snippet**\n\n```tsx\nimport {\n createDeferredValue,\n Deferred,\n} from \"@tavojs/core\";\n\nconst recommendations = createDeferredValue(loadRecommendations(), {\n id: \"recommendations\",\n timeoutMs: 1500,\n});\n\nexport function Recommendations() {\n return (\n Loading recommendations…

    }\n errorFallback={

    Recommendations are unavailable.

    }\n >\n {(items) => }\n \n );\n}\n```\n\nAPI / option\n\nType\n\nDefault\n\nBehavior\n\n`value`\n\n`T` `|` `Promise``<``T``>` `|` [`DeferredValue`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferredvalue)`<``T``>`\n\nrequired\n\nThe immediate or deferred value rendered by the boundary.\n\n`fallback`\n\n[`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child)\n\nnull\n\nInitial SSR and pending content.\n\n`errorFallback`\n\n[`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child) `|` `(``error``)` `=>` [`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child)\n\nfallback\n\nReplaces the boundary when the promise rejects.\n\n`timeoutFallback`\n\n[`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child) `|` `(``error``)` `=>` [`Child`](/docs/core/api/components-and-dom#api-tavojs-core--child)\n\nerrorFallback\n\nUsed specifically for `TAVO_DEFERRED_TIMEOUT`.\n\n`id`\n\n`string`\n\ngenerated\n\nStable sharing and hydration key. Reusing an ID coordinates one promise across boundaries.\n\n`timeoutMs`\n\n`number`\n\ndisabled\n\nPositive finite timeout in milliseconds; other values do not create a timer.\n\n`signal`\n\n`AbortSignal`\n\nunset\n\nRejects pending work with the signal reason or `AbortError`.\n\n`serialize / deserialize`\n\n`functions`\n\nidentity\n\nControls the value stored in and restored from the hydration registry.\n\n**Value options take precedence**\n\nOptions stored by createDeferredValue take precedence over the same props on Deferred. This lets a shared async unit own its ID, serialization, timeout, fallback, and signal once." }, { "id": "streaming-behavior-matrix", "title": "SSR, CSR, and hydration behavior", "markdown": "API / option\n\nType\n\nDefault\n\nBehavior\n\n`SSR` `string` [`render`](/docs/core/api/components-and-dom#api-tavojs-core--render)\n\n`HTML string`\n\nfallback\n\nPromise-backed boundaries render fallback content synchronously.\n\n`SSR stream`\n\n`HTML chunks`\n\nstream: false\n\nWith streaming enabled, fallback arrives first and patch scripts follow as work settles.\n\n`CSR`\n\n`DOM` [`render`](/docs/core/api/components-and-dom#api-tavojs-core--render)\n\nfallback\n\nPromise-backed [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") does not coordinate browser data loading; use loaders, resources, controllers, or stores.\n\n`Hydration`\n\n`DOM hydrate`\n\nreuse server state\n\nResolved, rejected, and timed-out streamed state is reused without restarting the client promise.\n\nA timeout rejects with code TAVO\\_DEFERRED\\_TIMEOUT plus id, timeoutMs, and a safe message. Other rejections are serialized as a generic failure string; application error objects are not copied into the client document." }, { "id": "production-streaming", "title": "Production streaming contract", "markdown": "**Reference Reference snippet**\n\n```ts\ncreateNodeRequestHandler({\n modules,\n stream: true,\n document: { nonce: requestNonce }\n});\n```\n\n- Streaming is disabled unless stream: true is passed to the handler.\n \n- [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") patch scripts and serialized state receive `document.nonce` for a strict Content Security Policy.\n \n- The Node handler waits for drain when response backpressure is signaled.\n \n- A disconnected Node request aborts route work and cancels the stream reader.\n \n- Redirects are returned as a complete one-chunk document with Location metadata.\n \n- Use timeouts for optional dependencies so one remote service cannot hold the response open indefinitely." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:errors-and-code-splitting", "section": "core", "slug": "errors-and-code-splitting", "title": "Errors and code splitting", "description": "Recover from component render failures, load component code on demand, and choose ErrorBoundary, lazy, or Deferred correctly.", "keywords": [ "ErrorBoundary", "lazy", "code splitting", "fallback", "resetKey", "Deferred" ], "kind": "guide", "prerequisites": [ "A component subtree that may fail while rendering or load code asynchronously." ], "outcomes": [ "Catch descendant render errors with an explicit recovery boundary.", "Load a component implementation lazily in browser and server workflows.", "Choose code loading separately from data streaming." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Streaming and async work", "href": "/docs/core/streaming-and-async", "description": "Stream promise-backed values with Deferred and progressive SSR." }, { "title": "Pages and layouts", "href": "/docs/core/pages-and-layouts", "description": "Handle route-loader failures with page error exports and _error.tsx." }, { "title": "Testing and diagnostics", "href": "/docs/core/testing-and-diagnostics", "description": "Capture runtime failures and hydration diagnostics." } ], "canonicalPath": "/docs/core/errors-and-code-splitting", "sections": [ { "id": "choose-boundary", "title": "Choose the boundary by what is pending", "markdown": "- Use a page error export for a contextual route-loader failure.\n \n- Use [`ErrorBoundary`](/docs/core/api/errors-and-code-splitting#api-tavojs-core--errorboundary \"View ErrorBoundary in the Core API reference\") for a descendant component that throws while rendering.\n \n- Use [`lazy`](/docs/core/api/errors-and-code-splitting#api-tavojs-core--lazy \"View lazy in the Core API reference\") when the component implementation should come from a dynamic import.\n \n- Use [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") or [`createDeferredValue`](/docs/core/api/data-actions-and-async#api-tavojs-core--createdeferredvalue \"View createDeferredValue in the Core API reference\") when a promise-backed data value should render fallback UI and participate in progressive SSR.\n \n- `Tavo.js` does not publish a Suspense component. Use the primitive that owns the actual failure or asynchronous work." }, { "id": "error-boundary", "title": "Recover from descendant render errors", "markdown": "[`ErrorBoundary`](/docs/core/api/errors-and-code-splitting#api-tavojs-core--errorboundary \"View ErrorBoundary in the Core API reference\") renders its children until a descendant render throws. It then renders a static fallback or calls a fallback function with the error. Static and progressive server rendering apply the same fallback contract.\n\n- Changing `resetKey` under `Object.is` clears a captured client error and retries the current children.\n \n- Changing `resetKey` does not fix the underlying state and does not reset an unrelated lazy-loader cache.\n \n- If rendering the fallback also fails, the error continues to the parent boundary or runtime error reporting.\n \n- A boundary is not a replacement for route error exports, rejected action state, or expected form validation.\n \n- Fallback UI should be accessible, concise, and offer only recovery that can actually change the failing condition.\n \n\n**Reference src/components/ProjectSummary.tsx**\n\n```tsx\nimport { ErrorBoundary } from \"@tavojs/core\";\n\nfunction ProjectSummary({\n project,\n}: {\n project: { name: string } | null;\n}) {\n if (!project) {\n throw new Error(\"Project data is unavailable.\");\n }\n\n return

    {project.name}

    ;\n}\n\nexport function ProjectPanel({\n project,\n version,\n}: {\n project: { name: string } | null;\n version: number;\n}) {\n return (\n {\n const message =\n error instanceof Error ? error.message : \"Project failed to render.\";\n\n return

    {message}

    ;\n }}\n >\n \n \n );\n}\n```" }, { "id": "lazy-components", "title": "Load component code on demand", "markdown": "[`lazy`](/docs/core/api/errors-and-code-splitting#api-tavojs-core--lazy \"View lazy in the Core API reference\") accepts a loader that resolves either a component or a module with a default component. Browser rendering starts one shared pending load, shows fallback UI, and rerenders mounted subscribers when the loader settles.\n\n- fallback receives idle or loading. `errorFallback` receives error status and the caught loader error.\n \n- If `errorFallback` is omitted, a failed load is thrown during the next render so the nearest `ErrorBoundary` can capture it.\n \n- preload deduplicates the active load and resolves to the loaded component. `getStatus` reports idle, loading, loaded, or error.\n \n- Synchronous SSR does not start the loader; it renders fallback. Call preload before rendering when loaded server output is required.\n \n- A successful load is cached on that lazy component definition. A failed definition stays in error state; create a new definition or reload the owning module for a real retry.\n \n\n**Reference src/pages/reports.tsx**\n\n```tsx\nimport { lazy } from \"@tavojs/core\";\nimport type { PageProps } from \"@tavojs/core/router\";\n\ntype ReportsData = {\n points: number[];\n};\n\nconst ReportsChart = lazy(\n () => import(\"../components/ReportsChart\"),\n {\n fallback: ({ status }) => {\n return

    Chart {status}…

    ;\n },\n errorFallback: ({ error }) => {\n const message =\n error instanceof Error ? error.message : \"Chart code failed to load.\";\n\n return

    {message}

    ;\n },\n },\n);\n\nexport async function load(): Promise {\n return { points: [12, 18, 25] };\n}\n\nexport default function ReportsPage({\n data,\n}: PageProps) {\n return (\n
    \n

    Reports

    \n \n
    \n );\n}\n```\n\n**Code loading and data loading are separate**\n\nlazy loads a component implementation. Keep route-critical data in load, independently refreshable component data in createResource, and streamed server data in Deferred." }, { "id": "preload-for-ssr", "title": "Preload only when the server needs loaded output", "markdown": "- Call preload from an explicit server preparation path before render, not from the component render function.\n \n- When fallback HTML is acceptable, let SSR render it and allow the browser to start loading after hydration.\n \n- Preloading changes code availability, not [`Deferred`](/docs/core/api/data-actions-and-async#api-tavojs-core--deferred \"View Deferred in the Core API reference\") data state or route-loader caching.\n \n\n**Reference Reference snippet**\n\n```tsx\nconst InvoicePreview = lazy(\n () => import(\"../components/InvoicePreview\"),\n);\n\nexport async function prepareInvoicePreview() {\n await InvoicePreview.preload();\n}\n\nexport function InvoiceSection() {\n return ;\n}\n```" }, { "id": "failure-verification", "title": "Verify every state and recovery path", "markdown": "- Render a throwing child on the server and in the browser; assert the boundary fallback receives the error.\n \n- Change `resetKey` with corrected child inputs and confirm the subtree renders again.\n \n- Hold a lazy loader pending and assert both idle/loading fallback behavior and final replacement.\n \n- Reject a lazy loader with and without `errorFallback`; verify the local fallback or parent `ErrorBoundary` owns the error.\n \n- Render lazy synchronously during SSR to confirm the loader is not called, then preload and confirm loaded output." }, { "id": "exact-api-reference", "title": "Look up exact public types", "markdown": "**Public API names are navigable**\n\nLinked API names throughout this guide open the canonical Core declaration with its complete signature, runtime boundary, stability, import path, and owning guide.\n\n[Browse every public Core symbol](/docs/core/api)" } ], "sourceId": "tavo-website" }, { "id": "core:seo-assets-and-styling", "section": "core", "slug": "seo-assets-and-styling", "title": "SEO, assets, and styling", "description": "Own route metadata, optimized media, fonts, scripts, and component styling without losing SSR safety.", "keywords": [ "seo", "image", "font", "css" ], "kind": "guide", "prerequisites": [ "A Tavo.js project with dependencies installed." ], "outcomes": [ "Own route metadata, optimized media, fonts, scripts, and component styling without losing SSR safety." ], "runtime": [ "browser", "server", "build" ], "related": [ { "title": "Tavo.js glossary", "href": "/docs/core/glossary", "description": "Look up framework-specific terminology." }, { "title": "Core API reference", "href": "/docs/core/api", "description": "Inspect public package entry points and exports." } ], "canonicalPath": "/docs/core/seo-assets-and-styling", "sections": [ { "id": "metadata", "title": "Put metadata next to the route", "markdown": "Use a page head export when metadata belongs to one route. Use [`Seo`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--seo \"View Seo in the Core API reference\") for structured title, description, canonical URL, robots, Open Graph, Twitter, and theme-color values. Dynamic head functions can read route params and loader data.\n\n**Merge src/pages/dashboard/index.tsx — merge this head export**\n\n```tsx\nimport { Seo } from \"@tavojs/core\";\n\nexport const head = ;\n```" }, { "id": "assets", "title": "Use framework asset components", "markdown": "[`Image`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--image \"View Image in the Core API reference\") provides one API for CSR assets and optional SSR optimization. Optimized remote images require an explicit HTTPS host allowlist; local assets must remain inside the public directory.\n\n- Install the optional sharp dependency only when the server performs image optimization.\n \n- Mark only above-the-fold images as priority.\n \n- Use the ?component query when an SVG should render inline and accept component props.\n \n- Use [`Font`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--font \"View Font in the Core API reference\") and [`Script`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--script \"View Script in the Core API reference\") when loading behavior and document placement matter." }, { "id": "styling", "title": "Keep styling boundaries clear", "markdown": "Use CSS modules or `Tavo.js` UI component props for ordinary local presentation. The lower-level style registry is for libraries that must register deduplicated CSS during both SSR and browser rendering.\n\n- Call style(id, css) while an SSR registry is active; repeated IDs are emitted once.\n \n- Use `ensureClientStyle`(id, css) when a browser-only integration must install one managed style element.\n \n- Keep IDs stable across server and browser rendering so hydration does not duplicate CSS.\n \n\n**Reference src/server/render-badge.tsx**\n\n```tsx\nimport {\n createStyleRegistry,\n renderStyleTags,\n renderToString,\n style,\n withStyleRegistry,\n} from \"@tavojs/core\";\n\nfunction StatusBadge({ label }: { label: string }) {\n style(\n \"status-badge\",\n \".status-badge{border-radius:999px;padding:.25rem .5rem}\"\n );\n return {label};\n}\n\nconst registry = createStyleRegistry();\nconst body = withStyleRegistry(registry, () => {\n return renderToString();\n});\n\nconst styles = renderStyleTags(registry);\nconst html = `${styles}${body}`;\n```\n\n**Prefer application-level styling**\n\nDo not build a parallel styling system for ordinary pages. Use this registry only when reusable framework-level code needs SSR collection and client deduplication." }, { "id": "head-seo-reference", "title": "Head and SEO properties", "markdown": "- Use the route head export for route-owned metadata and [`Head`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--head \"View Head in the Core API reference\") for component-owned insertion. Raw HTML is accepted only through `unsafeHeadHtml`; there is no head string alias.\n \n- An explicit robots string takes precedence over `noIndex` and `noFollow`. Arrays of keywords become a comma-separated meta value.\n \n- SEO title, description, canonical, and Open Graph image provide fallbacks for corresponding Open Graph and Twitter fields.\n \n- `unsafeHeadHtml` is not escaped. Never place user-controlled data in it.\n \n\n**Reference Reference snippet**\n\n```ts\ntype PageHead = {\n title?: string;\n unsafeHeadHtml?: string;\n status?: number;\n htmlAttributes?: Record;\n bodyAttributes?: Record;\n};\n\ntype HeadProps = {\n title?: string;\n unsafeHeadHtml?: string;\n children?: Child;\n};\n\ntype SeoProps = {\n title?: string; description?: string; canonical?: string;\n robots?: string; noIndex?: boolean; noFollow?: boolean;\n keywords?: string | string[]; author?: string; themeColor?: string;\n openGraph?: SeoOpenGraph; twitter?: SeoTwitter;\n};\n```" }, { "id": "image-reference", "title": "Image properties and optimizer defaults", "markdown": "- Default candidate widths are 320, 640, 960, 1280, and 1600. A supplied width also adds its 2x candidate; values above 3840 or at most zero are removed.\n \n- Quality defaults to 75 and is rounded and clamped from 1 to 100. Format defaults to webp and generated sizes defaults to 100vw.\n \n- priority selects eager loading and high fetch priority. Other images default to lazy loading; decoding defaults to async.\n \n- Set unoptimized to keep the original URL. Remote optimization requires an HTTPS allowlist; local sources must stay inside `publicDir`.\n \n\n**Reference Reference snippet**\n\n```tsx\n\n```\n\n**Remote images are untrusted input**\n\nThe optimizer rejects private hosts, revalidates redirects, and applies file limits. Keep remote patterns exact and do not enable insecure remote fetching without a controlled network boundary." }, { "id": "font-script-reference", "title": "Font and Script properties", "markdown": "- [`Font`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--font \"View Font in the Core API reference\") uses href for an external stylesheet or src plus family for a self-hosted @font-face. Self-hosted fonts preload by default; external stylesheet preload is opt-in.\n \n- Self-hosted format is inferred from woff2, woff, ttf, or otf when type is omitted. `crossOrigin` defaults to anonymous for font preloads.\n \n- [`Font`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--font \"View Font in the Core API reference\") variable must be a CSS custom property name. fallback is appended to the generated variable value.\n \n- [`Script`](/docs/core/api/localization-seo-and-assets#api-tavojs-core--script \"View Script in the Core API reference\") supports src, type, async, defer, module, `noModule`, preload, content, json, id, nonce, integrity, `crossOrigin`, `referrerPolicy`, and `fetchPriority`.\n \n- A json value without src defaults to application/ld+json. Inline content escapes less-than signs and closing script sequences.\n \n\n**Reference Reference snippet**\n\n```tsx\n\n\n\n\n