This file is Pitlane's documentation, every page as Markdown: the home page, then every page in the order [llms.txt](https://pitlane.tools/llms.txt) lists it.

Each page begins with its title as a level-one heading (`# Title`), then, after a blank line, `Source: ` and the address of the page's own Markdown, then its description as a quote. A page runs until the next level-one heading; none appears anywhere else outside code blocks.

# Pitlane

Source: https://pitlane.tools/index.md

> Pitlane gives you composable packages to help you put your Remix app on the grid.

Start with [Pitlane guides](https://pitlane.tools/guides.md).

## Packages

### @pitlane/vite-plugin-remix: Build & develop

Development, server, and browser builds, all in one Vite plugin.

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix()],
});
```

Guide: [Using the Vite plugin](https://pitlane.tools/guides/vite-plugin.md) · Reference: [@pitlane/vite-plugin-remix](https://pitlane.tools/package/vite-plugin-remix/index.md)

### @pitlane/content: Load & validate

Your files become typed, queryable collections.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";

export let content = createContent(c => ({
    posts: c.collection({
        loader: loaders.glob({
            base: "app/posts",
            pattern: "**/*.md",
        }),
        schema: s.object({ title: s.string() }),
    }),
}));
```

Guide: [Content](https://pitlane.tools/guides/content.md) · Reference: [@pitlane/content](https://pitlane.tools/package/content/index.md)

### @pitlane/theme: Style & compose

Typed design tokens. Native Remix styling.

```ts title="app/theme.ts"
import { createTheme } from "pitlane/theme";
import * as s from "pitlane/theme/schema";

export let { token: t, Theme } = createTheme({
    schema: {
        color: s.color(),
        spacing: s.scale(),
    },
    tokens: {
        color: { brand: "#eb2027" },
        spacing: "0.25rem",
    },
});
```

Guide: [Theme](https://pitlane.tools/guides/theme.md) · Reference: [@pitlane/theme](https://pitlane.tools/package/theme/index.md)

### @pitlane/crawler: Crawl & prerender

Follow your app’s links without starting an HTTP server.

```ts title="scripts/crawl.ts"
import { crawl } from "pitlane/crawler";
import router from "../app/entry.server.ts";

for await (let { pathname, response } of crawl(router)) {
    console.log(pathname, response.status);
}
```

Guide: [Crawler](https://pitlane.tools/guides/crawler.md) · Reference: [@pitlane/crawler](https://pitlane.tools/package/crawler/index.md)

### @pitlane/data-table-d1: Connect your data

Remix’s database API, backed by your Cloudflare D1 binding.

```ts title="app/database.ts"
import { createD1Database } from "pitlane/data-table-d1";
import { env } from "cloudflare:workers";

export let db = createD1Database(env.DB);
```

Guide: [Cloudflare D1](https://pitlane.tools/guides/cloudflare-d1.md) · Reference: [@pitlane/data-table-d1](https://pitlane.tools/package/data-table-d1/index.md)

## Deployment

- [Cloudflare](https://pitlane.tools/deploy/cloudflare.md): workerd
- [Netlify](https://pitlane.tools/deploy/netlify.md): Node.js
- [Vercel](https://pitlane.tools/deploy/vercel.md): Node.js
- [Railway](https://pitlane.tools/deploy/railway.md): Node.js, Bun, or Deno
- [Deno Deploy](https://pitlane.tools/deploy/deno-deploy.md): Deno
- [GitHub Pages](https://pitlane.tools/deploy/github-pages.md): Browser

## Start from a template

```sh
vpx giget github:pitlane-tools/templates/cloudflare my-app
```

# Pitlane guides

Source: https://pitlane.tools/guides.md

> An introduction to Pitlane, a composable toolkit for Remix 3, with guides for each task.

Pitlane is a composable toolkit for [Remix 3](https://remix.run). Its Vite plugin runs the dev server and builds the app for its host. Additional packages resolve built assets and handle content and styling, with a Cloudflare D1 driver and an in-memory crawler available separately.

Remix owns routing and UI. Pitlane's packages compose with its APIs: content collections validate with `remix/data-schema`, and the D1 driver plugs into `remix/data-table`.

These guides explain how each piece behaves and when to reach for it. The [API reference](https://pitlane.tools/package/vite-plugin-remix/index.md) documents every export separately.

## Guides

### Build and develop

- [Using the Vite plugin](https://pitlane.tools/guides/vite-plugin.md)

    What `remix()` does in dev, preview, and the build, including the `clientEntry()` transform.

- [Hot module replacement](https://pitlane.tools/guides/hmr.md)

    Component state across edits and server-data revalidation through the frame runtime.

- [Single-page apps](https://pitlane.tools/guides/spa.md)

    A client-rendered app with `remix({ server: false })`, and what the plugin still does without a server.

- [Prerendering](https://pitlane.tools/guides/prerendering.md)

    Rendering paths to static HTML during `vite build`, and where those paths come from.

- [Fetch server](https://pitlane.tools/guides/fetch-server.md)

    Serving a `fetch` handler through Vite's dev server with `fetchServer()`.

### Assets

- [Asset resolution](https://pitlane.tools/guides/assets.md)

    Script entries, stylesheets, and preloads from `createAssetResolver()`, with or without Remix.

- [Manifest integrations](https://pitlane.tools/guides/asset-build.md)

    Turning another bundler's output into an asset manifest with `createAssetManifest()`.

### Deploy

- [Cloudflare Workers](https://pitlane.tools/deploy/cloudflare.md)

    Local development with workerd and deployment through Wrangler.

- [Netlify](https://pitlane.tools/deploy/netlify.md)

    A one-file Netlify Function around the built fetch handler.

- [Vercel](https://pitlane.tools/deploy/vercel.md)

    Deploying server functions through Nitro.

- [Railway](https://pitlane.tools/deploy/railway.md)

    Container deployment with a choice of runtime.

- [Deno Deploy](https://pitlane.tools/deploy/deno-deploy.md)

    The fetch handler behind a short `Deno.serve` entrypoint.

- [GitHub Pages](https://pitlane.tools/deploy/github-pages.md)

    A single-page app or a fully prerendered site, with the base path a project site needs.

### Content and styling

- [Content](https://pitlane.tools/guides/content.md)

    Querying schema-validated collections of Markdown, MDX, JSON, or YAML.

- [Theme](https://pitlane.tools/guides/theme.md)

    Typed design tokens for styling with `css()` mixins.

### Crawling

- [Crawler](https://pitlane.tools/guides/crawler.md)

    Walking the app's router in memory for sitemaps and link checks.

### Data

- [Cloudflare D1](https://pitlane.tools/guides/cloudflare-d1.md)

    Running `remix/data-table` on a D1 binding, and the D1 limits the driver cannot hide.

Content, prerendering, and the Railway and Deno Deploy guides also cover apps that run straight from source with no build step. Their pages switch between the Vite and No Build versions.

## Start a new app

The [starter templates](https://github.com/pitlane-tools/templates) are one guest book app, wired once for each deploy target. Scaffold the Cloudflare one with [giget](https://github.com/unjs/giget):

```sh
npx giget github:pitlane-tools/templates/cloudflare my-app
```

The repository names the other targets, and the [deploy guides](#deploy) cover each one.

## Add Pitlane to a Remix app

Install the `pitlane` package. It needs `remix` 3 and `vite` 8.1 or later as peer dependencies.

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Then add the Vite plugin from `pitlane/vite-plugin-remix` to `vite.config.ts`:

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix()],
});
```

[Using the Vite plugin](https://pitlane.tools/guides/vite-plugin.md#the-three-file-core) shows the server and browser entry files the plugin expects, and what changes between dev, preview, and the build.

### Imports

`pitlane` installs every Pitlane package and re-exports each one under a subpath named after it: `@pitlane/vite-plugin-remix` becomes `pitlane/vite-plugin-remix`, and `@pitlane/theme/schema` becomes `pitlane/theme/schema`. Bare `pitlane` has no exports, so every import names a subpath.

Each package also installs on its own under its `@pitlane/*` name. That route suits an app that uses one package or needs a release newer than the one `pitlane` pins. [Installing Pitlane](https://pitlane.tools/guides/umbrella.md) compares the installs and explains the version pins, with a full subpath reference.

## For coding agents

`pitlane` releases after `1.0.0-alpha.1` install these guides with the package, so an agent working in an app can read the version the app depends on. [Documentation for coding agents](https://pitlane.tools/guides/umbrella.md#documentation-for-coding-agents) explains where the files are and how to point an agent at them.

# Installing Pitlane

Source: https://pitlane.tools/guides/umbrella.md

> Install every Pitlane package with one dependency, import each through a pitlane/* subpath, and decide when the scoped @pitlane/* packages fit better.

`pitlane` is one install for all seven Pitlane packages. Each package is published on its own under `@pitlane/*`, and `pitlane` re-exports every one of them through focused subpaths, the way `remix` re-exports the `@remix-run/*` packages:

```ts
import { remix } from "pitlane/vite-plugin-remix";
import { createAssetResolver } from "pitlane/assets";
import { createTheme } from "pitlane/theme";
```

A subpath has the same exports as the package it re-exports, so every API page under [`@pitlane/vite-plugin-remix`](https://pitlane.tools/package/vite-plugin-remix/index.md), [`@pitlane/assets`](https://pitlane.tools/package/assets/index.md), and the rest applies to the matching `pitlane/*` import unchanged. The scoped packages stay independently usable. An app that wants only one of them can install it alone.

## Install

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

`pitlane` declares three peer dependencies, lifted from the packages it installs:

| Peer | Range | Required |
| --- | --- | --- |
| `remix` | `^3.0.0` | Yes |
| `vite` | `>=8.1.0` | Yes |
| `satteri` | `^0.10.5` | Only when a content collection holds `.md` or `.mdx` files |

Install `pitlane` as a dependency, not a dev dependency, whenever the app imports a runtime subpath such as `pitlane/assets`, `pitlane/theme`, `pitlane/content`, or `pitlane/data-table-d1`. Those imports run in production, so a production install has to include the package that provides them.

`pitlane` has no command-line interface. To start a new app, copy one of the [starter templates](https://github.com/pitlane-tools/templates).

## Subpaths

Bare `pitlane` has no exports, so `import … from "pitlane"` fails. Every import names a subpath, and each subpath mirrors a scoped package export:

| Import | Re-exports | Use it for |
| --- | --- | --- |
| `pitlane/vite-plugin-remix` | [`@pitlane/vite-plugin-remix`](https://pitlane.tools/package/vite-plugin-remix/index.md) | The `remix()` Vite plugin |
| `pitlane/vite-plugin-remix/hmr` | [`@pitlane/vite-plugin-remix/hmr`](https://pitlane.tools/package/vite-plugin-remix/hmr.md) | `revalidate()`, the browser entry's server-update helper |
| `pitlane/assets` | [`@pitlane/assets`](https://pitlane.tools/package/assets/index.md) | `createAssetResolver()` and `renderImportMap()` |
| `pitlane/assets/manifest` | [`@pitlane/assets/manifest`](https://pitlane.tools/package/assets/manifest.md) | The asset manifest the build supplies, passed to `createAssetResolver()` |
| `pitlane/assets/build` | [`@pitlane/assets/build`](https://pitlane.tools/package/assets/build.md) | `createAssetManifest()`, for bundler integration authors |
| `pitlane/assets/vite-plugin` | [`@pitlane/assets/vite-plugin`](https://pitlane.tools/package/assets/vite-plugin.md) | The `assets()` Vite plugin, for apps without `remix()` |
| `pitlane/vite-plugin-fetch-server` | [`@pitlane/vite-plugin-fetch-server`](https://pitlane.tools/package/vite-plugin-fetch-server/index.md) | The `fetchServer()` development request bridge |
| `pitlane/theme` | [`@pitlane/theme`](https://pitlane.tools/package/theme/index.md) | `createTheme()`, `css()`, and `tva()` |
| `pitlane/theme/schema` | [`@pitlane/theme/schema`](https://pitlane.tools/package/theme/schema.md) | Schema factories |
| `pitlane/theme/default` | [`@pitlane/theme/default`](https://pitlane.tools/package/theme/default.md) | Tailwind CSS v4's primitives as `DefaultTheme` |
| `pitlane/theme/dtcg` | [`@pitlane/theme/dtcg`](https://pitlane.tools/package/theme/dtcg.md) | Conversion to and from Design Tokens Community Group documents |
| `pitlane/content` | [`@pitlane/content`](https://pitlane.tools/package/content/index.md) | `createContent()` and collections |
| `pitlane/content/loaders` | [`@pitlane/content/loaders`](https://pitlane.tools/package/content/loaders.md) | The `glob()` and `file()` loaders |
| `pitlane/content/vite-plugin` | [`@pitlane/content/vite-plugin`](https://pitlane.tools/package/content/vite-plugin.md) | The `contentLayer()` Vite plugin |
| `pitlane/content/hot` | [`@pitlane/content/hot`](https://pitlane.tools/package/content/hot.md) | Browser reloads for content without a build |
| `pitlane/content/satteri` | [`@pitlane/content/satteri`](https://pitlane.tools/package/content/satteri.md) | The `headings()` and `rawStyles()` Satteri plugins |
| `pitlane/crawler` | [`@pitlane/crawler`](https://pitlane.tools/package/crawler/index.md) | `crawl()` and `staticPaths()` |
| `pitlane/data-table-d1` | [`@pitlane/data-table-d1`](https://pitlane.tools/package/data-table-d1/index.md) | The Cloudflare D1 driver for `remix/data-table` |
| `pitlane/data-table-d1/migrations` | [`@pitlane/data-table-d1/migrations`](https://pitlane.tools/package/data-table-d1/migrations.md) | `generateD1Migrations()`, build tooling kept out of the Worker |

A subpath is the scoped package name without its scope, followed by the package's own subpath: `@pitlane/theme/schema` becomes `pitlane/theme/schema`.

## Versions

Each `pitlane` release depends on an exact version of every scoped package, and its changelog lists those versions. Installing `pitlane@1.0.0-alpha.1` installs the package versions that release was built and documented against, never newer ones.

The umbrella is released by hand when enough package changes have accumulated. A scoped package's newest release can be ahead of the version the current `pitlane` pins. Need a fix before the next umbrella release? Install that scoped package directly and use its `@pitlane/<name>` import. [Mixing the two](#mixing-the-two) explains how the installs coexist.

`1.0.0-alpha.1` is the first umbrella release. It pins `@pitlane/dev@0.7.1`, `@pitlane/theme@0.5.0`, `@pitlane/content@0.3.1`, `@pitlane/crawler@0.3.0`, and `@pitlane/data-table-d1@0.3.0`. Releases before it, `0.0.x`, were a placeholder with no usable exports.

Alpha releases are published to npm's `latest` tag until a stable `1.0.0` exists, so a plain install picks up the newest alpha. Pin an exact version, such as `pitlane@1.0.0-alpha.1`, to decide when the app moves to the next one.

## Production installs

`pitlane` installs every package, `@pitlane/vite-plugin-remix` and its Vite peer included. Because an app with runtime imports lists it in `dependencies`, a production install that omits dev dependencies still installs the Vite plugins and Vite itself. `remix` makes the same trade for its CLI and test runner. The cost is install size and time on the production host.

## Scoped packages

The scoped packages are the lean alternative. Put `@pitlane/vite-plugin-remix` in dev dependencies and only the runtime packages the app imports in dependencies. For an app that resolves its assets and uses the theme and content collections:

```sh
npm add @pitlane/assets @pitlane/theme @pitlane/content
npm add -D @pitlane/vite-plugin-remix
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Then import from the scoped names, such as `@pitlane/vite-plugin-remix` and `@pitlane/theme/schema`. Choose this when production install size matters, when an app uses a single package, or when it needs a package release newer than the umbrella pins.

## Migrate from scoped packages

1. Install `pitlane` as shown in [Install](#install).
2. Rewrite the public imports listed in [Subpaths](#subpaths) from `@pitlane/<name>` to `pitlane/<name>`, keeping the listed subpath: `@pitlane/content/vite-plugin` becomes `pitlane/content/vite-plugin`, and `@pitlane/assets/manifest` becomes `pitlane/assets/manifest`.
3. Remove a scoped package from `package.json` only when nothing in the app or its tooling imports it directly.

The umbrella excludes `@pitlane/content/internal/*`. Custom bundler integrations using those unstable APIs must keep their scoped imports and a direct `@pitlane/content` dependency. Keep that dependency at the umbrella's pinned content version when both are used, so the plugin and collections share the same content package.

### Mixing the two

An app can keep a direct `@pitlane/*` dependency next to `pitlane`. Different versions mean two copies of that package. The `pitlane/*` import reaches the pinned copy, while the `@pitlane/*` import reaches the direct dependency. Use one import path consistently for each package.

## Documentation for coding agents

`pitlane` releases after `1.0.0-alpha.1` install these guides and every package's README with the package. A coding agent working in the app reads documentation for the version the app depends on, offline, instead of what it remembers or what pitlane.tools last deployed. The layout follows the one `remix` uses for its installed documentation:

| Path in `node_modules/pitlane/` | What it holds |
| --- | --- |
| `INDEX.md` | Every guide listed by task and every export listed by subpath, each linking the installed file that covers it |
| `guides/index.md` | The [guides overview](https://pitlane.tools/guides.md) |
| `guides/<slug>.md` | Each guide, such as `guides/vite-plugin.md` |
| `guides/deploy/<slug>.md` | Each deploy guide, such as `guides/deploy/cloudflare.md` |
| `dist/<package>/README.md` | Each scoped package's README beside its compiled code, such as `dist/vite-plugin-remix/README.md` for `pitlane/vite-plugin-remix` and its subpaths |

These are the same Markdown pages pitlane.tools publishes. A link between two of them leads to the installed copy, so following one never leaves the installed version. Links to the [API reference](https://pitlane.tools/package/vite-plugin-remix/index.md) stay on pitlane.tools. The installed type declarations carry the same TSDoc, so an editor or agent can read an export's signature and documentation from the `.d.ts` file instead.

An agent has to know the index exists. Point it there with a line in the app's `AGENTS.md`:

```md
Before changing Pitlane code, read `node_modules/pitlane/INDEX.md`; prefer the installed documentation over memory or the latest website.
```

An app that installs only scoped `@pitlane/*` packages has none of these files. It can read the same pages as Markdown through [`llms.txt`](https://pitlane.tools/llms.txt), which describes whatever was last deployed.

# Using the Vite plugin

Source: https://pitlane.tools/guides/vite-plugin.md

> How the remix() plugin from pitlane/vite-plugin-remix behaves in your app day to day, across document assets, the clientEntry() transform and its footguns, dev-server semantics, preview, and the build.

This guide covers living with [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) from `pitlane/vite-plugin-remix` day to day. It explains how your document and islands find their browser assets and what the `clientEntry()` transform does, including what it deliberately refuses to do. Dev, preview, and the production build each get their own section. Hot module replacement has its own guide, [Hot module replacement](https://pitlane.tools/guides/hmr.md). Exact API signatures live in the generated [API reference](https://pitlane.tools/package/vite-plugin-remix/index.md). Per-target deployment configs live in the [deploy guides](#deploying).

## Installation

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The `pitlane` package goes in `dependencies` because app code imports runtime subpaths such as `pitlane/assets`. It requires `remix@^3.0.0` and `vite@>=8.1` as peer dependencies. The underlying `@pitlane/vite-plugin-remix` package also installs on its own, with the same peers. An app using it directly adds `@pitlane/assets` to `dependencies` for the resolver. The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) compares the two. The tested matrix is **Vite 8.1 and later** (Rolldown) and **Vite+ 1.0 and later** (`vp`) with `remix@3.0.0`. Vite 7 and 8.0 are not supported, and neither are the Vite+ 0.x releases built on them.

### Upgrading from `pitlane/dev`

The plugin was published as `@pitlane/dev` and `pitlane/dev` until this release. The rename comes with a new way to name assets, and there are no aliases for the old paths. Change these together:

| Before | After |
| --- | --- |
| `remix` from `pitlane/dev` | `remix` from `pitlane/vite-plugin-remix` |
| `revalidate` from `pitlane/dev/hmr` | `revalidate` from `pitlane/vite-plugin-remix/hmr` |
| `import clientAssets from "./entry.browser.ts?assets=client"`, then `.entry` | `(await assets.getScriptEntry("app/entry.browser.ts")).href` |
| `clientAssets.js` as `modulepreload` links | `.preloads` from the same call |
| `import serverAssets from "./entry.server.tsx?assets=ssr"`, then `.css` | `await assets.getStylesheets("app/entry.server.tsx")` |
| `mergeAssets(…)` from `pitlane/dev/runtime` | plain arrays; the resolver deduplicates |
| `render()` without options, or a hand-written `resolveClientEntry` | `render({ assets })` from `remix/middleware/render` |
| `"types": ["pitlane/dev/assets"]` in `tsconfig.json` | delete it |
| `import { HMR } from "pitlane:dev"` and `<HMR />` in the document | delete both; add the `server:update` listener from the [HMR guide](https://pitlane.tools/guides/hmr.md#setup) to the browser entry |

[Document assets](#document-assets) shows the resulting files.

### Upgrading from a Remix prerelease

Upgrade Remix and the Pitlane packages together. The stable-compatible releases require `remix@^3.0.0`. Their previous prerelease-compatible versions remain available for apps that have not migrated.

- Replace `remix/ui` imports with `remix/component`, including `/server`, `/jsx-runtime`, and `/jsx-dev-runtime` subpaths. Set TypeScript's `jsxImportSource` and Satteri's `mdx.jsxImportSource` to `remix/component`.
- Replace `remix/ui-hmr` with `remix/component-hmr`. For no-build apps, rename the asset loader from `uiHmr()` to `componentHmr()` and the Node hook to `remix/component-hmr/node`. The Vite plugin supplies its own HMR integration.
- Raw HTML props such as `innerHTML` now require `unsafeHTML()` from `remix/component`. It marks trusted or already-sanitized content. It does not sanitize strings. Pitlane's content renderer and `<Theme />` wrap their own markup this way, and neither sanitizes it.
- Animation utilities and headless primitives are separate `@remix-run/ui` imports. The old styled components and style mixins, including `button()` and `inputStyle`, were removed. Replacing those requires an application change.

See the [Remix 3.0.0 release notes](https://github.com/remix-run/remix/releases/tag/remix%403.0.0) for the upstream entrypoint changes.

## Templates

Prefer starting from a working app? The [`pitlane-tools/templates`](https://github.com/pitlane-tools/templates) monorepo has the same Remix 3 guest book wired for eight deploy targets. Cloudflare uses D1. Netlify uses Netlify DB, while Vercel pairs Nitro with Postgres. Railway runs on Node, Bun, or Deno. The remaining templates cover Deno Deploy and GitHub Pages, which runs in the browser with IndexedDB. Scaffold one with [giget](https://github.com/unjs/giget):

```sh
npx giget github:pitlane-tools/templates/<template> my-app
```

Because every template is the same app, diffing any two shows exactly what a platform swap touches, usually only the database middleware and deploy config. The templates still depend on the scoped `@pitlane/*` packages and import from them. Those imports keep working; to use the `pitlane/*` paths this guide shows, add `pitlane` and update the imports.

## The three-file core

Everything the plugin does orbits three files you own:

- **`vite.config.ts`** needs only `plugins: [remix()]`, and the defaults cover the rest.
- **`app/entry.server.tsx`** builds a router and **default-exports it**. The default export's `.fetch(Request)` is the contract every consumer reads: the dev server, `vite preview`, and whatever runs in production.
- **`app/entry.browser.ts`** calls `run()` from `remix/component` to hydrate `clientEntry()` components against server HTML.

A server-rendered app adds a fourth, `app/assets.ts`, which constructs the asset resolver your document and renderer share. See [Document assets](#document-assets).

`vite dev`, `vite build`, `vite preview`: the standard lifecycle, nothing bespoke.

## Options

Every option has a sensible default. Most projects pass none. [`RemixPluginOptions`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md) documents each one.

```ts
remix({
    server: true, // false selects SPA mode
    prerender: undefined, // true, a path array, a function, or a config object
    clientEntry: "app/entry.browser", // false disables the client build
    serverEntry: "app/entry.server",
    serverEnvironments: ["ssr"],
    serverHandler: true, // false when a platform plugin serves dev and preview requests
    assets: {}, // { include, chunkImportMap, allowFiles, … } for the asset plugin; maps are on
});
```

| Option | Type | Default | Purpose |
| --- | --- | --- | --- |
| `server` | `boolean` | `true` | Whether the app has a server. Pass `false` for [SPA mode](#spa-mode), which ignores every option below. |
| `prerender` | `boolean \| string[] \| fn \| obj` | none | Render paths to static HTML at build time. See [Prerendering](https://pitlane.tools/guides/prerendering.md). |
| `clientEntry` | `string \| false` | `"app/entry.browser"` | Client entry module. Pass `false` for fully server-rendered apps with no hydration. |
| `serverEntry` | `string` | `"app/entry.server"` | Server entry module, built as `dist/ssr/index.js`, and the module dev requests are served through. |
| `serverEnvironments` | `string[]` | `["ssr"]` | Environment names treated as "server" by asset collection and hot module replacement. |
| `serverHandler` | `boolean` | `true` | Serve dev and `vite preview` requests through your server entry. Set `false` when `@cloudflare/vite-plugin` or `nitro/vite` owns request handling. |
| `assets` | `{ include?, chunkImportMap?, allowFiles?, allowPackages?, denyFiles? }` | `{}` | Passed to the asset plugin. `include` lists extra browser entries for computed paths. `chunkImportMap` switches [chunk import maps](#chunk-import-maps), and `remix()` defaults it to `true`. The allow and deny lists set up the [browser boundary](https://pitlane.tools/guides/assets.md#browser-boundary). |

## SPA mode

Some apps have no server: the router runs in the browser, the build is a folder of static files. `remix({ server: false })` targets those. React Router spells the same switch `ssr: false`.

```ts title="vite.config.ts"
export default defineConfig({
    plugins: [remix({ server: false })],
});
```

The three-file core collapses to one. `index.html` is the entry, and `vite build` emits a static site beside it. `app/entry.server.tsx`, the server environment, and `dist/ssr` are all gone. Every other option on this page goes unread, and the rest of this guide covers machinery a client-only app never reaches. [Single-page apps](https://pitlane.tools/guides/spa.md) is the guide for that mode.

The switch removes the server, not the server rendering. An app that wants a browser-rendered UI in front of routes that still run per request keeps the default mode: see [client rendering with a server](https://pitlane.tools/guides/spa.md#client-rendering-with-a-server).

## Document assets

Server-rendered HTML needs browser asset URLs that differ between `vite dev` and a build. The plugin supplies a manifest for the resolver from [`pitlane/assets`](https://pitlane.tools/guides/assets.md). Construct the resolver in `app/assets.ts`:

```ts title="app/assets.ts"
import { createAssetResolver } from "pitlane/assets";
import manifest from "pitlane/assets/manifest";

export let assets = createAssetResolver(manifest);

export let scriptEntry = await assets.getScriptEntry("app/entry.browser.ts");
export let stylesheets = await assets.getStylesheets("app/entry.server.tsx");
```

Paths are relative to the project root, the directory holding `vite.config.ts`. Writing `getScriptEntry` with a literal path makes that module a browser entry. `getStylesheets` only reports the CSS a module already imports and never sends server code to the browser. The [assets guide](https://pitlane.tools/guides/assets.md#resolver-methods) lists every method.

The document reads those values. Nothing in it is specific to Pitlane, and the same document works against `remix/assets` in a no-build app:

```tsx title="app/document.tsx"
import type { Handle, RemixNode } from "remix/component";

import { scriptEntry, stylesheets } from "./assets.ts";

export function Document(handle: Handle<{ children?: RemixNode }>) {
    return () => (
        <html lang="en">
            <head>
                <meta charSet="utf-8" />
                {stylesheets.map(href => (
                    <link key={href} rel="stylesheet" href={href} />
                ))}
                {scriptEntry.preloads.map(href => (
                    <link key={href} rel="modulepreload" href={href} />
                ))}
                <script type="module" src={scriptEntry.href} />
            </head>
            <body>{handle.props.children}</body>
        </html>
    );
}
```

The server entry hands the same object to Remix's own `render()` middleware, which uses it to resolve islands:

```tsx title="app/entry.server.tsx"
import { render } from "remix/middleware/render";
import { staticFiles } from "remix/middleware/static";
import { createRouter, type MiddlewareContext } from "remix/router";

import { assets } from "./assets.ts";
import { Document } from "./document.tsx";
import { routes } from "./routes.ts";

let renderMiddleware = render({ assets });
type AppContext = MiddlewareContext<[typeof renderMiddleware]>;

declare module "remix/router" {
    interface RouterTypes {
        context: AppContext;
    }
}

export let router = createRouter<AppContext>({
    middleware: [staticFiles("./dist/client"), renderMiddleware],
});

router.map(routes.home, ({ render }) => render(<Document>{/* ... */}</Document>));

export default router;

if (import.meta.hot) {
    import.meta.hot.accept();
}
```

> [!WARNING]
>
> **Footgun Warning**
>
> `render()` without `assets` renders pages until the first island, then fails with Remix's own error: `clientEntry() cannot use a file: source entry ID without an asset server. Pass the asset server to render({ assets }).` Pass the resolver.

### Dev and production resolve differently, by design

|  | `vite dev` | production build |
| --- | --- | --- |
| `scriptEntry.href` | source URL (`/app/entry.browser.ts`) | hashed chunk (`/assets/entry.browser-D3adB33f.js`) |
| `scriptEntry.preloads` | **always empty** (no chunk graph exists yet) | the entry chunk, then its static imports |
| `scriptEntry.importMap` | `{ imports: {} }` | the client build's import map, or `{ imports: {} }` with chunk import maps off |
| `getStylesheets(…)` | dev URLs for the CSS the server graph imports | hashed files in `dist/client` |

The same document works in both modes. Empty hint arrays produce no tags during development. Vite injects browser-only CSS and updates stylesheets in place when their rules change.

The manifest is server-side data. Import `app/assets.ts` from server-rendered modules such as your document, never from code that only runs in the browser.

### Chunk import maps

On by default. `remix()` turns on Vite's chunk import map for the client build, so a dependency's new hash changes one map entry instead of every chunk importing it. `scriptEntry.importMap` carries the complete map, and the document must deliver it before any module script or `modulepreload` link:

```tsx
import { ImportMap } from "remix/component/server";

// inside <head>, first:
<ImportMap value={scriptEntry.importMap} />;
```

The option requires browsers with import maps and `import.meta.resolve`, and conflicts with Vite's `experimental.renderBuiltUrl`. An app that uses `renderBuiltUrl`, or targets browsers without those features, turns maps off:

```ts
remix({ assets: { chunkImportMap: false } });
```

Chunks then import each other by their final URLs, and `scriptEntry.importMap` stays `{ imports: {} }`. A plugin value wins over Vite's own `build.chunkImportMap` in the client environment. With no plugin value, a native setting applies. The [assets guide](https://pitlane.tools/guides/assets.md#chunk-import-maps) covers the caching limits and renderers other than Remix.

## The `clientEntry()` transform

`clientEntry(import.meta.url, …)` marks a component for hydration. The plugin rewrites the first argument into a portable identity: `file:` plus the module's path from the project root, plus an `#ExportName` fragment. Every environment, in dev and in the build, gets the same literal:

```diff
export let Counter = clientEntry(import.meta.url, function Counter(handle) {
export let Counter = clientEntry("file:app/counter.tsx#Counter", function Counter(handle) {
```

When a page renders `<Counter />`, `render({ assets })` sees the `file:` prefix and asks the resolver for the island's script entry. In dev that is the module's own URL, `/app/counter.tsx`. In a build it is the island's emitted chunk, and the renderer hoists the chunk and its static imports into the head as `modulepreload` links. The hydration record still names the chunk URL and export, and the browser's `run()` imports it and hydrates in place.

```tsx
import { clientEntry, on } from "remix/component";

export let Counter = clientEntry(import.meta.url, handle => {
    let count = 0;
    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: <span>{count}</span>
        </button>
    );
});
```

Each island module becomes its own client chunk with its exports intact, even when no browser code imports it: the plugin finds islands while building the server and emits them in the client build. Multiple `clientEntry` exports in one file share that chunk, so grouping related islands per file is free.

`vite dev` follows the same rule without a build. When the server imports a module that declares an island, the plugin registers that module as a browser entry. The resolver then answers with its dev URL. Delete the module's last `clientEntry` export and the registration goes with it on the next edit. An island file outside the server graph is not an entry.

The identity contains no checkout directory, so builds on different machines write the same server code. A module linked from outside the project root, such as a workspace package, keeps leading `../` segments (`file:../packages/ui/src/counter.tsx#Counter`), which assumes the same relative workspace layout on every machine that builds it.

### The pattern is strict

The transform matches **exactly** this shape, at the top level of a module:

```
export let Name = clientEntry(import.meta.url, …at least one more argument)
```

The declaration kind is the one part that is free. `let`, `const`, and `var` all match, because the `#Name` fragment comes from the name the export binds and nothing else. Examples here use `let`, matching the rest of the codebase.

Anything else is left untouched. An untransformed call keeps `import.meta.url`, which on Node is the module's absolute `file:///` URL. `render({ assets })` passes it to the resolver, which rejects absolute file URLs and asks for a portable source key, so the page fails to render. If you see that error for an island, check these first:

```tsx
// ✗ default export — no export name for the #fragment
export default clientEntry(import.meta.url, handle => {
    /* … */
});

// ✗ aliased callee — the transform matches the literal name `clientEntry`
import { clientEntry as ce } from "remix/component";

export let Counter = ce(import.meta.url, handle => {
    /* … */
});

// ✗ not exported — the browser could never import it by name
let Counter = clientEntry(import.meta.url, handle => {
    /* … */
});

// ✗ wrapped in a helper — the call site the transform sees isn't clientEntry()
export let Counter = myIslandHelper(import.meta.url, handle => {
    /* … */
});

// ✗ computed first argument — must be literally `import.meta.url`
export let Counter = clientEntry(String(import.meta.url), handle => {
    /* … */
});

// ✓ the correct shape
export let Counter = clientEntry(import.meta.url, handle => {
    /* … */
});

// ✓ the correct shape
export const Counter = clientEntry(import.meta.url, handle => {
    /* … */
});

// ✓ the correct shape
export var Counter = clientEntry(import.meta.url, handle => {
    /* … */
});
```

Only a top-level export binding whose initializer is a literal `clientEntry(import.meta.url, …)` call is rewritten. The `#Name` fragment names a real export, and the explicit pattern cannot false-positive on unrelated `import.meta.url` usage in the same file (which the transform leaves alone).

### `serverEnvironments`

The plugin needs to know which environments are "server". Islands are discovered while those environments build, and their stylesheets are collected from those graphs. The default, `["ssr"]`, is right unless you've renamed or added server environments. If you have, pass the same names to `remix({ serverEnvironments })`. [Hot module replacement](https://pitlane.tools/guides/hmr.md) reads the same option to tell server modules from client ones, so a mismatch breaks both.

## Dev server semantics

With the default `serverHandler: true`, every request is answered by your server entry through Vite's module runner: `serverEntry`, so `app/entry.server` unless you set another path. The entry is re-imported per request, so server-side edits are live without restarting. The `if (import.meta.hot) import.meta.hot.accept()` line in the server entry is what keeps those re-imports cheap, so keep it.

The request bridge is the [Fetch server plugin](https://pitlane.tools/guides/fetch-server.md), which `remix()` installs for you with your `serverEntry`. Vite handles module requests and static files first. Everything else reaches your router.

> [!NOTE]
>
> **Hot module replacement**
>
> Component edits swap in place and keep live island state, and edits to server-only modules refetch the page through your fetch handler without discarding that state. Component HMR is on by default in `vite dev`. Server-data revalidation also needs a short listener in your browser entry. See [Hot module replacement](https://pitlane.tools/guides/hmr.md) for the listener, which edits preserve state, and which remount.

- **Set `serverHandler: false` when a platform plugin owns requests.** `@cloudflare/vite-plugin` (workerd) and `nitro/vite` bring their own runtimes, for dev and for preview. Netlify's plugin does not serve SSR, so keep the default there. Each [deploy guide](#deploying) states the right value.
- **Aborted requests stay quiet.** Search-as-you-type and mid-navigation fetch cancellations end the response without reaching Vite's error overlay, and the next request is served normally. Real errors still surface.

## Preview and the static-files footgun

`vite preview` imports `dist/ssr/index.js` and serves requests through its default export, the same artifact that production runs. With `serverHandler: false`, the plugin installs no preview server at all, and the platform plugin's preview serves the build in the runtime that runs it in production. That holds for a self-contained Worker bundle too, even though Node could load it. With the default `serverHandler: true`, a failed import is the signal instead: a bundle targeting another runtime (a Workers bundle importing `cloudflare:workers`) makes the plugin step aside so the platform's preview can take over.

> [!WARNING]
>
> **Footgun Warning**
>
> In dev, Vite serves every module and stylesheet itself. In preview and production, hashed assets under `dist/client` are served by **your router's** `staticFiles("./dist/client")` middleware (on platforms without a static layer, such as Node, Railway images, and preview). Forget the middleware and everything works in dev while every asset 404s in preview. That missing middleware is the usual cause of an unstyled preview. Platforms with their own static serving (Workers assets, Netlify's CDN, Vercel) bypass the middleware for those paths. Keeping it in the router is still correct and makes preview match production.

## The build

`vite build` runs a coordinated multi-environment build:

```
dist/
├── client/          # hashed static assets
│   └── assets/*
└── ssr/
    └── index.js     # the fetch handler
```

`dist` is Vite's `build.outDir`. Set it and both environments move beneath it, to `<outDir>/client` and `<outDir>/ssr`, so point your router's `staticFiles()` middleware at the new client directory. Setting `environments.client.build.outDir` or `environments.ssr.build.outDir` places that environment's output exactly where you name instead.

- **Server environments build first, then the client.** Islands and literal `getScriptEntry` paths are discovered while the server builds, and the client build emits them. The plugin sequences it and writes the asset manifest into `dist/ssr` before anything else reads the build, so don't hand-orchestrate builds around it.
- **Server-imported stylesheets are copied into `dist/client`**, along with the fonts and images they reference and any file the server code imports, so every URL `getStylesheets` returns is served from the client output. Nothing else from the server output is copied. Server sourcemaps stay private, and so do files a platform plugin writes beside the server bundle, like `.dev.vars` or `wrangler.json`.
- **Composing with another build orchestrator is coordinated.** When a platform plugin also drives builds (Cloudflare's does), each environment still builds exactly once, and [prerendering](https://pitlane.tools/guides/prerendering.md) runs after the manifest is complete.

## Compatibility

| Dependency | Tested against |
| --- | --- |
| `vite` | 8.1 and the latest 8.x |
| `vite-plus` | 1.0 |
| `remix` | 3.0.0 |
| Node | 24 LTS, 26 |

Each `@pitlane/vite-plugin-remix` release records the exact Remix version it was verified against. The transform runs identically on generic Vite and Vite+.

### Troubleshooting

**`vp` stops with `Expected @voidzero-dev/vite-plus-core@…, but found vite@…`**. Vite+ 1.0 requires the `vite` your project declares to be Vite+ core at the same version as `vite-plus`. Alias it to the core. `vp migrate` sets up the same alias, pinned to the exact version:

```jsonc title="package.json"
{
    "devDependencies": {
        "vite": "npm:@voidzero-dev/vite-plus-core@^1.0.0",
        "vite-plus": "^1.0.0",
    },
}
```

**pnpm reports the `vite >=8.1.0` peer as unmet under that alias**. `@voidzero-dev/vite-plus-core` reports its own version (`1.x`), not the Vite version it bundles, so the peer range cannot match it. Tell pnpm which versions of `vite` satisfy it:

```yaml title="pnpm-workspace.yaml"
peerDependencyRules:
    allowedVersions:
        vite: "1"
```

Bun and npm install without complaint.

**`AssertionError: isRunnableDevEnvironment(environment)` on dev**. The project resolves two different `vite` packages, typically because a dependency installs a plain `vite` beside the alias. Override `vite` with the same alias in your package manager's configuration, such as `overrides` in `pnpm-workspace.yaml`, so the whole project resolves one copy.

Generic-Vite projects have one vite by construction and are unaffected.

## Deploying

Once the app works, pick a target. Each guide covers config, CLI deploys, and a GitHub Actions workflow, all with the Vite build running in your CI:

- [Cloudflare Workers](https://pitlane.tools/deploy/cloudflare.md)
- [Netlify](https://pitlane.tools/deploy/netlify.md)
- [Vercel](https://pitlane.tools/deploy/vercel.md)
- [Railway](https://pitlane.tools/deploy/railway.md)
- [Deno Deploy](https://pitlane.tools/deploy/deno-deploy.md)
- [GitHub Pages](https://pitlane.tools/deploy/github-pages.md) (client-only apps)

# Hot module replacement

Source: https://pitlane.tools/guides/hmr.md

> How the pitlane/vite-plugin-remix Vite plugin hot-updates a Remix 3 app during vite dev, covering which component edits swap in place, which remount, how server-only edits revalidate through the frame runtime, and the requirements and limits of both halves.

`vite dev` updates a running app in place. Editing a component swaps its new code in without remounting, so hydrated islands keep their open menus, input values, and counters. Editing a server-only module refetches the current page through your fetch handler and reconciles the new HTML into the DOM, which keeps that same island state while the server output changes underneath it.

Component HMR needs no configuration. Server-data revalidation needs a few lines in your browser entry, described under [Setup](#setup). Both are development-only. Component transforms run only on a dev server with HMR on. A test runner such as Vitest serves modules with `server.hmr` off, so your components reach your tests untouched. A production build removes the browser-entry listener guarded by `import.meta.hot`.

## What each kind of edit does

| You edit | What happens | What keeps its state |
| --- | --- | --- |
| The render function of an HMR-compatible component | Its new code is swapped in place | Every island, including this one |
| The setup scope of an HMR-compatible component | That component remounts | Every other island |
| A component export the transform skips | The page refetches and reconciles | Every other island |
| A server-only module | The page refetches and reconciles | Every island |
| A non-component module the browser imports | The importing island updates, output can go stale | Every island (see [limits](#limits)) |
| CSS | Vite's own CSS handling | Every island |
| Which stylesheets a server module imports | The page refetches with the new stylesheet links | Every island |

No row in that table is a full page reload.

## Setup

Keep the runtime that `run()` returns in your browser entry, and pass it to `revalidate` from `pitlane/vite-plugin-remix/hmr` when the plugin reports a server update:

```ts title="app/entry.browser.ts"
import { revalidate } from "pitlane/vite-plugin-remix/hmr";
import { run } from "remix/component";

let app = run({
    async loadModule(moduleUrl, exportName) {
        let mod = await import(/* @vite-ignore */ moduleUrl);
        return mod[exportName];
    },
});

if (import.meta.hot) {
    import.meta.hot.on("server:update", () => revalidate(app));
}
```

Pass `run()` the same options you already do. Only the captured `app`, the import, and the `import.meta.hot` block are new.

`revalidate` waits on `app.ready()`, so an update that lands during initial hydration does not reload a frame that is still being adopted. It then reloads the top frame, which refetches the page through your fetch handler and reconciles it in place. A failed reload is logged, and the next server edit tries again.

Keep the listener as written, without `async` or `await`. Vite handles HMR messages one at a time and waits for any promise a listener returns. A listener that awaited the reload would hold back every later HMR message until that reload settled, including the next server update. `revalidate` returns nothing for the same reason.

No environment guard is needed beyond `import.meta.hot`. A production build replaces it with `undefined`, so the whole block, the event name included, is removed from the client bundle. `import.meta.hot` is typed by `vite/client`, which a Vite project's `vite-env.d.ts` already references.

Component HMR is independent of this listener and runs whether or not you add it. Without it, server-only edits reach the server and the page does not change until you reload. The same holds on any page that never loads the module holding the listener, so keep `run()` and the listener in the entry every page loads, not in a module that only island pages import.

`@pitlane/dev` 0.7 and earlier provided this listener as an `<HMR />` component imported from `pitlane:dev`. That module is gone: remove the import and the `<HMR />` element from your document, and add the block above to your browser entry. An app that used the helper from `pitlane/dev/hmr` or `@pitlane/dev/hmr` imports the same `revalidate` from `pitlane/vite-plugin-remix/hmr` or `@pitlane/vite-plugin-remix/hmr`.

## Component HMR

Component edits run through the [`remix/component-hmr`](https://github.com/remix-run/remix/tree/main/packages/component-hmr) transforms. The browser transform runs in the client environment and the server transform in your server environments, and both emit the standard `import.meta.hot.accept()` protocol that Vite's own HMR runtime drives. The `pitlane/vite-plugin-remix` plugin supplies the wiring and one transform of its own, described below.

### Which exports are boundaries

An exported symbol is injected with the HMR runtime when all of these hold (i.e. when it is "HMR-compatible"):

- **The file ends in `.tsx` or `.jsx`** and does not live under `node_modules`. A component in a `.ts` file is never injected with the HMR runtime.
- **The export is named and top level.** Default exports are skipped, because the hydration protocol needs an export name.
- **The name starts with a capital letter.** `Counter` qualifies, `counter` does not.
- **The setup function returns a render function**, or the export is a `clientEntry(import.meta.url, setup)` call.

All four of these authoring styles qualify:

```tsx
export const Counter = clientEntry(import.meta.url, handle => {
    /* ... */
});
export const Toggle = clientEntry(import.meta.url, function Toggle(handle) {
    /* ... */
});
export const Card = handle => () => <div />;
export function Panel(handle) {
    /* ... */
}
```

`remix/component-hmr` only recognizes a setup function that carries a name. To allow you to define your components using arrow functions, the `pitlane/vite-plugin-remix` plugin rewrites qualifying arrow exports before `remix/component-hmr` sees them. `export const Counter = clientEntry(url, handle => …)` becomes `export const Counter = clientEntry(url, function Counter(handle) { … })` in the dev transform only. Setup functions never rely on a lexical `this` or `arguments`, so the rewrite is behavior-identical. If `remix/component-hmr` declines to inject the component with the HMR runtime, the rewrite is discarded, which leaves non-component arrow functions untouched.

### State survives a render edit and resets on a setup edit

This is the line that decides whether your counter keeps counting. `remix/component-hmr` hashes the setup scope, meaning the source from the start of the setup body up to its `return`. While that hash stays the same, the new render function replaces the old one and the live component keeps its state. Change it and the component is marked stale, then remounts.

```tsx
export const Counter = clientEntry(import.meta.url, handle => {
    let count = 0; // setup scope: editing this line remounts and count returns to 0
    let step = 1;

    function increment() {
        // still setup scope
        count += step;
        handle.update();
    }

    return () => (
        // everything below swaps in place, count intact
        <button mix={[on("click", increment)]}>
            Count: <span>{count}</span>
        </button>
    );
});
```

Iterating on markup and styles keeps the count. Changing how state is declared resets it, which is the correct outcome, because the new setup scope describes different state.

### Exports the transform skips

An export that misses one of the four conditions is left alone, and nothing is logged. The edit still reaches the server, so the server-data half picks it up. The page refetches and the DOM updates, other islands keep their state, and the edited component remounts. The change is never lost. It costs that one component's state.

To make such a component hold its state across edits, check it against the four conditions above.

## Server-data HMR

Editing the document, a middleware, a route handler, a data module, or anything else the browser never loads refetches the current page and reconciles it. Hydrated island state survives. This is the Remix 3 analog of React Router's loader and action revalidation, driven through the frame runtime rather than a client data router.

### How a server edit reaches the browser

1. The changed file is classified in your server environment. A file counts as server-only when the client module graph does not serve it as a script.
2. The plugin broadcasts a `server:update` event to the browser.
3. The listener in your browser entry receives the event and calls `revalidate(app)`, which reloads the top frame of the runtime `run()` returned.
4. The frame runtime refetches the page through your fetch handler and reconciles the new HTML in place.

The browser entry is where the app's runtime lives, which is what gives step 3 the top frame. Reloading the frame directly is what revalidation means here. It produces no history entry and fires no `navigate` event, so an app that intercepts navigation itself keeps working, and a listener watching for real navigations never sees dev traffic.

### What counts as server-only

The classification asks one question per changed file: does the client module graph serve this file as a script? Only script modules count. Plugins that scan your sources for their own reasons register other node types for ordinary server files, and Tailwind's content scanner is the common case: it registers an asset node for every file it scans. Counting those would mark every server module as client-owned and switch server-data HMR off for the whole app.

Files ending in `.ts`, `.tsx`, `.js`, and `.jsx` are considered. Other file types are left to the plugins that own them.

### Bursts collapse into one refetch

The broadcast waits 50ms. Two things fall out of that. A save that touches several files refetches _once_ instead of _once per file_. And the request cannot reach your fetch handler while Vite is still applying the update to the server environment, which on slower runtimes (such as workerd) can produce an error in dev mode.

A newer update supersedes one still in flight. The frame runtime abandons the older refetch, and the page shows the output of the latest server edit.

## Requirements

| Requirement | Why | When unmet |
| --- | --- | --- |
| The server-update listener in your browser entry | It is the browser half, and it holds the runtime whose top frame it reloads | Server edits reach the server and the page does not change |
| A client entry file (e.g. `entry.browser.ts`) that the document loads | The listener lives there, next to `run()` | Nothing receives the event and revalidation never runs |
| `serverEnvironments` matches your config | It selects which environment classifies files as server-only | Neither half can tell client from server |

If a platform plugin renames the server environment, pass the same names to [`remix({ serverEnvironments })`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#serverenvironments). `@cloudflare/vite-plugin` with `viteEnvironment: { name: "ssr" }` matches the default and needs nothing. This is the same option island discovery uses, so a mismatch shows up as broken hydration too.

Nothing here depends on navigation, so an app that installs its own `navigate` listener and stops Remix from seeing navigations still revalidates normally.

### Fully server-rendered apps

`clientEntry: false` turns off the client environment, so nothing calls `run()`, nothing hydrates, and no script tag reaches the browser. There is no browser entry to hold the listener, so server edits do not revalidate the page.

To serve no browser JavaScript in production and still revalidate in dev, keep the client entry and gate the script tag instead:

```tsx
{
    import.meta.env.DEV && <script async src={scriptEntry.href} type="module" />;
}
```

Production drops the tag and serves zero JavaScript, since the hydration markers are inert HTML on their own. Dev keeps the full client runtime, so both halves of HMR work. The production build still emits an unused client chunk under `dist/client`. Dev also carries a client runtime that production does not, so links soft-navigate through the frame runtime in dev while production loads whole documents.

### Client-rendered apps

`remix({ server: false })` is the mirror image. Everything renders in the browser, so component HMR is the whole story and there is no server data to revalidate. The plugin never broadcasts a server update, so the browser entry needs no listener, and the requirements table above does not apply. The client entry is whatever `index.html` loads. There are no server environments to name.

This is also the only mode that currently works under Vite's experimental bundled dev mode, component hot-swap included. See [Single-page apps](https://pitlane.tools/guides/spa.md) for the whole mode.

## Limits

**A shared module the browser imports can render stale output.** Editing a non-component module that a hydrated island imports (a constants file or a formatting helper) updates the island's boundary and keeps its state. The rendered output can keep showing the previous value, including after an interaction re-renders the component. Reload to pick it up. Component modules and server-only modules are the two reliable boundaries.

**The first edit after a dependency change can be missed.** Installing or re-pinning a dependency makes Vite rebuild its client dependency cache. The first edit after that reaches the server but not the browser. One reload settles it. The cause is Vite's dependency prebundling rather than the plugin.

**Production is untouched.** Both transforms are dev-only, so no wrapper indirection and no runtime imports reach a build, and the browser-entry listener is removed with its `import.meta.hot` branch. Nothing about HMR changes `vite build` output.

## How this maps to Remix's HMR packages

[`remix/component-hmr`](https://github.com/remix-run/remix/tree/main/packages/component-hmr) provides the component transforms plus the browser and server runtimes. The `pitlane/vite-plugin-remix` plugin runs those transforms and owns the server-data half. The arrow normalization is its own addition, so that arrow exports qualify for instrumentation.

[`remix/node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr) is deliberately not used. It supervises a child Node process and provides `import.meta.hot` through Node's module customization hooks, which is the job Vite's module runner already does here. Its fetch-proxy and restart behavior would duplicate the dev server rather than add to it.

# Single-page apps

Source: https://pitlane.tools/guides/spa.md

> How remix({ server: false }) sets up a client-rendered Remix 3 app, and what the plugin still contributes once there is no server.

Some Remix 3 apps have no server. The router runs in the browser. The build is a folder of static files, and the host is a CDN. [`remix({ server: false })`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#server) is the switch for those apps.

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite"; // or "vite-plus"

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

The `pitlane` package provides `pitlane/vite-plugin-remix`. If only `vite.config.ts` imports it, the app can install `pitlane` as a dev dependency. The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) covers its `remix` and `vite` requirements and the standalone `@pitlane/vite-plugin-remix` alternative.

If you want browser-only UI in front of server routes that still run per request, that is [the default mode](#client-rendering-with-a-server), not this one.

Nothing in this mode renders outside a browser, so there is no server-safe rendering to worry about. `index.html` is served as written. [Prerendering](https://pitlane.tools/guides/prerendering.md) needs a server to render through, and `remix({ server: false, prerender })` throws.

## What the switch changes

|  | `server: true` (default) | `server: false` |
| --- | --- | --- |
| Vite Environments | `client` and `ssr` | `client` |
| Build input | `clientEntry` and `serverEntry` | `index.html` |
| Build output | `dist/client` and `dist/ssr` | `dist` |
| Dev requests | your fetch handler | Vite's static server |
| Component HMR | yes | yes |
| Server-data HMR | yes | no server data exists |
| Asset resolver | how HTML names its client assets | Vite injects the tags |
| Chunk import map | on; the document renders it | on; Vite writes it into `index.html` |

Every `server*` option goes with it: `serverEntry`, `serverEnvironments`, and `serverHandler` describe a server that no longer exists. `clientEntry` goes too, because the browser entry is whatever `index.html` loads. Of the `assets` options, only `chunkImportMap` still applies. `remix({ server: false, assets: { chunkImportMap: false } })` turns the map off.

## Why use the plugin at all

Vite already serves `index.html` in dev and builds it into a static site. The plugin's remaining job is [component hot module replacement](https://pitlane.tools/guides/hmr.md#component-hmr). Without HMR, editing a component reloads the page and every piece of live state goes with it (a half-typed form, an open menu, a scroll position). With it, the component swaps in place and that state survives.

Both authoring styles hot-swap. The plugin rewrites an arrow-form component export to a function expression with a name before instrumenting it:

```tsx title="app/counter.tsx"
import { on, type Handle } from "remix/component";

export function Counter(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}
```

Editing the returned markup swaps it in and the count keeps counting. Editing the setup scope above the `return` remounts the component, which is the same rule as everywhere else. See [state survives a render edit](https://pitlane.tools/guides/hmr.md#state-survives-a-render-edit-and-resets-on-a-setup-edit).

Server-data revalidation has no server to revalidate against, so the plugin never broadcasts a server update here and the browser entry needs no [server-update listener](https://pitlane.tools/guides/hmr.md#setup).

## The app shell

`index.html` is the entry, at the project root, loading one module:

```html
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/entry.browser.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```jsonc title="tsconfig.json"
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "remix/component",
    },
}
```

## Rendering

Two shapes work, depending on whether the app needs routing.

### A root component

`createRoot` from `remix/component` renders a component tree into an element. There is no routing, and the URL never changes:

```tsx title="app/entry.browser.tsx"
import { createRoot } from "remix/component";

import { App } from "./app.tsx";

let container = document.getElementById("app");
if (!container) throw new Error("missing #app container");

createRoot(container).render(<App />);
```

### A router

`remix/spa` connects an ordinary Remix fetch router to the document. The `render()` middleware gives every handler a `context.render()` that answers with a UI node, and `run()` dispatches the current URL plus every same-origin navigation and form submission through that router:

```tsx title="app/router.tsx"
import { createRouter } from "remix/router";
import { render } from "remix/spa";

export let router = createRouter({ middleware: [render()] });

router.get("/", ({ render }) => render(<Home />));
router.get("/about", ({ render }) => render(<About />));
```

```tsx title="app/entry.browser.tsx"
import { run } from "remix/spa";

import { Loading } from "./loading.tsx";
import { router } from "./router.tsx";

let app = run(router, { fallback: <Loading /> });
await app.ready();
```

`run()` renders into the document's top frame. Whatever the shell left in `<body>` goes away with the first render, so the `#app` container from [the app shell](#the-app-shell) is `createRoot` machinery this shape never reads.

The optional `fallback` is a live node for the gap before the first route resolves. `app.ready()` waits for the routed node to take its place.

Everything past the first render stays inside the router. Anchors, form submissions, and history traversal become `Request` objects it answers, and a handler that returns a `redirect()` is followed before anything renders. Redirects have to stay same-origin, and a chain longer than ten throws.

Give `render()` a transform when every route shares a shell. It receives the route's node and the request context, so the layout can read the URL it is rendering:

```tsx title="app/router.tsx"
export let router = createRouter({
    middleware: [
        render((content, { url }) => (
            <main>
                <Nav pathname={url.pathname} />
                {content}
            </main>
        )),
    ],
});
```

## The build

`vite build` produces a static site and no server bundle:

```
dist/
├─ index.html
└─ assets/
   ├─ index-<hash>.js
   └─ index-<hash>.css
```

The HMR instrumentation is dev-only, so none of it reaches those chunks.

## Serving it

A SPA answers every URL with the same HTML and lets the client sort out the rest. `vite preview` already does that, so a deep link works locally without configuration. Static hosts need telling:

| Host | Fallback |
| --- | --- |
| GitHub Pages | copy `index.html` to `404.html` after the build |
| Netlify | `/* /index.html 200` in `_redirects` |
| Cloudflare | `/* /index.html 200` in `_redirects` |
| Nginx or Caddy | `try_files $uri /index.html` |

The [GitHub Pages guide](https://pitlane.tools/deploy/github-pages.md) walks through the full workflow, including the base path a project site needs.

## Bundled dev mode

Vite's experimental [bundled dev mode](https://github.com/vitejs/vite/discussions/22746) serves your app as a Rolldown bundle during `vite dev` instead of as unbundled modules. Pitlane's SPA mode works with bundled dev mode today, HMR included:

```ts
export default defineConfig({
    plugins: [remix({ server: false })],
    experimental: {
        bundledDev: true,
    },
});
```

**Bundled dev mode does not yet support SSR apps in its experimental form**. Bundled dev mode serves bundle entrypoints only, so the client module URLs a server-side renderer writes into its HTML resolve to nothing. Upstream tracks server environments as [Phase 4 of the bundled-dev roadmap](https://github.com/vitejs/vite/discussions/22746), and it is still a prototype.

## Client rendering with a server

If you want a browser-rendered UI in front of routes that still run on the server, leave the default `server` setting alone for the plugin. Serving a client-rendered app from a server with server routes is easy in Remix:

### The shell

The document the server sends for every navigable route, written as a component rather than a template literal, so the markup is typed and the asset URL comes from the asset resolver:

```ts title="app/assets.ts"
import { createAssetResolver } from "pitlane/assets";
import manifest from "pitlane/assets/manifest";

export let assets = createAssetResolver(manifest);

export let scriptEntry = await assets.getScriptEntry("app/entry.browser.tsx");
```

```tsx title="app/shell.tsx"
import { scriptEntry } from "./assets.ts";

export function Shell() {
    return () => (
        <html lang="en">
            <head>
                <meta charSet="utf-8" />
                <title>My app</title>
                <script src={scriptEntry.href} type="module" />
            </head>
            <body>
                <div id="app" />
            </body>
        </html>
    );
}
```

`scriptEntry.href` is the URL of `app/entry.browser.tsx`: the dev URL during `vite dev` and the hashed chunk after a build. That one call is the whole reason the shell does not need to know its own build output. The [Vite plugin guide](https://pitlane.tools/guides/vite-plugin.md#document-assets) covers the resolver, including stylesheets and preloads for apps that need them.

### The server

`renderToString` from `remix/component/server` turns the shell into HTML, and `createHtmlResponse` puts the DOCTYPE and the content type on it. Data routes answer next to it, in the same router:

```tsx title="app/entry.server.tsx"
import { createHtmlResponse as html } from "remix/response/html";
import { createRouter } from "remix/router";
import { renderToString } from "remix/component/server";

import { getPosts } from "./posts.ts";
import { routes } from "./routes.ts";
import { Shell } from "./shell.tsx";

export let router = createRouter();

router.map(routes.posts, () => Response.json(getPosts()));

async function shell(): Promise<Response> {
    return html(await renderToString(<Shell />));
}

router.map(routes.home, () => shell());
router.map(routes.post, () => shell());

export default router;
```

`renderToString` renders the element tree and stops there. It emits no DOCTYPE, which is what `createHtmlResponse` is for. A shell without one puts the browser in quirks mode.

### The browser

This is what `scriptEntry.href` loads, and it is the same code SPA mode runs. Either shape from [Rendering](#rendering) works here. A `createRoot` tree:

```tsx title="app/entry.browser.tsx"
import { createRoot } from "remix/component";

import { App } from "./app.tsx";

let container = document.getElementById("app");
if (!container) throw new Error("missing #app container");

createRoot(container).render(<App />);
```

Or a client router through `remix/spa`, which is the shape that earns the shell in the first place, because now the URL means something:

```tsx title="app/router.tsx"
import { createRouter } from "remix/router";
import { render } from "remix/spa";

export let router = createRouter({ middleware: [render()] });

router.get("/", ({ render }) => render(<Home />));
router.get("/posts/:id", ({ render, params }) => render(<Post id={params.id} />));
```

```tsx title="app/entry.browser.tsx"
import { run } from "remix/spa";

import { router } from "./router.tsx";

let app = run(router);
await app.ready();
```

Two routers, and they are not the same one. The browser router owns what the user sees. The server router owns the shell and the data those views fetch. Both meet at the URL, so the server maps every navigable route to the shell. A deep link or a refresh has to arrive at HTML that boots the client router, which then resolves the path.

The shell's `<div id="app" />` is there for the `createRoot` shape. Under `remix/spa`, `run()` renders into the top frame and replaces the body the server sent, so the container goes unread and an empty `<body>` works just as well.

# Fetch server

Source: https://pitlane.tools/guides/fetch-server.md

> Serve a Vite app's development requests through the Fetch handler your server module exports, with fetchServer() from pitlane/vite-plugin-fetch-server, alone or beside assets().

`fetchServer()` connects `vite dev` to your application's server code. Every request Vite does not answer itself goes to the `fetch(request)` method of a server module you name, and its response goes back to the browser. Vite transforms that module like the rest of your app. An edit applies on the next request, without a server restart.

Any app can use the plugin. It needs no router, renderer, or Pitlane runtime, only a module that exports `{ fetch }`. It covers development only and leaves the production build and preview alone.

## Install

Through the umbrella package, which most apps already depend on:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The scoped package also works on its own, with Vite 8.1 or later as its peer dependency:

```sh
npm add -D @pitlane/vite-plugin-fetch-server
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Examples on this page import from `pitlane/vite-plugin-fetch-server`. With the scoped package, import the same `fetchServer` from `@pitlane/vite-plugin-fetch-server`.

## Write the server module

The module's default export is an object with a `fetch` method. It receives a standard `Request` and returns a `Response` or a promise of one:

```ts title="src/http.ts"
export default {
    greeting: "Hello from src/http.ts",

    async fetch(request: Request): Promise<Response> {
        let url = new URL(request.url);
        if (url.pathname === "/") return new Response(this.greeting);
        return new Response("Not found", { status: 404 });
    },
};
```

`fetch` is called as a method of the default export, so it can read the object's other properties through `this`, as `greeting` does here. A router object that exposes `fetch` qualifies too.

## Add the plugin

Pass the module's path as `entry`:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { fetchServer } from "pitlane/vite-plugin-fetch-server";

export default defineConfig({
    plugins: [fetchServer({ entry: "src/http.ts" })],
});
```

Run `vite dev` and open the printed URL. The page reads `Hello from src/http.ts`. Change `greeting`, save, and reload the page: the new text appears without a server restart.

`entry` is required. The plugin assumes no filename or directory, and it never derives the path from your build inputs, so it is the path you pass and nothing else. It is resolved the way Vite resolves a module the server loads, so a path relative to the project root works.

### Options

| Option | Default | Meaning |
| --- | --- | --- |
| `entry` | none, required | Path to the server module. |
| `environment` | `"ssr"` | The Vite environment that loads `entry`. It must be one whose modules run inside the dev server process. |

### With `assets()`

The plugin composes with the asset plugin from `pitlane/assets/vite-plugin`. Asset metadata and request serving stay separate concerns, each with its own plugin:

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { assets } from "pitlane/assets/vite-plugin";
import { fetchServer } from "pitlane/vite-plugin-fetch-server";

export default defineConfig({
    environments: {
        client: { build: { outDir: "dist/client" } },
        ssr: {
            build: {
                outDir: "dist/server",
                rolldownOptions: { input: "src/http.ts" },
            },
        },
    },
    plugins: [assets(), fetchServer({ entry: "src/http.ts" })],
});
```

The server build input and `entry` name the same file here because this app chose to. They are separate settings. The build input controls what `vite build` emits, while `entry` controls what `vite dev` serves.

A Remix app does not add this plugin itself. [`remix()`](https://pitlane.tools/guides/vite-plugin.md) composes it with its own server entry.

## What reaches your handler

The plugin is Vite's fallback for application requests. Requests Vite answers on its own come first, such as files in `public/` and modules the browser imports. Middleware from other plugins, such as `assets()`, also runs first. Whatever is left goes to your handler, including `/`. Unless you set Vite's `appType` yourself, the plugin sets it to `"custom"`, so Vite does not answer HTML requests from an `index.html`. An `appType` you set is kept as is.

The handler sees the request as the browser sent it:

- `request.url` is the full original URL, including any query string and the configured Vite `base`. With `base: "/app/"`, a request for `/app/echo?x=1` arrives as `http://localhost:5173/app/echo?x=1`.
- The method, headers, and body are passed through unchanged.
- The host and protocol come from the connection. `Forwarded`, `X-Forwarded-Host`, and `X-Forwarded-Proto` headers are ignored, so a client cannot rewrite `request.url` with them.

Responses keep their status line and every header, including repeated `Set-Cookie` headers. A streamed body reaches the browser chunk by chunk as your handler produces it, not after it finishes. When the client disconnects, `request.signal` aborts and a streaming body is cancelled, so long-running work can stop.

## Edits

Each request loads the module through Vite's module runner. After you edit the server module or anything it imports, the next request runs the new code. The plugin keeps no handler between requests, so there is no stale copy to restart away.

Edits do not reload the browser. This plugin only serves requests, so component hot module replacement, or a page refresh after a server edit, has to come from another Vite plugin or from you reloading the page.

## Errors

When a request fails, you get Vite's development error page and Vite logs `Internal server error:` with the message and stack in the terminal. The response status is 500, and a page with the Vite client loaded shows its error overlay. That covers:

- an error your `fetch` method throws or a promise it rejects;
- a server module or one of its imports that fails to load or to transform, such as a syntax error or a missing file;
- a server module whose default export has no `fetch` method.

A failed request never falls through to another handler or reuses an earlier response. Fix the code and the next request runs it.

An error after a streamed response has started cannot become an error page, because the status and headers are already sent. The connection closes instead.

## Configuration errors

These stop `vite dev` at startup with a message naming the problem:

- `entry` is missing or an empty string. That holds even when the environment has exactly one build input, or has an `index` input. Pass the path explicitly.
- `environment` names an environment the Vite config does not have.
- `environment` names an environment whose modules do not run inside the dev server process. Cloudflare's Vite plugin creates one of these: its code runs in workerd, and the Cloudflare plugin serves its requests. Leave `fetchServer()` out of that config rather than pointing it elsewhere.

## Limits

- Development only. The plugin does nothing during `vite build` or `vite preview`, and opens no port of its own. In production, run the built server module with your platform's server.
- The `environment` must run its modules in the dev server process, which Vite's default `ssr` environment does. Runtimes that serve requests themselves bring their own Vite integration.
- No trusted-proxy handling. During development the request URL always reflects the dev server's own host and protocol.

# Asset resolution

Source: https://pitlane.tools/guides/assets.md

> Resolve browser entries, stylesheets, preload hints, and import maps from a Vite build or dev server with pitlane/assets, in a Remix app or any other server-rendered app.

A server-rendered page has to name its browser assets: the script that boots the page, the stylesheets it needs, `modulepreload` hints for the chunks that script imports, and the chunk of every island it hydrates. Those URLs differ between `vite dev` and a production build, and only the bundler knows them.

`pitlane/assets` answers those questions through an asset resolver you construct from a manifest. The Vite plugin supplies the manifest. The resolver turns source paths such as `app/entry.browser.ts` into the URLs the current dev server or build produced for them. It imports nothing from Remix or any UI library, so the same object serves a Remix document, a React or Vue renderer, or a hand-written HTML string.

The resolver has the resolution methods of the asset server from `remix/assets`: `getScriptEntry`, `getHref`, `getPreloads`, and `getImportMap`, plus `getStylesheets`. A Remix document written for that asset server runs unchanged. Only the file that constructs it differs.

## Install

Through the umbrella package, which most apps already depend on:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The scoped package also works on its own. Add it to `dependencies`, not `devDependencies`, since application code imports its runtime:

```sh
npm add @pitlane/assets
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Examples on this page import from `pitlane/assets`. With the scoped package, import the same names from `@pitlane/assets`.

The Vite adapter needs Vite 8.1 or later. The resolver and [manifest generator](https://pitlane.tools/guides/asset-build.md) do not require Vite.

## Setup

`remix()` from `pitlane/vite-plugin-remix` installs the assets plugin itself. Pass its options as `remix({ assets: { … } })`. Any other Vite app adds `assets()` directly:

```ts title="vite.config.ts"
import { assets } from "pitlane/assets/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [assets()],
});
```

Then construct the resolver once, in a module of your own:

```ts title="app/assets.ts"
import { createAssetResolver } from "pitlane/assets";
import manifest from "pitlane/assets/manifest";

export let assets = createAssetResolver(manifest);

export let scriptEntry = await assets.getScriptEntry("app/entry.browser.ts");
export let stylesheetHref = await assets.getHref("app/styles.css");
```

The plugin replaces `pitlane/assets/manifest` with the manifest for the current dev server or build. Each resolver method returns a promise. In `app/assets.ts` above, the document's own entry and stylesheet resolve once, when the module loads.

The scoped packages work the same way: `@pitlane/assets`, `@pitlane/assets/manifest`, and `@pitlane/assets/vite-plugin`.

## Source keys

Every method takes a source key: the module's path relative to the project root, with forward slashes. These all name the same module:

| Spelling | Why you might see it |
| --- | --- |
| `app/counter.tsx` | The plain form |
| `./app/counter.tsx` | A relative-looking path |
| `/app/counter.tsx` | A leading slash marks the project root, not the filesystem root |
| `file:app/counter.tsx` | The island identity `remix()` writes |
| `app/counter.tsx#Counter` | An export fragment, which lookups ignore |

`.` and `..` segments inside a key collapse, so `app/lib/../counter.tsx` is `app/counter.tsx`. A module outside the project root keeps its leading `..` segments. A linked workspace package might have the key `../shared/widget.ts`. That key works from any checkout directory as long as the project and the linked package keep the same relative layout.

Absolute file URLs are not keys. `file:///Users/me/app/counter.tsx` and `file:/Users/me/app/counter.tsx` throw an error asking for the portable key. A manifest never contains the build machine's checkout path, so a deployed server has nothing to compare an absolute path against.

`#` starts the export fragment, so a source file whose name contains `#` cannot be a key.

## Resolver methods

| Method | Returns |
| --- | --- |
| `getScriptEntry(key)` | `{ href, preloads, importMap }` for a browser entry |
| `getHref(key)` | The URL of a browser entry, a stylesheet, or another emitted asset |
| `getPreloads(key \| key[])` | `modulepreload` URLs for scripts |
| `getStylesheets(key \| key[])` | Stylesheet URLs a module needs, from the client graph and this server's |
| `getImportMap(key \| key[])` | The client build's import map |

Methods that take an array return one list in argument order, with duplicate URLs removed.

### `getScriptEntry`

```ts
let { href, preloads, importMap } = await assets.getScriptEntry("app/entry.browser.ts");
```

In a build, `href` is the emitted chunk and `preloads` lists that chunk followed by its static imports, shallowest first. Dynamic imports are not preloaded. `importMap` is the complete client map when [chunk import maps](#chunk-import-maps) are on, and `{ imports: {} }` otherwise.

Under `vite dev`, `href` is the module's dev URL (`/app/entry.browser.ts`), `preloads` is `[]`, and `importMap` is `{ imports: {} }`.

### `getHref`

Returns the URL of a registered browser entry, a stylesheet, or another asset, such as an image you reference by key. Under `vite dev` it returns the dev URL.

### `getPreloads`

Each script key contributes its chunk and its static JavaScript dependencies, never their CSS, so you can render every result as `<link rel="modulepreload">`. A stylesheet key passed explicitly contributes its own URL. Render those as `<link rel="preload" as="style">`, not as `modulepreload`. Under `vite dev` the result is always `[]`.

### `getStylesheets`

Returns the stylesheets a module needs, following its static imports. A dependency's stylesheets come before the stylesheets of the module importing it. Modules loaded only through `import()`, such as lazy routes, are left out.

Every lookup reads the client build's graph and the graph of the server environment the running server was built as. A key only has to appear in one of them, and the result combines both:

```ts
let stylesheets = await assets.getStylesheets(["app/entry.server.tsx", "app/entry.browser.ts"]);
```

When both builds emit a stylesheet with the same contents, the result links it once, as the client build's file. Vite emits one CSS file per chunk. A server chunk that combines a shared stylesheet with its own produces a file unlike the client's, and both are linked. The Remix document queries the server entry alone, with no overlap.

A server's manifest describes those two graphs and no other server environment's, in development and in a build alike. A key that only another server environment imports fails with the missing-module error. There is no option to read one graph alone: a document needs the stylesheets of both. A stylesheet lookup never turns the module into a browser entry, so asking for the CSS of `app/entry.server.tsx` does not compile your server code for the browser.

With Vite's `build.cssCodeSplit: false`, the environment emits one combined stylesheet. Lookups return that stylesheet rather than a route-specific subset. It also contains the lazy-module CSS that Vite combines into it.

Under `vite dev`, CSS from server graphs comes back as dev URLs. CSS a browser module imports is injected by Vite itself, so the client graph reports none.

### `getImportMap`

Checks that each key is part of the client graph, then returns the complete client import map, not a subset for those keys. Lazy modules and later islands need the rest of it. An empty array returns `{ imports: {} }`, as do `vite dev` and builds with chunk import maps off.

## Registering browser entries

Only a browser entry has a script URL. The plugin registers one when:

- a server module calls `getScriptEntry` or `getHref` on a resolver with a string literal, as `app/assets.ts` does above;
- you list it in `assets({ include: ["app/widgets/chart.ts"] })`, which is how a computed path gets registered;
- it is already a client input in your Vite config;
- another plugin declares it, as `remix()` does for each island. See [Declaring entries from another plugin](#declaring-entries-from-another-plugin).

A literal call counts only when its receiver is the result of `createAssetResolver()`, imported from `pitlane/assets` or `@pitlane/assets`, or a top-level variable holding that result. The variable still counts when the module copies it (`const resolver = assets`) or calls a copy of the constructor (`const make = createAssetResolver`), and when another module imports it by any name, through `export { assets } from "./assets.ts"` or `export * from "./assets.ts"`, or as a default export. A copy counts only as a plain variable, not a destructured one. Each of those names needs exactly one declaration in its module. A second one anywhere in that module, even a parameter of an unrelated function, disqualifies every call through the name. A same-named method on another object registers nothing, and neither does a `createAssetResolver` imported from another module, a call through a namespace import (`import * as`), a function parameter, or `this`. Nor does a resolver imported from a dependency that Vite externalizes, since the plugin does not read that package's source; construct the resolver in a module of your own app, or list those keys in `include`.

`getStylesheets`, `getPreloads`, and `getImportMap` only read graphs the build already has. They register nothing, and routes discovered through `import.meta.glob` need no second list.

A script registered this way is emitted with its exports intact, and a stylesheet as a CSS file. Asking for a server module's stylesheets never puts that module in the client build.

An app with no browser entries, such as a server-rendered app that only links stylesheets, still builds without an `index.html`.

### Declaring entries from another plugin

During development, plugins declare discovered browser entries through `api.setBrowserEntries()` rather than emitting chunks. Find the `pitlane-assets` plugin in `configResolved`:

```ts
import type { AssetsPluginApi } from "pitlane/assets/vite-plugin";

let api: AssetsPluginApi;

// Inside your plugin object:
configResolved(config) {
    let assetsPlugin = config.plugins.find(plugin => plugin.name === "pitlane-assets");
    if (!assetsPlugin) throw new Error("my-islands needs assets() from pitlane/assets/vite-plugin.");
    api = assetsPlugin.api;
},
```

Then, in the transform hook where your plugin already finds its islands in a server module, report them for that module:

```ts
if (this.environment.mode === "dev") {
    api.setBrowserEntries({ environment: this.environment.name, owner: id, entries: browserModules });
}
```

`environment` is the server environment doing the transform, and `owner` is the resolved id of the module being transformed. `browserModules` holds the resolved ids of the browser modules that module declares, such as `(await this.resolve(specifier, id))?.id` for each island specifier your plugin found.

- Each call replaces everything that module declared in that environment. The same module can declare different entries in `ssr` and in another server environment without either overwriting the other.
- An empty `entries` list removes the declaration. Call the method on every transform that could declare entries, including ones that find none. Otherwise a deleted island stays registered.
- A declaration counts only while its owner is part of that environment's server graph, including lazy routes. Once nothing imports the owner, or the file is deleted, its entries are dropped.

Builds keep using ordinary client inputs and `this.emitFile`. `remix()` calls this API for its islands, so a Remix app needs none of this code.

## Under `vite dev`

No bundle exists during development. The plugin builds the manifest from Vite's module graph the first time a server environment imports `pitlane/assets/manifest`. To learn which stylesheets each module imports, it transforms the server graph and the client graphs of registered browser entries without running that code, so lazy routes stay unloaded until a request needs them. The result is plain data with no live connection to Vite, so it reaches a Cloudflare worker the same way it reaches Node.

Development follows server entries imported by Vite's module runner as well as configured build inputs. The development entry can differ from the production entry without losing its asset metadata.

When you add or remove an import, a glob route, or a browser entry, the plugin invalidates that environment's manifest and every module that imports it. The next import of your server entry builds a fresh manifest and re-runs those modules, so `await assets.getStylesheets(…)` at the top of a module sees the change too. A rebuild transforms only the files that changed. Every other module keeps the imports recorded the last time it was transformed. `fetchServer()` and Cloudflare's dev server re-import the entry on each request. A custom server that holds on to a handler across requests will keep serving the old one. Editing only a stylesheet's rules leaves the manifest alone, and Vite updates the CSS in place.

A stylesheet used on both sides keeps its server-rendered `<link>` instead of gaining a second browser-injected copy. This preserves the document's CSS cascade order. Rule edits update the linked stylesheet without resetting browser state.

Browser code cannot import the manifest. It describes your server graph, so a browser module that imports it throws a server-only error when it runs.

## Plugin options

| Option | Default | Meaning |
| --- | --- | --- |
| `include` | `[]` | Source keys of browser entries the server code names with computed strings |
| `serverEnvironments` | `["ssr"]` | The Vite environments that run your server. Each one's server bundle, or dev server graph, receives a manifest naming it, which `getStylesheets` reads by default alongside the client. Importing the manifest from any other server environment is an error naming the environment and this option |
| `chunkImportMap` | off | Turns on [chunk import maps](#chunk-import-maps) for the client build |
| `allowFiles` | unset | Files and globs the browser may load. Setting it turns on the [browser boundary](#browser-boundary) |
| `allowPackages` | `[]` | Packages the browser may load, with their dependencies. Requires `allowFiles` |
| `denyFiles` | `[]` | Files and globs the browser may not load, even when allowed. Requires `allowFiles` |

Before building the client, the plugin builds the server environments, because they reveal which modules are browser entries. A platform plugin that orchestrates builds itself, such as Cloudflare's, keeps doing so, and each environment builds once. `vite build --watch` is not supported: its watchers start every environment at once, so the client fails with the build-order error. Use `vite dev` while editing.

The build writes each server environment's manifest as a separate module at the root of that environment's output directory, and the server bundle imports it by a relative path. `pitlane/assets/vite-plugin` exports the file name as `ASSETS_MANIFEST_FILE`. A host that deploys a single module has to bundle that file into the server bundle after `vite build` finishes. Read the name from the constant rather than writing it out.

The plugin replaces both `pitlane/assets/manifest` and `@pitlane/assets/manifest`, so either specifier works in `app/assets.ts`.

## Browser boundary

By default, every file a browser module imports reaches the browser. The build bundles it into the client output, and the dev server serves it. The asset server from `remix/assets` is stricter and serves only the files you allow. `assets()` accepts the same three options to hold a Vite app to that boundary:

```ts
assets({
    allowFiles: ["app/**/public/**"],
    allowPackages: ["remix", "@shopify/hydrogen"],
    denyFiles: ["app/**/*.test.*", "app/**/*.spec.*"],
});
```

With `remix()`, pass them as `remix({ assets: { allowFiles, allowPackages, denyFiles } })`. The same values then describe what the Node asset server serves and what the Vite build lets through.

`allowFiles` turns the boundary on. `allowPackages` and `denyFiles` only refine it, so passing either one without `allowFiles` is a configuration error.

The options match the way `remix/assets` reads them:

- `allowFiles` and `denyFiles` hold file paths and globs. Relative values resolve from the Vite root. An absolute file path matches that file, and a directory path matches every file below it.
- `allowPackages` holds exact package names, such as `remix` or `@shopify/hydrogen`, never a path inside one. Surrounding whitespace is trimmed. Each package's `dependencies` and installed `optionalDependencies` are allowed with it, and so are their own dependencies. Peer dependencies are not, so list each peer the browser loads. A name that the project root cannot resolve fails with `Could not resolve allowed package "name".`
- `denyFiles` takes precedence over both lists.
- `@oxc-project/runtime` is always allowed, because compilers inject imports of its helpers into code you wrote.

### What a build checks

`vite build` fails when a file outside the boundary would reach the browser:

- any file in the client module graph, even a module whose code tree-shaking drops, because the asset server would refuse its import;
- any stylesheet or asset a stylesheet reads in, such as an `@import`ed stylesheet, a preprocessor partial, or a `url()` target the build emits or inlines;
- any file a worker bundle contains, for a worker the client starts with `new Worker(new URL(…, import.meta.url))` or imports with `?worker`;
- the stylesheets a server environment links and the assets its code imports, which the build copies into the client output.

Vite's CSS plugin also reports files that PostCSS plugins watch, such as Tailwind's content files. The boundary takes only stylesheets and the file types Vite treats as assets from those reports, so a watched source file passes. A watched stylesheet counts as read in even when the plugin never inlines it. A file a CSS module names in `composes: … from` is not checked, because Vite reports no dependency on it.

The error lists every such file, with the module or stylesheet that imports it where there is one:

```txt
[assets] Outside the browser boundary:
  app/data/storefront.ts (imported by app/public/island.ts): not in allowFiles or allowPackages
  app/public/island.test.ts (imported by app/public/island.ts): matches denyFiles "app/**/*.test.*"
```

### What `vite dev` checks

Transforming a module outside the boundary for the browser fails with the same message, and Vite shows it in its error overlay. So does transforming a stylesheet that imports a stylesheet, or references an image, font, or other Vite asset type, from outside the boundary. Any other file a stylesheet references fails when the browser requests it. The manifest transforms the client graphs of browser entries too, so a server request that builds the manifest fails with the same error. A file the dev server sends as it is, such as an image a stylesheet references, gets a `500` response carrying that message.

Vite prebundles dependencies under `vite dev`, and the boundary checks a prebundled dependency by the package entry it came from. A package that reaches the browser only inside another prebundled package is caught by the build.

Neither mode checks HTML documents, Vite's own client runtime, virtual modules, or files in Vite's `publicDir`, which Vite publishes as they are. The modules and assets an HTML document loads are checked like any others, and so is an HTML file a module imports as text with `?raw`.

## Public URLs and `base`

Build URLs carry Vite's `base`. With `base: "/docs/"`, an entry resolves to `/docs/assets/entry.browser-a1.js`. A CDN base such as `https://cdn.example/app/` produces absolute URLs on that host.

A relative base such as `./` produces relative URLs like `./assets/entry.browser-a1.js`, which the browser resolves against the URL of the document it is reading. A document served at a nested route, such as `/blog/hello`, would look for `/blog/assets/…`. So a server-rendered app with nested routes needs an absolute base, or a `<base href>` element pointing at the directory its assets are served from.

## With Remix

Pass the resolver to Remix's own `render()` middleware. When an island renders, Remix calls `assets.getScriptEntry("file:app/counter.tsx")` and hoists the result's preloads into the head, so islands get preload hints without any code of yours:

```tsx title="app/entry.server.tsx"
import { render } from "remix/middleware/render";
import { createRouter } from "remix/router";

import { assets } from "./assets.ts";

let renderMiddleware = render({ assets });

export let router = createRouter({ middleware: [renderMiddleware] });
```

The document reads the browser entry like the `remix` CLI template's document does:

```tsx title="app/document.tsx"
import type { Handle, RemixNode } from "remix/component";
import { ImportMap } from "remix/component/server";

import { scriptEntry, stylesheetHref } from "./assets.ts";

export function Document(handle: Handle<{ children?: RemixNode }>) {
    return () => {
        let { href, importMap, preloads } = scriptEntry;

        return (
            <html lang="en">
                <head>
                    <meta charSet="utf-8" />
                    <link rel="stylesheet" href={stylesheetHref} />
                    <ImportMap value={importMap} />
                    {preloads.map(preloadHref => (
                        <link key={preloadHref} rel="modulepreload" href={preloadHref} />
                    ))}
                    <script type="module" src={href} />
                </head>
                <body>{handle.props.children}</body>
            </html>
        );
    };
}
```

A renderer you call directly, such as `renderToStream`, resolves an island by splitting off the export name itself: `{ ...(await assets.getScriptEntry(entryId)), exportName }`.

## Without Remix

Any renderer can use the returned strings. This builds a document head as plain HTML, escaping each URL for the quoted attribute it goes into:

```ts
import { renderImportMap } from "pitlane/assets";

import { assets } from "./assets.ts";

let attribute = (text: string) =>
    text.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");

let entry = await assets.getScriptEntry("src/entry.client.ts");
let stylesheets = await assets.getStylesheets("src/entry.server.ts");

let head = [
    renderImportMap({ value: entry.importMap }),
    ...stylesheets.map(href => `<link rel="stylesheet" href="${attribute(href)}">`),
    ...entry.preloads.map(href => `<link rel="modulepreload" href="${attribute(href)}">`),
    `<script type="module" src="${attribute(entry.href)}"></script>`,
].join("\n");
```

Escape URLs before putting them in HTML attributes. A configured base or filename can contain a quote or `<`. JSX handles attribute escaping for you. Plain HTML strings need the `attribute` function above. `renderImportMap` escapes its own output.

### Framework examples

Five small apps under [`packages/assets/examples`](https://github.com/pitlane-tools/pitlane/tree/main/packages/assets/examples) show the resolver with a renderer that is not Remix. Each one installs `@pitlane/assets` as an ordinary dependency and serves development requests through [`fetchServer()`](https://pitlane.tools/guides/fetch-server.md). The document is an `@remix-run/html-template` template. The build has a client and a server environment, with a verify script and a browser check run against the output.

| Example | Shows |
| --- | --- |
| `react-router` | React 19 with React Router's data router. Routes come from `import.meta.glob` with a source key each; the matched keys go to `getPreloads` and `getStylesheets` |
| `vue-router` | Vue Router with pages written in Vue's Vapor mode inside a server-rendered shell |
| `solid-router` | Solid 2.0 with Solid Router: the pages are lazy routes registered as browser entries, so Solid's own asset resolver gets each page's script URL |
| `preact-islands` | Preact islands served through `@remix-run/fetch-router`; a transform registers each island with a literal `getScriptEntry` call |
| `lit-islands` | Lit elements rendered with declarative shadow roots and hydrated in place; a registry module holds the literal `getScriptEntry` calls |

No route-specific API is involved. The manifest indexes every module the glob discovered, so a computed key works in the metadata methods. Vue Vapor and Solid 2.0 are prereleases, pinned exactly in those two examples.

## Chunk import maps

Off by default for `assets()`, and on by default under `remix()`. With them off, chunks import each other by their final URLs, and a document needs no import map.

Turning them on makes Vite give each chunk a stable identifier and rewrite imports to use it, then emit a map from those identifiers to the current hashed files. When only a dependency's code changes, its map target can change while importing chunks keep the same bytes and filenames.

```ts
assets({ chunkImportMap: true });
// the Remix plugin has them on; turn them off with:
remix({ assets: { chunkImportMap: false } });
```

Vite's own `build.chunkImportMap` in the client environment's config also sets it. When both are set, the plugin option wins, so `chunkImportMap: false` overrides a native `true`. With neither set, the plugin's default applies.

With maps on, `getScriptEntry` and `getImportMap` return the complete map. Every document must deliver it before any `modulepreload` link or module script. Remix's `<ImportMap>` component handles that, and other renderers can use [`renderImportMap`](#rendering-the-import-map).

Preloads keep listing emitted chunk URLs. An island's `moduleUrl` in the page is also the emitted chunk URL.

Requirements and limits:

- Browsers need import maps and `import.meta.resolve`.
- The option cannot be combined with Vite's `experimental.renderBuiltUrl`. The build stops with an error naming both. `renderBuiltUrl` alone works with maps off, so a Remix app that uses it passes `remix({ assets: { chunkImportMap: false } })`.
- Caching holds only for changes to a dependency's content. Changing exports, chunk membership, CSS, assets, or compiler output can still change importing chunks.
- Vite derives some identifiers from the module's absolute path. Building the same source from a different checkout directory changes every chunk that imports an entry or island chunk.
- Cache headers and keeping old hashed files available are your deployment's job.

Choose vendor groups through Vite's `environments.client.build.rolldownOptions.output.codeSplitting.groups`. `[{ name: "vendor", test: /node_modules/ }]` puts dependency modules in a vendor group. Pitlane does not choose groups for you.

## Rendering the import map

`renderImportMap({ value, nonce })` returns a complete `<script type="importmap">` element as a string:

```ts
import { renderImportMap } from "pitlane/assets";

renderImportMap({
    value: { imports: { "/assets/counter-Bj6c.js": "/assets/counter-BuA5.js" } },
    nonce: "r4nd0m",
});
// <script type="importmap" nonce="r4nd0m">{"imports":{"/assets/counter-Bj6c.js":"/assets/counter-BuA5.js"}}</script>
```

- It writes every `<` in the map as the JSON escape `\u003c`, so no key or URL can close the script element. The browser parses the same strings back.
- `nonce` is written as an escaped, quoted attribute. The helper neither generates a nonce nor sets a Content Security Policy.
- It returns `""` when the map has no mappings in `imports`, `scopes`, or `integrity`, including scopes that are all empty. That covers `vite dev` and builds with maps off, where it renders nothing.
- It serializes one map. It does not merge maps or install them in a live page. Insert the string into server-rendered HTML before your module scripts, through your renderer's raw-HTML mechanism. Setting it with client-side `innerHTML` does not install a map.

## Outside Vite

Published as is, `pitlane/assets/manifest` exports `{ mode: "unavailable" }`. Constructing a resolver from it succeeds, so importing `app/assets.ts` in a test runner or type checker does not fail. Every method call then rejects with an error explaining how to supply a manifest.

A test, or a build that Vite did not run, can pass a manifest object of its own to `createAssetResolver`, or alias `pitlane/assets/manifest` to a module that exports one. [Manifest integrations](https://pitlane.tools/guides/asset-build.md) describes how another bundler produces one with `createAssetManifest`.

## Errors

Each error names the method, the key, and the environment it looked in.

| Message begins | Cause | Fix |
| --- | --- | --- |
| `assets.getScriptEntry("…") has no asset manifest to read` | The manifest is the published `{ mode: "unavailable" }` | Add `assets()` or `remix()` to your Vite config, or pass a manifest |
| `… found no browser entry "…" in the "client" environment. The module is in the "ssr" graph but is not registered as a browser entry.` | A server module, or one the build saw, was never registered | Pass the key to the resolver's `getScriptEntry` as a string literal, or list it in `assets({ include })` |
| `… found no browser entry "…" in the "client" environment. No environment's graph contains the module.` | Nothing in the build has that key | Check the spelling, then register it as above |
| `assets.getHref("…") found no browser entry or asset` | The key is neither a registered entry nor an emitted asset | Register it as above |
| `… found no module "…" in the "client" environment's graph` | A preload, stylesheet, or import-map lookup for a module the graphs it reads do not contain | Check the key and the environment |
| `… received an absolute file URL` | The key was `file:///…` or `file:/…` | Use the key relative to the project root |

Only a missing browser entry suggests `assets({ include })`. A stylesheet or preload lookup never asks you to emit a server module into the client build.

# Manifest integrations

Source: https://pitlane.tools/guides/asset-build.md

> Produce an asset manifest from any bundler's output with createAssetManifest from pitlane/assets/build, and consume it through createAssetResolver without Vite.

The resolver from [`pitlane/assets`](https://pitlane.tools/guides/assets.md) reads a manifest of emitted browser URLs and per-module JavaScript and CSS dependencies. The Vite plugin produces this manifest for Vite apps. Other build systems need an integration that supplies the same information.

`createAssetManifest(build)` from `pitlane/assets/build` (or `@pitlane/assets/build`) does the shared work once you describe what your bundler emitted. It walks the dependency graph to order preloads and stylesheets, then resolves public URLs into the manifest `createAssetResolver` reads. The Vite plugin calls this same function, so a manifest from your integration behaves exactly like one from Vite.

The generator does no file I/O: your integration reads the bundler's output and writes the manifest. It adds no dependency edges of its own and generates no import map. It imports no bundler, Vite included.

## What your integration supplies

```ts
import { createAssetManifest } from "pitlane/assets/build";

let manifest = createAssetManifest({
    base: "/",
    environments: {
        client: {
            role: "client",
            chunks: {
                entry: {
                    file: "assets/entry.browser-a1.js",
                    modules: ["app/entry.browser.ts"],
                    imports: ["runtime"],
                    dynamicImports: ["counter"],
                    stylesheets: ["assets/entry.browser-c3.css"],
                },
                counter: {
                    file: "assets/counter-d4.js",
                    modules: ["app/counter.tsx"],
                    imports: ["runtime"],
                    dynamicImports: [],
                    stylesheets: ["assets/counter-e5.css"],
                },
                runtime: {
                    file: "assets/runtime-b2.js",
                    modules: ["app/runtime.ts"],
                    imports: [],
                    dynamicImports: [],
                    stylesheets: [],
                },
            },
            entries: { "app/entry.browser.ts": "entry", "app/counter.tsx": "counter" },
            assets: { "app/styles.css": "assets/styles-i9.css" },
        },
        ssr: {
            role: "server",
            chunks: {
                server: {
                    file: "entry.server.js",
                    modules: ["app/entry.server.tsx", "app/counter.tsx"],
                    imports: [],
                    dynamicImports: [],
                    stylesheets: ["assets/document-g7.css", "assets/counter-e5.css"],
                },
            },
            entries: {},
            assets: {},
        },
    },
});
```

The fields of `build`:

| Field | Contents |
| --- | --- |
| `base` | The public base relative filenames resolve against: `/`, `/docs/`, `https://cdn.example/app/`, `./`, or `""` |
| `environments` | Every environment that participated, by name. Exactly one has `role: "client"`; the others are `"server"` |
| `importMap` | The import map your bundler generated for the client, if it generated one |

Each environment has:

| Field | Contents |
| --- | --- |
| `chunks` | Every emitted JavaScript chunk, keyed by an identity you choose. Keys only need to be unique within the environment |
| `entries` | Browser-entry source keys mapped to chunk identities. Only the client environment has entries |
| `assets` | Source keys mapped to emitted non-script files, such as a stylesheet entry or an image |

Each chunk has:

| Field | Contents |
| --- | --- |
| `file` | The emitted filename, or an absolute public URL |
| `modules` | Source keys of every module the chunk contains |
| `imports` | Identities of the chunks it imports statically, in import order |
| `dynamicImports` | Identities of the chunks it loads through `import()` |
| `stylesheets` | Emitted stylesheet filenames, or absolute public URLs, the chunk requires |

All four lists are required on every chunk, even when they are empty.

### Source keys

Source keys are paths relative to the project root with forward slashes, such as `app/counter.tsx`. A module outside the root, such as a linked workspace package, keeps leading `..` segments: `../shared/widget.ts`. Convert your bundler's absolute paths and `file:///` URLs to this form before passing them in. A key the build machine's checkout path leaks into cannot match on another machine. The generator rejects absolute file URLs.

Keys are normalized the way the resolver normalizes them: `./app/a.ts`, `/app/a.ts`, and `file:app/a.ts` are all `app/a.ts`, and `.` and `..` segments inside a key collapse. Resolve symlinks the way your bundler does, consistently, so one module has one key.

### Public URLs

A `file`, stylesheet, or asset value that is relative resolves against `base`, with a `/` inserted when `base` lacks a trailing one. An absolute value is used as is. That means a value starting with `/` (including `//`) or with a URL scheme such as `https:`.

| `base` | `assets/a.js` becomes |
| --- | --- |
| `/` | `/assets/a.js` |
| `/docs/` or `/docs` | `/docs/assets/a.js` |
| `https://cdn.example/app/` | `https://cdn.example/app/assets/a.js` |
| `./` | `./assets/a.js` |
| `""` | `assets/a.js` |

## What the generator computes

For every module in every environment, it records the module's preloads and stylesheets:

- Preloads start with the chunk holding the module, followed by every chunk reachable through static `imports`, shallowest first. Chunks at the same depth keep the order your `imports` lists give them. Each URL appears once.
- Stylesheets come from the `stylesheets` of the same chunks, with a dependency's listed before those of the chunk importing it. Each URL appears once.
- Edges in `dynamicImports` must name real chunks. The generator validates those references without adding their preloads or stylesheets to the importer.
- A cycle of imports is walked once. Each chunk in it appears once.
- A module in several chunks gets the union of every chunk's results, so report every chunk that contains it.

A browser entry's preloads always start with its own entry chunk, even when your `modules` lists leave the entry module out.

Environments stay separate. A server environment's graph never contributes to the client's metadata, and a module that appears only in a server graph never becomes a browser entry. That is what lets an app ask for a server module's stylesheets without compiling the server module for the browser.

The returned manifest has `mode: "build"`, `entries` and `assets` mapped to public URLs, per-environment `modules` metadata, and `importMap` set to your bundler's map or `{ imports: {} }`. It is plain JSON-compatible data.

## Writing and consuming the manifest

The generator leaves `serverEnvironment` unset, because one build can serve several servers. Set it to the environment a server was built as when you hand that server its manifest. It decides which server graph `getStylesheets` reads by default:

```ts
import { createAssetResolver } from "pitlane/assets";

let assets = createAssetResolver({ ...manifest, serverEnvironment: "ssr" });

await assets.getScriptEntry("app/counter.tsx");
// { href: "/assets/counter-d4.js",
//   preloads: ["/assets/counter-d4.js", "/assets/runtime-b2.js"],
//   importMap: { imports: {} } }

await assets.getStylesheets("app/entry.server.tsx");
// ["/assets/document-g7.css", "/assets/counter-e5.css"]
```

Getting the manifest to the server is your integration's job. Serialize it with `JSON.stringify` into a module in the server's output. Then either alias `pitlane/assets/manifest` to that module, so application code written for the Vite plugin runs unchanged, or import the object directly and pass it to `createAssetResolver`.

Copy any files a server environment emitted, such as stylesheets imported only by server code, into the client's public output, so their URLs resolve.

## Errors

The generator stops at the first problem and names the environment and the chunk or key involved.

| Message | Cause |
| --- | --- |
| `createAssetManifest() needs exactly one client environment; found none.` | No environment has `role: "client"`, or more than one does |
| `chunk "…" in the "…" environment imports "…", which is not a chunk in that environment.` | An `imports` or `dynamicImports` edge names a missing chunk |
| `browser entry "…" in the "…" environment names chunk "…", which is not a chunk in that environment.` | An entry points at a missing chunk |
| `the "…" environment lists browser entries, but only the client environment has them.` | A server environment has `entries` |
| `chunk "…" in the "…" environment has no file.` | A chunk has no `file` |
| `chunk "…" in the "…" environment has no imports list.` | A chunk is missing one of its four lists |
| `source key "…" maps to "…" in the "…" environment and "…" in the "…" environment.` | Two spellings of one key, or two environments, name different entries or assets for it |
| `source key "…" in the "…" environment is an absolute file URL.` | A key was not normalized to a project-relative path |

The generator cannot detect a fact your integration omitted. A chunk whose `imports` list is incomplete produces incomplete preloads without an error.

## Rsbuild integration example

Pitlane has no Rsbuild plugin. The [Rsbuild example](https://github.com/pitlane-tools/pitlane/tree/main/packages/assets/examples/rsbuild) shows what an integration for another bundler looks like end to end. Its small plugin, `pitlane-assets.ts`, hands Rsbuild's real compilations to `createAssetManifest` and writes the result for a Node server, which reads it with `createAssetResolver`. The plugin is a file the application owns, not a supported Pitlane API. The server renders the document with `@remix-run/html-template`, which escapes each URL the resolver returns, and serves it through `@remix-run/node-fetch-server`, the adapter Pitlane's Fetch server plugin also uses. The example installs those two, `@pitlane/assets`, and `@rsbuild/core@2.2.12`, and neither Vite nor the `remix` package.

### The output it assumes

The example builds two Rsbuild environments:

- `web` targets browsers with `output.module: true`. Rspack emits every chunk as an ES module and loads lazy chunks with `import()`. An entry chunk statically imports the other chunks its entrypoint needs at startup, so the entry's URL is the only module script a document needs.
- `node` targets Node as ES modules, with `output.emitCss: true` so stylesheets the server imports are written as files.

The plugin checks that the `web` compilation uses `output.module`, the `module` chunk format, and `import` chunk loading, and fails the build for any other combination. Rsbuild's generated HTML is turned off, because the server renders the document.

### What the plugin reads

In `onAfterEnvironmentCompile`, the plugin reads each environment's Rspack compilation from `stats.compilation`:

| `createAssetManifest` input | Read from the compilation |
| --- | --- |
| environment `role` | `client` for the `web` target, `server` for `node` |
| chunk identity | the chunk's id |
| `file` | the chunk's one `.js` file |
| `stylesheets` | the chunk's `.css` files |
| `modules` | every module in the chunk, with concatenated modules expanded into their parts |
| `imports` | for an entrypoint's entry chunk, the entrypoint's other chunks |
| `dynamicImports` | the chunks of every lazy chunk group whose `import()` sits in a module of this chunk |
| `entries` | each client entrypoint's entry module, mapped to its entry chunk |
| `assets` | each emitted file whose asset info names a `sourceFilename` |

Source keys are module paths relative to the project root, taken after Rspack resolves symlinks, so a linked module outside the root keeps its leading `../`. Once every environment has compiled, `onAfterBuild` passes the collected graphs to `createAssetManifest` with the `web` environment's `output.assetPrefix` as `base`. It then copies the server's stylesheets into the `web` output and writes the manifest, with `serverEnvironment: "node"`, to `dist/server/pitlane-assets-manifest.json`. The server reads that file once at startup and passes it to `createAssetResolver`.

### Limits

- Only `rsbuild build`. The development server, hot module replacement, and watch rebuilds are not translated.
- Only the browser ES module output above. Classic scripts, `output.module: false`, and runtime chunks that HTML loads with separate script tags are not handled.
- A lazily imported module's preloads name only its own chunk. Chunks Rspack loads beside it in parallel go in the importing chunk's `dynamicImports`, never in its static `imports`.
- `output.assetPrefix: "auto"` fails the build, because the manifest needs a known public base.
- Every chunk must have exactly one JavaScript file. A configuration that splits CSS into chunks of its own fails the build.
- Rspack generates no import map, so `importMap` is `{ imports: {} }` and `renderImportMap` returns an empty string.

### Run it

The example needs Node 22.18 or later, which runs its TypeScript configuration and checks directly. Copy the example directory out of the Pitlane repository, so that Node cannot find the Vite that Pitlane itself builds with, then run:

```sh
npm install
npm run check
npm start
```

`npm run check` runs the example's type check against its own `tsconfig.json`, then the build, then `npm run verify`.

`npm run verify` first confirms that neither Vite nor the `remix` package is installed. It then reads the written manifest through `createAssetResolver` and checks each answer against the files in `dist/web`. The entry's preloads hold the entry chunk and its shared startup chunk. The lazy module is observed but is neither a preload of the entry nor a browser entry. The server's stylesheet is found through the `node` graph. The SVG resolves to its emitted file. It prints what the resolver returned. `npm start` serves the page at `http://localhost:3000/`, where the client entry inserts the logo and the **Load the lazy module** button imports the lazy chunk and its stylesheet.

# Deploy to Cloudflare Workers

Source: https://pitlane.tools/deploy/cloudflare.md

> Run a Remix 3 app on Cloudflare Workers with pitlane/vite-plugin-remix and the Cloudflare Vite plugin, with workerd in dev, Miniflare preview, and wrangler deploy.

Deploy a Remix 3 app to [Cloudflare Workers](https://developers.cloudflare.com/workers/) by composing [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) with [`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/). Cloudflare's plugin owns the runtime story end to end: dev requests run inside [workerd](https://github.com/cloudflare/workerd) (real bindings, real runtime), `vite preview` serves the production build through Miniflare, and `wrangler deploy` publishes it.

> [!TIP]
>
> **Start from the template**
>
> `npx giget github:pitlane-tools/templates/cloudflare my-app` scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

## Configuration

The examples import from `pitlane/*` paths, which come from the `pitlane` package. The cloudflare template depends on scoped packages such as `@pitlane/vite-plugin-remix`, `@pitlane/assets`, and `@pitlane/theme`, so add `pitlane` before switching its imports. Put it in `dependencies`, because the Worker imports `pitlane/assets` at runtime, and one that reads D1 imports `pitlane/data-table-d1` too:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires and the standalone scoped packages. Then install the platform pieces:

```sh
npm add -D @cloudflare/vite-plugin wrangler
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Point Cloudflare's plugin at the `ssr` environment and let it own request handling in dev and preview with [`serverHandler: false`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#serverhandler):

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ serverHandler: false }), cloudflare({ viteEnvironment: { name: "ssr" } })],
});
```

`wrangler.jsonc` points at your server entry and the client build output:

```jsonc title="wrangler.jsonc"
{
    "name": "my-remix-app",
    "main": "app/entry.server.tsx",
    "assets": { "directory": "dist/client" },
    "compatibility_date": "2026-04-02",
    "compatibility_flags": ["nodejs_compat"],
}
```

Your server entry is already a Workers module: the default-exported router is the `fetch` handler. Extra worker events compose around it:

```ts
export default router;

// or, with queue/cron handlers:
export default {
    fetch: router.fetch,
    async queue(batch) {
        /* ... */
    },
};
```

## Bindings

Read bindings through the `cloudflare:workers` module. In dev they come from workerd's local emulation, in production from the deployed worker:

```ts
import { env } from "cloudflare:workers";

let value = await env.MY_KV.get("key");
```

> [!TIP]
>
> **Tip**
>
> Importing `cloudflare:workers` makes the SSR bundle resolvable only inside workerd. That's expected. With `serverHandler: false`, the `pitlane/vite-plugin-remix` preview server stays out of the way and Cloudflare's Miniflare preview serves the build, whether or not Node could import it.

A D1 binding gets you a `remix/data-table` database through [`createD1Database()`](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) from [`pitlane/data-table-d1`](https://pitlane.tools/guides/cloudflare-d1.md), which supplies the async driver D1 needs in place of the synchronous SQLite one.

## Prerendering and frame navigation

Cloudflare's default asset-first routing serves generated HTML before your Worker ever runs. It selects assets by URL, so a header-based frame request to a document URL can receive the full document and duplicate the page shell.

### Fully static frame navigation

Prefer [separate prerendered frame URLs](https://pitlane.tools/guides/prerendering.md#fully-static-frame-navigation). Both documents and frame responses remain static, with no request-time SSR or application Worker invocation.

Prerender `/platform/` as a complete document and `/_frames/main/platform/` as frame content. Use `href="/platform/"`, `data-rmx-target="main"`, and `data-rmx-src="/_frames/main/platform/"` on the link. Remix fetches the frame URL while keeping `/platform/` in the address bar. Use the frame URL for the initial `<Frame src>` too.

Keep the server entry for build-time rendering and list both kinds of route in [`prerender`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#prerender). A portable app can build with `remix({ prerender: [...] })` alone. An app that needs Cloudflare bindings while rendering can keep the Cloudflare Vite plugin for the build. Deploy only `dist/client` with a separate assets-only configuration:

```jsonc title="wrangler.static.jsonc"
{
    "name": "my-static-remix-app",
    "assets": {
        "directory": "dist/client",
        "not_found_handling": "none",
    },
    "compatibility_date": "2026-04-02",
}
```

This configuration has no `main`, `ASSETS` binding, or `run_worker_first`. Select it explicitly for both preview and deployment:

```sh
vp build
vpx wrangler dev --config wrangler.static.jsonc
# After checking the static preview:
vpx wrangler deploy --config wrangler.static.jsonc
```

Use this assets-only preview to prove the site works without its SSR entry. `vp preview` can still run the built server and hide missing prerendered files. Check initial loads, frame-targeted links, hydration, and direct document reloads. A missing frame file must return 404, never a document-shell fallback.

Cloudflare's default [HTML handling](https://developers.cloudflare.com/workers/static-assets/routing/advanced/html-handling/) serves directory indexes at trailing-slash URLs. Keep those slashes in both document and frame destinations to avoid redirects. No frame headers are needed.

### Optional hybrid rendering

Choose the Worker-first recipe below only when frame content must render at request time. Document responses stay prerendered, but frame navigation depends on a running SSR app. This alternative gives up fully static deployment.

| Request | Response source |
| --- | --- |
| Document request for a prerendered path | Static HTML |
| Frame request | Runtime app rendering |
| JavaScript, CSS, or another existing asset | Static file |
| Non-prerendered route or mutation | Runtime app |

With `run_worker_first: true`, every request invokes the Worker, including requests that return static HTML or assets. Those static responses do not require SSR, but they still incur Worker invocations.

This recipe tells frame requests apart by their `x-remix-frame` and `x-remix-target` headers, and assumes your controller recognizes them too. Remix's default frame resolver sends `x-remix-frame: true` on every frame request, plus `x-remix-target` when the frame is named, so an app that calls `run()` without a `resolveFrame` needs no change.

A custom `resolveFrame(src, options)` builds its own request instead. Build its headers like this and pass them to its `fetch` call:

```ts
let headers = new Headers({ accept: "text/html", "x-remix-frame": "true" });
if (options?.target) headers.set("x-remix-target", options.target);
```

Set `x-remix-frame` even when no target is named. Keep the resolver's method, form-body encoding, abort signal, and response handling unchanged. This fragment only changes its headers.

Run the Worker first and give it an asset binding:

```jsonc title="wrangler.jsonc"
{
    "name": "my-remix-app",
    "main": "app/entry.server.tsx",
    "assets": {
        "directory": "dist/client",
        "binding": "ASSETS",
        "run_worker_first": true,
    },
    "compatibility_date": "2026-04-02",
    "compatibility_flags": ["nodejs_compat"],
}
```

Wrap the router at the server entry. Keep any `routes` export needed by `prerender: true`:

```ts title="app/entry.server.tsx"
import { env } from "cloudflare:workers";
import { router } from "./router.ts";

export { routes } from "./routes.ts";

export default {
    async fetch(request: Request) {
        if (
            (request.method === "GET" || request.method === "HEAD") &&
            !request.headers.has("x-remix-frame") &&
            !request.headers.has("x-remix-target")
        ) {
            let asset = await env.ASSETS.fetch(request);
            if (asset.status !== 404) return asset;
        }
        return router.fetch(request);
    },
};
```

Generate binding types with `vpx wrangler types` after adding `ASSETS`. Frame requests and mutations go straight to the router. Ordinary GET/HEAD requests can use the prerendered document or another static asset. A missing asset falls through to the router. The controller still decides which content belongs in each frame.

Keep `assets.not_found_handling` unset (its default is `"none"`). A `"single-page-application"` fallback answers missing assets with a 200 shell, preventing the 404 fallthrough to the router.

Both changes are required. `run_worker_first` without the wrapper stops serving assets, and the wrapper without `run_worker_first` never sees a request that matches an asset. Cloudflare supports [selective Worker-first paths](https://developers.cloudflare.com/workers/static-assets/routing/worker-script/#run-worker-first-for-selective-paths), but every frame-resolved prerendered path must be included, with and without its trailing slash. Excluding it restores the asset-first behavior that causes this bug.

Keep the Vite plugins composed as above, with `prerender` added to `remix({ serverHandler: false, prerender: true })`. The `pitlane/vite-plugin-remix` plugin does not change your Wrangler routing settings.

Check the production build with `vp preview`. A request to a frame-resolved route carrying the frame headers must return frame content without an asset redirect or a document shell. The wrapper forwards the URL unchanged, so the controller must handle the trailing-slash forms used by your links and frame sources. Register both `/page` and `/page/` with the same action if both are reachable. An ordinary document request should still serve the prerendered HTML. Click between frame-targeted links and confirm that the page retains one header and footer.

## Local development and preview

```sh
vp dev      # dev server — SSR runs inside workerd with your bindings
vp build    # production build
vp preview  # serve the production build through Miniflare
```

For local secrets during `vp dev`, use a gitignored [`.dev.vars`](https://developers.cloudflare.com/workers/configuration/secrets/#local-development-with-secrets) file next to `wrangler.jsonc`. Non-secret values can live in `wrangler.jsonc` under `"vars"`.

## Deploy with the CLI

```sh
vpx wrangler login
vp build
vpx wrangler deploy
```

Production secrets are write-only through Wrangler:

```sh
vpx wrangler secret put MY_SECRET
```

## Deploy with GitHub Actions

Create an API token at **My Profile → API Tokens** using the _Edit Cloudflare Workers_ template, and store it as the `CLOUDFLARE_API_TOKEN` repository secret.

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    deployments: write

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: voidzero-dev/setup-vp@v1.21.1
              with:
                  cache: true

            - run: vp install --frozen-lockfile

            - run: vp build

            - run: vpx wrangler deploy
              env:
                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
```

`wrangler deploy` reads `wrangler.jsonc`, so the workflow needs no name, paths, or account flags. The config is the single source of truth locally and in CI.

## Client-only apps

A client-only Remix 3 app runs `remix()` in [SPA mode](https://pitlane.tools/guides/spa.md) and drops `@cloudflare/vite-plugin`: `server: false` builds no server environment, so there is no worker to run. The plugin's remaining job is [component HMR](https://pitlane.tools/guides/hmr.md#component-hmr), so it is worth keeping in a static build.

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "remix/component",
    },
}
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`vite build` emits the site into `dist/`. The Worker config becomes assets-only: no `main`, and `single-page-application` fallback serves `index.html` on deep links:

```jsonc title="wrangler.jsonc"
{
    "name": "my-remix-spa",
    "compatibility_date": "2026-04-02",
    "assets": {
        "directory": "./dist",
        "not_found_handling": "single-page-application",
    },
}
```

Deploys are unchanged: `vpx wrangler deploy` from the CLI, or the same [GitHub Actions workflow](#deploy-with-github-actions) above.

# Deploy to Netlify

Source: https://pitlane.tools/deploy/netlify.md

> Run a Remix 3 app on Netlify with pitlane/vite-plugin-remix: a one-file Netlify Function wraps the built fetch handler, and the Netlify Vite plugin emulates the platform locally.

Deploy a Remix 3 app to [Netlify](https://www.netlify.com) by publishing the client build as static files and serving everything else through one [Netlify Function](https://docs.netlify.com/build/functions/overview/) that wraps the built fetch handler. [`@netlify/vite-plugin`](https://www.npmjs.com/package/@netlify/vite-plugin) adds local emulation of the Netlify platform (Functions, Blobs, redirects, headers, environment variables, Image CDN) to `vite dev`.

> [!TIP]
>
> **Start from the template**
>
> `npx giget github:pitlane-tools/templates/netlify my-app` scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

## Configuration

The examples import from `pitlane/*` paths, which come from the `pitlane` package. The netlify template depends on scoped packages such as `@pitlane/vite-plugin-remix`, `@pitlane/assets`, and `@pitlane/theme`, so add `pitlane` before switching its imports. Put it in `dependencies` when app code imports runtime subpaths such as `pitlane/assets`:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires and the standalone scoped packages. Then install the Netlify plugin:

```sh
npm add -D @netlify/vite-plugin
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import netlify from "@netlify/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix(), netlify()],
});
```

> [!NOTE]
>
> **Who serves what in dev**
>
> Keep [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md)'s default [`serverHandler: true`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#serverhandler) here. Netlify's plugin emulates platform primitives around the dev server. SSR itself is still served by your app's fetch handler.

## The server function

Netlify runs server code two ways, and both speak the same fetch-handler language as the built server entry. The wrapper is three lines either way. Pick **one**:

|  | [Netlify Functions](https://docs.netlify.com/build/functions/overview/) | [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) |
| --- | --- | --- |
| Runtime | Node, in Netlify's serverless infrastructure | Deno, at the edge PoP nearest the visitor |
| Static assets | CDN wins first via `preferStatic` | Run **before** static serving, so assets must be excluded via `excludedPath` |
| Fits | The default; larger CPU/memory limits, Node APIs | Latency-sensitive SSR; stricter [runtime limits](https://docs.netlify.com/build/edge-functions/limits/) |

### Netlify Functions (Node)

Create `netlify/functions/server.mjs`:

```js title="netlify/functions/server.mjs"
import server from "../../dist/ssr/index.js";

export default request => server.fetch(request);

export const config = {
    path: "/*",
    preferStatic: true,
};
```

`path: "/*"` routes every request to the function; `preferStatic: true` lets files in the publish directory win first, so hashed client assets are served from the CDN and never touch the function.

### Netlify Edge Functions (Deno)

Create `netlify/edge-functions/server.mjs` instead:

```js title="netlify/edge-functions/server.mjs"
import server from "../../dist/ssr/index.js";

export default request => server.fetch(request);

export const config = {
    path: "/*",
    excludedPath: ["/assets/*", "/favicon.ico"],
};
```

Edge functions run **before** the CDN serves static files, so there is no `preferStatic`. Instead, [`excludedPath`](https://docs.netlify.com/build/edge-functions/declarations/) carves the static surface out of the match. `/assets/*` covers the hashed client build. Extend the array with anything else you serve from `public/`.

The edge variant has its own rules:

- The handler executes on **Deno**. Remix 3 is built on Web APIs, so the SSR bundle runs there. But avoid Node-only APIs (`node:fs`, `node:crypto` beyond WebCrypto) in server code you deploy to the edge.
- Don't deploy both files: the edge function matches first and the Node function would never run.

Either way, `netlify.toml` names the publish directory and deliberately sets **no build command**. The Vite build always runs in your CI (or your shell), never on Netlify's build system, so the fingerprinted assets you tested are the ones that reach production:

```toml title="netlify.toml"
[build]
    publish = "dist/client"
```

> [!TIP]
>
> **Under the hood**
>
> The Functions variant is the same shape Netlify's TanStack Start integration generates automatically (a thin function re-exporting the `ssr` environment's `fetch`). Netlify's generic Vite plugin generates it too, but only behind a private, explicitly unsupported flag today; the committed function file above is the documented, stable path. If Netlify promotes that flag to public API, this guide gets three lines shorter.

## Local development

```sh
vp dev      # dev server + Netlify platform emulation
vp build    # production build
vp preview  # serve the production build via the pitlane/vite-plugin-remix preview
```

Running under the Netlify CLI instead? `netlify dev` configures the environment itself and the Vite plugin steps aside automatically.

## Deploy with the CLI

Create the site once and link the directory, then every deploy is two commands:

```sh
vpx netlify-cli login
vpx netlify-cli init      # create + link the site (or `link` for an existing one)

vp build
vpx netlify-cli deploy --no-build            # draft URL
vpx netlify-cli deploy --no-build --prod     # production
```

`--no-build` keeps the CLI from triggering a build of its own (you already built). The deploy uploads `dist/client` and bundles whichever server wrapper you committed. The Node function goes through Netlify's function bundler, the edge function through the Deno-based edge bundler. Both trace the import of `dist/ssr/index.js` and package it automatically, locally in the CLI.

## Deploy with GitHub Actions

Store two repository secrets: `NETLIFY_AUTH_TOKEN` (a [personal access token](https://app.netlify.com/user/applications#personal-access-tokens)) and `NETLIFY_SITE_ID` (**Site configuration → Site details → Site ID**, or `netlify sites:list`).

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    deployments: write

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: voidzero-dev/setup-vp@v1.21.1
              with:
                  cache: true

            - run: vp install --frozen-lockfile

            - run: vp build

            - run: vpx netlify-cli deploy --no-build --prod
              env:
                  NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
                  NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
```

## Environment variables

Set them in the Netlify UI (**Site configuration → Environment variables**) or via `netlify env:set`. Netlify Functions read them as `process.env.*`. Edge Functions use [`Netlify.env.get("KEY")`](https://docs.netlify.com/build/edge-functions/api/#netlify-specific-context-object). The Vite plugin mirrors them into `vite dev`.

## Client-only apps

A client-only Remix 3 app runs `remix()` in [SPA mode](https://pitlane.tools/guides/spa.md): `server: false` builds no server environment, so there is no server function to write. The plugin's remaining job is [component HMR](https://pitlane.tools/guides/hmr.md#component-hmr), so it is worth keeping in a static build.

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "remix/component",
    },
}
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`vite build` emits the site into `dist/`. Publish that directory and add the SPA fallback so deep links serve `index.html`:

```toml title="netlify.toml"
[build]
    publish = "dist"

[[redirects]]
    from = "/*"
    to = "/index.html"
    status = 200
```

Deploys are unchanged: `vpx netlify-cli deploy --no-build --prod` from the CLI, or the same [GitHub Actions workflow](#deploy-with-github-actions) above.

# Deploy to Vercel

Source: https://pitlane.tools/deploy/vercel.md

> Run a Remix 3 app on Vercel with pitlane/vite-plugin-remix and the Nitro Vite plugin, which produces Vercel Functions through the Build Output API.

Deploy a Remix 3 app to [Vercel](https://vercel.com) by composing [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) with [`nitro/vite`](https://nitro.build). Nitro packages the `ssr` environment's fetch handler for the deploy target. Vercel injects `VERCEL=1` into builds, so Nitro auto-selects its `vercel` preset and emits Vercel's [Build Output API](https://vercel.com/docs/build-output-api) format that the platform reads directly. There is no **Framework Preset**, build command, or output directory to configure by hand.

> [!TIP]
>
> **Start from the template**
>
> `npx giget github:pitlane-tools/templates/vercel my-app` scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

## Configuration

The examples import from `pitlane/*` paths, which come from the `pitlane` package. The vercel template depends on scoped packages such as `@pitlane/vite-plugin-remix`, `@pitlane/assets`, and `@pitlane/theme`, so add `pitlane` before switching its imports. Put it in `dependencies` when app code imports runtime subpaths such as `pitlane/assets`:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires and the standalone scoped packages. Then install Nitro:

```sh
npm add -D nitro
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ serverHandler: false }), nitro()],
});
```

[`serverHandler: false`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#serverhandler) hands request handling to Nitro: its dev server in `vp dev`, and its preview of the packaged output in `vp preview`. Both run the same fetch handler Nitro packages for production.

Server routes run as [Vercel Functions](https://vercel.com/docs/functions) on Fluid compute, with standard Web APIs and scale-to-zero. Client assets are served from Vercel's CDN.

## Local development and preview

```sh
vp dev      # dev server through Nitro's runtime
vp build    # locally: portable .output build
vp preview  # preview the build
```

Locally, Nitro builds its portable Node output; the Vercel-specific `.vercel/output` structure is produced when the build runs under `vercel build` (which sets `VERCEL=1`, locally or in CI).

## Deploy with the CLI

Link the project once, then always deploy **prebuilt**. The artifact built on your machine (or CI) is the artifact that reaches production, and Vercel's build system never runs:

```sh
vpx vercel login
vpx vercel link

vpx vercel build && vpx vercel deploy --prebuilt            # preview deployment
vpx vercel build --prod && vpx vercel deploy --prebuilt --prod   # production
```

`vercel build` runs the Vite build locally with Vercel's environment applied (so Nitro emits `.vercel/output`), and `--prebuilt` uploads that directory as-is.

> [!WARNING]
>
> **Don't use plain `vercel`**
>
> A plain `vercel` / `vercel --prod` uploads _source_ and builds on Vercel's infrastructure. Skip it. The Vite build point stays in your CI.

## Deploy with GitHub Actions

Store three repository secrets: `VERCEL_TOKEN` (an [access token](https://vercel.com/account/settings/tokens)), plus `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` (both written to `.vercel/project.json` by `vercel link`).

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    deployments: write

env:
    VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: voidzero-dev/setup-vp@v1.21.1
              with:
                  cache: true

            - run: vp install --frozen-lockfile

            - run: vpx vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

            - run: vpx vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

            - run: vpx vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
```

`vercel build` runs the Vite build with Vercel's environment applied (so Nitro emits `.vercel/output`), and `--prebuilt` uploads that directory as-is. The build you tested is the build that reaches production.

## Environment variables

Define them per environment in the Vercel dashboard (**Settings → Environment Variables**) or with `vercel env add`. They reach the server handler as `process.env.*`. `vercel env pull` writes a local `.env.local` for development.

## Client-only apps

A client-only Remix 3 app runs `remix()` in [SPA mode](https://pitlane.tools/guides/spa.md) and drops `nitro/vite`: `server: false` builds no server environment, so there is nothing for Nitro to package. The plugin's remaining job is [component HMR](https://pitlane.tools/guides/hmr.md#component-hmr), so it is worth keeping in a static build.

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "remix/component",
    },
}
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`vite build` emits the site into `dist/`, which Vercel's Vite preset picks up. Add the SPA fallback so deep links serve `index.html`:

```json title="vercel.json"
{
    "rewrites": [
        {
            "source": "/(.*)",
            "destination": "/index.html"
        }
    ]
}
```

Deploys are unchanged. Build prebuilt, then upload the artifact: `vpx vercel build --prod && vpx vercel deploy --prebuilt --prod`, or use the same [GitHub Actions workflow](#deploy-with-github-actions) above.

# Deploy to Railway

Source: https://pitlane.tools/deploy/railway.md

> Run a Remix 3 app on Railway under Node, Bun, or Deno: the built fetch handler plus one Dockerfile.

This guide for: **Vite** · [No Build](https://pitlane.tools/deploy/railway-no-build.md)

Deploy a Remix 3 app to [Railway](https://railway.com) as a plain server process. No platform plugin is involved. `vite build` produces `dist/ssr/index.js` (your fetch handler) and `dist/client/` (static assets that the `staticFiles` middleware in your router serves), and a Dockerfile runs whichever runtime you choose.

> [!TIP]
>
> **Start from a template**
>
> `npx giget github:pitlane-tools/templates/railway-node my-app` (or `railway-bun`, `railway-deno`) scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

The Dockerfile is **built in your CI, never by Railway**: CI runs `docker build` (the Vite build happens inside it, under your control) and pushes the image to [GitHub Container Registry](https://ghcr.io). The Railway service [deploys that pre-built image](https://docs.railway.com/quick-start#deploying-your-project---from-a-docker-image). Railway only pulls and runs. It injects a `PORT` environment variable at runtime. Your server binds `0.0.0.0:$PORT`.

Add a `.dockerignore` so builds stay small and reproducible:

```
node_modules
dist
.git
.env*
```

## Node

The Node template's `server.ts` already reads `PORT` (Node runs TypeScript directly):

```ts title="server.ts"
import * as http from "node:http";
import { createRequestListener } from "remix/node-fetch-server";

// @ts-expect-error - built output has no types
import ssr from "./dist/ssr/index.js";

let server = http.createServer(createRequestListener(request => ssr.fetch(request)));
server.listen(process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000);
```

```dockerfile
# Dockerfile
FROM node:24-alpine
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build && npm prune --omit=dev

ENV NODE_ENV=production
CMD ["node", "server.ts"]
```

The exec-form `CMD` is fine here because `server.ts` reads `process.env.PORT` itself.

## Bun

Bun's automatic serving of default-exported `fetch` handlers doesn't apply cleanly here: `bun run` passes its `Server` object as a second argument and routes through its own server wrapper, which breaks the router's action dispatch (form `POST`s fall through to the index render). Wrap the built entry in a three-line `Bun.serve` server instead:

```ts title="server.ts"
// @ts-expect-error - built output has no types
import ssr from "./dist/ssr/index.js";

let server = Bun.serve({
    port: process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000,
    fetch: request => ssr.fetch(request),
});
```

```dockerfile
# Dockerfile
FROM oven/bun:1-alpine
WORKDIR /app

COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

ENV NODE_ENV=production
CMD ["bun", "server.ts"]
```

## Deno

The built entry matches `deno serve`'s default-export contract exactly. One flag matters: `deno serve` does not read `$PORT` itself, so pass it explicitly, and use the **shell-form `CMD`**, because exec-form (`CMD ["deno", …]`) never expands environment variables:

```dockerfile
# Dockerfile
FROM denoland/deno:alpine
WORKDIR /app

COPY . .
RUN deno install --allow-scripts
RUN deno task build

# Shell form so Railway's injected $PORT expands.
CMD deno serve -A --port=$PORT dist/ssr/index.js
```

(`-A` grants the runtime permissions the server code needs. Tighten to specific `--allow-*` flags once you know your app's surface.)

## Deploy with the CLI

One-time setup: create an empty project at [railway.com/new](https://railway.com/new). Add a service with **Docker Image** as the source (e.g. `ghcr.io/<user>/my-remix-app:latest`). Generate a domain under **Settings → Networking**, because services are private by default.

A new GHCR package is [private by default](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), and Railway pulls a private image only with [registry credentials](https://docs.railway.com/builds/private-registries), which require the Pro plan. On any other plan, make the package public after the first push, from **Package settings → Change visibility** on the package's GitHub page. The change is permanent. A public image exposes every file `COPY . .` put in it, so the `.dockerignore` above leaves out `.env*`.

Install the [Railway CLI](https://docs.railway.com/cli) as a dev dependency:

```sh
npm add -D @railway/cli
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Then every deploy is a build, a push, and a `railway redeploy` that tells Railway to pull it.

```sh
docker build -t ghcr.io/<user>/my-remix-app:latest .
docker push ghcr.io/<user>/my-remix-app:latest

vpx railway login
vpx railway link            # link this directory to the project once
vpx railway redeploy --service my-remix-app --yes
```

`railway redeploy` re-pulls the image tag and rolls the service. The platform uploads no source and runs no build.

## Deploy with GitHub Actions

Create a project-scoped token (**Project Settings → Tokens**) and store it as the `RAILWAY_TOKEN` repository secret. The workflow builds the image (running the Vite build inside `docker build`, in CI), pushes it to GHCR with the built-in `GITHUB_TOKEN`, and redeploys the service:

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    packages: write

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: docker/login-action@v3
              with:
                  registry: ghcr.io
                  username: ${{ github.actor }}
                  password: ${{ secrets.GITHUB_TOKEN }}

            - uses: docker/build-push-action@v6
              with:
                  context: .
                  push: true
                  tags: ghcr.io/${{ github.repository }}:latest

            - uses: voidzero-dev/setup-vp@v1.21.1

            - run: vp install --frozen-lockfile

            - run: vpx railway redeploy --service my-remix-app --yes
              env:
                  RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
```

`--service` names the Railway service to roll (`railway status` lists them). The Vite build point is the `docker build` step, which runs in CI under your control and never on the platform.

## Environment variables

Set them per service in the dashboard (**Variables**) or `railway variable set KEY=value`. Railway injects `PORT`. Define your own only if you need a fixed port. `railway run <cmd>` injects the service's variables into a local process for parity debugging.

## Client-only apps

A client-only Remix 3 app runs [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) in [SPA mode](https://pitlane.tools/guides/spa.md): `server: false` builds no server environment, so there is no `server.ts` and no runtime process. The plugin's remaining job is [component HMR](https://pitlane.tools/guides/hmr.md#component-hmr). `vite build` emits a static site; on Railway, a multi-stage Dockerfile builds it and serves it with [Caddy](https://caddyserver.com).

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "remix/component" } }
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`pitlane/vite-plugin-remix` comes from the `pitlane` package. The Railway templates depend on the scoped `@pitlane/vite-plugin-remix` package, so add `pitlane` before switching the import. Only `vite.config.ts` imports it, so a dev dependency is enough:

```sh
npm add -D pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires.

The Caddyfile binds Railway's injected port and rewrites deep links to `index.html`:

```
# Caddyfile
:{$PORT}
root * /srv
encode gzip
try_files {path} /index.html
file_server
```

```dockerfile
# Dockerfile
FROM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM caddy:alpine
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/dist /srv
```

Deploys are unchanged: the same image flow (`docker build` + push + `railway redeploy`) from the CLI, or the same [GitHub Actions workflow](#deploy-with-github-actions) above.

> [!TIP]
>
> **Platform features**
>
> However the image arrives, the service gets automatic SSL, [custom domains](https://docs.railway.com/networking/domains), per-PR [preview environments](https://docs.railway.com/environments#pr-environments), and an optional [built-in CDN](https://docs.railway.com/networking/cdn).

# Deploy to Railway (No Build)

Source: https://pitlane.tools/deploy/railway-no-build.md

> Run a Remix 3 app on Railway under Node, Bun, or Deno straight from source: one Dockerfile that installs dependencies and starts server.ts, with no build step.

This guide for: [Vite](https://pitlane.tools/deploy/railway.md) · **No Build**

Deploy a Remix 3 app to [Railway](https://railway.com) as a plain server process that runs straight from source. Nothing compiles the app ahead of time. The image installs dependencies and starts `server.ts`, and [`remix/assets`](https://github.com/remix-run/remix/tree/main/packages/assets) compiles each browser module the first time a browser asks for it, the same way it does in development.

> [!TIP]
>
> **Start from the Remix starter**
>
> `npx remix@next new my-app` scaffolds an app with no build step. This guide deploys it with one change to its asset server, under Node, Bun, or Deno.

The Dockerfile is **built in your CI, never by Railway**. CI runs `docker build` and pushes the image to [GitHub Container Registry](https://ghcr.io), and installing dependencies is the only work inside that build. The Railway service [deploys that pre-built image](https://docs.railway.com/quick-start#deploying-your-project---from-a-docker-image). Railway only pulls and runs. It injects a `PORT` environment variable at runtime, which the starter's `server.ts` already reads.

Add a `.dockerignore`. Leaving out `node_modules` matters more than usual here. The asset server compiles with native addons, and the image needs the binaries for its own platform rather than the ones installed for yours.

```
node_modules
.git
.env*
```

## Production assets

The starter's `app/assets.ts` already reads `NODE_ENV`: outside development it stops watching files and minifies what it serves. Add fingerprinting, which is what Remix recommends for a deployment:

```ts title="app/assets.ts"
export const assets = createAssetServer({
    // ...
    minify: !isDevelopment,
    watch: isDevelopment,
    fingerprint: !isDevelopment,
});
```

Every asset URL then carries a content hash, `/assets/app/actions/public/entry.@xnRkP3.ts`, and is served with `Cache-Control: public, max-age=31536000, immutable`. Fingerprinting and file watching cannot be combined, so both follow the same flag.

An unset `NODE_ENV` counts as development, so each Dockerfile below sets it to `production`. The starter's `start` script runs that mode locally, under Node, before you build an image:

```sh
npm start
```

## Node

`remix/node-tsx` is the loader that lets Node run the app's `.tsx` files. It comes with `remix` and needs Node 24.3 or later. Production dependencies are everything the server needs, since nothing is compiled ahead of time:

```dockerfile
# Dockerfile
FROM node:24-alpine
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --omit=dev

COPY . .

ENV NODE_ENV=production
CMD ["node", "--import", "remix/node-tsx", "server.ts"]
```

The starter has no lockfile. Run `npm install` once to create the `package-lock.json` this Dockerfile installs from.

## Bun

Bun runs TypeScript and JSX natively and takes the JSX settings from `tsconfig.json`, so it runs the starter's `server.ts` as it is, `node:http` server included:

```dockerfile
# Dockerfile
FROM oven/bun:1-alpine
WORKDIR /app

COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production

COPY . .

ENV NODE_ENV=production
CMD ["bun", "server.ts"]
```

Run `bun install` once to create the `bun.lock` this Dockerfile installs from.

Bun does not resolve [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) that start with `#/`. The starter uses relative imports and is unaffected. If your app maps `"#/*"` in `package.json`, give the pattern a name, such as `"#app/*"`.

## Deno

Deno runs TypeScript and JSX natively and installs from `package.json`. It reads the JSX settings from `tsconfig.json`, so it too runs the starter's `server.ts` as it is:

```dockerfile
# Dockerfile
FROM denoland/deno:debian
WORKDIR /app

COPY package.json deno.lock ./
RUN deno install --frozen

COPY . .

ENV NODE_ENV=production
CMD ["deno", "run", "-A", "server.ts"]
```

Run `deno install` once to create the `deno.lock` this Dockerfile installs from.

Use the Debian image. On `denoland/deno:alpine` the install picks the musl build of the asset server's native addons, and Deno cannot load that build there, so the server exits before it starts listening.

The exec-form `CMD` is fine here because `server.ts` reads `process.env.PORT` itself. (`-A` grants the runtime permissions the server code needs. Tighten to specific `--allow-*` flags once you know your app's surface.)

## Deploy with the CLI

One-time setup: create an empty project at [railway.com/new](https://railway.com/new). Add a service with **Docker Image** as the source (e.g. `ghcr.io/<user>/my-remix-app:latest`). Generate a domain under **Settings → Networking**, because services are private by default.

A new GHCR package is [private by default](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), and Railway pulls a private image only with [registry credentials](https://docs.railway.com/builds/private-registries), which require the Pro plan. On any other plan, make the package public after the first push, from **Package settings → Change visibility** on the package's GitHub page. The change is permanent. A public image exposes every file `COPY . .` put in it, so the `.dockerignore` above leaves out `.env*`.

Install the [Railway CLI](https://docs.railway.com/cli) as a dev dependency:

```sh
npm add -D @railway/cli
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

Then every deploy is a build, a push, and a `railway redeploy` that tells Railway to pull it.

```sh
docker build -t ghcr.io/<user>/my-remix-app:latest .
docker push ghcr.io/<user>/my-remix-app:latest

vpx railway login
vpx railway link            # link this directory to the project once
vpx railway redeploy --service my-remix-app --yes
```

`railway redeploy` re-pulls the image tag and rolls the service. The platform uploads no source and runs no build.

## Deploy with GitHub Actions

Create a project-scoped token (**Project Settings → Tokens**) and store it as the `RAILWAY_TOKEN` repository secret. The workflow builds the image (installing dependencies inside `docker build`, in CI), pushes it to GHCR with the built-in `GITHUB_TOKEN`, and redeploys the service:

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    packages: write

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: docker/login-action@v3
              with:
                  registry: ghcr.io
                  username: ${{ github.actor }}
                  password: ${{ secrets.GITHUB_TOKEN }}

            - uses: docker/build-push-action@v6
              with:
                  context: .
                  push: true
                  tags: ghcr.io/${{ github.repository }}:latest

            - uses: voidzero-dev/setup-vp@v1.21.1

            - run: vp install --frozen-lockfile

            - run: vpx railway redeploy --service my-remix-app --yes
              env:
                  RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
```

`--service` names the Railway service to roll (`railway status` lists them). The image the workflow pushes holds your source and its installed dependencies, nothing more.

## Environment variables

Set them per service in the dashboard (**Variables**) or `railway variable set KEY=value`. Railway injects `PORT`. Define your own only if you need a fixed port. `railway run <cmd>` injects the service's variables into a local process for parity debugging.

> [!TIP]
>
> **Platform features**
>
> However the image arrives, the service gets automatic SSL, [custom domains](https://docs.railway.com/networking/domains), per-PR [preview environments](https://docs.railway.com/environments#pr-environments), and an optional [built-in CDN](https://docs.railway.com/networking/cdn).

# Deploy to Deno Deploy

Source: https://pitlane.tools/deploy/deno-deploy.md

> Run a Remix 3 app on Deno Deploy: the built fetch handler behind a three-line Deno.serve entrypoint, built and deployed by Deploy's own infrastructure.

This guide for: **Vite** · [No Build](https://pitlane.tools/deploy/deno-deploy-no-build.md)

Deploy a Remix 3 app to [Deno Deploy](https://deno.com/deploy), the new platform at [console.deno.com](https://console.deno.com), which runs full Deno 2 apps with CDN caching and built-in logs, traces, and metrics. No platform plugin is involved: the Vite build runs in your CI, and Deploy runs the uploaded fetch handler under real Deno.

> [!TIP]
>
> **Start from the template**
>
> `npx giget github:pitlane-tools/templates/deno-deploy my-app` scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

> [!WARNING]
>
> **New Deploy only**
>
> This guide targets the current Deno Deploy. Deploy Classic (`dash.deno.com`) shut down on July 20, 2026. If you're coming from it, see the [migration guide](https://docs.deno.com/deploy/migration_guide/).

## Configuration

[`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) needs no Deploy-specific options. The defaults apply. `deno.json` and `main.ts` adapt the project to Deno:

```jsonc title="deno.json"
{
    "nodeModulesDir": "auto",
    "tasks": {
        "build": "vite build",
    },
    "deploy": {
        // Uploads respect .gitignore; un-exclude the built output so the
        // deploy tarball ships dist/.
        "exclude": ["!dist"],
    },
}
```

Deploy's **Dynamic Entrypoint** is executed the way `deno run` executes a file, so it must start a server. Wrap the built fetch handler in three lines:

```ts title="main.ts"
import server from "./dist/ssr/index.js";

Deno.serve({ port: Number(Deno.env.get("PORT") ?? 8000) }, request => server.fetch(request));
```

Static assets keep flowing through the `staticFiles("./dist/client")` middleware in your router, same as every other server target.

The app's build configuration (dashboard **Edit build config**, or CLI flags):

| Setting | Value |
| --- | --- |
| Framework preset | No Preset |
| Install command | `deno install --allow-scripts` |
| Build command | _(empty: the Vite build runs before deploying)_ |
| Runtime configuration | Dynamic |
| Dynamic Entrypoint | `main.ts` |

The Vite build runs **before** `deno deploy`, and the `deploy.exclude` entry above un-excludes the gitignored `dist/` from the upload, so the tarball already contains the fingerprinted assets the running app serves. The install command only restores `node_modules` for the runtime. Leave the build command empty so Deploy doesn't build a second time.

## Local development

```sh
vp dev      # dev server through Pitlane's Vite plugin
vp build    # production build
vp preview  # serve the production build
```

To exercise the production bundle under Deno itself before deploying:

```sh
deno serve --port 3000 dist/ssr/index.js
```

## Deploy with the CLI

The `deno deploy` command comes with the Deno CLI. Build first, then deploy. The CLI tarballs the directory (respecting `.gitignore`, so the `deploy.exclude` un-exclusion above) and uploads it:

```sh
vp build
deno deploy --app my-remix-app --prod
```

(The first bare `deno deploy` run authenticates and prompts for an app name.)

Create the app non-interactively (flags switch the wizard off):

Run it after `vp build`: `--source local` uploads this directory and publishes a first revision straight away.

```sh
deno deploy create \
    --org my-org \
    --app my-remix-app \
    --source local \
    --do-not-use-detected-build-config \
    --install-command "deno install --allow-scripts" \
    --runtime-mode dynamic \
    --entrypoint main.ts \
    --region global
```

Without `--do-not-use-detected-build-config`, a build configuration Deploy detects in the directory takes precedence over the flags. `--region` also takes `us` or `eu`.

Useful companions:

```sh
deno deploy logs                 # stream runtime logs
deno deploy env load .env       # push env vars; secret-looking keys are auto-marked secret
```

## Deploy with GitHub Actions

Create an access token at [console.deno.com/account/access-tokens](https://console.deno.com/account/access-tokens) and store it as the `DENO_DEPLOY_TOKEN` repository secret. The workflow builds the Vite app (producing the fingerprinted assets in `dist/`) and then uploads it:

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: voidzero-dev/setup-vp@v1.21.1
              with:
                  cache: true

            - run: vp install --frozen-lockfile

            - run: vp build

            - uses: denoland/setup-deno@v2
              with:
                  deno-version: v2.x

            - run: deno deploy --app my-remix-app --prod
              env:
                  DENO_DEPLOY_TOKEN: ${{ secrets.DENO_DEPLOY_TOKEN }}
```

## Environment variables

Set them per context (**Production** for production domains, **Development** for preview/branch URLs) in the dashboard's environment-variables drawer, or push a local file with `deno deploy env load .env`. They reach the app through `Deno.env.get()` (and `process.env` under Node compatibility).

## Client-only apps

A client-only Remix 3 app runs `remix()` in [SPA mode](https://pitlane.tools/guides/spa.md): `server: false` builds no server environment, so there is no wrapper entrypoint to write. The plugin's remaining job is [component HMR](https://pitlane.tools/guides/hmr.md#component-hmr), so it is worth keeping in a static build. Deno Deploy hosts static sites first-class, including a **Single Page App mode** that serves `index.html` for unmatched paths.

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "remix/component" } }
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`pitlane/vite-plugin-remix` comes from the `pitlane` package. The deno-deploy template maps the scoped packages in its `deno.jsonc`, such as `"@pitlane/vite-plugin-remix": "npm:@pitlane/vite-plugin-remix@…"`, so add `pitlane` before switching the import. Run `deno add npm:pitlane`, which records a `"pitlane": "npm:pitlane@…"` entry in the same `imports` map. Deno resolves `pitlane/vite-plugin-remix` and the other subpaths through that entry. The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires.

Configure the app as **Static** with directory `dist` and Single Page App mode on, either in the dashboard or in one non-interactive command:

```sh
deno deploy create \
    --org my-org \
    --app my-remix-spa \
    --source local \
    --do-not-use-detected-build-config \
    --runtime-mode static \
    --static-dir dist \
    --single-page-app \
    --region global
```

Deploys are unchanged: `deno deploy --prod` from the CLI, or the same [GitHub Actions workflow](#deploy-with-github-actions) above.

# Deploy to Deno Deploy (No Build)

Source: https://pitlane.tools/deploy/deno-deploy-no-build.md

> Run a Remix 3 app on Deno Deploy straight from source. Deploy installs dependencies, and Deno runs the TypeScript behind a three-line Deno.serve entrypoint with no build step.

This guide for: [Vite](https://pitlane.tools/deploy/deno-deploy.md) · **No Build**

Deploy a Remix 3 app to [Deno Deploy](https://deno.com/deploy), the new platform at [console.deno.com](https://console.deno.com), which runs full Deno 2 apps with CDN caching and built-in logs, traces, and metrics. Nothing compiles the app ahead of time. Deploy installs the dependencies of the source you upload, and Deno runs the TypeScript directly. [`remix/assets`](https://github.com/remix-run/remix/tree/main/packages/assets) compiles each browser module the first time a browser asks for it, the same way it does in development.

> [!TIP]
>
> **Start from the Remix starter**
>
> `npx remix@next new my-app` scaffolds an app with no build step. This guide deploys it with one change to its asset server and one extra file.

> [!WARNING]
>
> **New Deploy only**
>
> This guide targets the current Deno Deploy. Deploy Classic (`dash.deno.com`) shut down on July 20, 2026. If you're coming from it, see the [migration guide](https://docs.deno.com/deploy/migration_guide/).

## Configuration

Deno reads the JSX settings from the starter's `tsconfig.json` and installs from its `package.json`, so the app needs no `deno.json`. It does need an entrypoint. Deploy's **Dynamic Entrypoint** is executed the way `deno run` executes a file, so it must start a server. Hand the router to `Deno.serve`:

```ts title="main.ts"
import { router } from "./app/router.ts";

Deno.serve({ port: Number(Deno.env.get("PORT") ?? 8000) }, request => router.fetch(request));
```

The starter's `app/assets.ts` reads `NODE_ENV`: outside development it stops watching files and minifies what it serves. Add fingerprinting, which is what Remix recommends for a deployment:

```ts title="app/assets.ts"
export const assets = createAssetServer({
    // ...
    minify: !isDevelopment,
    watch: isDevelopment,
    fingerprint: !isDevelopment,
});
```

Every asset URL then carries a content hash, `/assets/app/actions/public/entry.@xnRkP3.ts`, and is served with `Cache-Control: public, max-age=31536000, immutable`. Fingerprinting and file watching cannot be combined, so both follow the same flag.

An unset `NODE_ENV` counts as development, and Deploy does not set it. Add `NODE_ENV` with the value `production` to both the **Production** and **Development** contexts, so preview URLs run the same way production does. From the CLI, `deno deploy env add NODE_ENV production --app my-remix-app` adds it to every context at once.

The app's build configuration (dashboard **Edit build config**, or CLI flags):

| Setting | Value |
| --- | --- |
| Framework preset | No Preset |
| Install command | `deno install` |
| Build command | _(empty: there is nothing to build)_ |
| Runtime configuration | Dynamic |
| Dynamic Entrypoint | `main.ts` |

The upload respects `.gitignore`, so `node_modules` stays behind and Deploy's install command restores it on Deploy's own Linux builders. That matters: the asset server compiles with native addons, and installing on Deploy fetches the ones built for Deploy's Linux rather than for your machine.

## Local development

```sh
npm run dev   # the starter's dev server, under Node
```

To exercise the deployed entrypoint under Deno, in production mode, before deploying:

```sh
deno install
NODE_ENV=production deno run -A main.ts
```

## Deploy with the CLI

The `deno deploy` command comes with the Deno CLI. There is nothing to build first. The CLI tarballs the directory (respecting `.gitignore`) and uploads it:

```sh
deno deploy --app my-remix-app --prod
```

(The first bare `deno deploy` run authenticates and prompts for an app name.)

Create the app non-interactively (flags switch the wizard off):

```sh
deno deploy create \
    --org my-org \
    --app my-remix-app \
    --source local \
    --do-not-use-detected-build-config \
    --install-command "deno install" \
    --runtime-mode dynamic \
    --entrypoint main.ts \
    --region global
```

Without `--do-not-use-detected-build-config`, a build configuration Deploy detects in the directory takes precedence over the flags. `--region` also takes `us` or `eu`.

`create` publishes a first revision straight away, before the app has any environment variables, so that revision runs in development mode. Add `NODE_ENV` and deploy again:

```sh
deno deploy env add NODE_ENV production --app my-remix-app
deno deploy --app my-remix-app --prod
```

Useful companions:

```sh
deno deploy logs                 # stream runtime logs
deno deploy env load .env       # push env vars; secret-looking keys are auto-marked secret
```

## Deploy with GitHub Actions

Create an access token at [console.deno.com/account/access-tokens](https://console.deno.com/account/access-tokens) and store it as the `DENO_DEPLOY_TOKEN` repository secret. The workflow uploads the checkout as it is. It installs nothing, because Deploy does:

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: denoland/setup-deno@v2
              with:
                  deno-version: v2.x

            - run: deno deploy --app my-remix-app --prod
              env:
                  DENO_DEPLOY_TOKEN: ${{ secrets.DENO_DEPLOY_TOKEN }}
```

## Environment variables

Set them per context (**Production** for production domains, **Development** for preview/branch URLs) in the dashboard's environment-variables drawer, or push a local file with `deno deploy env load .env`. They reach the app through `Deno.env.get()` (and `process.env` under Node compatibility).

# Deploy to GitHub Pages

Source: https://pitlane.tools/deploy/github-pages.md

> Deploy a Remix 3 app to GitHub Pages, in SPA mode with remix({ server: false }) or as a fully prerendered build, covering the base path and the 404.html fallback a project site needs.

[GitHub Pages](https://pages.github.com) serves static files only. There is no server runtime. A client-only app in [SPA mode](https://pitlane.tools/guides/spa.md) works, and so does a server-rendered app whose pages are all [prerendered](https://pitlane.tools/guides/prerendering.md) at build time. (Need a server at runtime? [Cloudflare](https://pitlane.tools/deploy/cloudflare.md), [Netlify](https://pitlane.tools/deploy/netlify.md), [Vercel](https://pitlane.tools/deploy/vercel.md), and [Railway](https://pitlane.tools/deploy/railway.md) all have one.)

> [!TIP]
>
> **Start from the template**
>
> `npx giget github:pitlane-tools/templates/github-pages my-app` scaffolds a working guest book app wired for this guide. See [pitlane-tools/templates](https://github.com/pitlane-tools/templates).

A client-only app runs [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) in [SPA mode](https://pitlane.tools/guides/spa.md): [`server: false`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#server) turns off the server environment, so there is nothing to build to `dist/ssr` and nothing serving requests in dev. The plugin still gives you [component hot module replacement](https://pitlane.tools/guides/hmr.md#component-hmr), so it is worth keeping in a static build.

## Setup

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Remix App</title>
        <script type="module" src="/app/main.tsx"></script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

```tsx title="app/main.tsx"
import { createRoot, on, type Handle } from "remix/component";

function App(handle: Handle) {
    let count = 0;

    return () => (
        <button
            mix={[
                on("click", () => {
                    count++;
                    handle.update();
                }),
            ]}
        >
            Count: {count}
        </button>
    );
}

createRoot(document.getElementById("app")!).render(<App />);
```

```jsonc title="tsconfig.json"
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "remix/component" } }
```

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

`pitlane/vite-plugin-remix` comes from the `pitlane` package. The github-pages template depends on the scoped `@pitlane/vite-plugin-remix` package, so add `pitlane` before switching the import. If only `vite.config.ts` imports it, install it as a dev dependency with `npm add -D pitlane`. The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) lists the `remix` and `vite` versions it requires and the standalone `@pitlane/vite-plugin-remix` alternative.

## The two GitHub Pages quirks

**Base path.** A project site is served from `https://<user>.github.io/<repo>/`, so Vite needs the base configured or every asset URL 404s:

```ts title="vite.config.ts"
export default defineConfig({
    base: "/<repo>/",
    plugins: [remix({ server: false })],
});
```

User/organization sites (`<user>.github.io`) and custom domains serve from `/` and skip this.

**SPA fallback.** Pages has no rewrite rules; the convention is a `404.html` that is a copy of `index.html`, so deep links boot the app:

```sh
vite build && cp dist/index.html dist/404.html
```

## Prerendered sites

SPA mode is one way to fill a static host. The other is a server-rendered app whose pages are all static: [`remix({ prerender })`](https://pitlane.tools/guides/prerendering.md) renders them to HTML during `vite build`, and Pages serves a real document per path instead of one shell.

```ts title="vite.config.ts"
export default defineConfig({
    plugins: [remix({ prerender: true })],
});
```

`true` covers every static path in the route map, read from the server entry's `routes` export; an explicit list, a function, or `spider: true` covers the rest. Pages has no server, so every URL the site answers must be in the output. See [where the paths come from](https://pitlane.tools/guides/prerendering.md#where-the-paths-come-from).

Each path lands as `<path>/index.html` under `dist/client`, beside the hashed assets, so the workflow below uploads `dist/client` instead of `dist` and skips the `404.html` copy: deep links hit real files, and a URL outside the prerendered set is a real 404.

The base path quirk holds, spelled differently: declare the routes under the base and set Vite's `base` to match. Output is written relative to the base. A route on `/<repo>/blog` still writes `blog/index.html`, because Pages mounts the uploaded directory at `/<repo>/`:

```ts title="app/routes.ts"
import { get, route } from "remix/routes";

export let routes = route({
    home: "/<repo>",
    blog: get("/<repo>/blog"),
});
```

## Deploy with GitHub Actions

GitHub Pages deploys through Actions. There is no separate CLI deploy. Enable it once under **Settings → Pages → Source: GitHub Actions**, then:

```yaml title=".github/workflows/deploy.yml"
name: Deploy

on:
    push:
        branches: [main]

permissions:
    contents: read
    pages: write
    id-token: write

concurrency:
    group: pages
    cancel-in-progress: false

jobs:
    deploy:
        runs-on: ubuntu-latest
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: 24

            - run: npm ci

            - run: npm run build && cp dist/index.html dist/404.html

            - uses: actions/configure-pages@v5

            - uses: actions/upload-pages-artifact@v3
              with:
                  path: dist

            - id: deployment
              uses: actions/deploy-pages@v4
```

Every push to `main` publishes. The deployment URL shows up on the workflow run and under the repository's **Environments**.

# Crawler

Source: https://pitlane.tools/guides/crawler.md

> How pitlane/crawler walks a Remix 3 fetch router in memory, and the jobs that walk is good for: sitemaps, link checks, and render smoke tests.

[`pitlane/crawler`](https://pitlane.tools/package/crawler/index.md) walks an app by dispatching requests straight into its router:

```ts
import { crawl } from "pitlane/crawler";

import router from "./app/entry.server.ts";

for await (let { pathname, response } of crawl(router)) {
    console.log(pathname, response.status);
}
```

`router.fetch` is the whole transport, so the crawl runs wherever the app runs and sees what a real request sees, at the cost of a function call per page.

Every page it fetches is scanned for links, and those are fetched too, so one call reaches everything reachable from `/`.

> [!TIP]
>
> **Prerendering a site?**
>
> Writing an app's pages to disk has its own guide in two halves. [Prerendering](https://pitlane.tools/guides/prerendering.md) is the one for an app built with Vite, where `remix({ prerender })` runs this package for you. [Prerendering without a build](https://pitlane.tools/guides/prerendering-no-build.md) is the one for an app with no bundler. This guide is for the other jobs a walk is good for.

## Install

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The `pitlane` package provides `pitlane/crawler` along with the rest of Pitlane. It requires `remix@^3.0.0` and `vite@>=8` as peer dependencies. An app without Vite can use `@pitlane/crawler` on its own with `remix@^3.0.0`. [Prerendering without a build](https://pitlane.tools/guides/prerendering-no-build.md) uses that setup. For this install, change the examples' imports to `@pitlane/crawler`:

```sh
npm add @pitlane/crawler
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) compares the two installs. The first argument to [`crawl()`](https://pitlane.tools/package/crawler/function/crawl.md) is anything with a `fetch(request: Request)` method, so a `createRouter()` router works, and so does a built bundle's default export or a hand-written `{ fetch }` object.

## Exporting a static site

Writing every response to disk has moved into [prerendering without a build](https://pitlane.tools/guides/prerendering-no-build.md), which covers the loop, where each response belongs on disk, and what to do about assets.

## Generating a sitemap

A crawl already knows every URL, so a sitemap is the same loop with a different body:

```ts
import { crawl } from "pitlane/crawler";

const ORIGIN = "https://example.com";

let urls: string[] = [];
for await (let { pathname, response } of crawl(router, { assets: false })) {
    if (response.headers.get("Content-Type")?.includes("text/html")) {
        urls.push(`${ORIGIN}${pathname}`);
    }
}

let sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls
    .sort()
    .map(url => `  <url><loc>${url}</loc></url>`)
    .join("\n")}
</urlset>`;
```

The `Content-Type` check keeps JSON endpoints out of the file. Redirects never arrive in the first place. Sorting keeps the output stable, so a rebuild produces no diff when nothing changed.

## Checking for broken links in CI

A crawl aborts on the first failing response, meaning any status outside the 2xx range that is not a redirect, with the failing path in the message. That makes a link check a test with no assertions in it:

```ts
import { crawl } from "pitlane/crawler";
import { it } from "vitest";

import router from "../app/entry.server.ts";

it("answers every page it links to", async () => {
    // Throws `Crawl failed: 404 Not Found (/blog/renamed-post)` on a dead link.
    for await (let _ of crawl(router, { concurrency: 8 })) {
        // Nothing to assert: reaching the end is the assertion.
    }
});
```

This catches the class of bug a type checker cannot see. An `href` typed by hand, a post that was renamed, a route deleted while a nav item survived it. Leave `assets: true` on and it checks stylesheet and script URLs too.

## Smoke-testing every page renders

The same walk, reading each response instead of discarding it, tells you whether any page throws once real data flows through it:

```ts
for await (let { pathname, response } of crawl(router, { concurrency: 8 })) {
    let html = await response.text();
    expect(html, `${pathname} rendered an error boundary`).not.toContain("data-error-boundary");
}
```

Bodies arrive unread, so the caller decides whether to read them. A crawl that never reads a body never buffers one.

## Crawling part of a site

Spidering is on by default, which makes `crawl(router)` mean "everything reachable". Turn it off and the crawl fetches exactly the paths it was given:

```ts
crawl(router, { paths: ["/", "/about", "/pricing"], spider: false });
```

Or keep it on and pick different starting points, which walks those subtrees and nothing else:

```ts
crawl(router, { paths: ["/docs"] });
```

`concurrency` sets how many paths are in flight at once. Rendering happens in process, so the useful value depends on how much of a render waits on I/O. Start at the default of 1 and measure. [`CrawlOptions`](https://pitlane.tools/package/crawler/interface/CrawlOptions.md) lists every option.

## Where a crawl stops

Crawling stops where a crawler should stop, so a walk over a real site does not wander off it:

- `rel="nofollow"` on a link, and `<meta name="robots" content="nofollow">` on a page.
- Absolute and protocol-relative URLs, which belong to another origin.
- `#fragment`, `mailto:`, `tel:`, `javascript:`, and `data:` hrefs.

`ignorePageNofollow` is the escape hatch for a page whose `nofollow` is aimed at search engines rather than at you, such as a versioned docs tree that should not be indexed but does need to be built:

```ts
crawl(router, {
    ignorePageNofollow: pathname => pathname.startsWith("/docs/v1/"),
});
```

## Asking what pages exist

[`staticPaths()`](https://pitlane.tools/package/crawler/function/staticPaths.md) answers the question that comes before a crawl: which paths can this app serve with no params?

```ts
import { staticPaths } from "pitlane/crawler";
import { get, route } from "remix/routes";

export let routes = route({
    home: "/",
    blog: get("/blog"),
    post: get("/blog/:slug"),
});

staticPaths(routes); // ["/", "/blog"]
```

A route qualifies when it answers `GET` (or any method) and its pattern declares no variables or wildcards. `/blog/:slug` drops out, because its values live outside the route map. Results are deduplicated and sorted.

This is the Remix 3 answer to React Router's `getStaticPaths`. A Remix router exposes no route table, but the route map it was built from is an ordinary object. That is the thing worth reading.

Pair it with the paths only the app knows:

```ts
crawl(router, {
    paths: [...staticPaths(routes), ...slugs.map(slug => `/blog/${slug}`)],
    spider: false,
});
```

## What it is not

A crawl dispatches `Request` objects and reads the HTML that comes back. It runs no JavaScript, so a page whose content appears after hydration looks empty to it. Use a browser for that.

It also has no opinion about robots.txt, rate limits, or other origins, because it never leaves the router it was handed. Point it at a URL and it will not go.

# Prerendering

Source: https://pitlane.tools/guides/prerendering.md

> How remix({ prerender }) renders paths to static HTML during vite build, and where the paths come from.

This guide for: **Vite** · [No Build](https://pitlane.tools/guides/prerendering-no-build.md)

A page whose content does not change per request does not need a server on the critical path. Render it once, write the HTML to disk, and a static host serves it without waking anything up.

[`remix({ prerender })`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md#prerender) renders those pages during `vite build` and writes the HTML into the client output.

```ts title="vite.config.ts"
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ prerender: ["/", "/blog", "/blog/hello-world"] })],
});
```

`pitlane/vite-plugin-remix` comes from the `pitlane` package. The [Pitlane package guide](https://pitlane.tools/guides/umbrella.md) covers installing it and the standalone `@pitlane/vite-plugin-remix` alternative.

There is no separate rendering path. A `Request` goes through the same fetch handler production runs, and the response that comes back is the page. Route handlers, middleware, and components behave exactly as they do at runtime, because they are the same code answering the same request.

Both setups write the same thing, real HTML at real paths, and differ only in what drives the rendering.

This page describes the Vite build, and [Prerendering without a build](https://pitlane.tools/guides/prerendering-no-build.md) describes doing the same job from a script, for an app with no bundler.

## Where the paths come from

Four shapes, in order of how much the app knows about its own URLs.

### Everything static

`true` prerenders every path the app's route map can serve with no params.

```ts
remix({ prerender: true });
```

`/` and `/blog` qualify. `/blog/:slug` does not, because the slugs live outside the route map. For this to work the server entry has to export the route map alongside its handler:

```ts title="app/entry.server.tsx"
export { routes } from "./routes.ts";
export default router;
```

Without that export the build fails and says so, rather than quietly prerendering nothing.

### An explicit list

```ts
let slugs = getPostSlugs();

remix({
    prerender: ["/", "/blog", ...slugs.map(slug => `/blog/${slug}`)],
});
```

### A function

When the list needs a database, a CMS, or a filesystem walk, pass a function. It receives [`getStaticPaths()`](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderContext.md#getstaticpaths), which is the `true` behavior on demand, so the per-slug half is the only part you write:

```ts
remix({
    async prerender({ getStaticPaths }) {
        let slugs = await getPostSlugsFromCMS();
        return [
            ...getStaticPaths(), // "/" and "/blog"
            ...slugs.map(slug => `/blog/${slug}`),
        ];
    },
});
```

### The object form

`paths` takes any of the three above, and two more options come with it, all documented on [`PrerenderConfig`](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md):

```ts
remix({
    prerender: {
        paths: true,
        concurrency: 4,
        spider: false,
    },
});
```

`concurrency` sets how many paths render at once. Rendering is CPU-bound in process, so the gain depends on how much of a render waits on I/O. Start at the default of 1 and measure.

## Spidering

Spidering turns the path list into a set of starting points. Every rendered page is scanned for links, and those get rendered too.

`spider: true` turns it on:

```ts
remix({ prerender: { paths: ["/"], spider: true } });
```

One starting path can be the whole list for a site whose pages all link to each other. Anything reachable gets built, including the page you forgot to list.

Crawling stops where a crawler should stop: `rel="nofollow"` links, `<meta name="robots" content="nofollow">` pages, other origins, and non-navigable hrefs like `mailto:`.

That is [`@pitlane/crawler`](https://pitlane.tools/package/crawler/index.md) underneath. Import it as `pitlane/crawler` for jobs outside prerendering. The [crawling guide](https://pitlane.tools/guides/crawler.md) covers sitemap generation and link checks.

## Output on disk

Each page becomes an `index.html` under its own path, so a static host serves it back for the original URL.

Under the client output:

```
dist/client/
├─ index.html                    ← /
├─ blog/
│  ├─ index.html                 ← /blog
│  └─ hello-world/
│     └─ index.html              ← /blog/hello-world
└─ assets/
   ├─ entry.browser-<hash>.js
   └─ index-<hash>.css
```

The build logs each file as it writes it.

The `assets/` directory beside them is the build's own output. Prerendering never fetches a page's stylesheets or scripts, because Vite already emitted every one of them.

Prerendering runs last, after both environments are built and the asset manifest is written. The [asset resolver](https://pitlane.tools/guides/vite-plugin.md#document-assets) supplies the same hashed chunk URLs and island preload links as it does for runtime server responses.

If the app is served from a sub-path, declare the routes under it (the [GitHub Pages guide](https://pitlane.tools/deploy/github-pages.md) shows the pattern) and set Vite's `base` to match. The rendered files still go to the top of the client output, because the host mounts that whole directory at the base.

## Paths that redirect

A redirect is not a page, so nothing is written for one. A route answering `302` is an ordinary thing to find in a route map: a `/` pointing at the real landing path, or a URL that moved.

`prerender: true` asks for every static path in the route map, so those routes turn up in the list. The build logs what it skipped and carries on:

```
prerendered nyc/index.html
skipped / (redirects to /nyc)
```

The app still answers that path at runtime, which is the behavior the redirect was for. Nothing about it changes.

When spidering, a redirect is followed rather than skipped, because following links is what spidering is. A crawl seeded at a `/` that points elsewhere still reaches the site instead of stopping at the door.

Any other failing response is a real failure and stops the walk, naming the path it came from:

```
Error: Crawl failed: 404 Not Found (/blog/renamed-post)
```

During a build, that arrives under Vite's own `error during build:` header.

A listed path that 404s is a stale prerender list, and a spidered one is a dead internal link. Both are worth knowing about before a deploy rather than after.

## Serving the output

Keep `server: true`, the default, so the build has a server entry to render through. You can then deploy only the client output for a fully static site, or deploy the server too when some routes need request-time rendering.

Hydration is unaffected. The HTML carries the same island markers a runtime render produces, and the same client entry picks them up.

### Fully static frame navigation

Use separate URLs for documents and frame content, and prerender both. This is the recommended workaround for static sites: initial loads and frame navigation stay 100% prerendered, with no request-time SSR.

Prerendering writes the response for each requested URL. A page route usually returns a full document. Serving that document into a frame duplicates the page shell. Headers cannot select another file at the same path on a static host.

Register separate GET routes in your app:

| URL | Rendered response |
| --- | --- |
| `/` | Home document, including the page shell |
| `/platform/` | Platform document, including the page shell |
| `/_frames/main/home/` | Home frame content only |
| `/_frames/main/platform/` | Platform frame content only |

The document and frame routes can share content components. Render the frame routes through the app's normal Remix renderer, without the document's `<html>`, `<head>`, `<body>`, or surrounding layout. Keep the complete rendered response, including client-entry and nested-frame metadata. Do not extract `innerHTML` from a document.

In the home document, use the frame URL as `<Frame src>` and put both destinations on each link:

```tsx
<>
    <header>
        <a href="/" data-rmx-target="main" data-rmx-src="/_frames/main/home/">
            Home
        </a>
        <a href="/platform/" data-rmx-target="main" data-rmx-src="/_frames/main/platform/">
            Platform
        </a>
    </header>
    <main>
        <Frame name="main" src="/_frames/main/home/" />
    </main>
</>
```

Import `Frame` from `remix/component`. The platform document uses `src="/_frames/main/platform/"` for its initial frame. Keep the existing client entry, assets, and `run({ loadModule })` setup.

`href` is the document URL for the address bar, reloads, and navigation without JavaScript. `data-rmx-src` is the URL Remix fetches into the frame selected by `data-rmx-target`. The default frame resolver works here. No frame headers or custom `resolveFrame` are required. Programmatic navigation uses the same distinction:

```ts
import { navigate } from "remix/component";

navigate("/platform/", {
    target: "main",
    src: "/_frames/main/platform/",
});
```

Prerender every document and frame route:

```ts
remix({
    prerender: ["/", "/platform/", "/_frames/main/home/", "/_frames/main/platform/"],
});
```

The build writes `_frames/main/home/index.html` and `_frames/main/platform/index.html` alongside the document files. Include the frame paths in the prerender list. Spidering follows link `href` values rather than `data-rmx-src`. Pitlane does not generate frame routes or their link attributes for you.

Use URLs that the static host serves directly. With directory-index output, the trailing slashes above avoid asset redirects. Use root-relative links and asset references inside frame content, with the deployment base included when applicable. Moving the response under `/_frames/` then leaves their meaning unchanged.

Every independently loading frame, including nested or unnamed frames, needs a prerendered response at its `src`. This recipe covers public content fixed at build time. A query string does not produce a separate static file. Query-dependent variants need distinct paths, while personalized content and mutations need a backend.

Deploy the output directory without an SSR handler. On Cloudflare, use the [assets-only configuration](https://pitlane.tools/deploy/cloudflare.md#fully-static-frame-navigation). Missing frame assets must return 404 rather than a document or SPA shell. For links that have a static document but no frame response, `data-rmx-document` opts into full-document navigation.

Verify the built output with an assets-only server. Navigate from `/` to Platform and back using the links, then reload `/platform/` directly. Frame requests should fetch `/_frames/main/.../`. The address bar should retain the document URL, with one page shell throughout navigation. Check hydration both on the initial document and on content introduced by a frame response.

### Optional runtime rendering

Apps with per-request frame content can choose the [hybrid Worker-first recipe](https://pitlane.tools/deploy/cloudflare.md#optional-hybrid-rendering) instead. Documents stay prerendered, but frame requests render at runtime. The shown configuration invokes the Worker even for static assets and requires a running SSR app.

## Data that goes stale

A prerendered page is frozen at the moment it rendered. That is the point, and it is also the constraint: a page showing anything that changes between deploys should not be in the list.

There is no revalidation mechanism here, and no incremental regeneration. Render again and redeploy, or leave the path out and let the server answer it.

## A server is required at build time

`remix({ server: false, prerender })` throws. Prerendering needs the server entry to render during the build, while [SPA mode](https://pitlane.tools/guides/spa.md) builds no server. Leave `server: true` for prerendering. Deploying only the generated client output still gives you a fully static site.

## Bundles Node cannot run

Prerendering imports the built server bundle and calls its fetch handler in the build process. A bundle built for another runtime does not load there. A Workers bundle opens with `import { env } from "cloudflare:workers"`, which Node has no answer for.

That is not a restriction on prerendering, only on how the request gets to the app. When the import fails, the build starts the project's own preview server and renders through that instead:

```ts title="vite.config.ts"
import { cloudflare } from "@cloudflare/vite-plugin";
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [
        remix({ serverHandler: false, prerender: true }),
        cloudflare({ viteEnvironment: { name: "ssr" } }),
    ],
});
```

Nothing there names the runtime twice. `@cloudflare/vite-plugin` already supplies a preview server that boots workerd with the app's real bindings, so the pages written to `dist/client` come from the runtime that will serve them. `env` reads resolve, and `navigator.userAgent` says `Cloudflare-Workers`. The same holds for any platform plugin that contributes a preview server.

One thing does change on this path. `getStaticPaths()` normally reads the `routes` export off the built bundle, and that bundle is the thing that will not load. So the build follows the export back to its source instead:

```ts title="app/entry.server.tsx"
import { routes } from "./routes.ts";

export { routes };
export default router;
```

Either spelling works. `export { routes } from "./routes.ts"` says the same thing in one line. What the build needs is a module to point at. A route map written inline in the server entry has none, and the build says so; move it to its own file, which is where it belongs anyway.

# Prerendering (No Build)

Source: https://pitlane.tools/guides/prerendering-no-build.md

> How @pitlane/crawler renders an app's paths to static HTML from a script with no bundler, and where the paths come from.

This guide for: [Vite](https://pitlane.tools/guides/prerendering.md) · **No Build**

A page whose content does not change per request does not need a server on the critical path. Render it once, write the HTML to disk, and a static host serves it without waking anything up.

[`crawl()`](https://pitlane.tools/package/crawler/function/crawl.md) from [`@pitlane/crawler`](https://pitlane.tools/package/crawler/index.md) walks the app from a script and hands back each response with the path it belongs at on disk. The whole job is a `for await` loop and two filesystem calls:

```ts
import { crawl } from "@pitlane/crawler";
import * as fs from "node:fs/promises";
import * as path from "node:path";

import router from "./app/entry.server.ts";

for await (let { filepath, response } of crawl(router)) {
    let outputPath = path.join("dist", filepath);
    await fs.mkdir(path.dirname(outputPath), { recursive: true });
    await fs.writeFile(outputPath, new Uint8Array(await response.arrayBuffer()));
}
```

This page imports from `@pitlane/crawler`, the standalone package, because the `pitlane` package requires Vite as a peer dependency and this app has no bundler. The [crawling guide](https://pitlane.tools/guides/crawler.md#install) has the install command for your package manager.

There is no separate rendering path. A `Request` goes through the same fetch handler production runs, and the response that comes back is the page. Route handlers, middleware, and components behave exactly as they do at runtime, because they are the same code answering the same request.

Both setups write the same thing, real HTML at real paths, and differ only in what drives the rendering.

This page describes the script, for an app with no bundler, and [Prerendering](https://pitlane.tools/guides/prerendering.md) describes the same job in a Vite build, where `remix({ prerender })` runs the crawl for you.

## Where the paths come from

`crawl(router)` starts at `/` and follows the links it finds there. `paths` replaces that starting list:

```ts
crawl(router, { paths: ["/", "/about", "/pricing"], spider: false });
```

[`staticPaths(routes)`](https://pitlane.tools/package/crawler/function/staticPaths.md) fills the half of that list the route map already knows. It returns every path the app can serve with no params, which leaves the per-slug half as the only part you write:

```ts
import { crawl, staticPaths } from "@pitlane/crawler";

import { routes } from "./app/routes.ts";

crawl(router, {
    paths: [...staticPaths(routes), ...slugs.map(slug => `/blog/${slug}`)],
    spider: false,
});
```

[Asking what pages exist](https://pitlane.tools/guides/crawler.md#asking-what-pages-exist) covers what qualifies.

`concurrency` sets how many paths render at once. Rendering is CPU-bound in process, so the gain depends on how much of a render waits on I/O. Start at the default of 1 and measure.

## Spidering

Spidering turns the path list into a set of starting points. Every rendered page is scanned for links, and those get rendered too.

It is on by default, so `crawl(router)` with nothing else already means "everything reachable". Pass `spider: false` to fetch exactly the paths you gave.

One starting path can be the whole list for a site whose pages all link to each other. Anything reachable gets built, including the page you forgot to list.

Crawling stops where a crawler should stop: `rel="nofollow"` links, `<meta name="robots" content="nofollow">` pages, other origins, and non-navigable hrefs like `mailto:`.

`ignorePageNofollow` is the escape hatch for a page whose `nofollow` is aimed at search engines rather than at you, such as a versioned docs tree that should not be indexed but does need to be built. See [where a crawl stops](https://pitlane.tools/guides/crawler.md#where-a-crawl-stops).

## Output on disk

Each page becomes an `index.html` under its own path, so a static host serves it back for the original URL.

`filepath` is where each response belongs, ready to join onto an output directory. Everything that is not HTML keeps its own path instead.

Assets come along too, which is what a site with no bundler needs: the `<link href>`, `<script src>`, and `<img src>` a page references are fetched and written beside it. Pass `assets: false` when something else already emitted those files.

## Paths that redirect

A redirect is not a page, so nothing is written for one. A route answering `302` is an ordinary thing to find in a route map: a `/` pointing at the real landing path, or a URL that moved.

Nothing is yielded for it, so the loop writes nothing. `onRedirect` is called with the path and the `Location` it pointed at, for a script that wants to report what it skipped.

The app still answers that path at runtime, which is the behavior the redirect was for. Nothing about it changes.

When spidering, a redirect is followed rather than skipped, because following links is what spidering is. A crawl seeded at a `/` that points elsewhere still reaches the site instead of stopping at the door.

Any other failing response is a real failure and stops the walk, naming the path it came from:

```
Error: Crawl failed: 404 Not Found (/blog/renamed-post)
```

A listed path that 404s is a stale prerender list, and a spidered one is a dead internal link. Both are worth knowing about before a deploy rather than after.

## Serving the output

The output directory contains the documents and assets for a static host. Frame navigation also needs the separate frame responses described below.

### Fully static frame navigation

Use separate URLs for documents and frame content, and prerender both. This is the recommended workaround for static sites: initial loads and frame navigation stay 100% prerendered, with no request-time SSR.

Prerendering writes the response for each requested URL. A page route usually returns a full document. Serving that document into a frame duplicates the page shell. Headers cannot select another file at the same path on a static host.

Register separate GET routes in your app:

| URL | Rendered response |
| --- | --- |
| `/` | Home document, including the page shell |
| `/platform/` | Platform document, including the page shell |
| `/_frames/main/home/` | Home frame content only |
| `/_frames/main/platform/` | Platform frame content only |

The document and frame routes can share content components. Render the frame routes through the app's normal Remix renderer, without the document's `<html>`, `<head>`, `<body>`, or surrounding layout. Keep the complete rendered response, including client-entry and nested-frame metadata. Do not extract `innerHTML` from a document.

In the home document, use the frame URL as `<Frame src>` and put both destinations on each link:

```tsx
<>
    <header>
        <a href="/" data-rmx-target="main" data-rmx-src="/_frames/main/home/">
            Home
        </a>
        <a href="/platform/" data-rmx-target="main" data-rmx-src="/_frames/main/platform/">
            Platform
        </a>
    </header>
    <main>
        <Frame name="main" src="/_frames/main/home/" />
    </main>
</>
```

Import `Frame` from `remix/component`. The platform document uses `src="/_frames/main/platform/"` for its initial frame. Keep the existing client entry, assets, and `run({ loadModule })` setup.

`href` is the document URL for the address bar, reloads, and navigation without JavaScript. `data-rmx-src` is the URL Remix fetches into the frame selected by `data-rmx-target`. The default frame resolver works here. No frame headers or custom `resolveFrame` are required. Programmatic navigation uses the same distinction:

```ts
import { navigate } from "remix/component";

navigate("/platform/", {
    target: "main",
    src: "/_frames/main/platform/",
});
```

Prerender every document and frame route:

```ts
crawl(router, {
    paths: ["/", "/platform/", "/_frames/main/home/", "/_frames/main/platform/"],
    spider: false,
});
```

The build writes `_frames/main/home/index.html` and `_frames/main/platform/index.html` alongside the document files. Include the frame paths in the prerender list. Spidering follows link `href` values rather than `data-rmx-src`. Pitlane does not generate frame routes or their link attributes for you.

Use URLs that the static host serves directly. With directory-index output, the trailing slashes above avoid asset redirects. Use root-relative links and asset references inside frame content, with the deployment base included when applicable. Moving the response under `/_frames/` then leaves their meaning unchanged.

Every independently loading frame, including nested or unnamed frames, needs a prerendered response at its `src`. This recipe covers public content fixed at build time. A query string does not produce a separate static file. Query-dependent variants need distinct paths, while personalized content and mutations need a backend.

Deploy the output directory without an SSR handler. On Cloudflare, use the [assets-only configuration](https://pitlane.tools/deploy/cloudflare.md#fully-static-frame-navigation). Missing frame assets must return 404 rather than a document or SPA shell. For links that have a static document but no frame response, `data-rmx-document` opts into full-document navigation.

Verify the built output with an assets-only server. Navigate from `/` to Platform and back using the links, then reload `/platform/` directly. Frame requests should fetch `/_frames/main/.../`. The address bar should retain the document URL, with one page shell throughout navigation. Check hydration both on the initial document and on content introduced by a frame response.

### Optional runtime rendering

Apps with per-request frame content can choose the [hybrid Worker-first recipe](https://pitlane.tools/deploy/cloudflare.md#optional-hybrid-rendering) instead. Documents stay prerendered, but frame requests render at runtime. The shown configuration invokes the Worker even for static assets and requires a running SSR app.

## Data that goes stale

A prerendered page is frozen at the moment it rendered. That is the point, and it is also the constraint: a page showing anything that changes between deploys should not be in the list.

There is no revalidation mechanism here, and no incremental regeneration. Render again and redeploy, or leave the path out and let the server answer it.

# Theme

Source: https://pitlane.tools/guides/theme.md

> Style Remix apps with remix/component css mixins and pitlane/theme design tokens.

Remix UI styles elements with the `css()` mixin through the `mix` prop. You manage no class names. Styles stream with server rendering, and structurally equal style objects share one generated class:

```tsx
import { css } from "remix/component";

function Card() {
    return () => <article mix={css({ padding: "16px", color: "#111" })}>…</article>;
}
```

That works, but every value is a loose string. Nothing stops `#111` here and `#121212` two files over. `pitlane/theme` layers design tokens and type safety on top. The [demo app](https://github.com/pitlane-tools/pitlane/tree/main/demos/theme) contains an application-level example.

First, install `pitlane` as a dependency, since the theme runs in production. `remix@^3.0.0` and `vite@>=8` are peer dependencies:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The theme also installs on its own as `@pitlane/theme`, which needs only the `remix` peer. Import from `@pitlane/theme` in place of `pitlane/theme` if you install it that way. [The `pitlane` package](https://pitlane.tools/guides/umbrella.md) compares the two.

## Define a theme

A theme has a schema tree, a token tree, and optional modes. Define it once with [`createTheme()`](https://pitlane.tools/package/theme/function/createTheme.md), such as in `app/theme.ts`, then export the typed accessor, raw-value resolver, and component:

```ts
import { createTheme, lightDark } from "pitlane/theme";
import * as s from "pitlane/theme/schema";

export let {
    token: t,
    raw,
    Theme,
} = createTheme({
    schema: {
        color: s.color(),
        spacing: s.scale(),
        radius: s.dimension(),
        text: s.group(s.dimension(), { leading: s.number() }),
        shadow: s.shadow(),
        animate: s.any(),
        control: s.group(s.dimension(), { color: s.color() }),
    },
    tokens: {
        color: {
            white: "#fff",
            gray: { 50: "#fafafa", 900: "#171717" },
            page: lightDark("#fff", "#171717"),
        },
        spacing: "0.25rem",
        radius: { full: "999px", responsive: "clamp(0.25rem, 2vw, 1rem)" },
        text: { sm: "0.875rem", lg: "1.125rem", leading: { sm: 1.5, lg: 1.35 } },
        shadow: { card: "0 1px 2px rgb(0 0 0 / 0.07)" },
        animate: { spin: "spin 1s linear infinite" },
        control: {
            height: { sm: "28px", md: "32px" },
            color: { default: "#d4d4d8" },
        },
    },
});
```

Token values are the CSS they become. Each schema decides its leaf shape. It can be a string or number, and some schemas use arrays. Plain objects form groups. CSS strings pass through, so `clamp()`, `em`, `%`, `light-dark()`, and CSS color functions remain valid values. Composite schemas use CSS text, as `shadow.card` does above, rather than sub-value objects.

`token`, conventionally destructured as `t`, mirrors the token tree with branded `var()` strings. `t.color.white` is `"var(--color-white)"`. `raw` follows a reference to its concrete value. `<Theme />` installs every custom property. The brands exist at compile time and let `css()` reject a color where a dimension is required.

### Choose schemas

The schema names the type for each token or group. Import the [factories](https://pitlane.tools/package/theme/schema.md) from `pitlane/theme/schema` as `s` to keep those declarations separate from the token values.

| Factory | Token type | Accepted authored value |
| --- | --- | --- |
| [`s.color()`](https://pitlane.tools/package/theme/schema/function/color.md) | `color` | CSS color text, including `light-dark()`, `color-mix()`, and `currentColor` |
| [`s.dimension()`](https://pitlane.tools/package/theme/schema/function/dimension.md) | `dimension` | CSS length text, including `clamp()`, `calc()`, `em`, and `%` |
| [`s.duration()`](https://pitlane.tools/package/theme/schema/function/duration.md) | `duration` | CSS time text, including `ms`, `s`, and `calc()` |
| [`s.number()`](https://pitlane.tools/package/theme/schema/function/number.md) | `number` | A finite number |
| [`s.easing()`](https://pitlane.tools/package/theme/schema/function/easing.md) | `cubicBezier` | `cubic-bezier(...)` text or a four-number tuple |
| [`s.shadow()`](https://pitlane.tools/package/theme/schema/function/shadow.md) | `shadow` | CSS shadow text, including `inset` |
| [`s.border()`](https://pitlane.tools/package/theme/schema/function/border.md) | `border` | CSS border shorthand text |
| [`s.transition()`](https://pitlane.tools/package/theme/schema/function/transition.md) | `transition` | CSS transition shorthand text |
| [`s.gradient()`](https://pitlane.tools/package/theme/schema/function/gradient.md) | `gradient` | CSS gradient function text |
| [`s.stroke()`](https://pitlane.tools/package/theme/schema/function/stroke.md) | `strokeStyle` | `solid`, `dashed`, `dotted`, `double`, `groove`, `ridge`, `outset`, or `inset` |
| [`s.font.family()`](https://pitlane.tools/package/theme/schema/variable/font.md) | `fontFamily` | A font name or an array of font names |
| [`s.font.weight()`](https://pitlane.tools/package/theme/schema/variable/font.md) | `fontWeight` | A number from 1 through 1000, or `thin`, `hairline`, `extra-light`, `ultra-light`, `light`, `normal`, `regular`, `book`, `medium`, `semi-bold`, `demi-bold`, `bold`, `extra-bold`, `ultra-bold`, `black`, `heavy`, `extra-black`, or `ultra-black` |
| [`s.scale()`](https://pitlane.tools/package/theme/schema/function/scale.md) | `dimension` | One base length whose accessor multiplies it |
| [`s.any()`](https://pitlane.tools/package/theme/schema/function/any.md) | None | A string or number emitted verbatim |
| [`s.group(self, children)`](https://pitlane.tools/package/theme/schema/function/group.md) | Inherited from `self` | A typed node with schema overrides for children |

`s.group(self, children)` gives a group a type and lets specific children use another type. In the example, `control.height.sm` inherits `s.dimension()`, while `control.color.default` uses `s.color()`. `default` is an ordinary token name. The schema stores its own type separately, so no token name is reserved.

Use `s.scale()` for a single base value that callers multiply. The accessor is callable, and its `.token` property holds the unmultiplied base:

```ts
t.spacing(4); // calc(var(--spacing) * 4)
t.spacing(0.5); // calc(var(--spacing) * 0.5)
t.spacing.token; // var(--spacing)
```

The module-level [`scale()`](https://pitlane.tools/package/theme/function/scale.md) applies the same operation to an ordinary dimension, duration, or number token:

```ts
import { scale } from "pitlane/theme";

scale(t.text.sm)(2); // calc(var(--text-sm) * 2)
```

Declare `s.any()` for CSS values without a token type, such as `animation` values and aspect ratios. Its accessor has its own brand. Open-grammar properties, including `animation` and `aspectRatio`, accept it. Token-mapped properties, including `color`, reject it.

### Reference and derive tokens

A reference to another token is a property access on the layer below. There is no string syntax for one, so every reference is checked by the compiler and renaming a token breaks its references at build time rather than in the stylesheet.

[`extend`](https://pitlane.tools/package/theme/interface/ThemeResult.md#extend) deep-merges a patch with its base. Its callback receives the accessor of the preceding layer:

```ts
let baseTheme = createTheme({
    schema: { color: s.color() },
    tokens: { color: { white: "#fff" } },
});

let applicationTheme = baseTheme.extend(base => ({
    schema: { surface: s.color() },
    tokens: { surface: { page: base.color.white } },
}));
```

`applicationTheme` emits `--surface-page: var(--color-white)`, so the declaration keeps its indirection and a later override of `color.white` reaches it.

References work across layers, so a semantic tier is a separate `extend` from the primitives it names. That is the shape a design system already has.

A layer's declarations follow the ones it references, which changes where they appear in the `:root` block. Custom properties in one rule resolve independently of order, so nothing about the cascade changes. To keep a namespace in its original place, declare it as an empty group in the base tree: it emits nothing and reserves the position.

```ts
createTheme({
    schema: { palette: s.color() },
    tokens: { palette: { ink: "#1c1a16" }, color: {} },
}).extend(base => ({
    schema: { color: s.color() },
    tokens: { color: { text: base.palette.ink } },
}));
```

A composite is authored as CSS text, so a reference goes inside the shorthand by interpolating the accessor leaf:

```ts
let shadows = baseTheme.extend(base => ({
    schema: { shadow: s.shadow() },
    tokens: { shadow: { card: `0 1px 2px ${base.color.white}` } },
}));
```

That emits `--shadow-card: 0 1px 2px var(--color-white);`, so a mode override of `color.white` reaches the shadow.

[`select`](https://pitlane.tools/package/theme/interface/ThemeResult.md#select) replaces a theme with a projection. It retains selected tokens, and its output paths decide the resulting custom-property names, so a projection can reshape and rename a tree:

```ts
let publicTheme = baseTheme.select(base => ({
    schema: { brand: { primary: s.color() } },
    tokens: { brand: { primary: base.color.white } },
}));

publicTheme.token.brand.primary; // var(--brand-primary)
```

`pitlane/theme/default` exports [`DefaultTheme`](https://pitlane.tools/package/theme/default/variable/DefaultTheme.md), a `<Theme />` component built from Tailwind v4 primitives. It has colors, spacing, radii, fonts, and other primitives. Semantic names belong in the theme that extends it. Select the primitives an application uses before rendering the theme:

```ts
import { createTheme } from "pitlane/theme";
import { DefaultTheme } from "pitlane/theme/default";
import * as s from "pitlane/theme/schema";

export let {
    token: t,
    raw,
    Theme,
} = createTheme(DefaultTheme).select(base => ({
    schema: {
        color: s.color(),
        spacing: s.scale(),
        radius: s.dimension(),
    },
    tokens: {
        color: { blue: base.color.blue, gray: base.color.gray },
        spacing: base.spacing.token,
        radius: base.radius,
    },
}));
```

Validation runs when `createTheme` compiles the theme. Invalid values raise `ValidationError` from `remix/data-schema`. Its `issues` array contains every invalid value with its path and diagnostic. `ValidationError.message` is generic. Structural failures raise [`ThemeError`](https://pitlane.tools/package/theme/class/ThemeError.md), including a reference whose type does not match its position, a reference to an untyped token, a projection that drops a token something it kept refers to, a CSS variable collision, an undeclared token, a mode that overrides an unknown token, and a token tree passed without the `tokens` key that wraps it.

## Install the tokens

Render `<Theme />` once near the root. It emits a `<style>` tag with your custom properties, and it streams correctly during server rendering:

```tsx
import { Theme } from "./theme.ts";

function App() {
    return () => (
        <html>
            <head>
                <Theme />
            </head>
            <body>…</body>
        </html>
    );
}
```

## Use tokens in styles

[`css`](https://pitlane.tools/package/theme/function/css.md) from `pitlane/theme` is remix/component's `css()` with brand enforcement. Token-mapped properties only accept tokens from your theme:

```tsx
import { css } from "pitlane/theme";
import { t } from "./theme.ts";

<article
    mix={css({
        color: t.color.page,
        padding: [t.spacing(2), t.spacing(4)], // tuples join with spaces
        margin: 0,
        // color: "#ff0000", // type error: outside the palette
        "&:hover": { color: t.color.gray[900] },
    })}
/>;
```

Inline `css()` infers the element type from `mix`. For fixed styles reused on one element type, create a descriptor once with an explicit type, such as `css<HTMLAnchorElement>({ color: t.color.page })`. Share [`ThemedCSSProps`](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md) objects instead when the same styles are used on different element types.

Off-palette literals fail to compile. Keywords such as `transparent` and literal `0` stay legal. Properties outside the token-mapped set carry [csstype](https://github.com/frenic/csstype)'s value union, so `resize: "vertical"` autocompletes and `resize: "diagonal"` is a type error, while open-grammar properties such as `background` and `gridTemplateColumns` take any string. Template interpolation covers shorthands: ``border: `1px solid ${t.color.gray[900]}```.

## Dark mode

Use [`lightDark(light, dark)`](https://pitlane.tools/package/theme/function/lightDark.md) for a color whose value follows the active CSS color scheme. The `color.page` token in the theme above becomes `light-dark(#fff, #171717)`, and responds to the operating-system preference without a theme mode. `lightDark()` accepts accessor references too, so its colors can still be overridden in a later layer.

`light-dark()` resolves against the `color-scheme` property, and an undeclared `color-scheme` behaves as light, so the function would otherwise keep its light value on a dark system. `<Theme />` declares `color-scheme: light dark` on `:root` whenever a token uses the function. Declare a narrower value yourself to override it.

Use `modes` for values that CSS `light-dark()` cannot carry, including shadows, dimensions, durations, and font stacks. A mode may set `media`, `selector`, or both. `selector` adds a selector block alongside the mode's media block. `light` and `dark` default to their matching `prefers-color-scheme` query. Supply `media` for an explicit condition or for another mode name.

```ts
modes: {
    light: {
        media: "(prefers-color-scheme: light)",
        selector: ':root[data-color-scheme="light"]',
        tokens: { shadow: { card: "0 1px 2px rgb(0 0 0 / 0.07)" } },
    },
    dark: {
        media: "(prefers-color-scheme: dark)",
        selector: ':root[data-color-scheme="dark"]',
        tokens: { shadow: { card: "0 1px 2px rgb(0 0 0 / 0.4)" } },
    },
},
```

`:root[data-color-scheme="dark"]` and `:root[data-color-scheme="light"]` have greater specificity than `:root` in a media block. An explicit choice wins over the operating-system preference. Set both the attribute and `color-scheme` when a toggle controls values from `modes` and `lightDark()`:

```ts
type ColorScheme = "light" | "dark";

function setColorScheme(scheme: ColorScheme | undefined) {
    let root = document.documentElement;

    if (scheme === undefined) {
        root.removeAttribute("data-color-scheme");
        root.style.removeProperty("color-scheme");
        return;
    }

    root.setAttribute("data-color-scheme", scheme);
    root.style.colorScheme = scheme;
}
```

Call `setColorScheme(undefined)` to return control to the operating-system preference.

## Variants with Theme Variance Authority

[`tva`](https://pitlane.tools/package/theme/function/tva.md) (Theme Variance Authority) is a cva-style variant resolver. It takes brand-enforced style objects instead of class strings and returns a `mix`-ready descriptor:

```ts
import { tva } from "pitlane/theme";
import { t } from "./theme.ts";

export let button = tva({
    base: { padding: [t.spacing(2), t.spacing(4)] },
    variants: {
        intent: {
            primary: { backgroundColor: t.color.gray[900], color: t.color.white },
            neutral: { backgroundColor: t.color.white, color: t.color.gray[900] },
        },
    },
    defaultVariants: { intent: "primary" },
});
```

```tsx
<button mix={button({ intent: "neutral" })} type="button">
    Save
</button>
```

Resolution merges `base` first, then each matching variant. The merged object feeds a single `css()` call, so one invocation produces one class.

### Boolean variants

Name a variant's options `true` and `false` and callers pass a boolean prop:

```ts
export let button = tva({
    variants: {
        block: {
            true: { display: "flex", width: "auto" },
        },
    },
});
```

```tsx
<button mix={button({ block: true })} type="button" />
```

### Compound variants

A compound variant applies extra styles when several conditions hold at once:

```ts
export let button = tva({
    variants: {
        intent: { primary: {}, link: {} },
        size: { sm: {}, md: {} },
    },
    compoundVariants: [{ intent: "link", size: "md", css: { fontSize: t.text.lg } }],
});
```

### Default variants

`defaultVariants` fill in anything the caller omits. An explicit `undefined` falls back to the default too, which keeps spread-through component props predictable:

```ts
button(); // intent "primary"
button({ intent: undefined }); // still "primary"
```

## Compose components with combine

[`combine`](https://pitlane.tools/package/theme/function/combine.md) merges tva components into one, like cva's `compose`. The composed component accepts the union of both prop sets and keeps each input's defaults:

```ts
import { combine, tva } from "pitlane/theme";

let rounded = tva({
    variants: {
        pill: { true: { borderRadius: t.radius.full } },
    },
});

export let pillButton = combine(button, rounded);
```

```tsx
<button mix={pillButton({ intent: "primary", pill: true })} type="button" />
```

## Mix with plain stylesheets

`mix` and `className` compose on the same element, so tokens and existing CSS coexist. [`cx`](https://pitlane.tools/package/theme/function/cx.md) joins class values, compatible with clsx:

```tsx
import { css, cx } from "pitlane/theme";

<span className={cx("mono", isReference && "reference-tag")} mix={css({ fontSize: t.text.sm })}>
    color.page
</span>;
```

## TypeScript

[`TVAProps`](https://pitlane.tools/package/theme/type/TVAProps.md) extracts a component's variant props, like cva's `VariantProps`:

```ts
import type { TVAProps } from "pitlane/theme";

export type ButtonProps = TVAProps<typeof button>;
// { intent?: "primary" | "neutral"; block?: boolean }
```

Wire it into a component's own props to pass variants through:

```tsx
import type { Handle } from "remix/component";

function SaveButton(handle: Handle<{ intent?: ButtonProps["intent"] }>) {
    return () => (
        <button mix={button({ intent: handle.props.intent })} type="button">
            Save
        </button>
    );
}
```

Every variant prop is optional. To require one, wrap the component and re-declare that prop as required:

```ts
import type { TVAProps } from "pitlane/theme";

type ButtonVariants = TVAProps<typeof button>;

type IntentButtonProps = Omit<ButtonVariants, "intent"> & Required<Pick<ButtonVariants, "intent">>;

export let intentButton = (props: IntentButtonProps) => button(props);
```

The [reference](https://pitlane.tools/package/theme/index.md) documents every export, the property-by-property enforcement table, and the error catalog.

## A complete component

These three files define a theme, a typed button variant, and a component that installs the theme near the document root:

```ts title="app/theme.ts"
import { createTheme, lightDark } from "pitlane/theme";
import * as s from "pitlane/theme/schema";

export let {
    token: t,
    raw,
    Theme,
} = createTheme({
    schema: {
        color: s.color(),
        spacing: s.scale(),
        radius: s.dimension(),
        text: s.group(s.dimension(), { leading: s.number() }),
    },
    tokens: {
        color: {
            white: "#fff",
            gray: { 50: "#fafafa", 900: "#171717" },
            page: lightDark("#fff", "#171717"),
        },
        spacing: "0.25rem",
        radius: { full: "999px" },
        text: { sm: "0.875rem", lg: "1.125rem", leading: { sm: 1.5 } },
    },
});
```

```ts title="app/components/button.ts"
import { tva } from "pitlane/theme";
import type { TVAProps } from "pitlane/theme";

import { t } from "../theme.ts";

export let button = tva({
    base: { padding: [t.spacing(2), t.spacing(4)], borderRadius: t.radius.full },
    variants: {
        intent: {
            primary: { backgroundColor: t.color.gray[900], color: t.color.white },
            neutral: { backgroundColor: t.color.white, color: t.color.gray[900] },
        },
    },
    defaultVariants: { intent: "primary" },
});

export type ButtonProps = TVAProps<typeof button>;
```

```tsx title="app/app.tsx"
import type { Handle } from "remix/component";

import { button } from "./components/button.ts";
import type { ButtonProps } from "./components/button.ts";
import { Theme } from "./theme.ts";

function SaveButton(handle: Handle<{ intent?: ButtonProps["intent"] }>) {
    return () => (
        <button mix={button({ intent: handle.props.intent })} type="button">
            Save
        </button>
    );
}

function App() {
    return () => (
        <html>
            <head>
                <Theme />
            </head>
            <body>
                <SaveButton intent="neutral" />
            </body>
        </html>
    );
}
```

## Explore the demo

The [theme demo](https://github.com/pitlane-tools/pitlane/tree/main/demos/theme) is a Remix application for inspecting rendered token styles and component variants. Build the package, then start the demo from its directory:

```sh
vp install
vp -C packages/theme run build
cd demos/theme
vp run dev
```

# Content

Source: https://pitlane.tools/guides/content.md

> How pitlane/content turns Markdown, MDX, and data files into schema-validated collections a Remix 3 controller can query, prebuilt into the bundle by the contentLayer() Vite plugin.

This guide for: **Vite** · [No Build](https://pitlane.tools/guides/content-no-build.md)

**`pitlane/content`** is the best way to manage Markdown, MDX, JSON, YAML, or any other kind of content for your Remix project, including blog posts, product descriptions, character profiles, recipes, or any structured content. Collections help you organize, validate, and query your documents.

The content package enables you to render content from anywhere, whether it lives in your repo or behind a remote API, fetched once or on every request.

## Install

`pitlane/content` is part of the `pitlane` package, which is a runtime dependency because your controllers import the content client. The same install provides [`pitlane/vite-plugin-remix`](https://pitlane.tools/guides/vite-plugin.md), so the Vite config below needs nothing more from Pitlane. Markdown and MDX add two more dependencies, and both are build-only: the plugin compiles the bodies, and [`contentLayer()`](https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md) calls `satteri` directly to retrieve a Markdown file's heading list.

```sh
npm add pitlane
npm add -D satteri vite-plugin-satteri
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

When writing a custom `LiveLoader` that returns a Markdown body which renders at request time even in a bundled application, make sure to declare `satteri` as a runtime dependency instead of a dev dependency.

Installing `pitlane` in `dependencies` already covers the dev server and build plugins, so there is no separate dev-only Pitlane install. Apps that want only the packages they use can install the scoped `@pitlane/*` packages instead, as [The `pitlane` Package](https://pitlane.tools/guides/umbrella.md) describes.

## Configuring Vite

Register two plugins in your Vite config, before [`remix()`](https://pitlane.tools/package/vite-plugin-remix/function/remix.md):

```ts title="vite.config.ts"
import { headings, rawStyles } from "pitlane/content/satteri";
import { contentLayer } from "pitlane/content/vite-plugin";
import { remix } from "pitlane/vite-plugin-remix";
import { defineConfig } from "vite";
import satteri from "vite-plugin-satteri";

export default defineConfig({
    plugins: [
        satteri({
            mdx: { jsxImportSource: "remix/component" },
            mdastPlugins: [headings()],
            hastPlugins: [rawStyles()],
        }),
        contentLayer(),
        remix(),
    ],
});
```

`satteri()` compiles Markdown and MDX bodies during the build. `jsxImportSource: "remix/component"` is required. It is what makes a compiled MDX file a Remix component rather than a React one. [`headings()`](https://pitlane.tools/package/content/satteri/function/headings.md) collects the heading list that `render()` returns, and [`rawStyles()`](https://pitlane.tools/package/content/satteri/function/rawStyles.md) keeps the CSS inside a `<style>` element intact, which any content with a highlighted code block produces.

`rawStyles()` uses `unsafeHTML()` from `remix/component` for a compiled MDX stylesheet. Only use it with trusted content. Its CSS is neither sanitized nor escaped: a literal `</style>` closes the element early. Markdown bodies and `<script>` elements are unchanged.

`contentLayer()` executes `app/content.ts` in Node during the build and inlines every collection's entries into the bundle. Entry data becomes plain values, and Markdown bodies become modules the bundler compiles, so a deployed application never reads the filesystem. That is what lets the same collections run on Cloudflare Workers. Keep that module to collection declarations, with no `cloudflare:workers` imports and nothing that needs a live server. A module at another path is named with `entry`:

```ts
contentLayer({ entry: "app/collections.ts" });
```

A collection of only `.json` or `.yaml` files needs none of the Sätteri setup. `contentLayer()` alone covers it.

## What Is Content?

Pitlane's content package covers a few different dimensions. There is structured data, validated by a schema and consumed as a plain JavaScript object, and there is a renderable body, consumed as a JSX component. Behind both is a source the data is loaded from. Content can be as simple as static JSON or YAML files. Markdown or MDX adds a renderable body while keeping structured data in its frontmatter. Or it could be any arbitrary API call, populating a local store or being refetched on every call. A typical layout:

- `app/`
    - `content.ts` (_the content schema_)
    - `content/`
        - `newsletters/` (_the "newsletters" collection_)
            - `week-1.md` (_a collection entry_)
            - `week-2.md` (_a collection entry_)
            - `week-3.md` (_a collection entry_)
        - `authors.json` (_a single file containing all collection entries for the "authors" collection_)

Collections are defined in the schema file (`app/content.ts`, by convention) which is where you create validations for your content's data and initialize the client for retrieving your content.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

export let content = createContent(c => ({
    newsletters: c.collection({
        loader: loaders.glob({ base: "app/content/newsletters", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            summary: s.string(),
            publishedOn: coerce.date(),
            author: c.reference("authors"),
        }),
    }),
    authors: c.collection({
        loader: loaders.file("app/content/authors.json"),
        schema: s.object({ name: s.string(), bio: s.string() }),
    }),
}));
```

Two types of content collections are available. A [`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md) collection loads its data once, and a live collection fetches it on every request. Both use:

- A required `loader` to retrieve your content and data from wherever it is stored and make it available to your project through content-focused APIs.
- A required `schema` that allows you to define the expected shape of each entry for type safety and validation.

Collections stored locally in your repo or on your filesystem can use one of the two provided loaders (from `pitlane/content/loaders`) to fetch data from Markdown, MDX, YAML, or JSON files. Point the content client to the location of your content, define your data schema, and you're good to go with a blog or another content-heavy, mostly static site in no time!

By writing a `ContentLoader` or a [`LiveLoader`](https://pitlane.tools/package/content/interface/LiveLoader.md) yourself, you can fetch remote data from any external source, such as a CMS, database, or headless payment system, once or live on demand.

## Defining Content Collections

All of your content collections are defined using the [`createContent()`](https://pitlane.tools/package/content/function/createContent.md) function from `pitlane/content`. There is no special location your collections must be defined in, though the `contentLayer()` plugin from `pitlane/content/vite-plugin` uses `app/content.ts` as the default. If you change this location, you'll need to make sure to update the `entry` option of the `contentLayer()` plugin in your `vite.config.ts` file.

`createContent()` returns the content client synchronously. Export it directly and import it where you need it. Construction does no loading. Keep `await` on `getCollection()`, `getEntry()`, and `entry.render()`.

With Vite, `contentLayer()` waits for the declarations to finish, then loads the prebuildable collections before emitting the bundle. Without a bundler, a `ContentLoader` collection loads on its first read. Live collections load on every read in either setup. Neither setup needs an initialization call.

Each individual collection configures:

- a `loader` for a data source (required)
- a `schema` for type safety (required)

```ts title="app/content.ts"
// 1. Import utilities from `pitlane/content`
import { createContent } from "pitlane/content";

// 2. Import loader(s)
import * as loaders from "pitlane/content/loaders";

// 3. Import data schema
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

// 4. Export a single `content` client to use in your controllers
export let content = createContent(c => ({
    // 5. Define a `loader` and `schema` for each collection
    blog: c.collection({
        loader: loaders.glob({ base: "app/content/blog", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            description: s.string(),
            pubDate: coerce.date(),
            updatedDate: s.optional(coerce.date()),
        }),
    }),
}));
```

You can then use the [`getCollection()`](https://pitlane.tools/package/content/interface/Collection.md#getcollection) and [`getEntry()`](https://pitlane.tools/package/content/interface/Collection.md#getentry) methods on each content collection to query your content collections' data and render your content.

## Defining the Collection Schema

Schemas enforce consistent frontmatter or entry data within a collection. A schema **guarantees** that this data exists in a predictable form when you need to reference or query it. If any entry violates its collection schema, the error names the collection, the entry, the file, and every field that failed:

```
Failed to parse entry "hello" in collection "blog" (app/content/blog/hello.md):
  - title: Expected string
  - publishedOn: Expected date
```

Schemas also provide the TypeScript types for your content. The parsed shape is what `entry.data` is typed as when you query the collection, so you get property autocompletion and type-checking with nothing generated and nothing that can go stale.

A `schema` is required. Every frontmatter or data property of your collection entries must be defined using a `remix/data-schema` type:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({ pattern: "**/*.md", base: "app/data/blog" }),
        schema: s.object({
            title: s.string(),
            description: s.string(),
            draft: s.defaulted(s.boolean(), false),
            pubDate: coerce.date(),
            updatedDate: s.optional(coerce.date()),
            tags: s.array(s.string()),
        }),
    }),
    dogs: c.collection({
        loader: loaders.file("app/data/dogs.json"),
        schema: s.object({
            breed: s.string(),
            temperament: s.array(s.string()),
        }),
    }),
}));
```

An entry's `id` is not part of its `data`, so the schema does not declare one. The `file()` loader removes the `id` from each array item before validation, and an object's keys never reach the data at all.

Frontmatter is parsed as YAML, so `pubDate: 2026-01-02` is already a `Date` and `tags: [a, b]` is already an array. `coerce` matters for the fields YAML leaves as strings, such as a quoted date, and for data from an API where everything is a string.

### Defining Datatypes

`remix/data-schema` is one [Standard Schema](https://standardschema.dev) validator. Any other works too, because that is all a schema is asked for, with one catch: [`c.reference()`](https://pitlane.tools/package/content/interface/ContentBuilder.md#reference) has to nest inside a combinator that accepts a foreign schema, which `s.object()` does and Zod's `z.object()` does not.

### Defining Collection References

Collection entries can also "reference" other related entries.

With `c.reference()`, you can define a property in a collection schema as an entry from another collection. It is a schema that accepts a string `id` and produces `{ collection, id }`, and it composes wherever a schema goes, including inside `s.array()` and `s.optional()`.

A common example is a blog post that references reusable author profiles stored as JSON, or related post URLs stored in the same collection:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({ base: "app/content/blog", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            // Reference a single author from the `authors` collection by `id`
            author: c.reference("authors"),
            // Reference an array of related posts from the `blog` collection by `id`
            relatedPosts: s.array(c.reference("blog")),
        }),
    }),
    authors: c.collection({
        loader: loaders.glob({ pattern: "**/*.json", base: "app/data/authors" }),
        schema: s.object({
            name: s.string(),
            portfolio: s.string(),
        }),
    }),
}));
```

This example blog post specifies the `id`s of related posts and the `id` of the post author:

```yaml
---
title: "Welcome to my blog"
author: ben-holmes # references `app/data/authors/ben-holmes.json`
relatedPosts:
    - about-me # references `app/content/blog/about-me.md`
    - my-year-in-review # references `app/content/blog/my-year-in-review.md`
---
```

These references are transformed into objects containing a `collection` key and an `id` key, which you hand straight to the referenced collection to [query the related data](#accessing-referenced-data).

A reference is checked for its collection, not for its entry. Naming a collection that does not exist throws synchronously when `createContent()` runs. Errors thrown by the declaration callback also propagate synchronously; loading and rendering errors reject the read or render call:

```
Unknown collection "wrtiers" referenced by createContent; known collections are blog, authors.
```

Pointing at an entry that does not exist is only discovered on lookup, where `getEntry()` resolves to `undefined`.

## Included Loaders

Pitlane provides two built-in loaders ([`glob()`](https://pitlane.tools/package/content/loaders/function/glob.md) and [`file()`](https://pitlane.tools/package/content/loaders/function/file.md)) for reading your local content. Pass the location of your data in your project or on your filesystem, and these loaders read the files and parse them into entries.

### The `glob()` Loader

The `glob()` loader fetches entries from directories of Markdown, MDX, JSON, or YAML files from anywhere on the filesystem. If you store your content entries locally as separate files, such as a directory of blog posts, then the `glob()` loader is all you need to access your content.

This loader requires a `pattern` of entry files to match, using the glob syntax Node's [`fs.glob`](https://nodejs.org/api/fs.html#fspromisesglobpattern-options) supports, and takes an optional `base` directory the pattern resolves against, which defaults to the project root. A unique `id` for each entry is generated from its path relative to `base`, but you can define custom IDs if needed.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import { glob } from "pitlane/content/loaders";

export let content = createContent(c => ({
    blog: c.collection({
        loader: glob({ pattern: "**/*.md", base: "app/data/blog" }),
        // ...
    }),
}));
```

#### Defining Custom IDs

When using the `glob()` loader, every entry `id` is the matched file path relative to `base`, with the extension removed. `app/content/blog/2026/hello.mdx` under `base: "app/content/blog"` becomes `2026/hello`. Nothing is slugified or lowercased. The `id` is exactly what you named the file, and it is what you pass to `getEntry()` to query the entry directly from your collection. Because it is a path, a nested directory gives you a nested URL when [creating pages from your content](#generating-routes-from-content).

To derive the `id` from something else, pass a `generateId()` function to the `glob()` loader. `entry` is the matched path with its extension still on, and `data` is the entry's parsed frontmatter. `base` is the directory the pattern resolved against. An `id` read from a `slug` field in the frontmatter is the "permalink" of other tools:

```md
---
title: My Blog Post
slug: my-custom-id/supports/slashes
---

Your blog post content here.
```

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({
            pattern: "**/*.{md,mdx}",
            base: "app/content/blog",
            // Prefer a frontmatter `slug`, falling back to the path-based default
            generateId: ({ data, entry }) => (data.slug as string) ?? entry.replace(/\.mdx?$/, ""),
        }),
        // ...
    }),
}));
```

The schema decides whether `slug` survives into `entry.data`. A key the schema does not declare is dropped, so add `slug: s.optional(s.string())` when a template needs to read it.

### The `file()` Loader

The `file()` loader fetches multiple entries from a single local file defined in your collection. The `file()` loader will automatically detect and parse (based on the file extension) a single array of objects from JSON and YAML files.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import { file } from "pitlane/content/loaders";

export let content = createContent(c => ({
    dogs: c.collection({
        loader: file("app/data/dogs.json"),
        // ...
    }),
}));
```

Each entry object in the file must have a unique `id` key property so that the entry can be identified and queried. Unlike the `glob()` loader, the `file()` loader will not automatically generate IDs for each entry.

You can provide your entries as an array of objects with an `id` property, or in object form where the unique `id` is the key:

```jsonc title="app/data/dogs.json"
// Specify an `id` property in each object of an array
[
    { "id": "poodle", "coat": "curly", "shedding": "low" },
    { "id": "afghan", "coat": "short", "shedding": "low" },
]
```

```jsonc title="app/data/dogs.json"
// Each key will be used as the `id`
{
    "poodle": { "coat": "curly", "shedding": "low" },
    "afghan": { "coat": "silky", "shedding": "low" },
}
```

#### Parsing Other Data Formats

Support for parsing single JSON and YAML files into collection entries with the `file()` loader is built-in (unless you have a nested JSON document). To load your collection from unsupported file types, such as `.csv`, you will need to create a parser function. It receives the file's text and must return the parsed entries synchronously.

The following example shows importing a third-party CSV parser then passing a custom `parser` function to the `file()` loader:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import { parse as parseCsv } from "csv-parse/sync";

export let content = createContent(c => ({
    cats: c.collection({
        loader: loaders.file("app/data/cats.csv", {
            parser: text => parseCsv(text, { columns: true, skipEmptyLines: true }),
        }),
        // ...
    }),
}));
```

#### Nested `.json` Documents

The `parser()` argument can be used to load a single collection from a nested JSON document. This JSON file holds two collections:

```jsonc title="app/data/pets.json"
{ "dogs": [{}], "cats": [{}] }
```

You can separate these collections by passing a custom `parser()` function to the `file()` loader for each collection, which parses the file with `JSON.parse` and picks one key:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";

export let content = createContent(c => ({
    dogs: c.collection({
        loader: loaders.file("app/data/pets.json", {
            parser: text => JSON.parse(text).dogs,
        }),
        // ...
    }),
    cats: c.collection({
        loader: loaders.file("app/data/pets.json", {
            parser: text => JSON.parse(text).cats,
        }),
        // ...
    }),
}));
```

## Custom Loaders

Anything that is not a local file is a loader you write, and the shape of the object is the declaration. A `ContentLoader` has a `load()` method that fills a store, and a `LiveLoader` has `loadCollection()` and `loadEntry()` methods that answer one query at a time. Either is passed to `c.collection()` the same way as `glob()` and `file()`:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

import { releases } from "./loaders/releases.ts";

export let content = createContent(c => ({
    releases: c.collection({
        loader: releases({ repository: "pitlane-tools/pitlane" }),
        schema: s.object({
            tag: s.string(),
            name: s.string(),
            publishedOn: coerce.date(),
            prerelease: s.boolean(),
        }),
    }),
}));
```

A custom loader gets everything a built-in one gets: schema validation, `getCollection()` and `getEntry()`, and `render()` when its entries carry a Markdown or MDX body. The reference documents both interfaces, [`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md) and [`LiveLoader`](https://pitlane.tools/package/content/interface/LiveLoader.md).

## Querying Collections

Every collection on the `content` object has two methods to query it and return one or more entries.

- `getCollection()` fetches an entire collection and returns an array of entries.
- `getEntry()` fetches a single entry from a collection by its `id`, or resolves to `undefined` when nothing has that `id`.

```ts
import { content } from "../content.ts";

// Get all entries from a collection
let allBlogPosts = await content.blog.getCollection();

// Get a single entry from a collection by `id`
let poodleData = await content.dogs.getEntry("poodle");
```

Every entry carries the same five things:

| Field | What it is |
| --- | --- |
| `id` | the entry's unique identifier within its collection |
| `collection` | the key this entry came from |
| `data` | the frontmatter or entry data, parsed and validated by the schema |
| `filePath` | the file it was read from, when it came from one |
| `render()` | resolves to the entry's `Content` component and its list of `headings` |

`getCollection()` returns entries sorted by `id` ascending. The order does not depend on the filesystem, so the same content always renders the same way. To return entries in any other order, such as blog posts sorted by date, sort them yourself:

```ts
let posts = (await content.blog.getCollection()).sort(
    (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
);
```

With `contentLayer()` in the Vite config, every `ContentLoader` collection is resolved during the build and its entries are inlined into the bundle. A query at request time reads nothing from disk. A [live collection](#live-collections) is the exception and runs its loader per read.

### Using Content in Components

After querying your collections, you can access each entry's content and metadata directly inside your components. A list of links to your blog posts, showing each entry's frontmatter through its `data` property:

```tsx title="app/actions/blog.tsx"
import { createController } from "remix/router";

import { content } from "../content.ts";
import { routes } from "../routes.ts";

export default createController(routes, {
    actions: {
        async blog({ render }) {
            let posts = await content.blog.getCollection();
            return await render(
                <>
                    <h1>My posts</h1>
                    <ul>
                        {posts.map(post => (
                            <li>
                                <a href={`/blog/${post.id}`}>{post.data.title}</a>
                            </li>
                        ))}
                    </ul>
                </>,
            );
        },
    },
});
```

### Rendering Body Content

Once queried, you can render Markdown and MDX entries to HTML by calling the entry's [`render()`](https://pitlane.tools/package/content/interface/Entry.md#render) method. It resolves to a `Content` component and a list of all rendered headings:

```tsx title="app/actions/blog.tsx"
async post({ params, render }) {
    let post = await content.blog.getEntry(params.slug);
    if (!post) return new Response("Not found", { status: 404 });

    let { Content, headings } = await post.render();
    return await render(
        <article>
            <h1>{post.data.title}</h1>
            <p>Published on: {post.data.pubDate.toDateString()}</p>
            <TableOfContents headings={headings} />
            <Content />
        </article>,
    );
},
```

Nothing parses Markdown until you call `render()`, so listing a collection's titles never pays for the bodies it does not show. Each heading is `{ depth, slug, text }`, and the `slug` matches the `id` on the rendered heading, so a link to `#install` lands on it.

Slugs are the ones GitHub gives the same headings: lowercased, with every character outside letters, marks, digits, and connector punctuation removed, spaces turned into hyphens, and nothing collapsed or trimmed. `## Databases & Data Loading` becomes `databases--data-loading`. Anchors you wrote against a GitHub render, or against Astro, which slugs the same way, keep landing. A heading left with no slug at all, such as `## 🎉`, becomes `heading` instead of an empty `id`, and a repeated slug takes a `-1`, `-2`, … suffix within its document.

A heading's `text`, and the slug made from it, come from what the heading shows on the page. Inline HTML contributes the words inside its tags and never the tags themselves, so `## <span>Visible</span> text` reads `Visible text`. An image contributes nothing, not even its alt text, which is also how GitHub and Astro treat it. The spaces around an image stay, so `## [Docs](/docs) ![Logo](logo.png)` reads `Docs ` and slugs to `docs-`. In MDX, an expression that is a single string literal contributes its value, so `## Hello {"world"}` reads `Hello world` and `## The {"{"} key` reads `The { key`. Any other expression, such as `{name}` or `{1 + 1}`, contributes nothing, because its value is not known until the page renders.

Props on `<Content />` reach an MDX document, which is how you replace the elements it renders with components of your own:

```tsx
<Content components={{ h2: Heading, a: Link }} />
```

Calling `render()` on an entry with no body, such as one from a `.json` file, is an error rather than an empty component, because a blank page is the harder bug to find:

```
Entry "authors/ada" has no renderable content.
```

`render()` does not sanitize a body. A Markdown body's HTML reaches the page as written, and an MDX body runs as code. Render only content you trust, which includes the bodies a `LiveLoader` returns at request time.

A `.md` or `.mdx` body is compiled during the build by the `satteri()` plugin [configured above](#configuring-vite), and `render()` hands back the compiled result.

#### Passing Content as Props

A component can also take an entire collection entry as a prop.

Use the [`CollectionEntry`](https://pitlane.tools/package/content/type/CollectionEntry.md) type to correctly type your component's props. It takes the collection itself rather than its name, so it inherits every property of that collection's schema and cannot drift from it:

```tsx title="app/ui/blog-card.tsx"
import type { CollectionEntry } from "pitlane/content";
import type { Handle } from "remix/component";

import type { content } from "../content.ts";

export function BlogCard(handle: Handle<{ post: CollectionEntry<typeof content.blog> }>) {
    // `post` matches your `blog` collection's schema type
    return () => <h2>{handle.props.post.data.title}</h2>;
}
```

Change the schema and the component stops type-checking.

### Filtering Collection Queries

`getCollection()` takes an optional "filter" callback that allows you to filter your query based on an entry's `id` or `data` properties.

You can use this to filter by any content criteria you like, such as a `draft` property that keeps unfinished blog posts off your blog:

```ts
// Filter out content entries with `draft: true`
let publishedBlogEntries = await content.blog.getCollection(({ data }) => {
    return data.draft !== true;
});
```

You can also keep draft pages visible in development but out of production:

```ts
// Filter out content entries with `draft: true` only when building for production
let blogEntries = await content.blog.getCollection(({ data }) => {
    return import.meta.env.PROD ? data.draft !== true : true;
});
```

The filter argument also supports filtering by nested directories within a collection. Since the `id` includes the full nested path, you can filter by the start of each `id` to only return items from a specific nested directory:

```ts
// Filter entries by sub-directory in the collection
let englishDocsEntries = await content.docs.getCollection(({ id }) => {
    return id.startsWith("en/");
});
```

### Accessing Referenced Data

To access [references defined in your schema](#defining-collection-references), first query your collection entry. The references are available on the returned `data` object as `{ collection, id }` values: `entry.data.author`, `entry.data.relatedPosts`.

Then pass each value to the referenced collection's `getEntry()`. A reference type-checks only against the collection it names, so handing `post.data.author` to `content.tags.getEntry()` is a compile error. There is no separate helper for an array of references. Look each one up:

```tsx title="app/actions/blog.tsx"
async post({ params, render }) {
    // First, query a blog post
    let post = await content.blog.getEntry(params.slug);
    if (!post) return new Response("Not found", { status: 404 });

    // Retrieve a single referenced entry: the blog post's author.
    // Equivalent to `content.authors.getEntry("ben-holmes")`
    let author = await content.authors.getEntry(post.data.author);

    // Retrieve an array of referenced entries: all the related posts
    let relatedPosts = await Promise.all(
        post.data.relatedPosts.map(reference => content.blog.getEntry(reference)),
    );

    return await render(
        <article>
            <h1>{post.data.title}</h1>
            <p>Author: {author?.data.name}</p>

            <h2>You might also like:</h2>
            {relatedPosts.map(
                related => related && <a href={`/blog/${related.id}`}>{related.data.title}</a>,
            )}
        </article>,
    );
},
```

A reference is not checked for existence, so each lookup can resolve to `undefined`. That is where a pointer at a deleted or misspelled entry surfaces.

## Generating Routes from Content

Nothing creates a page for a collection entry on its own. A route with a parameter, and a controller action that looks the parameter up, is what turns entries into pages:

```ts title="app/routes.ts"
import { get, route } from "remix/routes";

export let routes = route({
    blog: get("/blog"),
    post: get("/blog/:slug"),
});
```

```tsx title="app/actions/blog.tsx"
import { createController } from "remix/router";

import { content } from "../content.ts";
import { routes } from "../routes.ts";

export default createController(routes, {
    actions: {
        async post({ params, render }) {
            let post = await content.blog.getEntry(params.slug);
            if (!post) return new Response("Not found", { status: 404 });

            let { Content } = await post.render();
            return await render(
                <article>
                    <h1>{post.data.title}</h1>
                    <Content />
                </article>,
            );
        },
    },
});
```

An entry's `id` is a path, so `app/content/blog/hello-world.md` has an `id` of `hello-world` and is served at `/blog/hello-world`. An `id` with a `/` in it, whether from a nested directory or a [custom `id`](#defining-custom-ids), needs a route pattern that accepts one, such as `/blog/*slug`.

That is the whole story for a page rendered on demand: the entry is looked up when the page is requested. To publish the collection as static HTML instead, hand the same paths to prerendering.

`remix({ prerender })` renders those pages during `vite build`. Pass a function, and the paths come from the collection itself:

```ts title="vite.config.ts"
import { content } from "./app/content.ts";

remix({
    async prerender({ getStaticPaths }) {
        let posts = await content.blog.getCollection();
        return [...getStaticPaths(), ...posts.map(post => `/blog/${post.id}`)];
    },
});
```

[Prerendering](https://pitlane.tools/guides/prerendering.md) covers the other shapes that option takes.

## Live Collections

A live collection fetches its data at request time rather than once. That is the choice for data that changes while the server runs, such as inventory, prices, or draft content an editor expects to see without a deploy, and it costs a fetch per request in exchange.

Live collections use the same `createContent()` and the same `c.collection()`, and are queried with the same `getCollection()` and `getEntry()`. What makes a collection live is its loader. A `LiveLoader` has `loadCollection()` and `loadEntry(id)` methods in place of `load()`, and each one returns its entries directly. There are no built-in live loaders, so every live collection uses one you write for your data source:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

import { cms } from "./loaders/cms.ts";

export let content = createContent(c => ({
    articles: c.collection({
        loader: cms({ endpoint: "https://cms.example.com/api", token: process.env.CMS_TOKEN }),
        schema: s.object({
            title: s.string(),
            updatedOn: coerce.date(),
        }),
    }),
}));
```

The `schema` is validated on every read, because a live source can change its mind between one request and the next.

Errors reach your action the same way a `ContentLoader` collection's do. A loader that throws rejects the query, with the collection named in the error, and `getEntry()` resolves to `undefined` when `loadEntry()` does:

```tsx
async article({ params, render }) {
    let article = await content.articles.getEntry(params.slug);
    if (!article) return new Response("Not found", { status: 404 });

    let { Content } = await article.render();
    return await render(<Content />);
},
```

`loadCollection()` takes no arguments. Filter with the callback `getCollection()` accepts, and when the filtering has to happen at the source, put it in the loader's options and declare a second collection:

```ts
export let content = createContent(c => ({
    articles: c.collection({ loader: cms({ endpoint, token }), schema: article }),
    drafts: c.collection({ loader: cms({ endpoint, token, status: "draft" }), schema: article }),
}));
```

Both kinds of collection can exist in the same `createContent()` call, so each data source gets the kind that fits it. What changes once a collection is live:

- **`contentLayer()` leaves it alone.** There is no single execution for the build to run, so the loader runs per read wherever the application is deployed, and its source has to be reachable from there.
- **Bodies render at request time.** Markdown needs `satteri` installed as a runtime dependency rather than a dev one, as noted under [Install](#install). MDX also needs `new Function`, which Cloudflare Workers forbids, so a live collection cannot serve `.mdx` there.

## Hot Reloading for Your Content

The `contentLayer()` plugin watches every path the loaders report. Editing, adding, or deleting a content file rebuilds the affected collection and reloads the page, so nothing here needs a restart. A `LiveLoader` re-reads on every request anyway and has nothing to watch.

## Reference

- [`pitlane/content`](https://pitlane.tools/package/content/index.md): [`createContent()`](https://pitlane.tools/package/content/function/createContent.md) and the types
- [`pitlane/content/loaders`](https://pitlane.tools/package/content/loaders.md): [`glob()`](https://pitlane.tools/package/content/loaders/function/glob.md) and [`file()`](https://pitlane.tools/package/content/loaders/function/file.md)

- [`pitlane/content/satteri`](https://pitlane.tools/package/content/satteri.md): the [`headings()`](https://pitlane.tools/package/content/satteri/function/headings.md) and [`rawStyles()`](https://pitlane.tools/package/content/satteri/function/rawStyles.md) plugins
- [`pitlane/content/vite-plugin`](https://pitlane.tools/package/content/vite-plugin.md): the [`contentLayer()`](https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md) plugin

# Content (No Build)

Source: https://pitlane.tools/guides/content-no-build.md

> How pitlane/content turns Markdown, MDX, and data files into schema-validated collections a Remix 3 controller can query, served straight from source with Sätteri rendering at request time.

This guide for: [Vite](https://pitlane.tools/guides/content.md) · **No Build**

**`pitlane/content`** is the best way to manage Markdown, MDX, JSON, YAML, or any other kind of content for your Remix project, including blog posts, product descriptions, character profiles, recipes, or any structured content. Collections help you organize, validate, and query your documents.

The content package enables you to render content from anywhere, whether it lives in your repo or behind a remote API, fetched once or on every request.

## Install

`pitlane` and `satteri` are runtime dependencies because the content client transforms the Markdown and MDX at runtime when using it within a Remix no-build setup.

```sh
npm add pitlane satteri
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

`satteri` is an optional peer dependency of `pitlane`, needed only when a collection holds `.md` or `.mdx` files. `pitlane` also requires `vite` 8.1 or later as a peer dependency, so installing it brings Vite into the project even though nothing here bundles. To leave Vite out, install the standalone `@pitlane/content` package instead and import from `@pitlane/content`. [The `pitlane` Package](https://pitlane.tools/guides/umbrella.md) explains the trade.

## What Is Content?

Pitlane's content package covers a few different dimensions. There is structured data, validated by a schema and consumed as a plain JavaScript object, and there is a renderable body, consumed as a JSX component. Behind both is a source the data is loaded from. Content can be as simple as static JSON or YAML files. Markdown or MDX adds a renderable body while keeping structured data in its frontmatter. Or it could be any arbitrary API call, populating a local store or being refetched on every call. A typical layout:

- `app/`
    - `content.ts` (_the content schema_)
    - `content/`
        - `newsletters/` (_the "newsletters" collection_)
            - `week-1.md` (_a collection entry_)
            - `week-2.md` (_a collection entry_)
            - `week-3.md` (_a collection entry_)
        - `authors.json` (_a single file containing all collection entries for the "authors" collection_)

Collections are defined in the schema file (`app/content.ts`, by convention) which is where you create validations for your content's data and initialize the client for retrieving your content.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

export let content = createContent(c => ({
    newsletters: c.collection({
        loader: loaders.glob({ base: "app/content/newsletters", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            summary: s.string(),
            publishedOn: coerce.date(),
            author: c.reference("authors"),
        }),
    }),
    authors: c.collection({
        loader: loaders.file("app/content/authors.json"),
        schema: s.object({ name: s.string(), bio: s.string() }),
    }),
}));
```

Two types of content collections are available. A [`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md) collection loads its data once, and a live collection fetches it on every request. Both use:

- A required `loader` to retrieve your content and data from wherever it is stored and make it available to your project through content-focused APIs.
- A required `schema` that allows you to define the expected shape of each entry for type safety and validation.

Collections stored locally in your repo or on your filesystem can use one of the two provided loaders (from `pitlane/content/loaders`) to fetch data from Markdown, MDX, YAML, or JSON files. Point the content client to the location of your content, define your data schema, and you're good to go with a blog or another content-heavy, mostly static site in no time!

By writing a `ContentLoader` or a [`LiveLoader`](https://pitlane.tools/package/content/interface/LiveLoader.md) yourself, you can fetch remote data from any external source, such as a CMS, database, or headless payment system, once or live on demand.

## Defining Content Collections

All of your content collections are defined using the [`createContent()`](https://pitlane.tools/package/content/function/createContent.md) function from `pitlane/content`. There is no special location your collections must be defined in. Our demos use `app/content.ts` by convention.

`createContent()` returns the content client synchronously. Export it directly and import it where you need it. Construction does no loading. Keep `await` on `getCollection()`, `getEntry()`, and `entry.render()`.

With Vite, `contentLayer()` waits for the declarations to finish, then loads the prebuildable collections before emitting the bundle. Without a bundler, a `ContentLoader` collection loads on its first read. Live collections load on every read in either setup. Neither setup needs an initialization call.

Each individual collection configures:

- a `loader` for a data source (required)
- a `schema` for type safety (required)

```ts title="app/content.ts"
// 1. Import utilities from `pitlane/content`
import { createContent } from "pitlane/content";

// 2. Import loader(s)
import * as loaders from "pitlane/content/loaders";

// 3. Import data schema
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

// 4. Export a single `content` client to use in your controllers
export let content = createContent(c => ({
    // 5. Define a `loader` and `schema` for each collection
    blog: c.collection({
        loader: loaders.glob({ base: "app/content/blog", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            description: s.string(),
            pubDate: coerce.date(),
            updatedDate: s.optional(coerce.date()),
        }),
    }),
}));
```

You can then use the [`getCollection()`](https://pitlane.tools/package/content/interface/Collection.md#getcollection) and [`getEntry()`](https://pitlane.tools/package/content/interface/Collection.md#getentry) methods on each content collection to query your content collections' data and render your content.

## Defining the Collection Schema

Schemas enforce consistent frontmatter or entry data within a collection. A schema **guarantees** that this data exists in a predictable form when you need to reference or query it. If any entry violates its collection schema, the error names the collection, the entry, the file, and every field that failed:

```
Failed to parse entry "hello" in collection "blog" (app/content/blog/hello.md):
  - title: Expected string
  - publishedOn: Expected date
```

Schemas also provide the TypeScript types for your content. The parsed shape is what `entry.data` is typed as when you query the collection, so you get property autocompletion and type-checking with nothing generated and nothing that can go stale.

A `schema` is required. Every frontmatter or data property of your collection entries must be defined using a `remix/data-schema` type:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({ pattern: "**/*.md", base: "app/data/blog" }),
        schema: s.object({
            title: s.string(),
            description: s.string(),
            draft: s.defaulted(s.boolean(), false),
            pubDate: coerce.date(),
            updatedDate: s.optional(coerce.date()),
            tags: s.array(s.string()),
        }),
    }),
    dogs: c.collection({
        loader: loaders.file("app/data/dogs.json"),
        schema: s.object({
            breed: s.string(),
            temperament: s.array(s.string()),
        }),
    }),
}));
```

An entry's `id` is not part of its `data`, so the schema does not declare one. The `file()` loader removes the `id` from each array item before validation, and an object's keys never reach the data at all.

Frontmatter is parsed as YAML, so `pubDate: 2026-01-02` is already a `Date` and `tags: [a, b]` is already an array. `coerce` matters for the fields YAML leaves as strings, such as a quoted date, and for data from an API where everything is a string.

### Defining Datatypes

`remix/data-schema` is one [Standard Schema](https://standardschema.dev) validator. Any other works too, because that is all a schema is asked for, with one catch: [`c.reference()`](https://pitlane.tools/package/content/interface/ContentBuilder.md#reference) has to nest inside a combinator that accepts a foreign schema, which `s.object()` does and Zod's `z.object()` does not.

### Defining Collection References

Collection entries can also "reference" other related entries.

With `c.reference()`, you can define a property in a collection schema as an entry from another collection. It is a schema that accepts a string `id` and produces `{ collection, id }`, and it composes wherever a schema goes, including inside `s.array()` and `s.optional()`.

A common example is a blog post that references reusable author profiles stored as JSON, or related post URLs stored in the same collection:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import * as s from "remix/data-schema";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({ base: "app/content/blog", pattern: "**/*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            // Reference a single author from the `authors` collection by `id`
            author: c.reference("authors"),
            // Reference an array of related posts from the `blog` collection by `id`
            relatedPosts: s.array(c.reference("blog")),
        }),
    }),
    authors: c.collection({
        loader: loaders.glob({ pattern: "**/*.json", base: "app/data/authors" }),
        schema: s.object({
            name: s.string(),
            portfolio: s.string(),
        }),
    }),
}));
```

This example blog post specifies the `id`s of related posts and the `id` of the post author:

```yaml
---
title: "Welcome to my blog"
author: ben-holmes # references `app/data/authors/ben-holmes.json`
relatedPosts:
    - about-me # references `app/content/blog/about-me.md`
    - my-year-in-review # references `app/content/blog/my-year-in-review.md`
---
```

These references are transformed into objects containing a `collection` key and an `id` key, which you hand straight to the referenced collection to [query the related data](#accessing-referenced-data).

A reference is checked for its collection, not for its entry. Naming a collection that does not exist throws synchronously when `createContent()` runs. Errors thrown by the declaration callback also propagate synchronously; loading and rendering errors reject the read or render call:

```
Unknown collection "wrtiers" referenced by createContent; known collections are blog, authors.
```

Pointing at an entry that does not exist is only discovered on lookup, where `getEntry()` resolves to `undefined`.

## Included Loaders

Pitlane provides two built-in loaders ([`glob()`](https://pitlane.tools/package/content/loaders/function/glob.md) and [`file()`](https://pitlane.tools/package/content/loaders/function/file.md)) for reading your local content. Pass the location of your data in your project or on your filesystem, and these loaders read the files and parse them into entries.

### The `glob()` Loader

The `glob()` loader fetches entries from directories of Markdown, MDX, JSON, or YAML files from anywhere on the filesystem. If you store your content entries locally as separate files, such as a directory of blog posts, then the `glob()` loader is all you need to access your content.

This loader requires a `pattern` of entry files to match, using the glob syntax Node's [`fs.glob`](https://nodejs.org/api/fs.html#fspromisesglobpattern-options) supports, and takes an optional `base` directory the pattern resolves against, which defaults to the project root. A unique `id` for each entry is generated from its path relative to `base`, but you can define custom IDs if needed.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import { glob } from "pitlane/content/loaders";

export let content = createContent(c => ({
    blog: c.collection({
        loader: glob({ pattern: "**/*.md", base: "app/data/blog" }),
        // ...
    }),
}));
```

#### Defining Custom IDs

When using the `glob()` loader, every entry `id` is the matched file path relative to `base`, with the extension removed. `app/content/blog/2026/hello.mdx` under `base: "app/content/blog"` becomes `2026/hello`. Nothing is slugified or lowercased. The `id` is exactly what you named the file, and it is what you pass to `getEntry()` to query the entry directly from your collection. Because it is a path, a nested directory gives you a nested URL when [creating pages from your content](#generating-routes-from-content).

To derive the `id` from something else, pass a `generateId()` function to the `glob()` loader. `entry` is the matched path with its extension still on, and `data` is the entry's parsed frontmatter. `base` is the directory the pattern resolved against. An `id` read from a `slug` field in the frontmatter is the "permalink" of other tools:

```md
---
title: My Blog Post
slug: my-custom-id/supports/slashes
---

Your blog post content here.
```

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({
            pattern: "**/*.{md,mdx}",
            base: "app/content/blog",
            // Prefer a frontmatter `slug`, falling back to the path-based default
            generateId: ({ data, entry }) => (data.slug as string) ?? entry.replace(/\.mdx?$/, ""),
        }),
        // ...
    }),
}));
```

The schema decides whether `slug` survives into `entry.data`. A key the schema does not declare is dropped, so add `slug: s.optional(s.string())` when a template needs to read it.

### The `file()` Loader

The `file()` loader fetches multiple entries from a single local file defined in your collection. The `file()` loader will automatically detect and parse (based on the file extension) a single array of objects from JSON and YAML files.

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import { file } from "pitlane/content/loaders";

export let content = createContent(c => ({
    dogs: c.collection({
        loader: file("app/data/dogs.json"),
        // ...
    }),
}));
```

Each entry object in the file must have a unique `id` key property so that the entry can be identified and queried. Unlike the `glob()` loader, the `file()` loader will not automatically generate IDs for each entry.

You can provide your entries as an array of objects with an `id` property, or in object form where the unique `id` is the key:

```jsonc title="app/data/dogs.json"
// Specify an `id` property in each object of an array
[
    { "id": "poodle", "coat": "curly", "shedding": "low" },
    { "id": "afghan", "coat": "short", "shedding": "low" },
]
```

```jsonc title="app/data/dogs.json"
// Each key will be used as the `id`
{
    "poodle": { "coat": "curly", "shedding": "low" },
    "afghan": { "coat": "silky", "shedding": "low" },
}
```

#### Parsing Other Data Formats

Support for parsing single JSON and YAML files into collection entries with the `file()` loader is built-in (unless you have a nested JSON document). To load your collection from unsupported file types, such as `.csv`, you will need to create a parser function. It receives the file's text and must return the parsed entries synchronously.

The following example shows importing a third-party CSV parser then passing a custom `parser` function to the `file()` loader:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";
import { parse as parseCsv } from "csv-parse/sync";

export let content = createContent(c => ({
    cats: c.collection({
        loader: loaders.file("app/data/cats.csv", {
            parser: text => parseCsv(text, { columns: true, skipEmptyLines: true }),
        }),
        // ...
    }),
}));
```

#### Nested `.json` Documents

The `parser()` argument can be used to load a single collection from a nested JSON document. This JSON file holds two collections:

```jsonc title="app/data/pets.json"
{ "dogs": [{}], "cats": [{}] }
```

You can separate these collections by passing a custom `parser()` function to the `file()` loader for each collection, which parses the file with `JSON.parse` and picks one key:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as loaders from "pitlane/content/loaders";

export let content = createContent(c => ({
    dogs: c.collection({
        loader: loaders.file("app/data/pets.json", {
            parser: text => JSON.parse(text).dogs,
        }),
        // ...
    }),
    cats: c.collection({
        loader: loaders.file("app/data/pets.json", {
            parser: text => JSON.parse(text).cats,
        }),
        // ...
    }),
}));
```

## Custom Loaders

Anything that is not a local file is a loader you write, and the shape of the object is the declaration. A `ContentLoader` has a `load()` method that fills a store, and a `LiveLoader` has `loadCollection()` and `loadEntry()` methods that answer one query at a time. Either is passed to `c.collection()` the same way as `glob()` and `file()`:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

import { releases } from "./loaders/releases.ts";

export let content = createContent(c => ({
    releases: c.collection({
        loader: releases({ repository: "pitlane-tools/pitlane" }),
        schema: s.object({
            tag: s.string(),
            name: s.string(),
            publishedOn: coerce.date(),
            prerelease: s.boolean(),
        }),
    }),
}));
```

A custom loader gets everything a built-in one gets: schema validation, `getCollection()` and `getEntry()`, and `render()` when its entries carry a Markdown or MDX body. The reference documents both interfaces, [`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md) and [`LiveLoader`](https://pitlane.tools/package/content/interface/LiveLoader.md).

## Querying Collections

Every collection on the `content` object has two methods to query it and return one or more entries.

- `getCollection()` fetches an entire collection and returns an array of entries.
- `getEntry()` fetches a single entry from a collection by its `id`, or resolves to `undefined` when nothing has that `id`.

```ts
import { content } from "../content.ts";

// Get all entries from a collection
let allBlogPosts = await content.blog.getCollection();

// Get a single entry from a collection by `id`
let poodleData = await content.dogs.getEntry("poodle");
```

Every entry carries the same five things:

| Field | What it is |
| --- | --- |
| `id` | the entry's unique identifier within its collection |
| `collection` | the key this entry came from |
| `data` | the frontmatter or entry data, parsed and validated by the schema |
| `filePath` | the file it was read from, when it came from one |
| `render()` | resolves to the entry's `Content` component and its list of `headings` |

`getCollection()` returns entries sorted by `id` ascending. The order does not depend on the filesystem, so the same content always renders the same way. To return entries in any other order, such as blog posts sorted by date, sort them yourself:

```ts
let posts = (await content.blog.getCollection()).sort(
    (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
);
```

A collection reads its files the first time something queries it, and keeps the result for the life of the process. Relative paths resolve against the directory you start the server from. A failed load is not kept, so the next query tries again.

### Using Content in Components

After querying your collections, you can access each entry's content and metadata directly inside your components. A list of links to your blog posts, showing each entry's frontmatter through its `data` property:

```tsx title="app/actions/blog.tsx"
import { createController } from "remix/router";

import { content } from "../content.ts";
import { routes } from "../routes.ts";

export default createController(routes, {
    actions: {
        async blog({ render }) {
            let posts = await content.blog.getCollection();
            return await render(
                <>
                    <h1>My posts</h1>
                    <ul>
                        {posts.map(post => (
                            <li>
                                <a href={`/blog/${post.id}`}>{post.data.title}</a>
                            </li>
                        ))}
                    </ul>
                </>,
            );
        },
    },
});
```

### Rendering Body Content

Once queried, you can render Markdown and MDX entries to HTML by calling the entry's [`render()`](https://pitlane.tools/package/content/interface/Entry.md#render) method. It resolves to a `Content` component and a list of all rendered headings:

```tsx title="app/actions/blog.tsx"
async post({ params, render }) {
    let post = await content.blog.getEntry(params.slug);
    if (!post) return new Response("Not found", { status: 404 });

    let { Content, headings } = await post.render();
    return await render(
        <article>
            <h1>{post.data.title}</h1>
            <p>Published on: {post.data.pubDate.toDateString()}</p>
            <TableOfContents headings={headings} />
            <Content />
        </article>,
    );
},
```

Nothing parses Markdown until you call `render()`, so listing a collection's titles never pays for the bodies it does not show. Each heading is `{ depth, slug, text }`, and the `slug` matches the `id` on the rendered heading, so a link to `#install` lands on it.

Slugs are the ones GitHub gives the same headings: lowercased, with every character outside letters, marks, digits, and connector punctuation removed, spaces turned into hyphens, and nothing collapsed or trimmed. `## Databases & Data Loading` becomes `databases--data-loading`. Anchors you wrote against a GitHub render, or against Astro, which slugs the same way, keep landing. A heading left with no slug at all, such as `## 🎉`, becomes `heading` instead of an empty `id`, and a repeated slug takes a `-1`, `-2`, … suffix within its document.

A heading's `text`, and the slug made from it, come from what the heading shows on the page. Inline HTML contributes the words inside its tags and never the tags themselves, so `## <span>Visible</span> text` reads `Visible text`. An image contributes nothing, not even its alt text, which is also how GitHub and Astro treat it. The spaces around an image stay, so `## [Docs](/docs) ![Logo](logo.png)` reads `Docs ` and slugs to `docs-`. In MDX, an expression that is a single string literal contributes its value, so `## Hello {"world"}` reads `Hello world` and `## The {"{"} key` reads `The { key`. Any other expression, such as `{name}` or `{1 + 1}`, contributes nothing, because its value is not known until the page renders.

Props on `<Content />` reach an MDX document, which is how you replace the elements it renders with components of your own:

```tsx
<Content components={{ h2: Heading, a: Link }} />
```

Calling `render()` on an entry with no body, such as one from a `.json` file, is an error rather than an empty component, because a blank page is the harder bug to find:

```
Entry "authors/ada" has no renderable content.
```

`render()` does not sanitize a body. A Markdown body's HTML reaches the page as written, and an MDX body runs as code. Render only content you trust, which includes the bodies a `LiveLoader` returns at request time.

Sätteri compiles the body when `render()` is called, and the result is cached with the entry, so a second render of the same post costs nothing. The heading list needs no setup: `pitlane/content` registers the plugin that produces it on `.md` and `.mdx` alike. Extra Sätteri plugins go through the loader:

```ts
loaders.glob({
    pattern: "**/*.md",
    base: "app/content/blog",
    satteri: { hastPlugins: [myPlugin()] },
});
```

> [!WARNING]
>
> **MDX needs a host that allows `new Function`**
>
> Compiling MDX for a request evaluates the compiled body, so the host has to allow it. Node, Bun, and Deno all do.
>
> Markdown has no such requirement and renders anywhere Sätteri runs.

#### Passing Content as Props

A component can also take an entire collection entry as a prop.

Use the [`CollectionEntry`](https://pitlane.tools/package/content/type/CollectionEntry.md) type to correctly type your component's props. It takes the collection itself rather than its name, so it inherits every property of that collection's schema and cannot drift from it:

```tsx title="app/ui/blog-card.tsx"
import type { CollectionEntry } from "pitlane/content";
import type { Handle } from "remix/component";

import type { content } from "../content.ts";

export function BlogCard(handle: Handle<{ post: CollectionEntry<typeof content.blog> }>) {
    // `post` matches your `blog` collection's schema type
    return () => <h2>{handle.props.post.data.title}</h2>;
}
```

Change the schema and the component stops type-checking.

### Filtering Collection Queries

`getCollection()` takes an optional "filter" callback that allows you to filter your query based on an entry's `id` or `data` properties.

You can use this to filter by any content criteria you like, such as a `draft` property that keeps unfinished blog posts off your blog:

```ts
// Filter out content entries with `draft: true`
let publishedBlogEntries = await content.blog.getCollection(({ data }) => {
    return data.draft !== true;
});
```

You can also keep draft pages visible in development but out of production:

```ts
// Filter out content entries with `draft: true` only in production
let blogEntries = await content.blog.getCollection(({ data }) => {
    return process.env.NODE_ENV === "production" ? data.draft !== true : true;
});
```

The filter argument also supports filtering by nested directories within a collection. Since the `id` includes the full nested path, you can filter by the start of each `id` to only return items from a specific nested directory:

```ts
// Filter entries by sub-directory in the collection
let englishDocsEntries = await content.docs.getCollection(({ id }) => {
    return id.startsWith("en/");
});
```

### Accessing Referenced Data

To access [references defined in your schema](#defining-collection-references), first query your collection entry. The references are available on the returned `data` object as `{ collection, id }` values: `entry.data.author`, `entry.data.relatedPosts`.

Then pass each value to the referenced collection's `getEntry()`. A reference type-checks only against the collection it names, so handing `post.data.author` to `content.tags.getEntry()` is a compile error. There is no separate helper for an array of references. Look each one up:

```tsx title="app/actions/blog.tsx"
async post({ params, render }) {
    // First, query a blog post
    let post = await content.blog.getEntry(params.slug);
    if (!post) return new Response("Not found", { status: 404 });

    // Retrieve a single referenced entry: the blog post's author.
    // Equivalent to `content.authors.getEntry("ben-holmes")`
    let author = await content.authors.getEntry(post.data.author);

    // Retrieve an array of referenced entries: all the related posts
    let relatedPosts = await Promise.all(
        post.data.relatedPosts.map(reference => content.blog.getEntry(reference)),
    );

    return await render(
        <article>
            <h1>{post.data.title}</h1>
            <p>Author: {author?.data.name}</p>

            <h2>You might also like:</h2>
            {relatedPosts.map(
                related => related && <a href={`/blog/${related.id}`}>{related.data.title}</a>,
            )}
        </article>,
    );
},
```

A reference is not checked for existence, so each lookup can resolve to `undefined`. That is where a pointer at a deleted or misspelled entry surfaces.

## Generating Routes from Content

Nothing creates a page for a collection entry on its own. A route with a parameter, and a controller action that looks the parameter up, is what turns entries into pages:

```ts title="app/routes.ts"
import { get, route } from "remix/routes";

export let routes = route({
    blog: get("/blog"),
    post: get("/blog/:slug"),
});
```

```tsx title="app/actions/blog.tsx"
import { createController } from "remix/router";

import { content } from "../content.ts";
import { routes } from "../routes.ts";

export default createController(routes, {
    actions: {
        async post({ params, render }) {
            let post = await content.blog.getEntry(params.slug);
            if (!post) return new Response("Not found", { status: 404 });

            let { Content } = await post.render();
            return await render(
                <article>
                    <h1>{post.data.title}</h1>
                    <Content />
                </article>,
            );
        },
    },
});
```

An entry's `id` is a path, so `app/content/blog/hello-world.md` has an `id` of `hello-world` and is served at `/blog/hello-world`. An `id` with a `/` in it, whether from a nested directory or a [custom `id`](#defining-custom-ids), needs a route pattern that accepts one, such as `/blog/*slug`.

That is the whole story for a page rendered on demand: the entry is looked up when the page is requested. To publish the collection as static HTML instead, hand the same paths to prerendering.

The [prerendering guide](https://pitlane.tools/guides/prerendering-no-build.md) covers how to use `@pitlane/crawler` to walk the app from a script and write each response to disk, and a collection's `id`s are the paths to hand it.

## Live Collections

A live collection fetches its data at request time rather than once. That is the choice for data that changes while the server runs, such as inventory, prices, or draft content an editor expects to see without a deploy, and it costs a fetch per request in exchange.

Live collections use the same `createContent()` and the same `c.collection()`, and are queried with the same `getCollection()` and `getEntry()`. What makes a collection live is its loader. A `LiveLoader` has `loadCollection()` and `loadEntry(id)` methods in place of `load()`, and each one returns its entries directly. There are no built-in live loaders, so every live collection uses one you write for your data source:

```ts title="app/content.ts"
import { createContent } from "pitlane/content";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

import { cms } from "./loaders/cms.ts";

export let content = createContent(c => ({
    articles: c.collection({
        loader: cms({ endpoint: "https://cms.example.com/api", token: process.env.CMS_TOKEN }),
        schema: s.object({
            title: s.string(),
            updatedOn: coerce.date(),
        }),
    }),
}));
```

The `schema` is validated on every read, because a live source can change its mind between one request and the next.

Errors reach your action the same way a `ContentLoader` collection's do. A loader that throws rejects the query, with the collection named in the error, and `getEntry()` resolves to `undefined` when `loadEntry()` does:

```tsx
async article({ params, render }) {
    let article = await content.articles.getEntry(params.slug);
    if (!article) return new Response("Not found", { status: 404 });

    let { Content } = await article.render();
    return await render(<Content />);
},
```

`loadCollection()` takes no arguments. Filter with the callback `getCollection()` accepts, and when the filtering has to happen at the source, put it in the loader's options and declare a second collection:

```ts
export let content = createContent(c => ({
    articles: c.collection({ loader: cms({ endpoint, token }), schema: article }),
    drafts: c.collection({ loader: cms({ endpoint, token, status: "draft" }), schema: article }),
}));
```

Both kinds of collection can exist in the same `createContent()` call, so each data source gets the kind that fits it. What changes once a collection is live:

- **Nothing is memoized.** A `ContentLoader` collection reads its source on the first query and keeps the result. A live one asks its loader every time.
- **Schema failures surface on every read** rather than once, so a schema that is expensive to run is a cost paid per request.

## Hot Reloading for Your Content

Add one line beside `createContent()`:

```ts title="app/content.ts"
import { hotContent } from "pitlane/content/hot";

export let content = createContent(c => ({ ... }));

await hotContent(content);
```

This call is safe to leave in place for production. [`hotContent()`](https://pitlane.tools/package/content/hot/function/hotContent.md) does nothing unless the process is supervised by [`remix/node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr), whose `run()` starts `server.ts` as a child process and watches its source. A development script that calls it, started with `NODE_ENV=development`, is the whole setup. Save an edited post and the collection it belongs to is discarded, then the page reloads. A collection whose files did not change keeps what it had.

> [!WARNING]
>
> **A new content file needs a restart**
>
> `remix/node-hmr` reports a file change only for a path it was given, so a post you have just created stays invisible until the server restarts. Edits and deletions to an existing post reload the page as part of HMR.

## Reference

- [`pitlane/content`](https://pitlane.tools/package/content/index.md): [`createContent()`](https://pitlane.tools/package/content/function/createContent.md) and the types
- [`pitlane/content/loaders`](https://pitlane.tools/package/content/loaders.md): [`glob()`](https://pitlane.tools/package/content/loaders/function/glob.md) and [`file()`](https://pitlane.tools/package/content/loaders/function/file.md)

- [`pitlane/content/hot`](https://pitlane.tools/package/content/hot.md): [`hotContent()`](https://pitlane.tools/package/content/hot/function/hotContent.md)

# Cloudflare D1

Source: https://pitlane.tools/guides/cloudflare-d1.md

> How pitlane/data-table-d1 runs Remix 3's data-table on Cloudflare D1, and which parts of D1 the driver cannot paper over.

[`pitlane/data-table-d1`](https://pitlane.tools/package/data-table-d1/index.md) enables you to use the Cloudflare Workers [D1](https://developers.cloudflare.com/d1/) SQLite database with Remix in the same way you'd use `remix/data-table` in a Node app.

```ts title="app/middleware/database.ts"
import { createD1Database } from "pitlane/data-table-d1";
import { env } from "cloudflare:workers";

export let db = createD1Database(env.DB);
```

[`createD1Database()`](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) returns a [`D1Database`](https://pitlane.tools/package/data-table-d1/class/D1Database.md), which is an ordinary `Database`. Queries, writes, migrations, and schema inspection all come from `remix/data-table` unchanged:

```ts
let post = await db.create(Post, { title: "Hello" }, { returnRow: true });
let recent = await db.query(Post).orderBy({ createdAt: "desc" }).limit(10).all();
```

## Setup

Declare the binding in `wrangler.jsonc`:

```jsonc
{
    "d1_databases": [
        {
            "binding": "DB",
            "database_name": "my-app",
            "database_id": "…",
        },
    ],
}
```

Install `pitlane` as a dependency, since the app imports the driver at run time. The same install provides the Vite plugin from `pitlane/vite-plugin-remix`:

```sh
npm add pitlane
```

With yarn, pnpm, bun, vp, vlt, or nub, run the same command with the manager's name in place of `npm`. With deno, put its name in place of `npm` and write each package as `npm:<package>`.

The driver also installs on its own as `@pitlane/data-table-d1`. Import from `@pitlane/data-table-d1` in place of `pitlane/data-table-d1` if you install it that way. [The `pitlane` package](https://pitlane.tools/guides/umbrella.md) compares the two.

Nothing else is required. Now you can start using the D1 database in your Cloudflare Workers Remix app!

## Migrations

Author migrations as `data-table` migrations, compile them to `.sql`, and let Wrangler apply them. The same generated files go to the local and the deployed database, so production runs what you tested.

[`generateD1Migrations`](https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md) does the compiling:

```ts title="db/generate-migrations.ts"
import { generateD1Migrations } from "pitlane/data-table-d1/migrations";

let migrations = await generateD1Migrations({
    to: "db/d1-migrations",
});

console.log(`Generated ${migrations.length} migration(s).`);
```

It reads `db/migrations` by default and writes one `<id>_<name>.sql` per migration into `to`, which is the directory Wrangler reads:

```jsonc
{
    "d1_databases": [
        {
            "binding": "DB",
            "database_name": "my-app",
            "database_id": "…",
            "migrations_dir": "db/d1-migrations",
        },
    ],
}
```

Then the loop is three commands:

```sh
node db/generate-migrations.ts             # TypeScript migrations -> .sql
wrangler d1 migrations apply DB --local    # dev
wrangler d1 migrations apply DB --remote   # production
```

Wrangler records what it has applied in a `d1_migrations` table, so re-running is a no-op and `--remote` picks up only what production has not seen.

Two details worth knowing about the generated directory. Files are written verbatim, so a semicolon inside a trigger body or a string literal survives. Splitting the SQL into statements is Wrangler's job, not the generator's. And the directory is a pure function of the source. A generated `.sql` file whose migration you deleted is removed on the next run, while anything that is not a generated file, such as a `README.md`, is left alone.

`generateD1Migrations` reads the filesystem, so it is build tooling and imports from a separate entry point. It never enters your Worker bundle.

## Knowing what a query cost

D1 bills on rows read and rows written, and its analytics report per database. That tells you the app got expensive, not which query did it. Every D1 response already carries the numbers per statement, and the driver already reads that metadata, so [`onStatement`](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md#onstatement) hands them over instead of discarding them:

```ts
let usage = { rowsRead: 0, rowsWritten: 0 };

let db = createD1Database(env.DB, {
    onStatement({ kind, table, rowsRead, rowsWritten, durationMs }) {
        usage.rowsRead += rowsRead;
        usage.rowsWritten += rowsWritten;
    },
});
```

## Limitations

There are two limitations to the D1 `data-table` driver due to limitations in D1's SQLite dialect itself:

### Transactions throw

D1 rejects `BEGIN`, `COMMIT`, `ROLLBACK`, and `SAVEPOINT` at the SQL layer. Its answer is `d1.batch()`, which is atomic but takes every statement up front, and that cannot express the interleaved begin/execute/commit a `Database` transaction drives.

So `db.transaction()` throws, with a message naming `batch()`. The capabilities say the same thing, which is what stops `data-table` from planning a transactional path in the first place:

```ts
({
    returning: true,
    savepoints: false,
    upsert: true,
    transactionalDdl: false,
    migrationLock: false,
});
```

Failing at the call is the point. The alternative is failing halfway through a write that cannot be rolled back.

#### When several writes must commit together

Use [`db.batch()`](https://pitlane.tools/package/data-table-d1/class/D1Database.md#batch). `batch()` is D1's one atomic primitive: it takes every statement up front and commits them as a unit, which is exactly why it cannot back `transaction()` and exactly why it can back this.

```ts
import { sql } from "remix/data-table";

await db.batch([
    sql`insert into post (title) values (${title})`,
    sql`update counter set posts = posts + 1`,
]);
```

If any statement fails the whole batch rolls back, which is the guarantee `transaction()` cannot give you here. Each result comes back in order, carrying `rows`, `affectedRows`, and `insertId`.

These are `SqlStatement`s rather than query-builder calls, because `data-table` exposes no way to build an operation without running it: `create` and `updateMany` execute on call, and a `Query` has no `toSql()`. `sql` still parameterises the values, so nothing is interpolated by hand and the raw binding stays out of your application code.

#### Opting out of the refusal

`data-table-d1` allows the user to opt into unsafe non-atomic transactions if you need to support shared code across multiple types of SQL databases; a repository layer used by both a Worker and a Postgres service, say.

```ts
let db = createD1Database(env.DB, {
    transactions: "unsafe-nonatomic",
});
```

In this mode, `transaction()` will run the callback and each statement commits on its own. The `unsafe` in the name means one specific thing. **A failure part-way through leaves the earlier writes in place**, because there is nothing to roll back.

```ts
await db.transaction(async tx => {
    await tx.create(Ledger, { note: "first" }); // committed
    await tx.create(Ledger, { note: "second" }); // committed
    throw new Error("boom"); // both rows are still there
});
```

Rollback stays silent rather than throwing, so the error you catch is your own rather than an `AggregateError` about a rollback that was never possible. Nested transactions still fail either way, because `savepoints: false` makes `data-table` reject them before the driver sees them.

Reach for it when portability is worth more than atomicity, and prefer a single statement whenever one will do.

### `wipe()` drops tables

There is no database file to delete, so `wipe()` enumerates the application's tables and drops them. D1's own `_cf_*` bookkeeping and SQLite's `sqlite_*` tables are excluded, because dropping either breaks the binding.

Everything else behaves: `returning`, upserts, bulk inserts, counts, and schema inspection are all exercised against real workerd in the package's test suite.

## Deploying

The [Cloudflare deploy guide](https://pitlane.tools/deploy/cloudflare.md) covers the rest of the picture, including reading bindings through `cloudflare:workers` and why `serverHandler: false` leaves preview to Miniflare.

# @pitlane/assets

Source: https://pitlane.tools/package/assets/index.md

> Framework-neutral asset resolution: construct a resolver from the manifest a build integration supplies, and read browser-entry URLs, preloads, stylesheets, and import maps from it.

Framework-neutral asset resolution: construct a resolver from the manifest a build integration supplies, and read browser-entry URLs, preloads, stylesheets, and import maps from it.

## See

[Asset resolution guide](https://pitlane.tools/guides/assets.md)

## Interfaces

- [AssetEnvironment](https://pitlane.tools/package/assets/interface/AssetEnvironment.md). Every source module observed in one environment's graph, keyed by portable source key.
- [AssetMetadata](https://pitlane.tools/package/assets/interface/AssetMetadata.md). The JavaScript and CSS one source module requires in one environment.
- [AssetResolver](https://pitlane.tools/package/assets/interface/AssetResolver.md). Resolves portable source keys, such as `app/entry.browser.ts` or `file:app/counter.tsx#Counter`, to the URLs a build or development server produced for them.
- [BuildAssetsManifest](https://pitlane.tools/package/assets/interface/BuildAssetsManifest.md). The manifest a production build produces.
- [DevAssetsManifest](https://pitlane.tools/package/assets/interface/DevAssetsManifest.md). The manifest a development server supplies, refreshed as the graph changes.
- [ImportMap](https://pitlane.tools/package/assets/interface/ImportMap.md). An import map as the HTML standard defines it: specifier mappings, optional scoped mappings, and optional integrity metadata.
- [RenderImportMapOptions](https://pitlane.tools/package/assets/interface/RenderImportMapOptions.md). Options for [renderImportMap](https://pitlane.tools/package/assets/function/renderImportMap.md).
- [ScriptEntry](https://pitlane.tools/package/assets/interface/ScriptEntry.md). What a browser needs to load one script entry: its URL, the URLs worth `modulepreload` hints, and the import map its imports resolve through.

## Type Aliases

- [AssetsManifest](https://pitlane.tools/package/assets/type/AssetsManifest.md). Everything `createAssetResolver` accepts. `{ mode: "unavailable" }` is what `@pitlane/assets/manifest` exports when no build integration replaced it.

## Functions

- [createAssetResolver](https://pitlane.tools/package/assets/function/createAssetResolver.md). Constructs the resolver for a manifest, usually the default export of `@pitlane/assets/manifest`. Construct it once, in a module of the app's own.
- [renderImportMap](https://pitlane.tools/package/assets/function/renderImportMap.md). Serializes an import map into an inline `<script type="importmap">` element for server-rendered HTML, or `""` when the map has no mappings.

# createAssetResolver

Source: https://pitlane.tools/package/assets/function/createAssetResolver.md

> Constructs the resolver for a manifest, usually the default export of `@pitlane/assets/manifest`. Construct it once, in a module of the app's own.

```ts
import { createAssetResolver } from "@pitlane/assets";
```

```ts
function createAssetResolver(manifest): AssetResolver;
```

Constructs the resolver for a manifest, usually the default export of `@pitlane/assets/manifest`. Construct it once, in a module of the app's own.

## Parameters

### manifest

[`AssetsManifest`](https://pitlane.tools/package/assets/type/AssetsManifest.md)

## Returns

[`AssetResolver`](https://pitlane.tools/package/assets/interface/AssetResolver.md)

# renderImportMap

Source: https://pitlane.tools/package/assets/function/renderImportMap.md

> Serializes an import map into an inline `<script type="importmap">` element for server-rendered HTML, or `""` when the map has no mappings.

```ts
import { renderImportMap } from "@pitlane/assets";
```

```ts
function renderImportMap(__namedParameters): string;
```

Serializes an import map into an inline `<script type="importmap">` element for server-rendered HTML, or `""` when the map has no mappings.

Every `<` in the JSON is written as `\u003c`, so no key or URL can end the script element; the browser parses the same strings back. The nonce is written as an escaped, quoted attribute. Place the result before any `modulepreload` link or module script.

## Parameters

### \_\_namedParameters

[`RenderImportMapOptions`](https://pitlane.tools/package/assets/interface/RenderImportMapOptions.md)

## Returns

`string`

# AssetEnvironment

Source: https://pitlane.tools/package/assets/interface/AssetEnvironment.md

> Every source module observed in one environment's graph, keyed by portable source key.

```ts
import type { AssetEnvironment } from "@pitlane/assets";
import type { AssetEnvironment } from "@pitlane/assets/build";
```

Every source module observed in one environment's graph, keyed by portable source key.

## Properties

### modules

```ts
modules: Record<string, AssetMetadata>;
```

---

### role

```ts
role: "client" | "server";
```

# AssetMetadata

Source: https://pitlane.tools/package/assets/interface/AssetMetadata.md

> The JavaScript and CSS one source module requires in one environment.

```ts
import type { AssetMetadata } from "@pitlane/assets";
import type { AssetMetadata } from "@pitlane/assets/build";
```

The JavaScript and CSS one source module requires in one environment.

## Properties

### preloads

```ts
preloads: string[];
```

Public URLs of the chunks holding the module and their static JavaScript dependencies.

---

### stylesheets

```ts
stylesheets: string[];
```

Public URLs of the stylesheets those chunks require.

# AssetResolver

Source: https://pitlane.tools/package/assets/interface/AssetResolver.md

> Resolves portable source keys, such as `app/entry.browser.ts` or `file:app/counter.tsx#Counter`, to the URLs a build or development server produced for them.

```ts
import type { AssetResolver } from "@pitlane/assets";
```

Resolves portable source keys, such as `app/entry.browser.ts` or `file:app/counter.tsx#Counter`, to the URLs a build or development server produced for them.

Structurally compatible with the resolution methods of a `remix/assets` asset server, so it can be passed to `render({ assets })`.

## Methods

### getHref()

```ts
getHref(path): Promise<string>;
```

The URL of a registered browser entry, stylesheet, or other asset.

#### Parameters

##### path

`string`

#### Returns

`Promise`\<`string`>

---

### getImportMap()

```ts
getImportMap(path): Promise<ImportMap>;
```

The complete client import map, after checking the keys belong to the client graph.

#### Parameters

##### path

`string` | readonly `string`\[\]

#### Returns

`Promise`\<[`ImportMap`](https://pitlane.tools/package/assets/interface/ImportMap.md)>

---

### getPreloads()

```ts
getPreloads(path): Promise<string[]>;
```

Scripts' chunks and static JavaScript dependencies, and explicitly requested stylesheets.

#### Parameters

##### path

`string` | readonly `string`\[\]

#### Returns

`Promise`\<`string`\[\]>

---

### getScriptEntry()

```ts
getScriptEntry(path): Promise<ScriptEntry>;
```

A registered browser entry's URL, `modulepreload` URLs, and the client import map.

#### Parameters

##### path

`string`

#### Returns

`Promise`\<[`ScriptEntry`](https://pitlane.tools/package/assets/interface/ScriptEntry.md)>

---

### getStylesheets()

```ts
getStylesheets(path): Promise<string[]>;
```

Stylesheets the modules need, from the client graph and the current server graph.

#### Parameters

##### path

`string` | readonly `string`\[\]

#### Returns

`Promise`\<`string`\[\]>

# BuildAssetsManifest

Source: https://pitlane.tools/package/assets/interface/BuildAssetsManifest.md

> The manifest a production build produces.

```ts
import type { BuildAssetsManifest } from "@pitlane/assets";
import type { BuildAssetsManifest } from "@pitlane/assets/build";
```

The manifest a production build produces.

## Properties

### assets

```ts
assets: Record<string, string>;
```

Non-script asset source keys mapped to public URLs.

---

### entries

```ts
entries: Record<string, string>;
```

Browser-entry source keys mapped to public URLs.

---

### environments

```ts
environments: Record<string, AssetEnvironment>;
```

---

### importMap

```ts
importMap: ImportMap;
```

---

### mode

```ts
mode: "build";
```

---

### serverEnvironment?

```ts
optional serverEnvironment?: string;
```

The server environment this manifest was written for.

# DevAssetsManifest

Source: https://pitlane.tools/package/assets/interface/DevAssetsManifest.md

> The manifest a development server supplies, refreshed as the graph changes.

```ts
import type { DevAssetsManifest } from "@pitlane/assets";
```

The manifest a development server supplies, refreshed as the graph changes.

## Properties

### assets

```ts
assets: Record<string, string>;
```

Non-script asset source keys mapped to development URLs.

---

### entries

```ts
entries: Record<string, string>;
```

Browser-entry source keys mapped to development URLs.

---

### environments

```ts
environments: Record<string, AssetEnvironment>;
```

---

### mode

```ts
mode: "dev";
```

---

### serverEnvironment?

```ts
optional serverEnvironment?: string;
```

The server environment this manifest was written for.

# ImportMap

Source: https://pitlane.tools/package/assets/interface/ImportMap.md

> An import map as the HTML standard defines it: specifier mappings, optional scoped mappings, and optional integrity metadata.

```ts
import type { ImportMap } from "@pitlane/assets";
import type { ImportMap } from "@pitlane/assets/build";
```

An import map as the HTML standard defines it: specifier mappings, optional scoped mappings, and optional integrity metadata.

## Properties

### imports

```ts
imports: Record<string, string>;
```

---

### integrity?

```ts
optional integrity?: Record<string, string>;
```

---

### scopes?

```ts
optional scopes?: Record<string, Record<string, string>>;
```

# RenderImportMapOptions

Source: https://pitlane.tools/package/assets/interface/RenderImportMapOptions.md

> Options for [renderImportMap](https://pitlane.tools/package/assets/function/renderImportMap.md).

```ts
import type { RenderImportMapOptions } from "@pitlane/assets";
```

Options for [renderImportMap](https://pitlane.tools/package/assets/function/renderImportMap.md).

## Properties

### nonce?

```ts
optional nonce?: string;
```

A nonce from the application's existing Content Security Policy.

---

### value

```ts
value: ImportMap;
```

The map to serialize, such as `ScriptEntry.importMap`.

# ScriptEntry

Source: https://pitlane.tools/package/assets/interface/ScriptEntry.md

> What a browser needs to load one script entry: its URL, the URLs worth `modulepreload` hints, and the import map its imports resolve through.

```ts
import type { ScriptEntry } from "@pitlane/assets";
```

What a browser needs to load one script entry: its URL, the URLs worth `modulepreload` hints, and the import map its imports resolve through.

Structurally the `ScriptEntry` of `remix/assets`.

## Properties

### href

```ts
href: string;
```

The public URL of the entry module.

---

### importMap

```ts
importMap: ImportMap;
```

The complete client import map, or `{ imports: {} }` when chunk import maps are disabled.

---

### preloads

```ts
preloads: string[];
```

The entry module's URL followed by its static JavaScript dependencies, shallowest first.

# AssetsManifest

Source: https://pitlane.tools/package/assets/type/AssetsManifest.md

> Everything `createAssetResolver` accepts. `{ mode: "unavailable" }` is what `@pitlane/assets/manifest` exports when no build integration replaced it.

```ts
import type { AssetsManifest } from "@pitlane/assets";
```

```ts
type AssetsManifest =
  | BuildAssetsManifest
  | DevAssetsManifest
  | {
  mode: "unavailable";
};
```

Everything `createAssetResolver` accepts. `{ mode: "unavailable" }` is what `@pitlane/assets/manifest` exports when no build integration replaced it.

# @pitlane/assets/build

Source: https://pitlane.tools/package/assets/build.md

> Bundler-neutral manifest generation for integration authors: describe what a bundler emitted as an [AssetBuild](https://pitlane.tools/package/assets/build/interface/AssetBuild.md), and [createAssetManifest](https://pitlane.tools/package/assets/build/function/createAssetManifest.md) returns the manifest `createAssetResolver` reads.

Bundler-neutral manifest generation for integration authors: describe what a bundler emitted as an [AssetBuild](https://pitlane.tools/package/assets/build/interface/AssetBuild.md), and [createAssetManifest](https://pitlane.tools/package/assets/build/function/createAssetManifest.md) returns the manifest `createAssetResolver` reads.

## See

[Manifest integrations guide](https://pitlane.tools/guides/asset-build.md)

## Interfaces

- [AssetBuild](https://pitlane.tools/package/assets/build/interface/AssetBuild.md). A bundler's output, normalized for `createAssetManifest`.
- [AssetBuildChunk](https://pitlane.tools/package/assets/build/interface/AssetBuildChunk.md). One emitted JavaScript chunk.
- [AssetBuildEnvironment](https://pitlane.tools/package/assets/build/interface/AssetBuildEnvironment.md). One environment's output graph.
- [AssetEnvironment](https://pitlane.tools/package/assets/interface/AssetEnvironment.md). Every source module observed in one environment's graph, keyed by portable source key.
- [AssetMetadata](https://pitlane.tools/package/assets/interface/AssetMetadata.md). The JavaScript and CSS one source module requires in one environment.
- [BuildAssetsManifest](https://pitlane.tools/package/assets/interface/BuildAssetsManifest.md). The manifest a production build produces.
- [ImportMap](https://pitlane.tools/package/assets/interface/ImportMap.md). An import map as the HTML standard defines it: specifier mappings, optional scoped mappings, and optional integrity metadata.

## Functions

- [createAssetManifest](https://pitlane.tools/package/assets/build/function/createAssetManifest.md). Converts a bundler's normalized output into the manifest `createAssetResolver` reads.

# createAssetManifest

Source: https://pitlane.tools/package/assets/build/function/createAssetManifest.md

> Converts a bundler's normalized output into the manifest `createAssetResolver` reads.

```ts
import { createAssetManifest } from "@pitlane/assets/build";
```

```ts
function createAssetManifest(build): BuildAssetsManifest;
```

Converts a bundler's normalized output into the manifest `createAssetResolver` reads.

It walks each environment's static chunk graph to record, for every source module, its `modulepreload` URLs (its chunk first, then dependencies shallowest first) and stylesheets (a dependency's before its importer's). Dynamic imports are validated and never followed. It reads no files, invents no edges, and generates no import map; `serverEnvironment` is left for the integration to set per server.

## Parameters

### build

[`AssetBuild`](https://pitlane.tools/package/assets/build/interface/AssetBuild.md)

## Returns

[`BuildAssetsManifest`](https://pitlane.tools/package/assets/interface/BuildAssetsManifest.md)

## Throws

When there is not exactly one client environment, an edge or entry names a missing chunk, a chunk lacks one of its lists, a server environment lists entries, a source key is an absolute file URL, or one source key maps to two URLs.

# AssetBuild

Source: https://pitlane.tools/package/assets/build/interface/AssetBuild.md

> A bundler's output, normalized for `createAssetManifest`.

```ts
import type { AssetBuild } from "@pitlane/assets/build";
```

A bundler's output, normalized for `createAssetManifest`.

Paths and filenames are already portable: source keys are relative to the project root, and `file`/`stylesheets` are emitted filenames relative to `base` or absolute public URLs.

## Properties

### base

```ts
base: string;
```

The public base relative emitted filenames resolve against, such as `/` or `https://cdn.example/app/`.

---

### environments

```ts
environments: Record<string, AssetBuildEnvironment>;
```

Every participating environment by name. Exactly one has the client role.

---

### importMap?

```ts
optional importMap?: ImportMap;
```

The import map the bundler generated for the client build, when it generated one.

# AssetBuildChunk

Source: https://pitlane.tools/package/assets/build/interface/AssetBuildChunk.md

> One emitted JavaScript chunk.

```ts
import type { AssetBuildChunk } from "@pitlane/assets/build";
```

One emitted JavaScript chunk.

## Properties

### dynamicImports

```ts
dynamicImports: string[];
```

Chunk identities this chunk imports dynamically.

---

### file

```ts
file: string;
```

The emitted filename, or an absolute public URL.

---

### imports

```ts
imports: string[];
```

Chunk identities this chunk imports statically, in import order.

---

### modules

```ts
modules: string[];
```

Source keys of every module the chunk contains.

---

### stylesheets

```ts
stylesheets: string[];
```

Emitted stylesheet filenames, or absolute public URLs, the chunk requires.

# AssetBuildEnvironment

Source: https://pitlane.tools/package/assets/build/interface/AssetBuildEnvironment.md

> One environment's output graph.

```ts
import type { AssetBuildEnvironment } from "@pitlane/assets/build";
```

One environment's output graph.

## Properties

### assets

```ts
assets: Record<string, string>;
```

Source keys mapped to emitted non-script files.

---

### chunks

```ts
chunks: Record<string, AssetBuildChunk>;
```

Emitted chunks by opaque, environment-local identity.

---

### entries

```ts
entries: Record<string, string>;
```

Browser-entry source keys mapped to chunk identities. Populated only on the client.

---

### role

```ts
role: "client" | "server";
```

# @pitlane/assets/manifest

Source: https://pitlane.tools/package/assets/manifest.md

> 

## Variables

- [default](https://pitlane.tools/package/assets/manifest/variable/default.md). `{ mode: "unavailable" }`, until `assets()` or an alias replaces this module.

# default

Source: https://pitlane.tools/package/assets/manifest/variable/default.md

> `{ mode: "unavailable" }`, until `assets()` or an alias replaces this module.

```ts
import { default } from "@pitlane/assets/manifest";
```

```ts
default: AssetsManifest;
```

`{ mode: "unavailable" }`, until `assets()` or an alias replaces this module.

# @pitlane/assets/vite-plugin

Source: https://pitlane.tools/package/assets/vite-plugin.md

> 

## Interfaces

- [AssetEntryRegistration](https://pitlane.tools/package/assets/vite-plugin/interface/AssetEntryRegistration.md). Browser entries declared by one server module's development transform.
- [AssetsPluginApi](https://pitlane.tools/package/assets/vite-plugin/interface/AssetsPluginApi.md). Available on the resolved plugin named `pitlane-assets`.
- [AssetsPluginOptions](https://pitlane.tools/package/assets/vite-plugin/interface/AssetsPluginOptions.md). Options for [assets](https://pitlane.tools/package/assets/vite-plugin/function/assets.md). `remix()` from `@pitlane/vite-plugin-remix` accepts them as `remix({ assets })`.

## Variables

- [ASSETS\_MANIFEST\_FILE](https://pitlane.tools/package/assets/vite-plugin/variable/ASSETS_MANIFEST_FILE.md). The manifest module a build writes at the root of each server environment's output directory. The server chunks that read the manifest import this file by a relative path, so a host that deploys a single module must bundle it in.

## Functions

- [assets](https://pitlane.tools/package/assets/vite-plugin/function/assets.md). The Vite plugins that give `@pitlane/assets` its manifest: they serve browser entries during `vite dev`, emit them in a build, and replace `@pitlane/assets/manifest` with the manifest of the current dev server or build. Setting `allowFiles` also enforces the browser boundary.

# assets

Source: https://pitlane.tools/package/assets/vite-plugin/function/assets.md

> The Vite plugins that give `@pitlane/assets` its manifest: they serve browser entries during `vite dev`, emit them in a build, and replace `@pitlane/assets/manifest` with the manifest of the current dev server or build. Setting `allowFiles` also enforces the browser boundary.

```ts
import { assets } from "@pitlane/assets/vite-plugin";
```

```ts
function assets(options?): PluginOption;
```

The Vite plugins that give `@pitlane/assets` its manifest: they serve browser entries during `vite dev`, emit them in a build, and replace `@pitlane/assets/manifest` with the manifest of the current dev server or build. Setting `allowFiles` also enforces the browser boundary.

## Parameters

### options?

[`AssetsPluginOptions`](https://pitlane.tools/package/assets/vite-plugin/interface/AssetsPluginOptions.md) = `{}`

## Returns

`PluginOption`

## Throws

When `allowPackages` or `denyFiles` is set without `allowFiles`.

# AssetEntryRegistration

Source: https://pitlane.tools/package/assets/vite-plugin/interface/AssetEntryRegistration.md

> Browser entries declared by one server module's development transform.

```ts
import type { AssetEntryRegistration } from "@pitlane/assets/vite-plugin";
```

Browser entries declared by one server module's development transform.

## Properties

### entries

```ts
entries: string[];
```

Resolved browser module IDs; an empty list removes the owner's declarations.

---

### environment

```ts
environment: string;
```

The server environment that transformed the owner.

---

### owner

```ts
owner: string;
```

The resolved server module ID declaring these entries.

# AssetsPluginApi

Source: https://pitlane.tools/package/assets/vite-plugin/interface/AssetsPluginApi.md

> Available on the resolved plugin named `pitlane-assets`.

```ts
import type { AssetsPluginApi } from "@pitlane/assets/vite-plugin";
```

Available on the resolved plugin named `pitlane-assets`.

## Methods

### setBrowserEntries()

```ts
setBrowserEntries(registration): void;
```

Replace an owner's declarations; an empty list removes them. Builds use `emitFile` instead.

#### Parameters

##### registration

[`AssetEntryRegistration`](https://pitlane.tools/package/assets/vite-plugin/interface/AssetEntryRegistration.md)

#### Returns

`void`

# AssetsPluginOptions

Source: https://pitlane.tools/package/assets/vite-plugin/interface/AssetsPluginOptions.md

> Options for [assets](https://pitlane.tools/package/assets/vite-plugin/function/assets.md). `remix()` from `@pitlane/vite-plugin-remix` accepts them as `remix({ assets })`.

```ts
import type { AssetsPluginOptions } from "@pitlane/assets/vite-plugin";
```

Options for [assets](https://pitlane.tools/package/assets/vite-plugin/function/assets.md). `remix()` from `@pitlane/vite-plugin-remix` accepts them as `remix({ assets })`.

## Properties

### allowFiles?

```ts
optional allowFiles?: string[];
```

Files and globs, relative to the Vite root, that may reach the browser. Setting it turns on the browser boundary: a build that would publish any other file fails, and `vite dev` refuses to serve one. Read as `remix/assets` reads it; a directory path matches every file below it.

---

### allowPackages?

```ts
optional allowPackages?: string[];
```

Packages that may reach the browser, with their `dependencies` and installed `optionalDependencies`. Peer dependencies are not included. Requires `allowFiles`.

---

### chunkImportMap?

```ts
optional chunkImportMap?: boolean;
```

Override Vite's native setting. With neither setting present, maps are disabled.

---

### denyFiles?

```ts
optional denyFiles?: string[];
```

Files and globs refused even when `allowFiles` or `allowPackages` allows them. Requires `allowFiles`.

---

### include?

```ts
optional include?: string[];
```

Extra source keys to make available as client entries or assets.

---

### serverEnvironments?

```ts
optional serverEnvironments?: string[];
```

Server environments whose module graphs provide metadata. Defaults to `["ssr"]`.

# ASSETS_MANIFEST_FILE

Source: https://pitlane.tools/package/assets/vite-plugin/variable/ASSETS_MANIFEST_FILE.md

> The manifest module a build writes at the root of each server environment's output directory. The server chunks that read the manifest import this file by a relative path, so a host that deploys a single module must bundle it in.

```ts
import { ASSETS_MANIFEST_FILE } from "@pitlane/assets/vite-plugin";
```

```ts
const ASSETS_MANIFEST_FILE: "__pitlane_assets_manifest.js";
```

The manifest module a build writes at the root of each server environment's output directory. The server chunks that read the manifest import this file by a relative path, so a host that deploys a single module must bundle it in.

# @pitlane/content

Source: https://pitlane.tools/package/content/index.md

> Schema-validated, cross-referenced content collections for Remix 3.

Schema-validated, cross-referenced content collections for Remix 3.

[createContent](https://pitlane.tools/package/content/function/createContent.md) declares collections of Markdown, MDX, JSON, and YAML entries, each read by a loader from `@pitlane/content/loaders` and validated by a Standard Schema, and returns a client a controller queries with `getCollection()` and `getEntry()`. The entry types come from the schemas, with nothing generated.

## See

- [Content guide](https://pitlane.tools/guides/content.md)
- [Content guide, without a build](https://pitlane.tools/guides/content-no-build.md)

## Interfaces

- [Collection](https://pitlane.tools/package/content/interface/Collection.md). The query surface of one collection.
- [CollectionDefinition](https://pitlane.tools/package/content/interface/CollectionDefinition.md). What `c.collection({ loader, schema })` returns.
- [ContentBuilder](https://pitlane.tools/package/content/interface/ContentBuilder.md). The builder `createContent` hands to its callback.
- [ContentLoader](https://pitlane.tools/package/content/interface/ContentLoader.md). A loader that resolves a whole collection by filling a store.
- [Entry](https://pitlane.tools/package/content/interface/Entry.md). One entry of a collection, as a caller sees it.
- [EntryBody](https://pitlane.tools/package/content/interface/EntryBody.md). The raw source of an entry's document, before anything renders it.
- [GenerateIdOptions](https://pitlane.tools/package/content/interface/GenerateIdOptions.md). Options handed to a `loaders.glob` `generateId` function.
- [Heading](https://pitlane.tools/package/content/interface/Heading.md). A heading collected from a Markdown or MDX document.
- [LiveEntry](https://pitlane.tools/package/content/interface/LiveEntry.md). What a [LiveLoader](https://pitlane.tools/package/content/interface/LiveLoader.md) returns for one entry.
- [LiveLoader](https://pitlane.tools/package/content/interface/LiveLoader.md). A loader that answers one query at a time.
- [LoadedEntry](https://pitlane.tools/package/content/interface/LoadedEntry.md). What a [ContentLoader](https://pitlane.tools/package/content/interface/ContentLoader.md) writes into the store for one entry.
- [LoaderContext](https://pitlane.tools/package/content/interface/LoaderContext.md). What a loader is handed to read its source and validate what it found.
- [Reference](https://pitlane.tools/package/content/interface/Reference.md). A resolved pointer from one entry to another, produced by `c.reference(collection)`.
- [RenderedEntry](https://pitlane.tools/package/content/interface/RenderedEntry.md). What `entry.render()` resolves to.

## Type Aliases

- [CollectionEntry](https://pitlane.tools/package/content/type/CollectionEntry.md). One entry of `collection`, named the way an application thinks of it: `CollectionEntry<typeof content.blog>`.
- [Content](https://pitlane.tools/package/content/type/Content.md). The object `createContent` returns: one [Collection](https://pitlane.tools/package/content/interface/Collection.md) per key of the definitions its callback returned, named after that key and typed by the output of that collection's schema.
- [Loader](https://pitlane.tools/package/content/type/Loader.md). Either kind of loader.
- [ReferenceSchema](https://pitlane.tools/package/content/type/ReferenceSchema.md). The schema `c.reference(collection)` returns: a Standard Schema that reads an entry id (a string) and outputs a [Reference](https://pitlane.tools/package/content/interface/Reference.md) into `collection`.

## Functions

- [createContent](https://pitlane.tools/package/content/function/createContent.md). Declares a set of content collections.

# createContent

Source: https://pitlane.tools/package/content/function/createContent.md

> Declares a set of content collections.

```ts
import { createContent } from "@pitlane/content";
```

```ts
function createContent<T>(build): Content<T>;
```

Declares a set of content collections.

Returns the collection object synchronously without loading entries. Reads and rendering remain asynchronous. Declaration errors throw here.

Under `contentLayer()`, registers deferred population work. The plugin awaits it after evaluating the declarations and before emitting the bundle.

## Type Parameters

### T

`T` _extends_ `Record`\<`string`, [`CollectionDefinition`](https://pitlane.tools/package/content/interface/CollectionDefinition.md)\<[`StandardSchemaV1`](https://standardschema.dev)\<`unknown`>>>

## Parameters

### build

(`c`: [`ContentBuilder`](https://pitlane.tools/package/content/interface/ContentBuilder.md)) => `T`

Receives the [ContentBuilder](https://pitlane.tools/package/content/interface/ContentBuilder.md) and returns one collection per key, each declared with `c.collection({ loader, schema })`

## Returns

[`Content`](https://pitlane.tools/package/content/type/Content.md)\<`T`>

One [Collection](https://pitlane.tools/package/content/interface/Collection.md) per key of the object `build` returned

## Throws

Error when `c.reference()` names a collection `build` did not declare

## See

- [Content guide](https://pitlane.tools/guides/content.md)
- [Content guide, without a build](https://pitlane.tools/guides/content-no-build.md)

## Example

```ts title="app/content.ts"
import { createContent } from "@pitlane/content";
import * as loaders from "@pitlane/content/loaders";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";

export let content = createContent(c => ({
    blog: c.collection({
        loader: loaders.glob({ base: "app/content/blog", pattern: "*.{md,mdx}" }),
        schema: s.object({
            title: s.string(),
            pubDate: coerce.date(),
            author: c.reference("authors"),
        }),
    }),
    authors: c.collection({
        loader: loaders.file("app/content/authors.json"),
        schema: s.object({ name: s.string() }),
    }),
}));

let posts = await content.blog.getCollection();
let post = await content.blog.getEntry("hello-world");
```

# Collection

Source: https://pitlane.tools/package/content/interface/Collection.md

> The query surface of one collection.

```ts
import type { Collection } from "@pitlane/content";
```

The query surface of one collection.

## Type Parameters

### Name

`Name` _extends_ `string`

### Data

`Data`

## Methods

### getCollection()

```ts
getCollection(filter?): Promise<Entry<Data>[]>;
```

Every entry, sorted by id, keeping only those `filter` returns truthy for when one is given.

#### Parameters

##### filter?

(`entry`: [`Entry`](https://pitlane.tools/package/content/interface/Entry.md)\<`Data`>) => `unknown`

#### Returns

`Promise`\<[`Entry`](https://pitlane.tools/package/content/interface/Entry.md)\<`Data`>\[\]>

---

### getEntry()

```ts
getEntry(id): Promise<Entry<Data> | undefined>;
```

The entry with this id, or the one a [Reference](https://pitlane.tools/package/content/interface/Reference.md) into this collection points at. Resolves to `undefined` when there is none.

#### Parameters

##### id

`string` | [`Reference`](https://pitlane.tools/package/content/interface/Reference.md)\<`Name`>

#### Returns

`Promise`\<[`Entry`](https://pitlane.tools/package/content/interface/Entry.md)\<`Data`> | `undefined`>

# CollectionDefinition

Source: https://pitlane.tools/package/content/interface/CollectionDefinition.md

> What `c.collection({ loader, schema })` returns.

```ts
import type { CollectionDefinition } from "@pitlane/content";
```

What `c.collection({ loader, schema })` returns.

## Type Parameters

### S

`S` _extends_ [`StandardSchemaV1`](https://standardschema.dev) = [`StandardSchemaV1`](https://standardschema.dev)

## Properties

### loader

```ts
loader: Loader;
```

---

### schema

```ts
schema: S;
```

# ContentBuilder

Source: https://pitlane.tools/package/content/interface/ContentBuilder.md

> The builder `createContent` hands to its callback.

```ts
import type { ContentBuilder } from "@pitlane/content";
```

The builder `createContent` hands to its callback.

## Methods

### collection()

```ts
collection<S>(input): CollectionDefinition<S>;
```

Declares one collection: where its entries come from and the schema each must satisfy.

#### Type Parameters

##### S

`S` _extends_ [`StandardSchemaV1`](https://standardschema.dev)\<`unknown`>

#### Parameters

##### input

###### loader

[`Loader`](https://pitlane.tools/package/content/type/Loader.md)

###### schema

`S`

#### Returns

[`CollectionDefinition`](https://pitlane.tools/package/content/interface/CollectionDefinition.md)\<`S`>

---

### reference()

```ts
reference<C>(collection): ReferenceSchema<C>;
```

A schema for a field holding the id of an entry in `collection`, which parses to a [Reference](https://pitlane.tools/package/content/interface/Reference.md) that collection's `getEntry` accepts.

#### Type Parameters

##### C

`C` _extends_ `string`

#### Parameters

##### collection

`C`

#### Returns

[`ReferenceSchema`](https://pitlane.tools/package/content/type/ReferenceSchema.md)\<`C`>

# ContentLoader

Source: https://pitlane.tools/package/content/interface/ContentLoader.md

> A loader that resolves a whole collection by filling a store.

```ts
import type { ContentLoader } from "@pitlane/content";
```

A loader that resolves a whole collection by filling a store.

Its shape is the claim that one execution produces the complete answer, which is what lets `contentLayer()` run it during the build and inline the result.

## Properties

### name

```ts
name: string;
```

## Methods

### load()

```ts
load(context): void | Promise<void>;
```

Reads the whole source and writes every entry through `context.store.set`. Runs on the collection's first read, or at build time under `contentLayer()`, and the result is kept for every read after it.

#### Parameters

##### context

[`LoaderContext`](https://pitlane.tools/package/content/interface/LoaderContext.md)

#### Returns

`void` | `Promise`\<`void`>

---

### watchedPaths()?

```ts
optional watchedPaths(): string[];
```

The files or directories the last `load` read, for a development host to watch. Omit it, or return nothing, for a source with no local files.

#### Returns

`string`\[\]

# Entry

Source: https://pitlane.tools/package/content/interface/Entry.md

> One entry of a collection, as a caller sees it.

```ts
import type { Entry } from "@pitlane/content";
```

One entry of a collection, as a caller sees it.

## Type Parameters

### Data

`Data`

## Properties

### collection

```ts
collection: string;
```

---

### data

```ts
data: Data;
```

---

### filePath?

```ts
optional filePath?: string;
```

---

### id

```ts
id: string;
```

## Methods

### render()

```ts
render(): Promise<RenderedEntry>;
```

Renders the entry's Markdown or MDX body, from the build's compiled output when `contentLayer()` prebuilt it and from source otherwise. Rejects for an entry its loader gave no body.

#### Returns

`Promise`\<[`RenderedEntry`](https://pitlane.tools/package/content/interface/RenderedEntry.md)>

# EntryBody

Source: https://pitlane.tools/package/content/interface/EntryBody.md

> The raw source of an entry's document, before anything renders it.

```ts
import type { EntryBody } from "@pitlane/content";
```

The raw source of an entry's document, before anything renders it.

## Properties

### format

```ts
format: "md" | "mdx";
```

---

### source

```ts
source: string;
```

# GenerateIdOptions

Source: https://pitlane.tools/package/content/interface/GenerateIdOptions.md

> Options handed to a `loaders.glob` `generateId` function.

```ts
import type { GenerateIdOptions } from "@pitlane/content";
```

Options handed to a `loaders.glob` `generateId` function.

## Properties

### base

```ts
base: string;
```

The directory the pattern resolved against.

---

### data

```ts
data: Record<string, unknown>;
```

The parsed data of the entry, for an id derived from frontmatter.

---

### entry

```ts
entry: string;
```

The matched path, relative to `base`.

# Heading

Source: https://pitlane.tools/package/content/interface/Heading.md

> A heading collected from a Markdown or MDX document.

```ts
import type { Heading } from "@pitlane/content";
```

A heading collected from a Markdown or MDX document.

## Properties

### depth

```ts
depth: number;
```

---

### slug

```ts
slug: string;
```

---

### text

```ts
text: string;
```

# LiveEntry

Source: https://pitlane.tools/package/content/interface/LiveEntry.md

> What a [LiveLoader](https://pitlane.tools/package/content/interface/LiveLoader.md) returns for one entry.

```ts
import type { LiveEntry } from "@pitlane/content";
```

What a [LiveLoader](https://pitlane.tools/package/content/interface/LiveLoader.md) returns for one entry.

## Type Parameters

### Data

`Data` = `Record`\<`string`, `unknown`>

## Properties

### body?

```ts
optional body?: EntryBody;
```

---

### data

```ts
data: Data;
```

---

### id

```ts
id: string;
```

# LiveLoader

Source: https://pitlane.tools/package/content/interface/LiveLoader.md

> A loader that answers one query at a time.

```ts
import type { LiveLoader } from "@pitlane/content";
```

A loader that answers one query at a time.

There is no store to fill and so nothing to serialize: the only way to get entries out of it is to ask, which means asking on every read.

## Type Parameters

### Data

`Data` = `Record`\<`string`, `unknown`>

## Properties

### name

```ts
name: string;
```

## Methods

### loadCollection()

```ts
loadCollection(): Promise<LiveEntry<Data>[]>;
```

Every entry the source holds, unvalidated; called on every `getCollection`.

#### Returns

`Promise`\<[`LiveEntry`](https://pitlane.tools/package/content/interface/LiveEntry.md)\<`Data`>\[\]>

---

### loadEntry()

```ts
loadEntry(id): Promise<
  | LiveEntry<Data>
| undefined>;
```

The entry with this id, or `undefined` when the source has none; called on every `getEntry`.

#### Parameters

##### id

`string`

#### Returns

`Promise`\< | [`LiveEntry`](https://pitlane.tools/package/content/interface/LiveEntry.md)\<`Data`> | `undefined`>

# LoadedEntry

Source: https://pitlane.tools/package/content/interface/LoadedEntry.md

> What a [ContentLoader](https://pitlane.tools/package/content/interface/ContentLoader.md) writes into the store for one entry.

```ts
import type { LoadedEntry } from "@pitlane/content";
```

What a [ContentLoader](https://pitlane.tools/package/content/interface/ContentLoader.md) writes into the store for one entry.

## Properties

### body?

```ts
optional body?: EntryBody;
```

---

### data

```ts
data: unknown;
```

---

### filePath?

```ts
optional filePath?: string;
```

---

### id

```ts
id: string;
```

# LoaderContext

Source: https://pitlane.tools/package/content/interface/LoaderContext.md

> What a loader is handed to read its source and validate what it found.

```ts
import type { LoaderContext } from "@pitlane/content";
```

What a loader is handed to read its source and validate what it found.

## Properties

### collection

```ts
collection: string;
```

---

### root

```ts
root: string;
```

The project root a relative path resolves against.

`process.cwd()` at runtime, and the Vite root under `contentLayer()`, which is what keeps a collection pointing at the same files when the build runs from somewhere else.

---

### store

```ts
store: object;
```

#### set()

```ts
set(entry): void;
```

Adds one entry to the collection. An id written twice throws rather than merging.

##### Parameters

###### entry

[`LoadedEntry`](https://pitlane.tools/package/content/interface/LoadedEntry.md)

##### Returns

`void`

## Methods

### parseData()

```ts
parseData<D>(input): Promise<D>;
```

Validates one entry's data against the collection's schema and resolves to the parsed value; rejects naming the entry when it does not conform. Pass its result to `store.set`, never the raw data.

#### Type Parameters

##### D

`D`

#### Parameters

##### input

###### data

`unknown`

###### filePath?

`string`

###### id

`string`

#### Returns

`Promise`\<`D`>

# Reference

Source: https://pitlane.tools/package/content/interface/Reference.md

> A resolved pointer from one entry to another, produced by `c.reference(collection)`.

```ts
import type { Reference } from "@pitlane/content";
```

A resolved pointer from one entry to another, produced by `c.reference(collection)`.

The `collection` type parameter is what stops a `Reference<"blog">` reaching `content.authors.getEntry`.

## Type Parameters

### C

`C` _extends_ `string`

## Properties

### collection

```ts
collection: C;
```

---

### id

```ts
id: string;
```

# RenderedEntry

Source: https://pitlane.tools/package/content/interface/RenderedEntry.md

> What `entry.render()` resolves to.

```ts
import type { RenderedEntry } from "@pitlane/content";
```

What `entry.render()` resolves to.

## Properties

### Content

```ts
Content: (handle: Handle<Record<string, unknown>>) => () => RemixNode;
```

The entry's rendered document as a Remix component, to render as `<Content />`.

#### Parameters

##### handle

`Handle`\<`Record`\<`string`, `unknown`>>

#### Returns

() => `RemixNode`

---

### headings

```ts
headings: Heading[];
```

# CollectionEntry

Source: https://pitlane.tools/package/content/type/CollectionEntry.md

> One entry of `collection`, named the way an application thinks of it: `CollectionEntry<typeof content.blog>`.

```ts
import type { CollectionEntry } from "@pitlane/content";
```

```ts
type CollectionEntry<C> = C extends Collection<string, infer Data> ? Entry<Data> : never;
```

One entry of `collection`, named the way an application thinks of it: `CollectionEntry<typeof content.blog>`.

[Entry](https://pitlane.tools/package/content/interface/Entry.md) is keyed by the shape of the data, which is what the query methods resolve to and all this package needs internally. An application has the collection rather than the shape, and pulling one out of the other is a conditional type every consumer would otherwise write for itself.

## Type Parameters

### C

`C`

# Content

Source: https://pitlane.tools/package/content/type/Content.md

> The object `createContent` returns: one [Collection](https://pitlane.tools/package/content/interface/Collection.md) per key of the definitions its callback returned, named after that key and typed by the output of that collection's schema.

```ts
import type { Content } from "@pitlane/content";
```

```ts
type Content<T> = { [K in keyof T]: Collection<K & string, InferSchema<T[K]["schema"]>> };
```

The object `createContent` returns: one [Collection](https://pitlane.tools/package/content/interface/Collection.md) per key of the definitions its callback returned, named after that key and typed by the output of that collection's schema.

## Type Parameters

### T

`T` _extends_ `Record`\<`string`, [`CollectionDefinition`](https://pitlane.tools/package/content/interface/CollectionDefinition.md)>

# Loader

Source: https://pitlane.tools/package/content/type/Loader.md

> Either kind of loader.

```ts
import type { Loader } from "@pitlane/content";
```

```ts
type Loader =
  | ContentLoader
| LiveLoader<unknown>;
```

Either kind of loader.

A `LiveLoader`'s own `Data` parameter is for whoever writes it; a collection accepts any of them, because what a loader hands back is unvalidated until `parseData` has seen it.

# ReferenceSchema

Source: https://pitlane.tools/package/content/type/ReferenceSchema.md

> The schema `c.reference(collection)` returns: a Standard Schema that reads an entry id (a string) and outputs a [Reference](https://pitlane.tools/package/content/interface/Reference.md) into `collection`.

```ts
import type { ReferenceSchema } from "@pitlane/content";
```

```ts
type ReferenceSchema<C> = ChainableSchema<string, Reference<C>>;
```

The schema `c.reference(collection)` returns: a Standard Schema that reads an entry id (a string) and outputs a [Reference](https://pitlane.tools/package/content/interface/Reference.md) into `collection`.

It composes inside `remix/data-schema`'s `s.object`, `s.array`, and `s.optional` like any other schema. It does not check that the target entry exists; a dangling id surfaces as `getEntry` resolving to `undefined`.

## Type Parameters

### C

`C` _extends_ `string`

# @pitlane/content/hot

Source: https://pitlane.tools/package/content/hot.md

> Browser reloads during development when a file behind a collection changes, for servers that `remix/node-hmr` supervises rather than Vite. See [hotContent](https://pitlane.tools/package/content/hot/function/hotContent.md).

Browser reloads during development when a file behind a collection changes, for servers that `remix/node-hmr` supervises rather than Vite. See [hotContent](https://pitlane.tools/package/content/hot/function/hotContent.md).

## See

[Content guide, without a build](https://pitlane.tools/guides/content-no-build.md)

## Interfaces

- [BrowserEvent](https://pitlane.tools/package/content/hot/interface/BrowserEvent.md). An event for the browser HMR client. A reload is the only one content sends.
- [BrowserHmrChannel](https://pitlane.tools/package/content/hot/interface/BrowserHmrChannel.md). The part of `remix/node-hmr`'s `BrowserHmrChannel` this module uses.
- [FileEvent](https://pitlane.tools/package/content/hot/interface/FileEvent.md). A file change the supervisor's watcher observed.

## Functions

- [hotContent](https://pitlane.tools/package/content/hot/function/hotContent.md). Reloads the browser when a file behind a collection changes.

# hotContent

Source: https://pitlane.tools/package/content/hot/function/hotContent.md

> Reloads the browser when a file behind a collection changes.

```ts
import { hotContent } from "@pitlane/content/hot";
```

```ts
function hotContent(content): Promise<void>;
```

Reloads the browser when a file behind a collection changes.

Call it once, beside `createContent`, and leave it in for production: it does nothing unless `remix/node-hmr` is supervising the process, which is what a `dev` command does and a production server does not. That is also why the import below is loaded on demand. `remix/node-hmr/runtime` is Node-only and can only be imported by a supervised child, so a static import would follow this module into a Worker bundle.

## Parameters

### content

`Record`\<`string`, `unknown`>

The object `createContent` returned.

## Returns

`Promise`\<`void`>

## See

[Content guide, without a build](https://pitlane.tools/guides/content-no-build.md)

# BrowserEvent

Source: https://pitlane.tools/package/content/hot/interface/BrowserEvent.md

> An event for the browser HMR client. A reload is the only one content sends.

```ts
import type { BrowserEvent } from "@pitlane/content/hot";
```

An event for the browser HMR client. A reload is the only one content sends.

## Properties

### files?

```ts
optional files?: string[];
```

---

### type

```ts
type: "reload";
```

# BrowserHmrChannel

Source: https://pitlane.tools/package/content/hot/interface/BrowserHmrChannel.md

> The part of `remix/node-hmr`'s `BrowserHmrChannel` this module uses.

```ts
import type { BrowserHmrChannel } from "@pitlane/content/hot";
```

The part of `remix/node-hmr`'s `BrowserHmrChannel` this module uses.

Declared structurally rather than imported, because importing the module that declares it would pull a Node-only dependency into every bundle this package reaches. [hotContent](https://pitlane.tools/package/content/hot/function/hotContent.md) holds the only import of it, loaded on demand behind its guard.

## Properties

### url

```ts
readonly url: string;
```

## Methods

### close()

```ts
close(): void;
```

Shuts the channel down.

#### Returns

`void`

---

### onFileEvents()

```ts
onFileEvents(handler): () => void;
```

Registers `handler` for batches of changed files. The browser events it resolves to are sent to connected clients. Returns a function that unregisters it.

#### Parameters

##### handler

(`events`: readonly [`FileEvent`](https://pitlane.tools/package/content/hot/interface/FileEvent.md)\[\]) => `Promise`\<readonly [`BrowserEvent`](https://pitlane.tools/package/content/hot/interface/BrowserEvent.md)\[\]>

#### Returns

() => `void`

---

### updateWatchedFiles()

```ts
updateWatchedFiles(delta): void;
```

Adds absolute paths to, and removes them from, the set the supervisor watches.

#### Parameters

##### delta

###### add

readonly `string`\[\]

###### remove

readonly `string`\[\]

#### Returns

`void`

# FileEvent

Source: https://pitlane.tools/package/content/hot/interface/FileEvent.md

> A file change the supervisor's watcher observed.

```ts
import type { FileEvent } from "@pitlane/content/hot";
```

A file change the supervisor's watcher observed.

## Properties

### event

```ts
event: "add" | "change" | "unlink";
```

---

### filePath

```ts
filePath: string;
```

# @pitlane/content/loaders

Source: https://pitlane.tools/package/content/loaders.md

> The two built-in loaders for collections on the filesystem: [glob](https://pitlane.tools/package/content/loaders/function/glob.md) reads every file a pattern matches as one entry, and [file](https://pitlane.tools/package/content/loaders/function/file.md) reads one JSON or YAML file holding many entries.

The two built-in loaders for collections on the filesystem: [glob](https://pitlane.tools/package/content/loaders/function/glob.md) reads every file a pattern matches as one entry, and [file](https://pitlane.tools/package/content/loaders/function/file.md) reads one JSON or YAML file holding many entries.

## See

[Content guide](https://pitlane.tools/guides/content.md)

## Functions

- [file](https://pitlane.tools/package/content/loaders/function/file.md). Reads one file holding many entries.
- [glob](https://pitlane.tools/package/content/loaders/function/glob.md). Reads every file a pattern matches as one entry.

# file

Source: https://pitlane.tools/package/content/loaders/function/file.md

> Reads one file holding many entries.

```ts
import { file } from "@pitlane/content/loaders";
```

```ts
function file(fileName, options?): ContentLoader;
```

Reads one file holding many entries.

Every entry is data rather than a document: a file of records has no body to render, so `render()` on one of these entries is a mistake and says so.

The file holds either an object whose keys are entry ids or an array of entries that each carry an `id`. `.json`, `.yaml`, and `.yml` parse without options; any other format needs `options.parser`, which turns the file's text into that object or array.

## Parameters

### fileName

`string`

### options?

#### parser?

(`text`: `string`) => `unknown`

## Returns

[`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md)

## See

[Content guide](https://pitlane.tools/guides/content.md)

# glob

Source: https://pitlane.tools/package/content/loaders/function/glob.md

> Reads every file a pattern matches as one entry.

```ts
import { glob } from "@pitlane/content/loaders";
```

```ts
function glob(options): ContentLoader;
```

Reads every file a pattern matches as one entry.

`pattern` is an ordinary runtime value — computed, read from the environment, or assembled in a loop — because nothing about it is read statically.

## Parameters

### options

#### base?

`string`

#### generateId?

(`options`: [`GenerateIdOptions`](https://pitlane.tools/package/content/interface/GenerateIdOptions.md)) => `string`

#### pattern

`string` | `string`\[\]

#### satteri?

`CompileOptions`

## Returns

[`ContentLoader`](https://pitlane.tools/package/content/interface/ContentLoader.md)

## See

[Content guide](https://pitlane.tools/guides/content.md)

# @pitlane/content/satteri

Source: https://pitlane.tools/package/content/satteri.md

> Sätteri plugins that Markdown and MDX entry bodies need: [headings](https://pitlane.tools/package/content/satteri/function/headings.md) collects the heading list `render()` returns, and [rawStyles](https://pitlane.tools/package/content/satteri/function/rawStyles.md) keeps the CSS inside a `<style>` element intact. With a Vite build, register both with `vite-plugin-satteri`; without one, `render()` applies them itself.

Sätteri plugins that Markdown and MDX entry bodies need: [headings](https://pitlane.tools/package/content/satteri/function/headings.md) collects the heading list `render()` returns, and [rawStyles](https://pitlane.tools/package/content/satteri/function/rawStyles.md) keeps the CSS inside a `<style>` element intact. With a Vite build, register both with `vite-plugin-satteri`; without one, `render()` applies them itself.

## See

[Content guide](https://pitlane.tools/guides/content.md)

## Functions

- [headings](https://pitlane.tools/package/content/satteri/function/headings.md). Collects every heading of a document as `{ depth, slug, text }`, publishes the list as `data.headings`, and gives each heading an `id` matching its slug so an anchor link lands on it. A heading's text is the text it shows on the page, as `visibleText` reads it. On MDX the list is also appended to the tree as `export const headings`, so the compiled module carries its own table of contents.
- [rawStyles](https://pitlane.tools/package/content/satteri/function/rawStyles.md). Hands a `<style>` element's CSS to Remix as markup rather than as text, so the stylesheet survives being rendered.

# headings

Source: https://pitlane.tools/package/content/satteri/function/headings.md

> Collects every heading of a document as `{ depth, slug, text }`, publishes the list as `data.headings`, and gives each heading an `id` matching its slug so an anchor link lands on it. A heading's text is the text it shows on the page, as `visibleText` reads it. On MDX the list is also appended to the tree as `export const headings`, so the compiled module carries its own table of contents.

```ts
import { headings } from "@pitlane/content/satteri";
```

```ts
function headings(): MdastPluginEntry;
```

Collects every heading of a document as `{ depth, slug, text }`, publishes the list as `data.headings`, and gives each heading an `id` matching its slug so an anchor link lands on it. A heading's text is the text it shows on the page, as `visibleText` reads it. On MDX the list is also appended to the tree as `export const headings`, so the compiled module carries its own table of contents.

The plugin is a factory rather than a definition because Sätteri resolves a factory once per compile: a single `headings()` shared by a whole build gets fresh slug state per document, instead of the second document's `notes` reading `notes-1`.

The definition is written out rather than passed through Sätteri's `defineMdastPlugin`, whose entire body checks that `name` is set. Calling it would make this module import the `satteri` package, and `render.ts` imports this module: a Worker bundle whose collections `contentLayer()` already prebuilt would then have to resolve a native addon it can never load.

## Returns

`MdastPluginEntry`

# rawStyles

Source: https://pitlane.tools/package/content/satteri/function/rawStyles.md

> Hands a `<style>` element's CSS to Remix as markup rather than as text, so the stylesheet survives being rendered.

```ts
import { rawStyles } from "@pitlane/content/satteri";
```

```ts
function rawStyles(): HastPluginEntry;
```

Hands a `<style>` element's CSS to Remix as markup rather than as text, so the stylesheet survives being rendered.

`remix/component` escapes `&`, `<`, and `>` in the text children of every element except `<script>`, and emits an `innerHTML` prop verbatim. `<style>` is a raw-text element, which is exactly the case where a browser does not undo that escaping: a rule written `pre > code` reaches the page as `pre &gt; code`, matches nothing, and says nothing. Expressive Code is how most applications meet this, because it ships its theme as one such element.

`innerHTML` only accepts a value made by `unsafeHTML()`, so the element becomes JSX whose prop calls it, and the document gains the import that provides it. The CSS was already in the compiled document, so this trusts nothing the document did not already ship.

A workaround, not a design. The fix belongs in `remix/component`, which already special-cases `<script>` and should treat `<style>` the same way. `<script>` is deliberately not touched here: routing it through `innerHTML` would skip `escapeScriptTextContent`, which keeps a `</script>` inside a string from ending the element early.

## Returns

`HastPluginEntry`

# @pitlane/content/vite-plugin

Source: https://pitlane.tools/package/content/vite-plugin.md

> The [contentLayer](https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md) Vite plugin, which resolves every collection during the build and inlines the entries into the bundle, so a host with no filesystem serves the same collections.

The [contentLayer](https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md) Vite plugin, which resolves every collection during the build and inlines the entries into the bundle, so a host with no filesystem serves the same collections.

## See

[Content guide](https://pitlane.tools/guides/content.md)

## Functions

- [contentLayer](https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md). Resolves content collections during the build and inlines them.

# contentLayer

Source: https://pitlane.tools/package/content/vite-plugin/function/contentLayer.md

> Resolves content collections during the build and inlines them.

```ts
import { contentLayer } from "@pitlane/content/vite-plugin";
```

```ts
function contentLayer(options?): Plugin;
```

Resolves content collections during the build and inlines them.

`entry` names the module that declares the collections, and defaults to `app/content.ts`. It is an ordinary application module rather than a configuration file this plugin owns; being told which module it is is the whole of the configuration.

The result is a host with no filesystem serving the collections the application declared, with no change to the declarations.

## Parameters

### options?

#### entry?

`string`

## Returns

`Plugin`

## See

[Content guide](https://pitlane.tools/guides/content.md)

# @pitlane/crawler

Source: https://pitlane.tools/package/crawler/index.md

> `crawl()` — spider a Remix 3 fetch router in memory. Requests go straight into `router.fetch`, so an app can be walked and written to disk without a socket, a server, or a browser. `staticPaths()` answers the question that comes first: which paths a route map can serve with no params.

`crawl()` — spider a Remix 3 fetch router in memory. Requests go straight into `router.fetch`, so an app can be walked and written to disk without a socket, a server, or a browser. `staticPaths()` answers the question that comes first: which paths a route map can serve with no params.

## See

- [Crawler guide](https://pitlane.tools/guides/crawler.md)
- [Prerendering guide, without a build](https://pitlane.tools/guides/prerendering-no-build.md)

## Interfaces

- [CrawlOptions](https://pitlane.tools/package/crawler/interface/CrawlOptions.md). What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) fetches and how: the starting paths, whether to follow links and queue assets, how many requests run at once, and hooks for `nofollow` pages and redirects. Every option has a default, so `crawl(router)` walks everything reachable from `/`.
- [CrawlResult](https://pitlane.tools/package/crawler/interface/CrawlResult.md). One fetched path and the response the router produced for it.
- [CrawlTarget](https://pitlane.tools/package/crawler/interface/CrawlTarget.md). What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) needs from a router. A `createRouter()` router satisfies it, and so does anything else that answers a `Request` — a built server bundle's default export, a worker-style `{ fetch }` object, a test double.

## Functions

- [crawl](https://pitlane.tools/package/crawler/function/crawl.md). Walks an app by dispatching requests straight into its router, yielding each response as it arrives. No socket, no server, no browser: the router's `fetch` is the whole transport, so this runs anywhere the app itself runs.
- [staticPaths](https://pitlane.tools/package/crawler/function/staticPaths.md). Collects every path in a route map that can be requested without params: the Remix 3 answer to "what pages does this app have", and the input a prerender pass needs before it knows any dynamic values.

# crawl

Source: https://pitlane.tools/package/crawler/function/crawl.md

> Walks an app by dispatching requests straight into its router, yielding each response as it arrives. No socket, no server, no browser: the router's `fetch` is the whole transport, so this runs anywhere the app itself runs.

```ts
import { crawl } from "@pitlane/crawler";
```

```ts
function crawl(router, options?): AsyncIterableIterator<CrawlResult>;
```

Walks an app by dispatching requests straight into its router, yielding each response as it arrives. No socket, no server, no browser: the router's `fetch` is the whole transport, so this runs anywhere the app itself runs.

Yields in completion order. Every path is fetched at most once. A redirect yields nothing and reports through [CrawlOptions.onRedirect](https://pitlane.tools/package/crawler/interface/CrawlOptions.md#onredirect); any other non-2xx response aborts the crawl.

## Parameters

### router

[`CrawlTarget`](https://pitlane.tools/package/crawler/interface/CrawlTarget.md)

The router to crawl.

### options?

[`CrawlOptions`](https://pitlane.tools/package/crawler/interface/CrawlOptions.md) = `{}`

Crawl options.

## Returns

`AsyncIterableIterator`\<[`CrawlResult`](https://pitlane.tools/package/crawler/interface/CrawlResult.md)>

An async iterator of results, one per fetched path.

## See

- [Crawler guide](https://pitlane.tools/guides/crawler.md)
- [Prerendering guide, without a build](https://pitlane.tools/guides/prerendering-no-build.md)

# staticPaths

Source: https://pitlane.tools/package/crawler/function/staticPaths.md

> Collects every path in a route map that can be requested without params: the Remix 3 answer to "what pages does this app have", and the input a prerender pass needs before it knows any dynamic values.

```ts
import { staticPaths } from "@pitlane/crawler";
```

```ts
function staticPaths(routes): string[];
```

Collects every path in a route map that can be requested without params: the Remix 3 answer to "what pages does this app have", and the input a prerender pass needs before it knows any dynamic values.

A route qualifies when it answers `GET` (or any method) and its pattern declares no variables or wildcards. `/blog` is a static path; `/blog/:slug` is not, because its values live outside the route map. Routes constrained to a protocol or hostname are skipped too, since their href is not a path.

Results are deduplicated and sorted, so a build that prerenders them lists its output the same way every time.

## Parameters

### routes

`RouteMap`

The route map, usually the one the app's router is built from.

## Returns

`string`\[\]

The static paths, sorted.

## See

- [Crawler guide: Asking what pages exist](https://pitlane.tools/guides/crawler.md#asking-what-pages-exist)
- [Prerendering guide, without a build: Where the paths come from](https://pitlane.tools/guides/prerendering-no-build.md#where-the-paths-come-from)

# CrawlOptions

Source: https://pitlane.tools/package/crawler/interface/CrawlOptions.md

> What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) fetches and how: the starting paths, whether to follow links and queue assets, how many requests run at once, and hooks for `nofollow` pages and redirects. Every option has a default, so `crawl(router)` walks everything reachable from `/`.

```ts
import type { CrawlOptions } from "@pitlane/crawler";
```

What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) fetches and how: the starting paths, whether to follow links and queue assets, how many requests run at once, and hooks for `nofollow` pages and redirects. Every option has a default, so `crawl(router)` walks everything reachable from `/`.

## See

[Crawler guide](https://pitlane.tools/guides/crawler.md)

## Properties

### assets?

```ts
optional assets?: boolean;
```

Queue the `<link href>`, `<script src>`, and `<img src>` a page references. Turn it off when something else already emitted those files, as a bundler does.

#### Default

```ts
true
```

---

### concurrency?

```ts
optional concurrency?: number;
```

How many paths to fetch at once.

#### Default

```ts
1
```

---

### ignorePageNofollow?

```ts
optional ignorePageNofollow?: (pathname: string) => boolean;
```

Crawl a page's links even though the page asked robots not to follow them. Receives the page's path.

#### Parameters

##### pathname

`string`

#### Returns

`boolean`

---

### onRedirect?

```ts
optional onRedirect?: (pathname: string, location: string | null) => void;
```

Called for a path that answered with a redirect rather than a document. Nothing is yielded for it: there is no page to write, and the app still answers the path at runtime.

Receives the requested path and the `Location` it pointed at, which is `null` for a redirect that named none.

#### Parameters

##### pathname

`string`

##### location

`string` | `null`

#### Returns

`void`

---

### paths?

```ts
optional paths?: string[];
```

Paths to start from.

#### Default

```ts
["/"]
```

---

### spider?

```ts
optional spider?: boolean;
```

Follow `<a href>` and `<link rel="alternate">` to discover more paths. Turn it off to fetch exactly the paths given.

#### Default

```ts
true
```

# CrawlResult

Source: https://pitlane.tools/package/crawler/interface/CrawlResult.md

> One fetched path and the response the router produced for it.

```ts
import type { CrawlResult } from "@pitlane/crawler";
```

One fetched path and the response the router produced for it.

## Properties

### filepath

```ts
filepath: string;
```

Where the response belongs on disk. HTML lands at `<pathname>/index.html` so a static host serves it for the original path; everything else keeps its own path.

---

### pathname

```ts
pathname: string;
```

The path that was requested, exactly as it was queued.

---

### response

```ts
response: Response;
```

The router's response. Unconsumed: the body is still readable.

# CrawlTarget

Source: https://pitlane.tools/package/crawler/interface/CrawlTarget.md

> What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) needs from a router. A `createRouter()` router satisfies it, and so does anything else that answers a `Request` — a built server bundle's default export, a worker-style `{ fetch }` object, a test double.

```ts
import type { CrawlTarget } from "@pitlane/crawler";
```

What [crawl](https://pitlane.tools/package/crawler/function/crawl.md) needs from a router. A `createRouter()` router satisfies it, and so does anything else that answers a `Request` — a built server bundle's default export, a worker-style `{ fetch }` object, a test double.

## Methods

### fetch()

```ts
fetch(request): Response | Promise<Response>;
```

Answers one request; [crawl](https://pitlane.tools/package/crawler/function/crawl.md) sends a `GET` for each queued path.

#### Parameters

##### request

`Request`

#### Returns

`Response` | `Promise`\<`Response`>

# @pitlane/data-table-d1

Source: https://pitlane.tools/package/data-table-d1/index.md

> A Cloudflare D1 driver for Remix 3's `data-table`.

A Cloudflare D1 driver for Remix 3's `data-table`.

D1 is SQLite, so the SQL is SQLite's, but the execution model is not: statements are prepared and awaited over an RPC binding, and the transaction verbs are rejected outright. `@remix-run/data-table-sqlite` builds on a synchronous client and cannot bridge that gap, so this package pairs the SQLite SQL compiler with a driver written against D1's async API.

## See

[Cloudflare D1 guide](https://pitlane.tools/guides/cloudflare-d1.md)

## Classes

- [D1Database](https://pitlane.tools/package/data-table-d1/class/D1Database.md). A `Database` bound to Cloudflare D1.
- [D1DatabaseDriver](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md). A `DatabaseDriver` backed by a Cloudflare D1 binding.

## Interfaces

- [D1BatchResult](https://pitlane.tools/package/data-table-d1/interface/D1BatchResult.md). What one statement in a [D1DatabaseDriver.batch](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md#batch) produced.
- [D1Binding](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md). The slice of Cloudflare's D1 API this driver uses.
- [D1DatabaseOptions](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md). The options [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) accepts: `remix/data-table`'s `DatabaseOptions`, plus D1's statement observer and transaction mode.
- [D1DriverOptions](https://pitlane.tools/package/data-table-d1/interface/D1DriverOptions.md). The options [D1DatabaseDriver](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md) accepts: the D1-specific half of [D1DatabaseOptions](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md), which [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) passes through.
- [D1Meta](https://pitlane.tools/package/data-table-d1/interface/D1Meta.md). What D1 reports about one statement it ran.
- [D1PreparedStatement](https://pitlane.tools/package/data-table-d1/interface/D1PreparedStatement.md). A statement [D1Binding.prepare](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md#prepare) returns, before it runs.
- [D1Result](https://pitlane.tools/package/data-table-d1/interface/D1Result.md). What one statement produced: its rows, empty for a write, and D1's metadata.
- [D1StatementReport](https://pitlane.tools/package/data-table-d1/interface/D1StatementReport.md). What one executed statement cost, as D1 reported it.

## Type Aliases

- [D1StatementObserver](https://pitlane.tools/package/data-table-d1/type/D1StatementObserver.md). Called after each statement the driver executes.
- [D1TransactionMode](https://pitlane.tools/package/data-table-d1/type/D1TransactionMode.md). How the driver answers a `transaction()` call.

## Functions

- [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md). Wraps a D1 binding in a `Database`.

# createD1Database

Source: https://pitlane.tools/package/data-table-d1/function/createD1Database.md

> Wraps a D1 binding in a `Database`.

```ts
import { createD1Database } from "@pitlane/data-table-d1";
```

```ts
function createD1Database(binding, options?): D1Database;
```

Wraps a D1 binding in a `Database`.

## Parameters

### binding

[`D1Binding`](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md)

The D1 binding, e.g. `env.DB`.

### options?

[`D1DatabaseOptions`](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md)

`Database` options, plus `onStatement` and `transactions`.

## Returns

[`D1Database`](https://pitlane.tools/package/data-table-d1/class/D1Database.md)

## See

[Cloudflare D1 guide](https://pitlane.tools/guides/cloudflare-d1.md)

## Example

```ts
import { createD1Database } from "@pitlane/data-table-d1";
import { env } from "cloudflare:workers";

let db = createD1Database(env.DB);
let posts = await db.query(Post).all();
```

# D1Database

Source: https://pitlane.tools/package/data-table-d1/class/D1Database.md

> A `Database` bound to Cloudflare D1.

```ts
import { D1Database } from "@pitlane/data-table-d1";
```

A `Database` bound to Cloudflare D1.

The same shape `SqliteDatabase` and `PostgresDatabase` have: a `Database` subclass that supplies its own driver, so every query, persistence and migration method comes from `remix/data-table` unchanged.

## Extends

- `Database`\<`"sqlite"`>

## Constructors

### Constructor

```ts
new D1Database(binding, options?): D1Database;
```

#### Parameters

##### binding

[`D1Binding`](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md)

##### options?

[`D1DatabaseOptions`](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md)

#### Returns

`D1Database`

#### Overrides

```ts
Database<"sqlite">.constructor
```

## Accessors

### capabilities

#### Get Signature

```ts
get capabilities(): DatabaseCapabilities;
```

Immutable feature flags used by shared query and migration behavior.

##### Returns

`DatabaseCapabilities`

#### Inherited from

```ts
Database.capabilities
```

---

### dialect

#### Get Signature

```ts
get dialect(): dialect;
```

Stable identifier for the SQL dialect.

##### Returns

`dialect`

#### Inherited from

```ts
Database.dialect
```

## Methods

### batch()

```ts
batch(statements): Promise<D1BatchResult[]>;
```

Runs statements together, atomically.

D1 has no transactions, so `transaction()` refuses. `batch()` is what it offers instead, and this is it without reaching for the raw binding:

```ts
import { sql } from "remix/data-table";

await db.batch([
    sql`insert into post (title) values (${title})`,
    sql`update counter set posts = posts + 1`,
]);
```

The statements are `SqlStatement`s rather than query-builder calls, because `data-table` exposes no way to build an operation without running it. `sql` still parameterises the values.

#### Parameters

##### statements

`SqlStatement`\[\]

#### Returns

`Promise`\<[`D1BatchResult`](https://pitlane.tools/package/data-table-d1/interface/D1BatchResult.md)\[\]>

---

### close()

```ts
close(): Promise<void>;
```

Closes resources owned by this database.

#### Returns

`Promise`\<`void`>

A promise that resolves when owned resources have been released.

#### Inherited from

```ts
Database.close
```

---

### count()

```ts
count<table>(table, options?): Promise<number>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

#### Parameters

##### table

`table`

##### options?

`CountOptions`\<`table`>

#### Returns

`Promise`\<`number`>

#### Inherited from

```ts
Database.count
```

---

### create()

#### Call Signature

```ts
create<table>(
   table,
   values,
options?): Promise<WriteResult>;
```

##### Type Parameters

###### table

`table` _extends_ `AnyTable`

##### Parameters

###### table

`table`

###### values

`Partial`\<`TableRow`\<`table`>>

###### options?

`CreateResultOptions`

##### Returns

`Promise`\<`WriteResult`>

##### Inherited from

```ts
Database.create
```

#### Call Signature

```ts
create<table, relations>(
   table,
   values,
options): Promise<{ [key in string | number | symbol]: ({ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] } & { [key in string | number | symbol]: { [name in string | number | symbol]: RelationResult<relations[name]> }[key] })[key] }>;
```

##### Type Parameters

###### table

`table` _extends_ `AnyTable`

###### relations

`relations` _extends_ `RelationMapForSourceName`\<`TableName`\<`table`>> = { }

##### Parameters

###### table

`table`

###### values

`Partial`\<`TableRow`\<`table`>>

###### options

`CreateRowOptions`\<`table`, `relations`>

##### Returns

`Promise`\<{ \[key in string | number | symbol\]: ({ \[key in string\]: { \[column in string\]: ColumnOutput\<TableColumns\<table>\[column\]> }\[key\] } \& { \[key in string | number | symbol\]: { \[name in string | number | symbol\]: RelationResult\<relations\[name\]> }\[key\] })\[key\] }>

##### Inherited from

```ts
Database.create
```

---

### createMany()

#### Call Signature

```ts
createMany<table>(
   table,
   values,
options?): Promise<WriteResult>;
```

##### Type Parameters

###### table

`table` _extends_ `AnyTable`

##### Parameters

###### table

`table`

###### values

`Partial`\<`{ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] }`>\[\]

###### options?

`CreateManyResultOptions`

##### Returns

`Promise`\<`WriteResult`>

##### Inherited from

```ts
Database.createMany
```

#### Call Signature

```ts
createMany<table>(
   table,
   values,
options): Promise<{ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] }[]>;
```

##### Type Parameters

###### table

`table` _extends_ `AnyTable`

##### Parameters

###### table

`table`

###### values

`Partial`\<`{ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] }`>\[\]

###### options

`CreateManyRowsOptions`

##### Returns

`Promise`\<`{ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] }`\[\]>

##### Inherited from

```ts
Database.createMany
```

---

### delete()

```ts
delete<table>(table, value): Promise<boolean>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

#### Parameters

##### table

`table`

##### value

`PrimaryKeyInput`\<`table`>

#### Returns

`Promise`\<`boolean`>

#### Inherited from

```ts
Database.delete
```

---

### deleteMany()

```ts
deleteMany<table>(table, options): Promise<WriteResult>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

#### Parameters

##### table

`table`

##### options

`DeleteManyOptions`\<`table`>

#### Returns

`Promise`\<`WriteResult`>

#### Inherited from

```ts
Database.deleteMany
```

---

### exec()

#### Call Signature

```ts
exec(statement, values?): Promise<DataManipulationResult>;
```

##### Parameters

###### statement

`string` | `SqlStatement`

###### values?

`unknown`\[\]

##### Returns

`Promise`\<`DataManipulationResult`>

##### Inherited from

```ts
Database.exec
```

#### Call Signature

```ts
exec<input>(input): Promise<QueryExecutionResult<input>>;
```

##### Type Parameters

###### input

`input` _extends_ `AnyQuery`

##### Parameters

###### input

`input`

##### Returns

`Promise`\<`QueryExecutionResult`\<`input`>>

##### Inherited from

```ts
Database.exec
```

---

### executeScript()

```ts
executeScript(sql): Promise<void>;
```

Executes a migration or raw multi-statement SQL script.

#### Parameters

##### sql

`string`

SQL script to execute.

#### Returns

`Promise`\<`void`>

A promise that resolves when execution completes.

#### Inherited from

```ts
Database.executeScript
```

---

### find()

```ts
find<table, relations>(
   table,
   value,
   options?): Promise<
  | { [key in string | number | symbol]: ({ [key in string]: { [column in string]: ColumnOutput<TableColumns<(...)>[column]> }[key] } & { [key in string | number | symbol]: { [name in string | number | symbol]: RelationResult<relations[name]> }[key] })[key] }
| null>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

##### relations

`relations` _extends_ `RelationMapForSourceName`\<`TableName`\<`table`>> = { }

#### Parameters

##### table

`table`

##### value

`PrimaryKeyInput`\<`table`>

##### options?

###### with?

`relations`

#### Returns

`Promise`\< | { \[key in string | number | symbol\]: ({ \[key in string\]: { \[column in string\]: ColumnOutput\<TableColumns\<(...)>\[column\]> }\[key\] } \& { \[key in string | number | symbol\]: { \[name in string | number | symbol\]: RelationResult\<relations\[name\]> }\[key\] })\[key\] } | `null`>

#### Inherited from

```ts
Database.find
```

---

### findMany()

```ts
findMany<table, relations>(table, options?): Promise<{ [key in string | number | symbol]: ({ [key in string]: { [column in string]: ColumnOutput<TableColumns<(...)>[column]> }[key] } & { [key in string | number | symbol]: { [name in string | number | symbol]: RelationResult<relations[name]> }[key] })[key] }[]>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

##### relations

`relations` _extends_ `RelationMapForSourceName`\<`TableName`\<`table`>> = { }

#### Parameters

##### table

`table`

##### options?

`FindManyOptions`\<`table`, `relations`>

#### Returns

`Promise`\<{ \[key in string | number | symbol\]: ({ \[key in string\]: { \[column in string\]: ColumnOutput\<TableColumns\<(...)>\[column\]> }\[key\] } \& { \[key in string | number | symbol\]: { \[name in string | number | symbol\]: RelationResult\<relations\[name\]> }\[key\] })\[key\] }\[\]>

#### Inherited from

```ts
Database.findMany
```

---

### findOne()

```ts
findOne<table, relations>(table, options): Promise<
  | { [key in string | number | symbol]: ({ [key in string]: { [column in string]: ColumnOutput<TableColumns<(...)>[column]> }[key] } & { [key in string | number | symbol]: { [name in string | number | symbol]: RelationResult<relations[name]> }[key] })[key] }
| null>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

##### relations

`relations` _extends_ `RelationMapForSourceName`\<`TableName`\<`table`>> = { }

#### Parameters

##### table

`table`

##### options

`FindOneOptions`\<`table`, `relations`>

#### Returns

`Promise`\< | { \[key in string | number | symbol\]: ({ \[key in string\]: { \[column in string\]: ColumnOutput\<TableColumns\<(...)>\[column\]> }\[key\] } \& { \[key in string | number | symbol\]: { \[name in string | number | symbol\]: RelationResult\<relations\[name\]> }\[key\] })\[key\] } | `null`>

#### Inherited from

```ts
Database.findOne
```

---

### hasColumn()

```ts
hasColumn(table, column): Promise<boolean>;
```

Reports whether a column exists on a table.

#### Parameters

##### table

`TableRef`

Table to inspect.

##### column

`string`

Column name to inspect.

#### Returns

`Promise`\<`boolean`>

A promise that resolves to `true` when the column exists.

#### Inherited from

```ts
Database.hasColumn
```

---

### hasTable()

```ts
hasTable(table): Promise<boolean>;
```

Reports whether a table exists.

#### Parameters

##### table

`TableRef`

Table to inspect.

#### Returns

`Promise`\<`boolean`>

A promise that resolves to `true` when the table exists.

#### Inherited from

```ts
Database.hasTable
```

---

### migrate()

```ts
migrate(migrations, options?): Promise<MigrateResult>;
```

Applies or reverts migrations in order.

#### Parameters

##### migrations

`Migrations`

Migration descriptors or registry to apply.

##### options?

`DatabaseMigrateOptions`

Migration direction, bound, dry-run, and journal configuration.

#### Returns

`Promise`\<`MigrateResult`>

The migrations applied or reverted by this run and their SQL scripts.

#### Inherited from

```ts
Database.migrate
```

---

### migrationStatus()

```ts
migrationStatus(migrations, options?): Promise<MigrationStatusEntry[]>;
```

Reports the current state of the provided migrations.

#### Parameters

##### migrations

`Migrations`

Migration descriptors or registry to inspect.

##### options?

`DatabaseMigrationStatusOptions`

Migration journal configuration.

#### Returns

`Promise`\<`MigrationStatusEntry`\[\]>

Status entries for the provided migrations.

#### Inherited from

```ts
Database.migrationStatus
```

---

### now()

```ts
now(): unknown;
```

#### Returns

`unknown`

#### Inherited from

```ts
Database.now
```

---

### query()

```ts
query<tableName, row, primaryKey>(table): Query<QueryTableInput<tableName, row, primaryKey>, { [key in string]: QueryColumnTypeMapFromRow<tableName, row>[key] }, row, {
}, BoundQueryPhase<"all">>;
```

#### Type Parameters

##### tableName

`tableName` _extends_ `string`

##### row

`row` _extends_ `Record`\<`string`, `unknown`>

##### primaryKey

`primaryKey` _extends_ readonly keyof `row` \& `string`\[\]

#### Parameters

##### table

`QueryTableInput`\<`tableName`, `row`, `primaryKey`>

#### Returns

`Query`\<`QueryTableInput`\<`tableName`, `row`, `primaryKey`>, `{ [key in string]: QueryColumnTypeMapFromRow<tableName, row>[key] }`, `row`, { }, `BoundQueryPhase`\<`"all"`>>

#### Inherited from

```ts
Database.query
```

---

### reset()

```ts
reset(options): Promise<void>;
```

Wipes the database, applies migrations, and optionally seeds data.

#### Parameters

##### options

`DatabaseResetOptions`

Migrations and optional seed function used to rebuild the database.

#### Returns

`Promise`\<`void`>

A promise that resolves when the database has been rebuilt.

#### Inherited from

```ts
Database.reset
```

---

### transaction()

```ts
transaction<result>(callback, options?): Promise<result>;
```

#### Type Parameters

##### result

`result`

#### Parameters

##### callback

(`database`: `Database`\<`"sqlite"`>) => `Promise`\<`result`>

##### options?

`TransactionOptions`

#### Returns

`Promise`\<`result`>

#### Inherited from

```ts
Database.transaction
```

---

### update()

```ts
update<table, relations>(
   table,
   value,
   changes,
options?): Promise<{ [key in string | number | symbol]: ({ [key in string]: { [column in string]: ColumnOutput<TableColumns<table>[column]> }[key] } & { [key in string | number | symbol]: { [name in string | number | symbol]: RelationResult<relations[name]> }[key] })[key] }>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

##### relations

`relations` _extends_ `RelationMapForSourceName`\<`TableName`\<`table`>> = { }

#### Parameters

##### table

`table`

##### value

`PrimaryKeyInput`\<`table`>

##### changes

`Partial`\<`TableRow`\<`table`>>

##### options?

`UpdateOptions`\<`table`, `relations`>

#### Returns

`Promise`\<{ \[key in string | number | symbol\]: ({ \[key in string\]: { \[column in string\]: ColumnOutput\<TableColumns\<table>\[column\]> }\[key\] } \& { \[key in string | number | symbol\]: { \[name in string | number | symbol\]: RelationResult\<relations\[name\]> }\[key\] })\[key\] }>

#### Inherited from

```ts
Database.update
```

---

### updateMany()

```ts
updateMany<table>(
   table,
   changes,
options): Promise<WriteResult>;
```

#### Type Parameters

##### table

`table` _extends_ `AnyTable`

#### Parameters

##### table

`table`

##### changes

`Partial`\<`TableRow`\<`table`>>

##### options

`UpdateManyOptions`\<`table`>

#### Returns

`Promise`\<`WriteResult`>

#### Inherited from

```ts
Database.updateMany
```

---

### wipe()

```ts
wipe(): Promise<void>;
```

Destructively recreates the configured database.

#### Returns

`Promise`\<`void`>

A promise that resolves when the database is ready for use.

#### Inherited from

```ts
Database.wipe
```

# D1DatabaseDriver

Source: https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md

> A `DatabaseDriver` backed by a Cloudflare D1 binding.

```ts
import { D1DatabaseDriver } from "@pitlane/data-table-d1";
```

A `DatabaseDriver` backed by a Cloudflare D1 binding.

Statements are compiled by the same SQLite compiler `@remix-run/data-table` uses, then executed through D1's async prepared-statement API. Pass it to `Database`, or use [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) to get one already wired.

## Implements

- `DatabaseDriver`\<`"sqlite"`>

## Constructors

### Constructor

```ts
new D1DatabaseDriver(d1, options?): D1DatabaseDriver;
```

#### Parameters

##### d1

[`D1Binding`](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md)

##### options?

[`D1DriverOptions`](https://pitlane.tools/package/data-table-d1/interface/D1DriverOptions.md) = `{}`

#### Returns

`D1DatabaseDriver`

## Accessors

### capabilities

#### Get Signature

```ts
get capabilities(): Readonly<{
  migrationLock: false;
  returning: true;
  savepoints: false;
  transactionalDdl: false;
  upsert: true;
}>;
```

Immutable feature flags used by shared query and migration behavior.

##### Returns

`Readonly`\<{ `migrationLock`: `false`; `returning`: `true`; `savepoints`: `false`; `transactionalDdl`: `false`; `upsert`: `true`; }>

#### Implementation of

```ts
DatabaseDriver.capabilities
```

---

### dialect

#### Get Signature

```ts
get dialect(): "sqlite";
```

Stable identifier for the SQL dialect.

##### Returns

`"sqlite"`

#### Implementation of

```ts
DatabaseDriver.dialect
```

## Methods

### batch()

```ts
batch(statements): Promise<D1BatchResult[]>;
```

Runs statements together, atomically, through D1's `batch()`.

This is the answer to "several writes must land together" on a database with no transactions. `batch()` is D1's only atomic primitive: it takes every statement up front and commits them as a unit, which is why it cannot back `transaction()` but can back this.

Statements are `SqlStatement`s, so `sql` from `remix/data-table` parameterises them and there is no reaching for the raw binding:

```ts
await db.batch([
    sql`insert into post (title) values (${title})`,
    sql`update counter set posts = posts + 1`,
]);
```

#### Parameters

##### statements

`SqlStatement`\[\]

The statements to run, in order.

#### Returns

`Promise`\<[`D1BatchResult`](https://pitlane.tools/package/data-table-d1/interface/D1BatchResult.md)\[\]>

One result per statement, in the same order.

---

### beginTransaction()

```ts
beginTransaction(_options?): Promise<TransactionToken>;
```

Opens a transaction, if the caller accepted that it will not be one.

No `BEGIN` is sent, because D1 rejects it. The token exists so `Database` has something to carry; statements inside the scope run and commit exactly as they would outside it.

#### Parameters

##### \_options?

`TransactionOptions`

#### Returns

`Promise`\<`TransactionToken`>

#### Implementation of

```ts
DatabaseDriver.beginTransaction
```

---

### close()

```ts
close(): void;
```

A binding is owned by the runtime; there is no connection to release.

#### Returns

`void`

#### Implementation of

```ts
DatabaseDriver.close
```

---

### commitTransaction()

```ts
commitTransaction(_token): Promise<void>;
```

Nothing to commit: every statement in the scope already did.

#### Parameters

##### \_token

`TransactionToken`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.commitTransaction
```

---

### createSavepoint()

```ts
createSavepoint(_token, _name): Promise<void>;
```

Creates a savepoint inside an open transaction.

#### Parameters

##### \_token

`TransactionToken`

##### \_name

`string`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.createSavepoint
```

---

### execute()

```ts
execute(request): Promise<DataManipulationResult>;
```

Executes a data-manipulation request.

#### Parameters

##### request

`DataManipulationRequest`

#### Returns

`Promise`\<`DataManipulationResult`>

#### Implementation of

```ts
DatabaseDriver.execute
```

---

### executeScript()

```ts
executeScript(sql, _transaction?): Promise<void>;
```

Executes a raw SQL script that may contain multiple statements.

#### Parameters

##### sql

`string`

##### \_transaction?

`TransactionToken`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.executeScript
```

---

### hasColumn()

```ts
hasColumn(
   table,
   column,
_transaction?): Promise<boolean>;
```

Checks whether a column exists on a table.

#### Parameters

##### table

`TableRef`

##### column

`string`

##### \_transaction?

`TransactionToken`

#### Returns

`Promise`\<`boolean`>

#### Implementation of

```ts
DatabaseDriver.hasColumn
```

---

### hasTable()

```ts
hasTable(table, _transaction?): Promise<boolean>;
```

Checks whether a table exists.

#### Parameters

##### table

`TableRef`

##### \_transaction?

`TransactionToken`

#### Returns

`Promise`\<`boolean`>

#### Implementation of

```ts
DatabaseDriver.hasTable
```

---

### releaseSavepoint()

```ts
releaseSavepoint(_token, _name): Promise<void>;
```

Releases a previously created savepoint.

#### Parameters

##### \_token

`TransactionToken`

##### \_name

`string`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.releaseSavepoint
```

---

### rollbackToSavepoint()

```ts
rollbackToSavepoint(_token, _name): Promise<void>;
```

Rolls back to a previously created savepoint.

#### Parameters

##### \_token

`TransactionToken`

##### \_name

`string`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.rollbackToSavepoint
```

---

### rollbackTransaction()

```ts
rollbackTransaction(_token): Promise<void>;
```

Nothing to roll back. This is the cost of `unsafe-nonatomic`, and it is silent by necessity: `Database` calls this while unwinding a failed callback, and throwing here would replace the caller's error with an `AggregateError` about a rollback that was never possible.

#### Parameters

##### \_token

`TransactionToken`

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.rollbackTransaction
```

---

### wipe()

```ts
wipe(): Promise<void>;
```

Drops every table the application owns.

D1 keeps its own bookkeeping in `_cf_*` tables and SQLite keeps `sqlite_*`; dropping either breaks the binding, so both are left alone. There is no file to delete the way the SQLite driver deletes one.

#### Returns

`Promise`\<`void`>

#### Implementation of

```ts
DatabaseDriver.wipe
```

# D1BatchResult

Source: https://pitlane.tools/package/data-table-d1/interface/D1BatchResult.md

> What one statement in a [D1DatabaseDriver.batch](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md#batch) produced.

```ts
import type { D1BatchResult } from "@pitlane/data-table-d1";
```

What one statement in a [D1DatabaseDriver.batch](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md#batch) produced.

## Properties

### affectedRows

```ts
affectedRows: number;
```

---

### insertId

```ts
insertId: number;
```

---

### rows

```ts
rows: Record<string, unknown>[];
```

Rows the statement returned. Empty for a write with no `returning`.

# D1Binding

Source: https://pitlane.tools/package/data-table-d1/interface/D1Binding.md

> The slice of Cloudflare's D1 API this driver uses.

```ts
import type { D1Binding } from "@pitlane/data-table-d1";
```

The slice of Cloudflare's D1 API this driver uses.

Declared structurally rather than imported from `@cloudflare/workers-types`, so the package adds no dependency and no ambient global types to a consumer that does not already have them. A real `D1Database` binding satisfies it; so does a test double.

## Methods

### batch()

```ts
batch(statements): Promise<D1Result[]>;
```

Runs the statements in order inside one transaction, resolving to one result each.

#### Parameters

##### statements

[`D1PreparedStatement`](https://pitlane.tools/package/data-table-d1/interface/D1PreparedStatement.md)\[\]

#### Returns

`Promise`\<[`D1Result`](https://pitlane.tools/package/data-table-d1/interface/D1Result.md)\[\]>

---

### exec()

```ts
exec(query): Promise<unknown>;
```

Runs raw SQL, which may hold several statements, without binding or returning rows.

#### Parameters

##### query

`string`

#### Returns

`Promise`\<`unknown`>

---

### prepare()

```ts
prepare(query): D1PreparedStatement;
```

Compiles one SQL statement with `?` placeholders, without running it.

#### Parameters

##### query

`string`

#### Returns

[`D1PreparedStatement`](https://pitlane.tools/package/data-table-d1/interface/D1PreparedStatement.md)

# D1DatabaseOptions

Source: https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md

> The options [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) accepts: `remix/data-table`'s `DatabaseOptions`, plus D1's statement observer and transaction mode.

```ts
import type { D1DatabaseOptions } from "@pitlane/data-table-d1";
```

The options [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) accepts: `remix/data-table`'s `DatabaseOptions`, plus D1's statement observer and transaction mode.

## Extends

- `DatabaseOptions`

## Properties

### now?

```ts
optional now?: () => unknown;
```

Clock function used for auto-managed timestamps.

#### Returns

`unknown`

#### Inherited from

```ts
DatabaseOptions.now
```

---

### onStatement?

```ts
optional onStatement?: D1StatementObserver;
```

Called after each statement, with the rows read, rows written, and duration D1 reported for it. See [D1StatementObserver](https://pitlane.tools/package/data-table-d1/type/D1StatementObserver.md).

---

### transactions?

```ts
optional transactions?: D1TransactionMode;
```

What `transaction()` does. Defaults to `throw`, because D1 has no transactions; `unsafe-nonatomic` accepts the call and gives up atomicity. See [D1TransactionMode](https://pitlane.tools/package/data-table-d1/type/D1TransactionMode.md).

# D1DriverOptions

Source: https://pitlane.tools/package/data-table-d1/interface/D1DriverOptions.md

> The options [D1DatabaseDriver](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md) accepts: the D1-specific half of [D1DatabaseOptions](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md), which [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) passes through.

```ts
import type { D1DriverOptions } from "@pitlane/data-table-d1";
```

The options [D1DatabaseDriver](https://pitlane.tools/package/data-table-d1/class/D1DatabaseDriver.md) accepts: the D1-specific half of [D1DatabaseOptions](https://pitlane.tools/package/data-table-d1/interface/D1DatabaseOptions.md), which [createD1Database](https://pitlane.tools/package/data-table-d1/function/createD1Database.md) passes through.

## Properties

### onStatement?

```ts
optional onStatement?: D1StatementObserver;
```

---

### transactions?

```ts
optional transactions?: D1TransactionMode;
```

# D1Meta

Source: https://pitlane.tools/package/data-table-d1/interface/D1Meta.md

> What D1 reports about one statement it ran.

```ts
import type { D1Meta } from "@pitlane/data-table-d1";
```

What D1 reports about one statement it ran.

## Properties

### changes

```ts
changes: number;
```

Rows written by the statement. D1 reports 0 for reads.

---

### duration?

```ts
optional duration?: number;
```

Wall time D1 spent on the statement, in milliseconds.

---

### last\_row\_id

```ts
last_row_id: number;
```

Rowid of the last inserted row, meaningful only after an insert.

---

### rows\_read?

```ts
optional rows_read?: number;
```

Rows D1 scanned. Billed, and absent on some responses.

---

### rows\_written?

```ts
optional rows_written?: number;
```

Rows D1 persisted. Billed, and absent on some responses.

# D1PreparedStatement

Source: https://pitlane.tools/package/data-table-d1/interface/D1PreparedStatement.md

> A statement [D1Binding.prepare](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md#prepare) returns, before it runs.

```ts
import type { D1PreparedStatement } from "@pitlane/data-table-d1";
```

A statement [D1Binding.prepare](https://pitlane.tools/package/data-table-d1/interface/D1Binding.md#prepare) returns, before it runs.

## Methods

### all()

```ts
all(): Promise<D1Result>;
```

Runs the statement and resolves to every row it returned, plus its metadata.

#### Returns

`Promise`\<[`D1Result`](https://pitlane.tools/package/data-table-d1/interface/D1Result.md)>

---

### bind()

```ts
bind(...values): D1PreparedStatement;
```

Binds values to the statement's `?` placeholders, in order.

#### Parameters

##### values

...`unknown`\[\]

#### Returns

`D1PreparedStatement`

# D1Result

Source: https://pitlane.tools/package/data-table-d1/interface/D1Result.md

> What one statement produced: its rows, empty for a write, and D1's metadata.

```ts
import type { D1Result } from "@pitlane/data-table-d1";
```

What one statement produced: its rows, empty for a write, and D1's metadata.

## Properties

### meta

```ts
meta: D1Meta;
```

---

### results

```ts
results: Record<string, unknown>[];
```

# D1StatementReport

Source: https://pitlane.tools/package/data-table-d1/interface/D1StatementReport.md

> What one executed statement cost, as D1 reported it.

```ts
import type { D1StatementReport } from "@pitlane/data-table-d1";
```

What one executed statement cost, as D1 reported it.

## Properties

### durationMs

```ts
durationMs: number;
```

Wall time D1 spent, in milliseconds. `0` when D1 omits it.

---

### kind

```ts
kind: string;
```

The operation that produced it: `select`, `insert`, `update`, and so on.

---

### rowsRead

```ts
rowsRead: number;
```

Rows D1 scanned. `0` when D1 omits the figure, never estimated.

---

### rowsWritten

```ts
rowsWritten: number;
```

Rows D1 persisted. `0` when D1 omits the figure, never estimated.

---

### table

```ts
table: string | undefined;
```

The table it targeted, absent for a raw statement.

# D1StatementObserver

Source: https://pitlane.tools/package/data-table-d1/type/D1StatementObserver.md

> Called after each statement the driver executes.

```ts
import type { D1StatementObserver } from "@pitlane/data-table-d1";
```

```ts
type D1StatementObserver = (report: D1StatementReport) => void;
```

Called after each statement the driver executes.

D1 bills on rows read and written, and its analytics report per database rather than per query, so these numbers are the only way to attribute cost to the query or the request that caused it. They ride along on responses the driver already reads, so observing them costs no extra statement and no extra billable operation.

It runs on the hot path, once per statement, so keep it cheap.

## Parameters

### report

[`D1StatementReport`](https://pitlane.tools/package/data-table-d1/interface/D1StatementReport.md)

## Returns

`void`

# D1TransactionMode

Source: https://pitlane.tools/package/data-table-d1/type/D1TransactionMode.md

> How the driver answers a `transaction()` call.

```ts
import type { D1TransactionMode } from "@pitlane/data-table-d1";
```

```ts
type D1TransactionMode = "throw" | "unsafe-nonatomic";
```

How the driver answers a `transaction()` call.

- `throw` refuses, because D1 cannot honour it. The default.
- `unsafe-nonatomic` accepts and runs each statement immediately, each committing on its own. A failure part-way leaves the earlier writes persisted, with no rollback. For code shared with a backend that does have transactions, where the alternative is not running at all.

# @pitlane/data-table-d1/migrations

Source: https://pitlane.tools/package/data-table-d1/migrations.md

> Compiles `data-table` migrations into the flat `.sql` files Wrangler's D1 migration runner reads.

Compiles `data-table` migrations into the flat `.sql` files Wrangler's D1 migration runner reads.

Node-only build tooling. Nothing here belongs in a Worker bundle, which is why it is a separate entry point from the driver.

## See

[Cloudflare D1 guide: Migrations](https://pitlane.tools/guides/cloudflare-d1.md#migrations)

## Interfaces

- [GenerateD1MigrationsOptions](https://pitlane.tools/package/data-table-d1/migrations/interface/GenerateD1MigrationsOptions.md). What [generateD1Migrations](https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md) needs to know.
- [GeneratedD1Migration](https://pitlane.tools/package/data-table-d1/migrations/interface/GeneratedD1Migration.md). One generated file.

## Functions

- [generateD1Migrations](https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md). Writes one `<id>_<name>.sql` per migration into `options.to`, then deletes generated files with no migration behind them, so the output directory is a pure function of the input one.

# generateD1Migrations

Source: https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md

> Writes one `<id>_<name>.sql` per migration into `options.to`, then deletes generated files with no migration behind them, so the output directory is a pure function of the input one.

```ts
import { generateD1Migrations } from "@pitlane/data-table-d1/migrations";
```

```ts
function generateD1Migrations(options): Promise<GeneratedD1Migration[]>;
```

Writes one `<id>_<name>.sql` per migration into `options.to`, then deletes generated files with no migration behind them, so the output directory is a pure function of the input one.

The SQL is copied verbatim. Splitting it into statements is the job of whatever executes the file, and a splitter naive enough to write here would corrupt any migration containing a semicolon inside a string literal or a `begin ... end` trigger body.

## Parameters

### options

[`GenerateD1MigrationsOptions`](https://pitlane.tools/package/data-table-d1/migrations/interface/GenerateD1MigrationsOptions.md)

Where to read migrations from, and where to write SQL to.

## Returns

`Promise`\<[`GeneratedD1Migration`](https://pitlane.tools/package/data-table-d1/migrations/interface/GeneratedD1Migration.md)\[\]>

The generated files, ordered by migration id.

## Throws

If `options.from` holds no migrations, or one of them has an empty `up`. Both mean the output directory is about to be wrong, and a migration runner is the worst place to discover that.

## Example

```ts
import { generateD1Migrations } from "@pitlane/data-table-d1/migrations";

await generateD1Migrations({ to: "db/d1-migrations" });
```

## See

[Cloudflare D1 guide: Migrations](https://pitlane.tools/guides/cloudflare-d1.md#migrations)

# GenerateD1MigrationsOptions

Source: https://pitlane.tools/package/data-table-d1/migrations/interface/GenerateD1MigrationsOptions.md

> What [generateD1Migrations](https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md) needs to know.

```ts
import type { GenerateD1MigrationsOptions } from "@pitlane/data-table-d1/migrations";
```

What [generateD1Migrations](https://pitlane.tools/package/data-table-d1/migrations/function/generateD1Migrations.md) needs to know.

## Properties

### from?

```ts
optional from?: string;
```

Directory holding the `data-table` migrations, one `<id>_<name>/` directory per migration.

#### Default

```ts
"db/migrations"
```

---

### to

```ts
to: string;
```

Where the generated `.sql` files land. Point this at the same directory as `migrations_dir` in your Wrangler config.

# GeneratedD1Migration

Source: https://pitlane.tools/package/data-table-d1/migrations/interface/GeneratedD1Migration.md

> One generated file.

```ts
import type { GeneratedD1Migration } from "@pitlane/data-table-d1/migrations";
```

One generated file.

## Properties

### file

```ts
file: string;
```

Path of the written file, relative to the working directory.

---

### id

```ts
id: string;
```

Migration id, typically a `YYYYMMDDHHmmss` timestamp.

---

### name

```ts
name: string;
```

Migration slug.

# @pitlane/theme

Source: https://pitlane.tools/package/theme/index.md

> Type-safe styling with design tokens for Remix 3.

Type-safe styling with design tokens for Remix 3.

`createTheme` takes a schema tree and the token tree it describes, and returns a typed token accessor plus a `<Theme />` component that installs the tokens as CSS custom properties. Token values are the CSS they become; the schema, built from `@pitlane/theme/schema`, names each token's type. The `css`, `tva`, `combine`, and `cx` helpers enforce the token palette at the type level on top of `remix/component`'s `css()` mixin.

## See

[Theme guide](https://pitlane.tools/guides/theme.md)

## Classes

- [ThemeError](https://pitlane.tools/package/theme/class/ThemeError.md). The error [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) throws for every structural failure: one problem, one sentence.

## Interfaces

- [CombinedTVAFn](https://pitlane.tools/package/theme/interface/CombinedTVAFn.md). A component built by [combine](https://pitlane.tools/package/theme/function/combine.md). Accepts the union of the input components' props and honors each input's own defaults.
- [ScaleFn](https://pitlane.tools/package/theme/interface/ScaleFn.md). The accessor leaf for a token declared with `s.scale()`: callable for steps, with the base itself as `.token`.
- [ThemeComponent](https://pitlane.tools/package/theme/interface/ThemeComponent.md). The `<Theme />` component [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns. Render it once near the document root to install the custom properties.
- [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md). The style-object type accepted by [css](https://pitlane.tools/package/theme/function/css.md) and every [tva](https://pitlane.tools/package/theme/function/tva.md) slot.
- [ThemeInit](https://pitlane.tools/package/theme/interface/ThemeInit.md). The argument [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: a schema tree, the token tree it describes, and any modes.
- [ThemeMode](https://pitlane.tools/package/theme/interface/ThemeMode.md). A theme's mode: a condition plus the values it overrides.
- [ThemePatch](https://pitlane.tools/package/theme/interface/ThemePatch.md). The argument `extend` accepts. `schema` is optional, because a patch that only adds tokens to an existing namespace needs no new entry.
- [ThemeResult](https://pitlane.tools/package/theme/interface/ThemeResult.md). The object [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns: the typed token accessor, the `raw` resolver, the `<Theme />` component, and the two derivation methods.
- [Tokens](https://pitlane.tools/package/theme/interface/Tokens.md). The token tree [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: nested records whose leaves are [TokenValue](https://pitlane.tools/package/theme/type/TokenValue.md)s. No reserved keys, so it is plain JSON and a designer can diff it.
- [TVAConfig](https://pitlane.tools/package/theme/interface/TVAConfig.md). Configuration for [tva](https://pitlane.tools/package/theme/function/tva.md). Every style slot is [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md), carrying the same brand enforcement as [css](https://pitlane.tools/package/theme/function/css.md).
- [TVAFn](https://pitlane.tools/package/theme/interface/TVAFn.md). A variant component built by [tva](https://pitlane.tools/package/theme/function/tva.md). Call it with a variant selection to get a `mix`-ready descriptor; call `resolve` for the merged [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md) without building a descriptor.

## Type Aliases

- [AnyToken](https://pitlane.tools/package/theme/type/AnyToken.md). The union of all twelve token brands. Brands are compile-time tags naming each token's type; they let [css](https://pitlane.tools/package/theme/function/css.md) reject a dimension where a color belongs. They exist only in the type system — every ref is a plain string at runtime, so brands cost nothing — and they are theme-independent, so tokens minted by two different [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) calls mix freely in one [css](https://pitlane.tools/package/theme/function/css.md) call.
- [BorderToken](https://pitlane.tools/package/theme/type/BorderToken.md). Compile-time brand for a `border` token.
- [ClassValue](https://pitlane.tools/package/theme/type/ClassValue.md). A value [cx](https://pitlane.tools/package/theme/function/cx.md) accepts: a string, a number, a nested array of the same, or a record whose truthy keys are emitted. `null`, `undefined`, and `false` are dropped. Compatible with clsx.
- [ColorToken](https://pitlane.tools/package/theme/type/ColorToken.md). Compile-time brand for a `color` token.
- [CubicBezierToken](https://pitlane.tools/package/theme/type/CubicBezierToken.md). Compile-time brand for a `cubicBezier` token.
- [DeepPartialTokens](https://pitlane.tools/package/theme/type/DeepPartialTokens.md). The mode-override shape for a token tree: every group optional, every leaf a value. A mode overrides values, never structure or types.
- [DimensionToken](https://pitlane.tools/package/theme/type/DimensionToken.md). Compile-time brand for a `dimension` token.
- [DurationToken](https://pitlane.tools/package/theme/type/DurationToken.md). Compile-time brand for a `duration` token.
- [FontFamilyToken](https://pitlane.tools/package/theme/type/FontFamilyToken.md). Compile-time brand for a `fontFamily` token.
- [FontWeightToken](https://pitlane.tools/package/theme/type/FontWeightToken.md). Compile-time brand for a `fontWeight` token.
- [GradientToken](https://pitlane.tools/package/theme/type/GradientToken.md). Compile-time brand for a `gradient` token.
- [NumberToken](https://pitlane.tools/package/theme/type/NumberToken.md). Compile-time brand for a `number` token.
- [ShadowToken](https://pitlane.tools/package/theme/type/ShadowToken.md). Compile-time brand for a `shadow` token.
- [StrokeStyleToken](https://pitlane.tools/package/theme/type/StrokeStyleToken.md). Compile-time brand for a `strokeStyle` token.
- [ThemedCSSMixin](https://pitlane.tools/package/theme/type/ThemedCSSMixin.md). The descriptor [css](https://pitlane.tools/package/theme/function/css.md) produces. `MixinDescriptor` is invariant in its node type, so — exactly like `remix/component`'s own `css` factory — the node binds per callsite through the generic parameter.
- [ThemeProps](https://pitlane.tools/package/theme/type/ThemeProps.md). Props for the [ThemeComponent](https://pitlane.tools/package/theme/interface/ThemeComponent.md). `nonce` sets the `nonce` attribute on the emitted `<style>` element for Content Security Policy setups.
- [TokenTree](https://pitlane.tools/package/theme/type/TokenTree.md). The accessor shape for an init `T`: the same nesting as its token tree, with every leaf replaced by the branded `var(--…)` reference its schema declares. Numeric keys index with brackets (`t.color.gray[900]`).
- [TokenType](https://pitlane.tools/package/theme/type/TokenType.md). The twelve DTCG token `$type` values.
- [TokenValue](https://pitlane.tools/package/theme/type/TokenValue.md). A token value: the CSS it becomes. A string, a number, or an array of either. Anything else is a group.
- [TransitionToken](https://pitlane.tools/package/theme/type/TransitionToken.md). Compile-time brand for a `transition` token.
- [TVAProps](https://pitlane.tools/package/theme/type/TVAProps.md). Extracts a [tva](https://pitlane.tools/package/theme/function/tva.md) component's variant props, like cva's `VariantProps`. All props are optional; wrap the component to require one.
- [UntypedToken](https://pitlane.tools/package/theme/type/UntypedToken.md). Compile-time brand for a token declared with `s.any()`. It carries no CSS type, so the open-grammar properties (`animation`, `aspectRatio`, `background`) accept it and the token-mapped longhands reject it.

## Functions

- [combine](https://pitlane.tools/package/theme/function/combine.md). Composes [tva](https://pitlane.tools/package/theme/function/tva.md) components, like cva's `compose`. Each input resolves independently against the shared props, the results deep-merge in argument order, and one [css](https://pitlane.tools/package/theme/function/css.md) call produces the descriptor. The result accepts the union of the inputs' props and honors each input's own defaults.
- [createTheme](https://pitlane.tools/package/theme/function/createTheme.md). Compiles a theme from a schema tree and the token tree it describes.
- [css](https://pitlane.tools/package/theme/function/css.md). Brand-enforced wrapper over `remix/component`'s `css()` mixin. Token-mapped longhands accept the matching token brand, CSS-wide keywords, property keywords, and `0`; anything else — including a raw `color: "#ff0000"` — is a type error. Every other CSS property carries csstype's value union, so `display`, `position`, `resize`, and the rest of the closed-grammar properties accept only their real keywords. Nested selectors, at-rules, and custom properties recurse.
- [cx](https://pitlane.tools/package/theme/function/cx.md). clsx-compatible `className` joiner for interop with plain stylesheets, since `mix` and `className` compose on the same element. Strings and numbers join with spaces, falsy values drop, arrays flatten, and truthy object keys join.
- [lightDark](https://pitlane.tools/package/theme/function/lightDark.md). A `light-dark()` color, resolved by the browser against the `color-scheme` property. A subtree that sets `color-scheme` flips whatever the media query says, which is what a theme toggle needs.
- [scale](https://pitlane.tools/package/theme/function/scale.md). Turns one token into a multiplier, so a scale does not have to name every step. The returned function produces `calc(<base> * <steps>)`, keeping whichever brand the base carried.
- [tva](https://pitlane.tools/package/theme/function/tva.md). Builds a variant resolver modeled on [cva](https://cva.style). Where cva composes class strings, `tva` composes brand-enforced style objects into a `mix`-ready descriptor.

# combine

Source: https://pitlane.tools/package/theme/function/combine.md

> Composes [tva](https://pitlane.tools/package/theme/function/tva.md) components, like cva's `compose`. Each input resolves independently against the shared props, the results deep-merge in argument order, and one [css](https://pitlane.tools/package/theme/function/css.md) call produces the descriptor. The result accepts the union of the inputs' props and honors each input's own defaults.

```ts
import { combine } from "@pitlane/theme";
```

```ts
function combine<Fns>(...fns): CombinedTVAFn<Fns>;
```

Composes [tva](https://pitlane.tools/package/theme/function/tva.md) components, like cva's `compose`. Each input resolves independently against the shared props, the results deep-merge in argument order, and one [css](https://pitlane.tools/package/theme/function/css.md) call produces the descriptor. The result accepts the union of the inputs' props and honors each input's own defaults.

## Type Parameters

### Fns

`Fns` _extends_ readonly [`TVAFn`](https://pitlane.tools/package/theme/interface/TVAFn.md)\<`VariantShape`>\[\]

## Parameters

### fns

...`Fns`

## Returns

[`CombinedTVAFn`](https://pitlane.tools/package/theme/interface/CombinedTVAFn.md)\<`Fns`>

## See

[CombinedTVAFn](https://pitlane.tools/package/theme/interface/CombinedTVAFn.md)

## Example

```tsx
export let pillButton = combine(button, rounded);
<button mix={pillButton({ intent: "primary", pill: true })} />;
```

# createTheme

Source: https://pitlane.tools/package/theme/function/createTheme.md

> Compiles a theme from a schema tree and the token tree it describes.

```ts
import { createTheme } from "@pitlane/theme";
```

## Call Signature

```ts
function createTheme<schema, tokens>(init): ThemeResult<{
  schema: schema;
  tokens: tokens;
}>;
```

Compiles a theme from a schema tree and the token tree it describes.

Values are the CSS they become: a color is any CSS color, a dimension is any CSS length, and a composite is the shorthand text. The schema names each token's type, which is what the accessor's compile-time brands are read from and what `css()` enforces.

A reference to another token is a property access on the layer below, so it needs an [ThemeResult.extend](https://pitlane.tools/package/theme/interface/ThemeResult.md#extend) layer. The accessor leaf is already a `var()` string, which keeps its indirection in the emitted CSS so a mode override cascades through it. There is no string syntax for a reference; a leftover `"{a.b.c}"` raises [ThemeError](https://pitlane.tools/package/theme/class/ThemeError.md).

All validation and serialization happen eagerly: a malformed theme throws at module load rather than emitting broken CSS. Bad values raise `ValidationError` from `remix/data-schema`, carrying one issue per bad token with its path. Structural problems raise [ThemeError](https://pitlane.tools/package/theme/class/ThemeError.md).

### Type Parameters

#### schema

`schema` _extends_ `object`

#### tokens

`tokens` _extends_ `object`

### Parameters

#### init

The schema, tokens, and modes, or a `<Theme />` to re-derive from

##### modes?

`Record`\<`string`, [`ThemeMode`](https://pitlane.tools/package/theme/interface/ThemeMode.md)\<`tokens`>>

##### schema

`schema`

##### tokens

`tokens`

### Returns

[`ThemeResult`](https://pitlane.tools/package/theme/interface/ThemeResult.md)\<{ `schema`: `schema`; `tokens`: `tokens`; }>

The [ThemeResult](https://pitlane.tools/package/theme/interface/ThemeResult.md)

### Throws

ThemeError on a structural failure

### Throws

ValidationError on one or more invalid values

### See

- [ThemeInit](https://pitlane.tools/package/theme/interface/ThemeInit.md) for the accepted shape.
- [Theme guide: Define a theme](https://pitlane.tools/guides/theme.md#define-a-theme)

### Example

```ts
import { createTheme } from "@pitlane/theme";
import * as s from "@pitlane/theme/schema";

export let { token: t, raw, Theme } = createTheme({
    schema: { color: s.color(), spacing: s.scale() },
    tokens: { color: { white: "#fff" }, spacing: "0.25rem" },
}).extend(base => ({
    schema: { color: s.color() },
    tokens: { color: { page: base.color.white } },
}));

t.color.page; // "var(--color-page)"
raw(t.color.page); // "#fff"
t.spacing(4); // "calc(var(--spacing) * 4)"
```

## Call Signature

```ts
function createTheme<T>(theme): ThemeResult<T>;
```

Compiles a theme from a schema tree and the token tree it describes.

Values are the CSS they become: a color is any CSS color, a dimension is any CSS length, and a composite is the shorthand text. The schema names each token's type, which is what the accessor's compile-time brands are read from and what `css()` enforces.

A reference to another token is a property access on the layer below, so it needs an [ThemeResult.extend](https://pitlane.tools/package/theme/interface/ThemeResult.md#extend) layer. The accessor leaf is already a `var()` string, which keeps its indirection in the emitted CSS so a mode override cascades through it. There is no string syntax for a reference; a leftover `"{a.b.c}"` raises [ThemeError](https://pitlane.tools/package/theme/class/ThemeError.md).

All validation and serialization happen eagerly: a malformed theme throws at module load rather than emitting broken CSS. Bad values raise `ValidationError` from `remix/data-schema`, carrying one issue per bad token with its path. Structural problems raise [ThemeError](https://pitlane.tools/package/theme/class/ThemeError.md).

### Type Parameters

#### T

`T`

### Parameters

#### theme

[`ThemeComponent`](https://pitlane.tools/package/theme/interface/ThemeComponent.md)\<`T`>

### Returns

[`ThemeResult`](https://pitlane.tools/package/theme/interface/ThemeResult.md)\<`T`>

The [ThemeResult](https://pitlane.tools/package/theme/interface/ThemeResult.md)

### Throws

ThemeError on a structural failure

### Throws

ValidationError on one or more invalid values

### See

- [ThemeInit](https://pitlane.tools/package/theme/interface/ThemeInit.md) for the accepted shape.
- [Theme guide: Define a theme](https://pitlane.tools/guides/theme.md#define-a-theme)

### Example

```ts
import { createTheme } from "@pitlane/theme";
import * as s from "@pitlane/theme/schema";

export let { token: t, raw, Theme } = createTheme({
    schema: { color: s.color(), spacing: s.scale() },
    tokens: { color: { white: "#fff" }, spacing: "0.25rem" },
}).extend(base => ({
    schema: { color: s.color() },
    tokens: { color: { page: base.color.white } },
}));

t.color.page; // "var(--color-page)"
raw(t.color.page); // "#fff"
t.spacing(4); // "calc(var(--spacing) * 4)"
```

# css

Source: https://pitlane.tools/package/theme/function/css.md

> Brand-enforced wrapper over `remix/component`'s `css()` mixin. Token-mapped longhands accept the matching token brand, CSS-wide keywords, property keywords, and `0`; anything else — including a raw `color: "#ff0000"` — is a type error. Every other CSS property carries csstype's value union, so `display`, `position`, `resize`, and the rest of the closed-grammar properties accept only their real keywords. Nested selectors, at-rules, and custom properties recurse.

```ts
import { css } from "@pitlane/theme";
```

```ts
function css<node>(styles): ThemedCSSMixin<node>;
```

Brand-enforced wrapper over `remix/component`'s `css()` mixin. Token-mapped longhands accept the matching token brand, CSS-wide keywords, property keywords, and `0`; anything else — including a raw `color: "#ff0000"` — is a type error. Every other CSS property carries csstype's value union, so `display`, `position`, `resize`, and the rest of the closed-grammar properties accept only their real keywords. Nested selectors, at-rules, and custom properties recurse.

Branded token refs are already `var()` strings and pass through; an array value joins with spaces, which is how the box shorthands take a 1–4 tuple. A comma list needs a template string.

Inline `css()` infers its node type from `mix`. Reusable descriptors need an explicit type, such as `css<HTMLAnchorElement>(styles)`, matching their elements.

Interpolating a token into a template string (```1px solid ${t.color.line}```) yields a plain string, which the open-grammar shorthands accept.

## Type Parameters

### node

`node` _extends_ `Element` = `Element`

## Parameters

### styles

[`ThemedCSSProps`](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md)

## Returns

[`ThemedCSSMixin`](https://pitlane.tools/package/theme/type/ThemedCSSMixin.md)\<`node`>

## See

- [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md) for the accepted per-property values.
- [ThemedCSSMixin](https://pitlane.tools/package/theme/type/ThemedCSSMixin.md) for the returned descriptor.
- [Theme guide: Use tokens in styles](https://pitlane.tools/guides/theme.md#use-tokens-in-styles)

## Example

```tsx
<div
    mix={css({
        color: t.color.bg,
        padding: [t.space.sm, t.space.md],
        margin: 0,
        "&:hover": { color: t.color.gray[900] },
    })}
/>
```

# cx

Source: https://pitlane.tools/package/theme/function/cx.md

> clsx-compatible `className` joiner for interop with plain stylesheets, since `mix` and `className` compose on the same element. Strings and numbers join with spaces, falsy values drop, arrays flatten, and truthy object keys join.

```ts
import { cx } from "@pitlane/theme";
```

```ts
function cx(...inputs): string;
```

clsx-compatible `className` joiner for interop with plain stylesheets, since `mix` and `className` compose on the same element. Strings and numbers join with spaces, falsy values drop, arrays flatten, and truthy object keys join.

## Parameters

### inputs

...[`ClassValue`](https://pitlane.tools/package/theme/type/ClassValue.md)\[\]

## Returns

`string`

## See

[ClassValue](https://pitlane.tools/package/theme/type/ClassValue.md)

## Example

```tsx
<span className={cx("mono", isAlias && "alias-tag")} />;
```

# lightDark

Source: https://pitlane.tools/package/theme/function/lightDark.md

> A `light-dark()` color, resolved by the browser against the `color-scheme` property. A subtree that sets `color-scheme` flips whatever the media query says, which is what a theme toggle needs.

```ts
import { lightDark } from "@pitlane/theme";
```

```ts
function lightDark(light, dark): string;
```

A `light-dark()` color, resolved by the browser against the `color-scheme` property. A subtree that sets `color-scheme` flips whatever the media query says, which is what a theme toggle needs.

Both arguments may be token references, so a mode override of either primitive still reaches the result.

`light-dark()` is color-only. Use `modes` for anything else.

## Parameters

### light

`string`

The color for a light `color-scheme`

### dark

`string`

The color for a dark `color-scheme`

## Returns

`string`

The `light-dark()` function text

## Example

```ts
tokens: { surface: { page: lightDark("#ffffff", "#1a1a1a") } }
```

# scale

Source: https://pitlane.tools/package/theme/function/scale.md

> Turns one token into a multiplier, so a scale does not have to name every step. The returned function produces `calc(<base> * <steps>)`, keeping whichever brand the base carried.

```ts
import { scale } from "@pitlane/theme";
```

```ts
function scale<base>(base): (steps: number) => base;
```

Turns one token into a multiplier, so a scale does not have to name every step. The returned function produces `calc(<base> * <steps>)`, keeping whichever brand the base carried.

Use this for a token you did not declare as a scale. A token declared with `s.scale()` is already a multiplier, and its base is `t.spacing.token` when you need it.

The result is a CSS string like any other, so it also works as an authored token value.

## Type Parameters

### base

`base` _extends_ `ScalableToken`

The token to multiply

## Parameters

### base

`base`

## Returns

A function from steps to a token of the same type

(`steps`: `number`) => `base`

## Example

```ts
import { scale } from "@pitlane/theme";

let step = scale(t.tracking.tight);
css({ letterSpacing: step(2) }); // calc(var(--tracking-tight) * 2)
```

# tva

Source: https://pitlane.tools/package/theme/function/tva.md

> Builds a variant resolver modeled on [cva](https://cva.style). Where cva composes class strings, `tva` composes brand-enforced style objects into a `mix`-ready descriptor.

```ts
import { tva } from "@pitlane/theme";
```

```ts
function tva<V>(config): TVAFn<V>;
```

Builds a variant resolver modeled on [cva](https://cva.style). Where cva composes class strings, `tva` composes brand-enforced style objects into a `mix`-ready descriptor.

Each invocation resolves the selection by deep-merging `base`, then every matching variant in declaration order, then every matching compound variant in array order, and feeds the result to a single [css](https://pitlane.tools/package/theme/function/css.md) call. `defaultVariants` fills in unset axes, and boolean axes come from options named `true` and `false`.

## Type Parameters

### V

`V` _extends_ `VariantShape`

## Parameters

### config

[`TVAConfig`](https://pitlane.tools/package/theme/interface/TVAConfig.md)\<`V`>

## Returns

[`TVAFn`](https://pitlane.tools/package/theme/interface/TVAFn.md)\<`V`>

## See

- [TVAConfig](https://pitlane.tools/package/theme/interface/TVAConfig.md) for the configuration shape.
- [TVAProps](https://pitlane.tools/package/theme/type/TVAProps.md) to extract the props type.
- [Theme guide: Variants with Theme Variance Authority](https://pitlane.tools/guides/theme.md#variants-with-theme-variance-authority)

## Example

```ts
export let button = tva({
    base: { borderRadius: t.radius.md },
    variants: {
        intent: {
            primary: { backgroundColor: t.color.accent },
            secondary: { backgroundColor: "transparent" },
        },
        size: { sm: { fontSize: t.text.sm }, md: { fontSize: t.text.md } },
        block: { true: { display: "flex" } },
    },
    compoundVariants: [
        { intent: "secondary", size: "md", css: { fontSize: t.text.lg } },
    ],
    defaultVariants: { intent: "primary", size: "md" },
});

<button mix={button({ intent: "secondary", block: true })} />;
```

# ThemeError

Source: https://pitlane.tools/package/theme/class/ThemeError.md

> The error [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) throws for every structural failure: one problem, one sentence.

```ts
import { ThemeError } from "@pitlane/theme";
```

The error [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) throws for every structural failure: one problem, one sentence.

| Failure | Message shape |
| --- | --- |
| No schema entry | `"space.md" has no schema entry` |
| Unknown reference | `"color.bg" references unknown token "color.nope"` |
| Reference type mismatch | `"color.bg" references "space.md" of type "dimension" where "color" is required` |
| Reference to an untyped token | `"color.bg" references untyped token "animate.spin"` |
| Reference cycle | `Reference cycle: color.a → color.b → color.a` |
| Variable collision | `Tokens "a.b" and "a-b" both produce the CSS variable --a-b` |
| Reserved characters | `Token or group name "a.b" contains characters reserved by references (".", "{", "}")` |
| Empty identifier | `Token path segment "!!" produces an empty CSS identifier` |
| Unknown mode token | `Mode "dark" overrides unknown token "color.nope"` |

Bad token _values_ raise `ValidationError` from `remix/data-schema` instead, because there may be several and each carries its own path.

## See

[createTheme](https://pitlane.tools/package/theme/function/createTheme.md)

## Extends

- `Error`

## Constructors

### Constructor

```ts
new ThemeError(message?): ThemeError;
```

#### Parameters

##### message?

`string`

#### Returns

`ThemeError`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new ThemeError(message?, options?): ThemeError;
```

#### Parameters

##### message?

`string`

##### options?

`ErrorOptions`

#### Returns

`ThemeError`

#### Inherited from

```ts
Error.constructor
```

## Properties

### cause?

```ts
optional cause?: unknown;
```

#### Inherited from

```ts
Error.cause
```

---

### message

```ts
message: string;
```

#### Inherited from

```ts
Error.message
```

---

### name

```ts
name: string = "ThemeError";
```

#### Overrides

```ts
Error.name
```

---

### stack?

```ts
optional stack?: string;
```

#### Inherited from

```ts
Error.stack
```

## Methods

### isError()

```ts
static isError(error): error is Error;
```

Indicates whether the argument provided is a built-in Error instance or not.

#### Parameters

##### error

`unknown`

#### Returns

`error is Error`

#### Inherited from

```ts
Error.isError
```

# CombinedTVAFn

Source: https://pitlane.tools/package/theme/interface/CombinedTVAFn.md

> A component built by [combine](https://pitlane.tools/package/theme/function/combine.md). Accepts the union of the input components' props and honors each input's own defaults.

```ts
import type { CombinedTVAFn } from "@pitlane/theme";
```

A component built by [combine](https://pitlane.tools/package/theme/function/combine.md). Accepts the union of the input components' props and honors each input's own defaults.

## Type Parameters

### Fns

`Fns` _extends_ readonly [`TVAFn`](https://pitlane.tools/package/theme/interface/TVAFn.md)\<`VariantShape`>\[\]

```ts
CombinedTVAFn<node>(props?): ThemedCSSMixin<node>;
```

Resolves every input and returns a `mix`-ready descriptor.

## Type Parameters

### node

`node` _extends_ `Element` = `Element`

## Parameters

### props?

`CombinedProps`\<`Fns`>

## Returns

[`ThemedCSSMixin`](https://pitlane.tools/package/theme/type/ThemedCSSMixin.md)\<`node`>

## Methods

### resolve()

```ts
resolve(props?): ThemedCSSProps;
```

Returns the merged style object without building a descriptor.

#### Parameters

##### props?

`CombinedProps`\<`Fns`>

#### Returns

[`ThemedCSSProps`](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md)

# ScaleFn

Source: https://pitlane.tools/package/theme/interface/ScaleFn.md

> The accessor leaf for a token declared with `s.scale()`: callable for steps, with the base itself as `.token`.

```ts
import type { ScaleFn } from "@pitlane/theme";
```

The accessor leaf for a token declared with `s.scale()`: callable for steps, with the base itself as `.token`.

`.token` is what a projection re-roots and what `raw` resolves, so it is load-bearing rather than decorative.

## See

[TokenTree](https://pitlane.tools/package/theme/type/TokenTree.md)

```ts
ScaleFn(steps): DimensionToken;
```

The accessor leaf for a token declared with `s.scale()`: callable for steps, with the base itself as `.token`.

`.token` is what a projection re-roots and what `raw` resolves, so it is load-bearing rather than decorative.

## Parameters

### steps

`number`

## Returns

[`DimensionToken`](https://pitlane.tools/package/theme/type/DimensionToken.md)

## See

[TokenTree](https://pitlane.tools/package/theme/type/TokenTree.md)

## Properties

### token

```ts
readonly token: DimensionToken;
```

# ThemeComponent

Source: https://pitlane.tools/package/theme/interface/ThemeComponent.md

> The `<Theme />` component [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns. Render it once near the document root to install the custom properties.

```ts
import type { ThemeComponent } from "@pitlane/theme";
```

The `<Theme />` component [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns. Render it once near the document root to install the custom properties.

It is an ordinary component with one extra property, `$theme`, holding the init it was compiled from, so a published theme can be handed straight back to [createTheme](https://pitlane.tools/package/theme/function/createTheme.md).

## Type Parameters

### T

`T`

```ts
ThemeComponent(handle): () => RemixElement;
```

The `<Theme />` component [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns. Render it once near the document root to install the custom properties.

It is an ordinary component with one extra property, `$theme`, holding the init it was compiled from, so a published theme can be handed straight back to [createTheme](https://pitlane.tools/package/theme/function/createTheme.md).

## Parameters

### handle

`Handle`\<[`ThemeProps`](https://pitlane.tools/package/theme/type/ThemeProps.md)>

## Returns

() => `RemixElement`

## Properties

### $theme

```ts
readonly $theme: T;
```

# ThemedCSSProps

Source: https://pitlane.tools/package/theme/interface/ThemedCSSProps.md

> The style-object type accepted by [css](https://pitlane.tools/package/theme/function/css.md) and every [tva](https://pitlane.tools/package/theme/function/tva.md) slot.

```ts
import type { ThemedCSSProps } from "@pitlane/theme";
```

The style-object type accepted by [css](https://pitlane.tools/package/theme/function/css.md) and every [tva](https://pitlane.tools/package/theme/function/tva.md) slot.

Two layers stack. Token-mapped longhands enforce the matching token brand plus the small set of CSS keywords the table lists, and the literal `0` where the value is a length. Every other property carries csstype's value union, so closed-grammar properties such as `display`, `position`, `resize`, and `overflow` only accept their real keywords. Unknown keys — nested selectors, at-rules, and CSS custom properties — recurse or stay loose.

`Wide` below is the CSS-wide keyword union `"inherit" | "initial" | "unset" | "revert" | "revert-layer"`.

| Property family | Accepted values |
| --- | --- |
| `color`, `backgroundColor`, `borderColor`, the four per-side and two logical border colors, `outlineColor`, `textDecorationColor`, `columnRuleColor`, `caretColor`, `accentColor`, `fill`, `stroke` | `ColorToken \| "transparent" \| "currentColor" \| Wide` |
| `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, their `blockSize`/`inlineSize` logical forms, `flexBasis` | `DimensionToken \| 0 \| "auto" \| "min-content" \| "max-content" \| "fit-content" \| Wide` |
| `top`, `right`, `bottom`, `left`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, and their `inset*`/`margin*` logical start/end forms | `DimensionToken \| 0 \| "auto" \| Wide` |
| `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, the logical padding start/end forms, `fontSize`, `textIndent`, `outlineOffset`, the four corner radii, `rowGap`, `columnGap` | `DimensionToken \| 0 \| Wide` |
| `letterSpacing`, `wordSpacing` | `DimensionToken \| 0 \| "normal" \| Wide` |
| `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`, `outlineWidth` | `DimensionToken \| 0 \| "thin" \| "medium" \| "thick" \| Wide` |
| `padding`, `borderRadius` | a single value as the longhand, or a tuple of 1–4 `DimensionToken \| 0` values, space-joined |
| `margin`, `inset` | a single value as the longhand, or a tuple of 1–4 `DimensionToken \| 0 \| "auto"` values, space-joined |
| `gap`, `paddingBlock`, `paddingInline` | the longhand value, or a 2-tuple of `DimensionToken \| 0` |
| `marginBlock`, `marginInline`, `insetBlock`, `insetInline` | the longhand value, or a 2-tuple of `DimensionToken \| 0 \| "auto"` |
| `fontFamily` | `FontFamilyToken \| Wide` |
| `fontWeight` | `FontWeightToken \| "normal" \| "bold" \| "lighter" \| "bolder" \| Wide` |
| `lineHeight` | `NumberToken \| DimensionToken \| "normal" \| Wide` |
| `opacity`, `zIndex`, `flexGrow`, `flexShrink`, `order` | `NumberToken \| number \| Wide` (plain numbers stay legal) |
| `transitionDuration`, `transitionDelay`, `animationDuration`, `animationDelay` | `DurationToken \| Wide` |
| `transitionTimingFunction`, `animationTimingFunction` | `CubicBezierToken \| "ease" \| "linear" \| "ease-in" \| "ease-out" \| "ease-in-out" \| "step-start" \| "step-end" \| Wide` |
| `boxShadow`, `textShadow` | `ShadowToken \| "none" \| Wide` |
| every other CSS property | csstype's union for that property, with `dimension` tokens for lengths and `duration` tokens for times |

Tuple items take no CSS-wide keyword; `Wide` applies only to a single value.

## See

[css](https://pitlane.tools/package/theme/function/css.md)

## Extends

- `KeywordProps`
- `TokenMappedProps`

## Indexable

```ts
[key: string]:
  | string
  | number
  | ThemedCSSProps
  | readonly (string | number)[]
  | null
  | undefined
```

## Properties

### accentColor?

```ts
optional accentColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.accentColor
```

---

### animationDelay?

```ts
optional animationDelay?: DurationToken | Wide;
```

#### Inherited from

```ts
TokenMappedProps.animationDelay
```

---

### animationDuration?

```ts
optional animationDuration?: DurationToken | Wide;
```

#### Inherited from

```ts
TokenMappedProps.animationDuration
```

---

### animationTimingFunction?

```ts
optional animationTimingFunction?: Easing;
```

#### Inherited from

```ts
TokenMappedProps.animationTimingFunction
```

---

### backgroundColor?

```ts
optional backgroundColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.backgroundColor
```

---

### blockSize?

```ts
optional blockSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.blockSize
```

---

### borderBlockColor?

```ts
optional borderBlockColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderBlockColor
```

---

### borderBottomColor?

```ts
optional borderBottomColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderBottomColor
```

---

### borderBottomLeftRadius?

```ts
optional borderBottomLeftRadius?: Size;
```

#### Inherited from

```ts
TokenMappedProps.borderBottomLeftRadius
```

---

### borderBottomRightRadius?

```ts
optional borderBottomRightRadius?: Size;
```

#### Inherited from

```ts
TokenMappedProps.borderBottomRightRadius
```

---

### borderBottomWidth?

```ts
optional borderBottomWidth?: LineWidth;
```

#### Inherited from

```ts
TokenMappedProps.borderBottomWidth
```

---

### borderColor?

```ts
optional borderColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderColor
```

---

### borderInlineColor?

```ts
optional borderInlineColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderInlineColor
```

---

### borderLeftColor?

```ts
optional borderLeftColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderLeftColor
```

---

### borderLeftWidth?

```ts
optional borderLeftWidth?: LineWidth;
```

#### Inherited from

```ts
TokenMappedProps.borderLeftWidth
```

---

### borderRadius?

```ts
optional borderRadius?: Size | Repeat1to4<PadItem>;
```

#### Inherited from

```ts
TokenMappedProps.borderRadius
```

---

### borderRightColor?

```ts
optional borderRightColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderRightColor
```

---

### borderRightWidth?

```ts
optional borderRightWidth?: LineWidth;
```

#### Inherited from

```ts
TokenMappedProps.borderRightWidth
```

---

### borderTopColor?

```ts
optional borderTopColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.borderTopColor
```

---

### borderTopLeftRadius?

```ts
optional borderTopLeftRadius?: Size;
```

#### Inherited from

```ts
TokenMappedProps.borderTopLeftRadius
```

---

### borderTopRightRadius?

```ts
optional borderTopRightRadius?: Size;
```

#### Inherited from

```ts
TokenMappedProps.borderTopRightRadius
```

---

### borderTopWidth?

```ts
optional borderTopWidth?: LineWidth;
```

#### Inherited from

```ts
TokenMappedProps.borderTopWidth
```

---

### bottom?

```ts
optional bottom?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.bottom
```

---

### boxShadow?

```ts
optional boxShadow?: ShadowLike;
```

#### Inherited from

```ts
TokenMappedProps.boxShadow
```

---

### caretColor?

```ts
optional caretColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.caretColor
```

---

### color?

```ts
optional color?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.color
```

---

### columnGap?

```ts
optional columnGap?: Size;
```

#### Inherited from

```ts
TokenMappedProps.columnGap
```

---

### columnRuleColor?

```ts
optional columnRuleColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.columnRuleColor
```

---

### fill?

```ts
optional fill?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.fill
```

---

### flexBasis?

```ts
optional flexBasis?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.flexBasis
```

---

### flexGrow?

```ts
optional flexGrow?: Numeric;
```

#### Inherited from

```ts
TokenMappedProps.flexGrow
```

---

### flexShrink?

```ts
optional flexShrink?: Numeric;
```

#### Inherited from

```ts
TokenMappedProps.flexShrink
```

---

### fontFamily?

```ts
optional fontFamily?: Wide | FontFamilyToken;
```

#### Inherited from

```ts
TokenMappedProps.fontFamily
```

---

### fontSize?

```ts
optional fontSize?: Size;
```

#### Inherited from

```ts
TokenMappedProps.fontSize
```

---

### fontWeight?

```ts
optional fontWeight?:
  | "normal"
  | Wide
  | FontWeightToken
  | "bold"
  | "lighter"
  | "bolder";
```

#### Inherited from

```ts
TokenMappedProps.fontWeight
```

---

### gap?

```ts
optional gap?: Size | readonly [PadItem, PadItem];
```

#### Inherited from

```ts
TokenMappedProps.gap
```

---

### height?

```ts
optional height?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.height
```

---

### inlineSize?

```ts
optional inlineSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.inlineSize
```

---

### inset?

```ts
optional inset?: SizeAuto | Repeat1to4<MarginItem>;
```

#### Inherited from

```ts
TokenMappedProps.inset
```

---

### insetBlock?

```ts
optional insetBlock?: SizeAuto | readonly [MarginItem, MarginItem];
```

#### Inherited from

```ts
TokenMappedProps.insetBlock
```

---

### insetBlockEnd?

```ts
optional insetBlockEnd?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.insetBlockEnd
```

---

### insetBlockStart?

```ts
optional insetBlockStart?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.insetBlockStart
```

---

### insetInline?

```ts
optional insetInline?: SizeAuto | readonly [MarginItem, MarginItem];
```

#### Inherited from

```ts
TokenMappedProps.insetInline
```

---

### insetInlineEnd?

```ts
optional insetInlineEnd?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.insetInlineEnd
```

---

### insetInlineStart?

```ts
optional insetInlineStart?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.insetInlineStart
```

---

### left?

```ts
optional left?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.left
```

---

### letterSpacing?

```ts
optional letterSpacing?: SpacingText;
```

#### Inherited from

```ts
TokenMappedProps.letterSpacing
```

---

### lineHeight?

```ts
optional lineHeight?:
  | DimensionToken
  | "normal"
  | Wide
  | NumberToken;
```

#### Inherited from

```ts
TokenMappedProps.lineHeight
```

---

### margin?

```ts
optional margin?: SizeAuto | Repeat1to4<MarginItem>;
```

#### Inherited from

```ts
TokenMappedProps.margin
```

---

### marginBlock?

```ts
optional marginBlock?: SizeAuto | readonly [MarginItem, MarginItem];
```

#### Inherited from

```ts
TokenMappedProps.marginBlock
```

---

### marginBlockEnd?

```ts
optional marginBlockEnd?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginBlockEnd
```

---

### marginBlockStart?

```ts
optional marginBlockStart?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginBlockStart
```

---

### marginBottom?

```ts
optional marginBottom?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginBottom
```

---

### marginInline?

```ts
optional marginInline?: SizeAuto | readonly [MarginItem, MarginItem];
```

#### Inherited from

```ts
TokenMappedProps.marginInline
```

---

### marginInlineEnd?

```ts
optional marginInlineEnd?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginInlineEnd
```

---

### marginInlineStart?

```ts
optional marginInlineStart?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginInlineStart
```

---

### marginLeft?

```ts
optional marginLeft?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginLeft
```

---

### marginRight?

```ts
optional marginRight?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginRight
```

---

### marginTop?

```ts
optional marginTop?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.marginTop
```

---

### maxBlockSize?

```ts
optional maxBlockSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.maxBlockSize
```

---

### maxHeight?

```ts
optional maxHeight?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.maxHeight
```

---

### maxInlineSize?

```ts
optional maxInlineSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.maxInlineSize
```

---

### maxWidth?

```ts
optional maxWidth?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.maxWidth
```

---

### minBlockSize?

```ts
optional minBlockSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.minBlockSize
```

---

### minHeight?

```ts
optional minHeight?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.minHeight
```

---

### minInlineSize?

```ts
optional minInlineSize?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.minInlineSize
```

---

### minWidth?

```ts
optional minWidth?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.minWidth
```

---

### opacity?

```ts
optional opacity?: Numeric;
```

#### Inherited from

```ts
TokenMappedProps.opacity
```

---

### order?

```ts
optional order?: Numeric;
```

#### Inherited from

```ts
TokenMappedProps.order
```

---

### outlineColor?

```ts
optional outlineColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.outlineColor
```

---

### outlineOffset?

```ts
optional outlineOffset?: Size;
```

#### Inherited from

```ts
TokenMappedProps.outlineOffset
```

---

### outlineWidth?

```ts
optional outlineWidth?: LineWidth;
```

#### Inherited from

```ts
TokenMappedProps.outlineWidth
```

---

### padding?

```ts
optional padding?: Size | Repeat1to4<PadItem>;
```

#### Inherited from

```ts
TokenMappedProps.padding
```

---

### paddingBlock?

```ts
optional paddingBlock?: Size | readonly [PadItem, PadItem];
```

#### Inherited from

```ts
TokenMappedProps.paddingBlock
```

---

### paddingBlockEnd?

```ts
optional paddingBlockEnd?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingBlockEnd
```

---

### paddingBlockStart?

```ts
optional paddingBlockStart?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingBlockStart
```

---

### paddingBottom?

```ts
optional paddingBottom?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingBottom
```

---

### paddingInline?

```ts
optional paddingInline?: Size | readonly [PadItem, PadItem];
```

#### Inherited from

```ts
TokenMappedProps.paddingInline
```

---

### paddingInlineEnd?

```ts
optional paddingInlineEnd?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingInlineEnd
```

---

### paddingInlineStart?

```ts
optional paddingInlineStart?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingInlineStart
```

---

### paddingLeft?

```ts
optional paddingLeft?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingLeft
```

---

### paddingRight?

```ts
optional paddingRight?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingRight
```

---

### paddingTop?

```ts
optional paddingTop?: Size;
```

#### Inherited from

```ts
TokenMappedProps.paddingTop
```

---

### right?

```ts
optional right?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.right
```

---

### rowGap?

```ts
optional rowGap?: Size;
```

#### Inherited from

```ts
TokenMappedProps.rowGap
```

---

### stroke?

```ts
optional stroke?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.stroke
```

---

### textDecorationColor?

```ts
optional textDecorationColor?: ColorLike;
```

#### Inherited from

```ts
TokenMappedProps.textDecorationColor
```

---

### textIndent?

```ts
optional textIndent?: Size;
```

#### Inherited from

```ts
TokenMappedProps.textIndent
```

---

### textShadow?

```ts
optional textShadow?: ShadowLike;
```

#### Inherited from

```ts
TokenMappedProps.textShadow
```

---

### top?

```ts
optional top?: SizeAuto;
```

#### Inherited from

```ts
TokenMappedProps.top
```

---

### transitionDelay?

```ts
optional transitionDelay?: DurationToken | Wide;
```

#### Inherited from

```ts
TokenMappedProps.transitionDelay
```

---

### transitionDuration?

```ts
optional transitionDuration?: DurationToken | Wide;
```

#### Inherited from

```ts
TokenMappedProps.transitionDuration
```

---

### transitionTimingFunction?

```ts
optional transitionTimingFunction?: Easing;
```

#### Inherited from

```ts
TokenMappedProps.transitionTimingFunction
```

---

### width?

```ts
optional width?: SizeIntrinsic;
```

#### Inherited from

```ts
TokenMappedProps.width
```

---

### wordSpacing?

```ts
optional wordSpacing?: SpacingText;
```

#### Inherited from

```ts
TokenMappedProps.wordSpacing
```

---

### zIndex?

```ts
optional zIndex?: Numeric;
```

#### Inherited from

```ts
TokenMappedProps.zIndex
```

761 more properties are inherited from `KeywordProps` and not listed individually.

# ThemeInit

Source: https://pitlane.tools/package/theme/interface/ThemeInit.md

> The argument [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: a schema tree, the token tree it describes, and any modes.

```ts
import type { ThemeInit } from "@pitlane/theme";
```

The argument [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: a schema tree, the token tree it describes, and any modes.

The members are typed as bare objects on purpose. A `const` type parameter constrained to an index-signature type widens the literal it was inferred from, which would erase every brand; the shapes are enforced by the schema factories being typed values, by an undeclared leaf resolving to `unknown`, and by validation at module load.

## Properties

### modes?

```ts
optional modes?: object;
```

---

### schema

```ts
schema: object;
```

---

### tokens

```ts
tokens: object;
```

# ThemeMode

Source: https://pitlane.tools/package/theme/interface/ThemeMode.md

> A theme's mode: a condition plus the values it overrides.

```ts
import type { ThemeMode } from "@pitlane/theme";
```

A theme's mode: a condition plus the values it overrides.

## Type Parameters

### T

`T`

## Properties

### media?

```ts
optional media?: string;
```

The media query this mode applies under. Defaults to `(prefers-color-scheme: <name>)` for the names `light` and `dark`, and is required for any other name.

---

### selector?

```ts
optional selector?: string;
```

A selector this mode also applies under, for a user-selectable toggle. An attribute selector outranks the media block on specificity, so an explicit choice beats the OS preference.

---

### tokens

```ts
tokens: DeepPartialTokens<T>;
```

The values this mode overrides. Structure only, never types.

# ThemePatch

Source: https://pitlane.tools/package/theme/interface/ThemePatch.md

> The argument `extend` accepts. `schema` is optional, because a patch that only adds tokens to an existing namespace needs no new entry.

```ts
import type { ThemePatch } from "@pitlane/theme";
```

The argument `extend` accepts. `schema` is optional, because a patch that only adds tokens to an existing namespace needs no new entry.

## Properties

### modes?

```ts
optional modes?: object;
```

---

### schema?

```ts
optional schema?: object;
```

---

### tokens

```ts
tokens: object;
```

# ThemeResult

Source: https://pitlane.tools/package/theme/interface/ThemeResult.md

> The object [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns: the typed token accessor, the `raw` resolver, the `<Theme />` component, and the two derivation methods.

```ts
import type { ThemeResult } from "@pitlane/theme";
```

The object [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) returns: the typed token accessor, the `raw` resolver, the `<Theme />` component, and the two derivation methods.

## Type Parameters

### T

`T`

## Properties

### Theme

```ts
readonly Theme: ThemeComponent<T>;
```

The component that installs the custom properties.

---

### token

```ts
readonly token: TokenTree<T>;
```

A typed mirror of the token tree whose leaves are branded `var()` reference strings. A `s.scale()` leaf is callable.

## Methods

### extend()

```ts
extend<schema, tokens>(patch): ThemeResult<Merged<T, {
  schema: schema;
  tokens: tokens;
}>>;
```

Deep-merges a patch onto this theme and returns a new one. A leaf replaces wholesale; every other node recurses.

The callback form receives this theme's accessor, so a patch can reference what it extends.

#### Type Parameters

##### schema

`schema` _extends_ `object`

##### tokens

`tokens` _extends_ `object`

#### Parameters

##### patch

| `ExtendPatch`\<`T`, `schema`, `tokens`> | ((`base`: [`TokenTree`](https://pitlane.tools/package/theme/type/TokenTree.md)\<`T`>) => `ExtendPatch`\<`T`, `schema`, `tokens`>)

The tokens and schema to merge, or a callback returning them: a [ThemePatch](https://pitlane.tools/package/theme/interface/ThemePatch.md) whose `schema` and `tokens` types are kept exactly. `schema` is optional when the patch only adds tokens to namespaces the theme already types. `modes` may override any token of the merged tree, including tokens the patch itself does not declare.

#### Returns

`ThemeResult`\<`Merged`\<`T`, { `schema`: `schema`; `tokens`: `tokens`; }>>

A new theme

#### Throws

ThemeError when the patch holds no `tokens` group

---

### raw()

```ts
raw(ref): string;
```

Resolves a token reference to its concrete base value, following references to the end.

#### Parameters

##### ref

| [`AnyToken`](https://pitlane.tools/package/theme/type/AnyToken.md) | [`UntypedToken`](https://pitlane.tools/package/theme/type/UntypedToken.md)

A token reference minted by this theme

#### Returns

`string`

The serialized base value

#### Throws

ThemeError when the reference was not minted here

---

### select()

```ts
select<P>(projection): ThemeResult<P>;
```

Replaces this theme with a projection of it. The callback receives this theme's accessor; every value in the projection is a reference into it, and the new path decides the new custom property name, so a projection may also reshape and rename.

#### Type Parameters

##### P

`P` _extends_ [`ThemeInit`](https://pitlane.tools/package/theme/interface/ThemeInit.md)

#### Parameters

##### projection

(`base`: [`TokenTree`](https://pitlane.tools/package/theme/type/TokenTree.md)\<`T`>) => `P`

A callback returning the schema and tokens to keep

#### Returns

`ThemeResult`\<`P`>

A new theme

#### Throws

ThemeError when the projection holds no `tokens` group

# Tokens

Source: https://pitlane.tools/package/theme/interface/Tokens.md

> The token tree [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: nested records whose leaves are [TokenValue](https://pitlane.tools/package/theme/type/TokenValue.md)s. No reserved keys, so it is plain JSON and a designer can diff it.

```ts
import type { Tokens } from "@pitlane/theme";
```

The token tree [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts: nested records whose leaves are [TokenValue](https://pitlane.tools/package/theme/type/TokenValue.md)s. No reserved keys, so it is plain JSON and a designer can diff it.

## Indexable

```ts
[key: string]: TokenValue | Tokens
```

# TVAConfig

Source: https://pitlane.tools/package/theme/interface/TVAConfig.md

> Configuration for [tva](https://pitlane.tools/package/theme/function/tva.md). Every style slot is [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md), carrying the same brand enforcement as [css](https://pitlane.tools/package/theme/function/css.md).

```ts
import type { TVAConfig } from "@pitlane/theme";
```

Configuration for [tva](https://pitlane.tools/package/theme/function/tva.md). Every style slot is [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md), carrying the same brand enforcement as [css](https://pitlane.tools/package/theme/function/css.md).

## Type Parameters

### V

`V` _extends_ `VariantShape`

## Properties

### base?

```ts
optional base?: ThemedCSSProps;
```

Styles applied to every invocation, before any variant.

---

### compoundVariants?

```ts
optional compoundVariants?: readonly Selection<V> & object[];
```

Extra styles applied when every listed variant condition matches, merged after the individual variants in array order.

---

### defaultVariants?

```ts
optional defaultVariants?: Selection<V>;
```

Options used for axes the caller leaves unset. Passing an axis `undefined` explicitly still falls back to its default.

---

### variants?

```ts
optional variants?: V;
```

The variant axes. Each axis maps option names to styles; name an axis's options `true` and `false` to accept a boolean.

# TVAFn

Source: https://pitlane.tools/package/theme/interface/TVAFn.md

> A variant component built by [tva](https://pitlane.tools/package/theme/function/tva.md). Call it with a variant selection to get a `mix`-ready descriptor; call `resolve` for the merged [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md) without building a descriptor.

```ts
import type { TVAFn } from "@pitlane/theme";
```

A variant component built by [tva](https://pitlane.tools/package/theme/function/tva.md). Call it with a variant selection to get a `mix`-ready descriptor; call `resolve` for the merged [ThemedCSSProps](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md) without building a descriptor.

## Type Parameters

### V

`V` _extends_ `VariantShape`

```ts
TVAFn<node>(props?): ThemedCSSMixin<node>;
```

Resolves the selection and returns a `mix`-ready descriptor. Node-generic like [css](https://pitlane.tools/package/theme/function/css.md): `MixinDescriptor` is invariant in its node, so the element type binds per `mix` callsite.

## Type Parameters

### node

`node` _extends_ `Element` = `Element`

## Parameters

### props?

`Selection`\<`V`>

## Returns

[`ThemedCSSMixin`](https://pitlane.tools/package/theme/type/ThemedCSSMixin.md)\<`node`>

## Methods

### resolve()

```ts
resolve(props?): ThemedCSSProps;
```

Returns the merged style object for a selection without producing a descriptor. [combine](https://pitlane.tools/package/theme/function/combine.md) is built on it.

#### Parameters

##### props?

`Selection`\<`V`>

#### Returns

[`ThemedCSSProps`](https://pitlane.tools/package/theme/interface/ThemedCSSProps.md)

# AnyToken

Source: https://pitlane.tools/package/theme/type/AnyToken.md

> The union of all twelve token brands. Brands are compile-time tags naming each token's type; they let [css](https://pitlane.tools/package/theme/function/css.md) reject a dimension where a color belongs. They exist only in the type system — every ref is a plain string at runtime, so brands cost nothing — and they are theme-independent, so tokens minted by two different [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) calls mix freely in one [css](https://pitlane.tools/package/theme/function/css.md) call.

```ts
import type { AnyToken } from "@pitlane/theme";
```

```ts
type AnyToken = BrandByType[TokenType];
```

The union of all twelve token brands. Brands are compile-time tags naming each token's type; they let [css](https://pitlane.tools/package/theme/function/css.md) reject a dimension where a color belongs. They exist only in the type system — every ref is a plain string at runtime, so brands cost nothing — and they are theme-independent, so tokens minted by two different [createTheme](https://pitlane.tools/package/theme/function/createTheme.md) calls mix freely in one [css](https://pitlane.tools/package/theme/function/css.md) call.

# BorderToken

Source: https://pitlane.tools/package/theme/type/BorderToken.md

> Compile-time brand for a `border` token.

```ts
import type { BorderToken } from "@pitlane/theme";
```

```ts
type BorderToken = string & object;
```

Compile-time brand for a `border` token.

## Type Declaration

### \[BORDER\]

```ts
readonly [BORDER]: true;
```

# ClassValue

Source: https://pitlane.tools/package/theme/type/ClassValue.md

> A value [cx](https://pitlane.tools/package/theme/function/cx.md) accepts: a string, a number, a nested array of the same, or a record whose truthy keys are emitted. `null`, `undefined`, and `false` are dropped. Compatible with clsx.

```ts
import type { ClassValue } from "@pitlane/theme";
```

```ts
type ClassValue =
  | string
  | number
  | null
  | undefined
  | false
  | readonly ClassValue[]
| Record<string, boolean | null | undefined>;
```

A value [cx](https://pitlane.tools/package/theme/function/cx.md) accepts: a string, a number, a nested array of the same, or a record whose truthy keys are emitted. `null`, `undefined`, and `false` are dropped. Compatible with clsx.

# ColorToken

Source: https://pitlane.tools/package/theme/type/ColorToken.md

> Compile-time brand for a `color` token.

```ts
import type { ColorToken } from "@pitlane/theme";
```

```ts
type ColorToken = string & object;
```

Compile-time brand for a `color` token.

## Type Declaration

### \[COLOR\]

```ts
readonly [COLOR]: true;
```

# CubicBezierToken

Source: https://pitlane.tools/package/theme/type/CubicBezierToken.md

> Compile-time brand for a `cubicBezier` token.

```ts
import type { CubicBezierToken } from "@pitlane/theme";
```

```ts
type CubicBezierToken = string & object;
```

Compile-time brand for a `cubicBezier` token.

## Type Declaration

### \[CUBIC\_BEZIER\]

```ts
readonly [CUBIC_BEZIER]: true;
```

# DeepPartialTokens

Source: https://pitlane.tools/package/theme/type/DeepPartialTokens.md

> The mode-override shape for a token tree: every group optional, every leaf a value. A mode overrides values, never structure or types.

```ts
import type { DeepPartialTokens } from "@pitlane/theme";
```

```ts
type DeepPartialTokens<T> = 0 extends 1 & T ? unknown : { [K in keyof T]?: T[K] extends string | number | readonly (string | number)[] ? TokenValue : DeepPartialTokens<T[K]> };
```

The mode-override shape for a token tree: every group optional, every leaf a value. A mode overrides values, never structure or types.

## Type Parameters

### T

`T`

# DimensionToken

Source: https://pitlane.tools/package/theme/type/DimensionToken.md

> Compile-time brand for a `dimension` token.

```ts
import type { DimensionToken } from "@pitlane/theme";
```

```ts
type DimensionToken = string & object;
```

Compile-time brand for a `dimension` token.

## Type Declaration

### \[DIMENSION\]

```ts
readonly [DIMENSION]: true;
```

# DurationToken

Source: https://pitlane.tools/package/theme/type/DurationToken.md

> Compile-time brand for a `duration` token.

```ts
import type { DurationToken } from "@pitlane/theme";
```

```ts
type DurationToken = string & object;
```

Compile-time brand for a `duration` token.

## Type Declaration

### \[DURATION\]

```ts
readonly [DURATION]: true;
```

# FontFamilyToken

Source: https://pitlane.tools/package/theme/type/FontFamilyToken.md

> Compile-time brand for a `fontFamily` token.

```ts
import type { FontFamilyToken } from "@pitlane/theme";
```

```ts
type FontFamilyToken = string & object;
```

Compile-time brand for a `fontFamily` token.

## Type Declaration

### \[FONT\_FAMILY\]

```ts
readonly [FONT_FAMILY]: true;
```

# FontWeightToken

Source: https://pitlane.tools/package/theme/type/FontWeightToken.md

> Compile-time brand for a `fontWeight` token.

```ts
import type { FontWeightToken } from "@pitlane/theme";
```

```ts
type FontWeightToken = string & object;
```

Compile-time brand for a `fontWeight` token.

## Type Declaration

### \[FONT\_WEIGHT\]

```ts
readonly [FONT_WEIGHT]: true;
```

# GradientToken

Source: https://pitlane.tools/package/theme/type/GradientToken.md

> Compile-time brand for a `gradient` token.

```ts
import type { GradientToken } from "@pitlane/theme";
```

```ts
type GradientToken = string & object;
```

Compile-time brand for a `gradient` token.

## Type Declaration

### \[GRADIENT\]

```ts
readonly [GRADIENT]: true;
```

# NumberToken

Source: https://pitlane.tools/package/theme/type/NumberToken.md

> Compile-time brand for a `number` token.

```ts
import type { NumberToken } from "@pitlane/theme";
```

```ts
type NumberToken = string & object;
```

Compile-time brand for a `number` token.

## Type Declaration

### \[NUMBER\]

```ts
readonly [NUMBER]: true;
```

# ShadowToken

Source: https://pitlane.tools/package/theme/type/ShadowToken.md

> Compile-time brand for a `shadow` token.

```ts
import type { ShadowToken } from "@pitlane/theme";
```

```ts
type ShadowToken = string & object;
```

Compile-time brand for a `shadow` token.

## Type Declaration

### \[SHADOW\]

```ts
readonly [SHADOW]: true;
```

# StrokeStyleToken

Source: https://pitlane.tools/package/theme/type/StrokeStyleToken.md

> Compile-time brand for a `strokeStyle` token.

```ts
import type { StrokeStyleToken } from "@pitlane/theme";
```

```ts
type StrokeStyleToken = string & object;
```

Compile-time brand for a `strokeStyle` token.

## Type Declaration

### \[STROKE\_STYLE\]

```ts
readonly [STROKE_STYLE]: true;
```

# ThemedCSSMixin

Source: https://pitlane.tools/package/theme/type/ThemedCSSMixin.md

> The descriptor [css](https://pitlane.tools/package/theme/function/css.md) produces. `MixinDescriptor` is invariant in its node type, so — exactly like `remix/component`'s own `css` factory — the node binds per callsite through the generic parameter.

```ts
import type { ThemedCSSMixin } from "@pitlane/theme";
```

```ts
type ThemedCSSMixin<node> = MixinDescriptor<node, [RemixCSSProps], ElementProps>;
```

The descriptor [css](https://pitlane.tools/package/theme/function/css.md) produces. `MixinDescriptor` is invariant in its node type, so — exactly like `remix/component`'s own `css` factory — the node binds per callsite through the generic parameter.

## Type Parameters

### node

`node` _extends_ `Element` = `Element`

## See

[css](https://pitlane.tools/package/theme/function/css.md)

# ThemeProps

Source: https://pitlane.tools/package/theme/type/ThemeProps.md

> Props for the [ThemeComponent](https://pitlane.tools/package/theme/interface/ThemeComponent.md). `nonce` sets the `nonce` attribute on the emitted `<style>` element for Content Security Policy setups.

```ts
import type { ThemeProps } from "@pitlane/theme";
```

```ts
type ThemeProps = object;
```

Props for the [ThemeComponent](https://pitlane.tools/package/theme/interface/ThemeComponent.md). `nonce` sets the `nonce` attribute on the emitted `<style>` element for Content Security Policy setups.

## Properties

### nonce?

```ts
optional nonce?: string;
```

# TokenTree

Source: https://pitlane.tools/package/theme/type/TokenTree.md

> The accessor shape for an init `T`: the same nesting as its token tree, with every leaf replaced by the branded `var(--…)` reference its schema declares. Numeric keys index with brackets (`t.color.gray[900]`).

```ts
import type { TokenTree } from "@pitlane/theme";
```

```ts
type TokenTree<T> = 0 extends 1 & T ? unknown : T extends object ? TreeOf<Tok, Sch, never> : unknown;
```

The accessor shape for an init `T`: the same nesting as its token tree, with every leaf replaced by the branded `var(--…)` reference its schema declares. Numeric keys index with brackets (`t.color.gray[900]`).

A leaf whose schema entry is missing resolves to `unknown`, which is unusable in `css()`. The compiler also throws for it at module load.

## Type Parameters

### T

`T`

## See

[ThemeResult](https://pitlane.tools/package/theme/interface/ThemeResult.md)

# TokenType

Source: https://pitlane.tools/package/theme/type/TokenType.md

> The twelve DTCG token `$type` values.

```ts
import type { TokenType } from "@pitlane/theme";
```

```ts
type TokenType = typeof TOKEN_TYPES[number];
```

The twelve DTCG token `$type` values.

## See

[AnyToken](https://pitlane.tools/package/theme/type/AnyToken.md)

# TokenValue

Source: https://pitlane.tools/package/theme/type/TokenValue.md

> A token value: the CSS it becomes. A string, a number, or an array of either. Anything else is a group.

```ts
import type { TokenValue } from "@pitlane/theme";
```

```ts
type TokenValue = number | readonly (number | string)[] | string;
```

A token value: the CSS it becomes. A string, a number, or an array of either. Anything else is a group.

## See

[Tokens](https://pitlane.tools/package/theme/interface/Tokens.md)

# TransitionToken

Source: https://pitlane.tools/package/theme/type/TransitionToken.md

> Compile-time brand for a `transition` token.

```ts
import type { TransitionToken } from "@pitlane/theme";
```

```ts
type TransitionToken = string & object;
```

Compile-time brand for a `transition` token.

## Type Declaration

### \[TRANSITION\]

```ts
readonly [TRANSITION]: true;
```

# TVAProps

Source: https://pitlane.tools/package/theme/type/TVAProps.md

> Extracts a [tva](https://pitlane.tools/package/theme/function/tva.md) component's variant props, like cva's `VariantProps`. All props are optional; wrap the component to require one.

```ts
import type { TVAProps } from "@pitlane/theme";
```

```ts
type TVAProps<F> = F extends TVAFn<infer V> ? Selection<V> : never;
```

Extracts a [tva](https://pitlane.tools/package/theme/function/tva.md) component's variant props, like cva's `VariantProps`. All props are optional; wrap the component to require one.

## Type Parameters

### F

`F`

## Example

```ts
export type ButtonProps = TVAProps<typeof button>;
// { intent?: "primary" | "secondary"; size?: "sm" | "md" }
```

# UntypedToken

Source: https://pitlane.tools/package/theme/type/UntypedToken.md

> Compile-time brand for a token declared with `s.any()`. It carries no CSS type, so the open-grammar properties (`animation`, `aspectRatio`, `background`) accept it and the token-mapped longhands reject it.

```ts
import type { UntypedToken } from "@pitlane/theme";
```

```ts
type UntypedToken = string & object;
```

Compile-time brand for a token declared with `s.any()`. It carries no CSS type, so the open-grammar properties (`animation`, `aspectRatio`, `background`) accept it and the token-mapped longhands reject it.

## Type Declaration

### \[UNTYPED\]

```ts
readonly [UNTYPED]: true;
```

# @pitlane/theme/default

Source: https://pitlane.tools/package/theme/default.md

> Tailwind CSS v4's default primitive theme as a ready-made [DefaultTheme](https://pitlane.tools/package/theme/default/variable/DefaultTheme.md) component: colors, spacing, radii, fonts, shadows, easing, and the rest of Tailwind's primitives. Select the primitives an application uses, and give them semantic names, in a theme built from it.

Tailwind CSS v4's default primitive theme as a ready-made [DefaultTheme](https://pitlane.tools/package/theme/default/variable/DefaultTheme.md) component: colors, spacing, radii, fonts, shadows, easing, and the rest of Tailwind's primitives. Select the primitives an application uses, and give them semantic names, in a theme built from it.

## See

[Theme guide](https://pitlane.tools/guides/theme.md)

## Variables

- [DefaultTheme](https://pitlane.tools/package/theme/default/variable/DefaultTheme.md). Tailwind CSS v4.3.2's default primitive theme.

# DefaultTheme

Source: https://pitlane.tools/package/theme/default/variable/DefaultTheme.md

> Tailwind CSS v4.3.2's default primitive theme.

```ts
import { DefaultTheme } from "@pitlane/theme/default";
```

```ts
DefaultTheme: ThemeComponent<DefaultThemeInit>;
```

Tailwind CSS v4.3.2's default primitive theme.

Its top-level token groups are `font`, `color`, `spacing` (a `scale` token), `breakpoint`, `container`, `text`, `fontWeight`, `tracking`, `leading`, `radius`, `shadow`, `insetShadow`, `dropShadow`, `textShadow`, `ease`, `animate`, `blur`, `perspective`, `aspect`, `default`, and `maxWidth`, named as Tailwind names its theme variables.

Text-scale line heights are available at `t.text.lineHeight.*`. Their generated custom-property names differ from Tailwind's double-hyphen modifier spelling.

The animation tokens name Tailwind keyframes but do not emit them. An application that uses `t.animate.spin`, `t.animate.ping`, `t.animate.pulse`, or `t.animate.bounce` must define the matching `@keyframes` rule itself.

## Example

```ts
import { createTheme } from "@pitlane/theme";
import { DefaultTheme } from "@pitlane/theme/default";
import * as s from "@pitlane/theme/schema";

let theme = createTheme(DefaultTheme).select(base => ({
    schema: { color: s.color(), spacing: s.scale() },
    tokens: {
        color: { red: { 500: base.color.red[500] } },
        spacing: base.spacing.token,
    },
}));

theme.token.spacing(4);
```

# @pitlane/theme/dtcg

Source: https://pitlane.tools/package/theme/dtcg.md

> Conversion between themes and W3C Design Tokens Community Group (DTCG) 2025.10 documents. [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md) turns a DTCG document into the schema and token trees ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts; [toDTCG](https://pitlane.tools/package/theme/dtcg/function/toDTCG.md) exports a theme back to DTCG, keeping values DTCG cannot express in a Pitlane extension.

Conversion between themes and W3C Design Tokens Community Group (DTCG) 2025.10 documents. [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md) turns a DTCG document into the schema and token trees ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts; [toDTCG](https://pitlane.tools/package/theme/dtcg/function/toDTCG.md) exports a theme back to DTCG, keeping values DTCG cannot express in a Pitlane extension.

## See

[Theme guide](https://pitlane.tools/guides/theme.md)

## Interfaces

- [DTCGExport](https://pitlane.tools/package/theme/dtcg/interface/DTCGExport.md). DTCG documents exported from a theme.
- [DTCGThemeInit](https://pitlane.tools/package/theme/dtcg/interface/DTCGThemeInit.md). The runtime-shaped init [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md) derives from a DTCG document.
- [PitlaneDTCGExtension](https://pitlane.tools/package/theme/dtcg/interface/PitlaneDTCGExtension.md). Pitlane's extension payload for a value DTCG cannot represent.

## Type Aliases

- [DTCGDocument](https://pitlane.tools/package/theme/dtcg/type/DTCGDocument.md). A JSON-compatible W3C Design Tokens Community Group document.

## Functions

- [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md). Converts a W3C DTCG 2025.10 document into the schema tree and bare token tree ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts.
- [toDTCG](https://pitlane.tools/package/theme/dtcg/function/toDTCG.md). Exports a compiled theme, a published theme component, or the init behind either one to W3C DTCG 2025.10 documents.

# fromDTCG

Source: https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md

> Converts a W3C DTCG 2025.10 document into the schema tree and bare token tree ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts.

```ts
import { fromDTCG } from "@pitlane/theme/dtcg";
```

```ts
function fromDTCG(document): DTCGThemeInit;
```

Converts a W3C DTCG 2025.10 document into the schema tree and bare token tree ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) accepts.

A token resolves its type in DTCG order: its own `$type`, the resolved type of a whole-value `{reference}`, then the nearest ancestor group's `$type`. `$description`, `$deprecated`, and `$extensions` are intentionally discarded until schema factories gain a metadata options bag. Typography tokens are not supported because one typography value would need several custom properties.

Runtime JSON cannot preserve literal paths, so using this init with ["@pitlane/theme"!createTheme](https://pitlane.tools/package/theme/function/createTheme.md) produces an unbranded accessor. Generate TypeScript from the result for the typed path.

## Parameters

### document

[`DTCGDocument`](https://pitlane.tools/package/theme/dtcg/type/DTCGDocument.md)

A DTCG document using `$value`, `$type`, and dotted references

## Returns

[`DTCGThemeInit`](https://pitlane.tools/package/theme/dtcg/interface/DTCGThemeInit.md)

A runtime [ThemeInit](https://pitlane.tools/package/theme/interface/ThemeInit.md)-shaped schema and token tree

## Throws

ThemeError for malformed groups, unsupported typography, unknown types, unresolvable references, cycles, or malformed structured DTCG values

## Example

```ts
import { createTheme } from "@pitlane/theme";
import { fromDTCG } from "@pitlane/theme/dtcg";

let imported = fromDTCG({
    color: {
        $type: "color",
        white: { $value: "#fff" },
        page: { $value: "{color.white}" },
    },
});
let theme = createTheme(imported);
```

# toDTCG

Source: https://pitlane.tools/package/theme/dtcg/function/toDTCG.md

> Exports a compiled theme, a published theme component, or the init behind either one to W3C DTCG 2025.10 documents.

```ts
import { toDTCG } from "@pitlane/theme/dtcg";
```

```ts
function toDTCG<T>(theme): DTCGExport;
```

Exports a compiled theme, a published theme component, or the init behind either one to W3C DTCG 2025.10 documents.

An export places `$type` on the lowest group whose complete descendant set has one expressible type; standard tokens below that group omit the redundant `$type`. Mixed groups put `$type` on their standard token leaves instead. Exact `var(--token-name)` values are converted back to `{token.path}` using the collector's variable-name map.

DTCG cannot represent all CSS values this package accepts. Inexpressible values are preserved in `$extensions["tools.pitlane"]` as `{ type, value, reason }`, on an extension-only node with no `$value`; this keeps the standard document valid while preserving the original value for a caller that reports or handles the loss. `inexpressible` counts those nodes in the base document and every mode document.

DTCG descriptions, deprecation metadata, and unrelated extensions are not in the authoring format and cannot be recovered.

## Type Parameters

### T

`T`

## Parameters

### theme

| [`ThemeInit`](https://pitlane.tools/package/theme/interface/ThemeInit.md) | [`ThemeComponent`](https://pitlane.tools/package/theme/interface/ThemeComponent.md)\<`T`> | [`ThemeResult`](https://pitlane.tools/package/theme/interface/ThemeResult.md)\<`T`>

A [ThemeResult](https://pitlane.tools/package/theme/interface/ThemeResult.md), its [ThemeComponent](https://pitlane.tools/package/theme/interface/ThemeComponent.md), or its init

## Returns

[`DTCGExport`](https://pitlane.tools/package/theme/dtcg/interface/DTCGExport.md)

The base document, one partial document per mode, and the lossy-value count

## Throws

ThemeError when the supplied init has an invalid token/schema structure

## Example

```ts
import { createTheme } from "@pitlane/theme";
import { toDTCG } from "@pitlane/theme/dtcg";
import * as s from "@pitlane/theme/schema";

let theme = createTheme({
    schema: { color: s.color() },
    tokens: { color: { white: "#fff" } },
});
let { document, inexpressible } = toDTCG(theme);
```

# DTCGExport

Source: https://pitlane.tools/package/theme/dtcg/interface/DTCGExport.md

> DTCG documents exported from a theme.

```ts
import type { DTCGExport } from "@pitlane/theme/dtcg";
```

DTCG documents exported from a theme.

## Properties

### document

```ts
document: DTCGDocument;
```

The theme's base document.

---

### inexpressible

```ts
inexpressible: number;
```

The number of base and mode values preserved only in Pitlane extensions.

---

### modes

```ts
modes: Record<string, DTCGDocument>;
```

One partial document of token overrides for each theme mode.

# DTCGThemeInit

Source: https://pitlane.tools/package/theme/dtcg/interface/DTCGThemeInit.md

> The runtime-shaped init [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md) derives from a DTCG document.

```ts
import type { DTCGThemeInit } from "@pitlane/theme/dtcg";
```

The runtime-shaped init [fromDTCG](https://pitlane.tools/package/theme/dtcg/function/fromDTCG.md) derives from a DTCG document.

Its `schema` and `tokens` use the broad [ThemeInit](https://pitlane.tools/package/theme/interface/ThemeInit.md) member types: a JSON document cannot produce the literal information required to brand a token accessor. Generate a checked-in schema and token module from the document when a typed accessor is required.

## Properties

### schema

```ts
schema: object;
```

The derived runtime schema tree.

---

### tokens

```ts
tokens: object;
```

The bare token values described by [schema](https://pitlane.tools/package/theme/dtcg/interface/DTCGThemeInit.md#schema).

# PitlaneDTCGExtension

Source: https://pitlane.tools/package/theme/dtcg/interface/PitlaneDTCGExtension.md

> Pitlane's extension payload for a value DTCG cannot represent.

```ts
import type { PitlaneDTCGExtension } from "@pitlane/theme/dtcg";
```

Pitlane's extension payload for a value DTCG cannot represent.

The extension is stored at `$extensions["tools.pitlane"]`. The surrounding node deliberately has no `$value`, making it a valid DTCG group that a strict consumer can ignore rather than a token carrying an invalid surrogate value.

## Properties

### reason

```ts
reason: string;
```

Why the value has no standard DTCG representation.

---

### type

```ts
type: SchemaTag;
```

The source schema tag, including Pitlane-only `any` and `scale`.

---

### value

```ts
value: unknown;
```

The original authoring value, with exact accessor references reversed.

# DTCGDocument

Source: https://pitlane.tools/package/theme/dtcg/type/DTCGDocument.md

> A JSON-compatible W3C Design Tokens Community Group document.

```ts
import type { DTCGDocument } from "@pitlane/theme/dtcg";
```

```ts
type DTCGDocument = Record<string, unknown>;
```

A JSON-compatible W3C Design Tokens Community Group document.

The DTCG specification permits arbitrary extension keys, so this deliberately remains open rather than attempting to model every standardized and vendor extension.

# @pitlane/theme/schema

Source: https://pitlane.tools/package/theme/schema.md

> Token schemas: one factory per token type, plus `scale`, `any`, and `group`. Each factory returns a `remix/data-schema` schema tagged with the token type it declares, so the same value both validates a token and names the brand its accessor leaf carries.

Token schemas: one factory per token type, plus `scale`, `any`, and `group`. Each factory returns a `remix/data-schema` schema tagged with the token type it declares, so the same value both validates a token and names the brand its accessor leaf carries.

Designed for a namespace import, the way `remix/data-schema` ships its own `string()` and `object()`:

```ts
import * as s from "@pitlane/theme/schema";

let schema = { color: s.color(), spacing: s.scale() };
```

## See

[Theme guide: Choose schemas](https://pitlane.tools/guides/theme.md#choose-schemas)

## Interfaces

- [SchemaGroup](https://pitlane.tools/package/theme/schema/interface/SchemaGroup.md). A schema group: per-child schemas, optionally under a schema for the node itself. [group](https://pitlane.tools/package/theme/schema/function/group.md) builds one; a plain object literal is the children-only form.
- [TokenSchema](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md). A `remix/data-schema` schema that also names the token type it declares. Every factory in this module returns one.

## Type Aliases

- [SchemaNode](https://pitlane.tools/package/theme/schema/type/SchemaNode.md). A node in a schema tree.

## Variables

- [font](https://pitlane.tools/package/theme/schema/variable/font.md). The two font token types, grouped because they share a prefix.

## Functions

- [any](https://pitlane.tools/package/theme/schema/function/any.md). A token with no type. Its value is emitted verbatim and its accessor leaf brands as a plain `string`, which the open-grammar CSS properties accept and the token-mapped longhands still reject.
- [border](https://pitlane.tools/package/theme/schema/function/border.md). A `border` token. Accepts CSS border shorthand text.
- [color](https://pitlane.tools/package/theme/schema/function/color.md). A `color` token. Accepts any CSS color, including `light-dark()`, `color-mix()`, and `currentColor`, plus DTCG's structured form.
- [dimension](https://pitlane.tools/package/theme/schema/function/dimension.md). A `dimension` token. Accepts any CSS length, including `clamp()`, `calc()`, `%`, and `em`.
- [duration](https://pitlane.tools/package/theme/schema/function/duration.md). A `duration` token. Accepts `ms`, `s`, and `calc()`.
- [easing](https://pitlane.tools/package/theme/schema/function/easing.md). A `cubicBezier` token, named for the CSS property it feeds. Accepts a four-number tuple or `cubic-bezier(…)` text.
- [gradient](https://pitlane.tools/package/theme/schema/function/gradient.md). A `gradient` token. Accepts CSS gradient function text.
- [group](https://pitlane.tools/package/theme/schema/function/group.md). A node that is itself typed and also carries per-child overrides. `self` applies to that node and to every descendant without its own entry; each key in `children` overrides it from there down.
- [number](https://pitlane.tools/package/theme/schema/function/number.md). A `number` token. Accepts a finite number, which is what unitless CSS values such as `line-height` and `opacity` take.
- [scale](https://pitlane.tools/package/theme/schema/function/scale.md). A dimension token whose accessor leaf is a multiplier rather than a value. The token emits its own custom property; the accessor leaf is callable, and carries the base itself as `.token`.
- [shadow](https://pitlane.tools/package/theme/schema/function/shadow.md). A `shadow` token. Accepts CSS shadow text, `inset` included.
- [stroke](https://pitlane.tools/package/theme/schema/function/stroke.md). A `strokeStyle` token, named for the CSS value it holds. Accepts a line-style keyword.
- [transition](https://pitlane.tools/package/theme/schema/function/transition.md). A `transition` token. Accepts CSS transition shorthand text.

# any

Source: https://pitlane.tools/package/theme/schema/function/any.md

> A token with no type. Its value is emitted verbatim and its accessor leaf brands as a plain `string`, which the open-grammar CSS properties accept and the token-mapped longhands still reject.

```ts
import { any } from "@pitlane/theme/schema";
```

```ts
function any(): TokenSchema<"any">;
```

A token with no type. Its value is emitted verbatim and its accessor leaf brands as a plain `string`, which the open-grammar CSS properties accept and the token-mapped longhands still reject.

This exists for CSS values with no DTCG type, such as `spin 1s linear infinite` and `16 / 9`. An untyped token may not be the target of a typed token's reference, because there is no type to check against.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"any"`>

A schema declaring an untyped token

# border

Source: https://pitlane.tools/package/theme/schema/function/border.md

> A `border` token. Accepts CSS border shorthand text.

```ts
import { border } from "@pitlane/theme/schema";
```

```ts
function border(): TokenSchema<"border">;
```

A `border` token. Accepts CSS border shorthand text.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"border"`>

A schema declaring the `border` token type

# color

Source: https://pitlane.tools/package/theme/schema/function/color.md

> A `color` token. Accepts any CSS color, including `light-dark()`, `color-mix()`, and `currentColor`, plus DTCG's structured form.

```ts
import { color } from "@pitlane/theme/schema";
```

```ts
function color(): TokenSchema<"color">;
```

A `color` token. Accepts any CSS color, including `light-dark()`, `color-mix()`, and `currentColor`, plus DTCG's structured form.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"color"`>

A schema declaring the `color` token type

## Example

```ts
let schema = { color: s.color() };
let tokens = { color: { white: "#fff", page: lightDark("#fff", "#111") } };
```

# dimension

Source: https://pitlane.tools/package/theme/schema/function/dimension.md

> A `dimension` token. Accepts any CSS length, including `clamp()`, `calc()`, `%`, and `em`.

```ts
import { dimension } from "@pitlane/theme/schema";
```

```ts
function dimension(): TokenSchema<"dimension">;
```

A `dimension` token. Accepts any CSS length, including `clamp()`, `calc()`, `%`, and `em`.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"dimension"`>

A schema declaring the `dimension` token type

# duration

Source: https://pitlane.tools/package/theme/schema/function/duration.md

> A `duration` token. Accepts `ms`, `s`, and `calc()`.

```ts
import { duration } from "@pitlane/theme/schema";
```

```ts
function duration(): TokenSchema<"duration">;
```

A `duration` token. Accepts `ms`, `s`, and `calc()`.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"duration"`>

A schema declaring the `duration` token type

# easing

Source: https://pitlane.tools/package/theme/schema/function/easing.md

> A `cubicBezier` token, named for the CSS property it feeds. Accepts a four-number tuple or `cubic-bezier(…)` text.

```ts
import { easing } from "@pitlane/theme/schema";
```

```ts
function easing(): TokenSchema<"cubicBezier">;
```

A `cubicBezier` token, named for the CSS property it feeds. Accepts a four-number tuple or `cubic-bezier(…)` text.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"cubicBezier"`>

A schema declaring the `cubicBezier` token type

# gradient

Source: https://pitlane.tools/package/theme/schema/function/gradient.md

> A `gradient` token. Accepts CSS gradient function text.

```ts
import { gradient } from "@pitlane/theme/schema";
```

```ts
function gradient(): TokenSchema<"gradient">;
```

A `gradient` token. Accepts CSS gradient function text.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"gradient"`>

A schema declaring the `gradient` token type

# group

Source: https://pitlane.tools/package/theme/schema/function/group.md

> A node that is itself typed and also carries per-child overrides. `self` applies to that node and to every descendant without its own entry; each key in `children` overrides it from there down.

```ts
import { group } from "@pitlane/theme/schema";
```

```ts
function group<self, children>(self, children): children & object;
```

A node that is itself typed and also carries per-child overrides. `self` applies to that node and to every descendant without its own entry; each key in `children` overrides it from there down.

The self schema rides on a symbol key, so no token name is reserved: a token named `default` can carry its own type.

## Type Parameters

### self

`self` _extends_ [`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`SchemaTag`>

The schema for this node and its unlabelled descendants

### children

`children` _extends_ `Record`\<`string`, [`SchemaNode`](https://pitlane.tools/package/theme/schema/type/SchemaNode.md)>

Per-child schema overrides

## Parameters

### self

`self`

### children

`children`

## Returns

`children` \& `object`

A schema group

## Example

```ts
let schema = {
    control: s.group(s.dimension(), { color: s.color(), opacity: s.number() }),
};
// control.height.sm is a dimension; control.color.border is a color.
```

# number

Source: https://pitlane.tools/package/theme/schema/function/number.md

> A `number` token. Accepts a finite number, which is what unitless CSS values such as `line-height` and `opacity` take.

```ts
import { number } from "@pitlane/theme/schema";
```

```ts
function number(): TokenSchema<"number">;
```

A `number` token. Accepts a finite number, which is what unitless CSS values such as `line-height` and `opacity` take.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"number"`>

A schema declaring the `number` token type

# scale

Source: https://pitlane.tools/package/theme/schema/function/scale.md

> A dimension token whose accessor leaf is a multiplier rather than a value. The token emits its own custom property; the accessor leaf is callable, and carries the base itself as `.token`.

```ts
import { scale } from "@pitlane/theme/schema";
```

```ts
function scale(): TokenSchema<"scale">;
```

A dimension token whose accessor leaf is a multiplier rather than a value. The token emits its own custom property; the accessor leaf is callable, and carries the base itself as `.token`.

This is Tailwind's `--spacing`: one base that the whole scale multiplies, with no named steps.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"scale"`>

A schema declaring a scale token

## Example

```ts
let theme = createTheme({
    schema: { spacing: s.scale() },
    tokens: { spacing: "0.25rem" },
});

theme.token.spacing(4); // "calc(var(--spacing) * 4)"
theme.token.spacing.token; // "var(--spacing)"
```

# shadow

Source: https://pitlane.tools/package/theme/schema/function/shadow.md

> A `shadow` token. Accepts CSS shadow text, `inset` included.

```ts
import { shadow } from "@pitlane/theme/schema";
```

```ts
function shadow(): TokenSchema<"shadow">;
```

A `shadow` token. Accepts CSS shadow text, `inset` included.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"shadow"`>

A schema declaring the `shadow` token type

# stroke

Source: https://pitlane.tools/package/theme/schema/function/stroke.md

> A `strokeStyle` token, named for the CSS value it holds. Accepts a line-style keyword.

```ts
import { stroke } from "@pitlane/theme/schema";
```

```ts
function stroke(): TokenSchema<"strokeStyle">;
```

A `strokeStyle` token, named for the CSS value it holds. Accepts a line-style keyword.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"strokeStyle"`>

A schema declaring the `strokeStyle` token type

# transition

Source: https://pitlane.tools/package/theme/schema/function/transition.md

> A `transition` token. Accepts CSS transition shorthand text.

```ts
import { transition } from "@pitlane/theme/schema";
```

```ts
function transition(): TokenSchema<"transition">;
```

A `transition` token. Accepts CSS transition shorthand text.

## Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"transition"`>

A schema declaring the `transition` token type

# SchemaGroup

Source: https://pitlane.tools/package/theme/schema/interface/SchemaGroup.md

> A schema group: per-child schemas, optionally under a schema for the node itself. [group](https://pitlane.tools/package/theme/schema/function/group.md) builds one; a plain object literal is the children-only form.

```ts
import type { SchemaGroup } from "@pitlane/theme/schema";
```

A schema group: per-child schemas, optionally under a schema for the node itself. [group](https://pitlane.tools/package/theme/schema/function/group.md) builds one; a plain object literal is the children-only form.

## See

[group](https://pitlane.tools/package/theme/schema/function/group.md)

## Indexable

```ts
[key: string]: SchemaNode | undefined
```

## Properties

### \[SELF\]?

```ts
readonly optional [SELF]?: TokenSchema<SchemaTag>;
```

# TokenSchema

Source: https://pitlane.tools/package/theme/schema/interface/TokenSchema.md

> A `remix/data-schema` schema that also names the token type it declares. Every factory in this module returns one.

```ts
import type { TokenSchema } from "@pitlane/theme/schema";
```

A `remix/data-schema` schema that also names the token type it declares. Every factory in this module returns one.

## See

[color](https://pitlane.tools/package/theme/schema/function/color.md)

## Extends

- `Schema`\<`unknown`, `string`>

## Type Parameters

### tag

`tag` _extends_ `SchemaTag` = `SchemaTag`

## Properties

### \[TAG\]

```ts
readonly [TAG]: tag;
```

---

### \~run

```ts
~run: (value: unknown, context: ValidationContext) => ValidationResult<string>;
```

Internal validator used to validate nested values while preserving `path`/`options`.

#### Parameters

##### value

`unknown`

##### context

`ValidationContext`

#### Returns

`ValidationResult`\<`string`>

#### Inherited from

```ts
Schema.~run
```

---

### \~standard

```ts
~standard: SyncStandardSchemaProps<unknown, string>;
```

#### Inherited from

```ts
Schema.~standard
```

---

### pipe

```ts
pipe: (...checks: Check<string>[]) => Schema<unknown, string>;
```

Compose one or more reusable checks onto this schema.

Checks run after the underlying schema has validated and produced an `output` value. If any check fails, validation fails with an issue (using the check's `message` if provided).

#### Parameters

##### checks

...`Check`\<`string`>\[\]

One or more `Check`s to apply in order

#### Returns

`Schema`\<`unknown`, `string`>

A new schema with the checks applied

#### Inherited from

```ts
Schema.pipe
```

---

### refine

```ts
refine: (predicate: (value: string) => boolean, message?: string) => Schema<unknown, string>;
```

Add an inline predicate check onto this schema.

The predicate runs after the underlying schema has validated and produced an `output` value. If the predicate returns `false`, validation fails with an issue.

#### Parameters

##### predicate

(`value`: `string`) => `boolean`

A function that returns `true` for valid values

##### message?

`string`

Optional issue message when the predicate fails

#### Returns

`Schema`\<`unknown`, `string`>

A new schema with the refinement applied

#### Inherited from

```ts
Schema.refine
```

---

### transform

```ts
transform: <newOutput>(transformer: (value: string) => newOutput) => Schema<unknown, newOutput>;
```

Transform the output of this schema with a function.

The transform function runs after the underlying schema has validated and produced an `output` value. The returned schema has a different output type.

#### Type Parameters

##### newOutput

`newOutput`

#### Parameters

##### transformer

(`value`: `string`) => `newOutput`

A function that transforms the validated output

#### Returns

`Schema`\<`unknown`, `newOutput`>

A new schema with the transformation applied

#### Inherited from

```ts
Schema.transform
```

# SchemaNode

Source: https://pitlane.tools/package/theme/schema/type/SchemaNode.md

> A node in a schema tree.

```ts
import type { SchemaNode } from "@pitlane/theme/schema";
```

```ts
type SchemaNode =
  | SchemaGroup
  | TokenSchema;
```

A node in a schema tree.

## See

[SchemaGroup](https://pitlane.tools/package/theme/schema/interface/SchemaGroup.md)

# font

Source: https://pitlane.tools/package/theme/schema/variable/font.md

> The two font token types, grouped because they share a prefix.

```ts
import { font } from "@pitlane/theme/schema";
```

```ts
font: object;
```

The two font token types, grouped because they share a prefix.

`font.family()` accepts a font stack, as a string or an array of names; an array joins with commas and quotes what needs quoting. `font.weight()` accepts 1 to 1000 or one of DTCG's nineteen keywords, and emits the number.

## Type Declaration

### family()

```ts
family(): TokenSchema<"fontFamily">;
```

A `fontFamily` token: a font stack as a string, or an array of names joined with commas.

#### Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"fontFamily"`>

### weight()

```ts
weight(): TokenSchema<"fontWeight">;
```

A `fontWeight` token: 1 to 1000 or a DTCG weight keyword, emitted as the number.

#### Returns

[`TokenSchema`](https://pitlane.tools/package/theme/schema/interface/TokenSchema.md)\<`"fontWeight"`>

## Example

```ts
let schema = { font: s.font.family(), weight: s.font.weight() };
let tokens = { font: { sans: ["Inter var", "system-ui"] }, weight: { bold: 700 } };
```

# @pitlane/vite-plugin-fetch-server

Source: https://pitlane.tools/package/vite-plugin-fetch-server/index.md

> 

## Interfaces

- [FetchServerOptions](https://pitlane.tools/package/vite-plugin-fetch-server/interface/FetchServerOptions.md). Options for [fetchServer](https://pitlane.tools/package/vite-plugin-fetch-server/function/fetchServer.md).

## Functions

- [fetchServer](https://pitlane.tools/package/vite-plugin-fetch-server/function/fetchServer.md). Serves `vite dev` requests through the Fetch handler an application's server module exports. Every request Vite does not answer itself goes to the current `default.fetch` of `entry`, loaded through the environment's module runner on each request, so an edit applies to the next request. Errors go to Vite's development error page.

# fetchServer

Source: https://pitlane.tools/package/vite-plugin-fetch-server/function/fetchServer.md

> Serves `vite dev` requests through the Fetch handler an application's server module exports. Every request Vite does not answer itself goes to the current `default.fetch` of `entry`, loaded through the environment's module runner on each request, so an edit applies to the next request. Errors go to Vite's development error page.

```ts
import { fetchServer } from "@pitlane/vite-plugin-fetch-server";
```

```ts
function fetchServer(options): Plugin;
```

Serves `vite dev` requests through the Fetch handler an application's server module exports. Every request Vite does not answer itself goes to the current `default.fetch` of `entry`, loaded through the environment's module runner on each request, so an edit applies to the next request. Errors go to Vite's development error page.

Development only: the plugin takes no part in `vite build` or `vite preview`. It sets `appType: "custom"` unless the config sets one.

## Parameters

### options

[`FetchServerOptions`](https://pitlane.tools/package/vite-plugin-fetch-server/interface/FetchServerOptions.md)

The server module and the environment that loads it; see [FetchServerOptions](https://pitlane.tools/package/vite-plugin-fetch-server/interface/FetchServerOptions.md)

## Returns

`Plugin`

The plugin, passed to Vite as one entry of `plugins`

## Throws

Error when `entry` is missing or empty

## Throws

Error at dev server startup when `environment` does not exist or is not runnable

## See

[Fetch server guide](https://pitlane.tools/guides/fetch-server.md)

## Example

```ts title="vite.config.ts"
import { fetchServer } from "@pitlane/vite-plugin-fetch-server";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [fetchServer({ entry: "src/http.ts" })],
});
```

# FetchServerOptions

Source: https://pitlane.tools/package/vite-plugin-fetch-server/interface/FetchServerOptions.md

> Options for [fetchServer](https://pitlane.tools/package/vite-plugin-fetch-server/function/fetchServer.md).

```ts
import type { FetchServerOptions } from "@pitlane/vite-plugin-fetch-server";
```

Options for [fetchServer](https://pitlane.tools/package/vite-plugin-fetch-server/function/fetchServer.md).

## Properties

### entry

```ts
entry: string;
```

Path to the application's server module, resolved through the environment's module runner, e.g. `"src/http.ts"`. Its default export must be an object with a `fetch(request)` method.

Required. It is never inferred from the environment's build inputs.

---

### environment?

```ts
optional environment?: string;
```

Vite environment whose module runner loads `entry`. It must be a runnable environment, one whose modules run inside the dev server process.

#### Default

```ts
"ssr"
```

# @pitlane/vite-plugin-remix

Source: https://pitlane.tools/package/vite-plugin-remix/index.md

> The `remix()` Vite plugin — Remix 3 build orchestration, the `clientEntry()` island identity transform, dev serving through the app's fetch handler, hot module replacement for components and server-rendered data, prerendering, and a preview server, for any Vite or Vite+ project.

The `remix()` Vite plugin — Remix 3 build orchestration, the `clientEntry()` island identity transform, dev serving through the app's fetch handler, hot module replacement for components and server-rendered data, prerendering, and a preview server, for any Vite or Vite+ project.

## See

- [Vite plugin guide](https://pitlane.tools/guides/vite-plugin.md)
- [Hot module replacement guide](https://pitlane.tools/guides/hmr.md)
- [Single-page apps guide](https://pitlane.tools/guides/spa.md)
- [Prerendering guide](https://pitlane.tools/guides/prerendering.md)

## Interfaces

- [PrerenderConfig](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md). The object form of the `prerender` option: which paths to render, plus how many to render at once and whether to follow the links they contain.
- [PrerenderContext](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderContext.md). What a `prerender` function receives.
- [RemixPluginOptions](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md). The options [remix](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) accepts. Every one has a default, and most projects pass none.

## Type Aliases

- [PrerenderOption](https://pitlane.tools/package/vite-plugin-remix/type/PrerenderOption.md). Everything `remix({ prerender })` accepts: `true` for every static path in the route map, `false` for none, an explicit path list, a function that computes one, or a [PrerenderConfig](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md) that adds `concurrency` and `spider`.
- [PrerenderPaths](https://pitlane.tools/package/vite-plugin-remix/type/PrerenderPaths.md). A function that decides which paths to prerender, for path sets that need async work — a CMS query, a filesystem scan, a database read.
- [PrerenderPathsOption](https://pitlane.tools/package/vite-plugin-remix/type/PrerenderPathsOption.md). The paths to prerender: `true` for every static path in the route map, an explicit list, or a function that computes one.

## Functions

- [remix](https://pitlane.tools/package/vite-plugin-remix/function/remix.md). Wires Remix 3 into a Vite or Vite+ project: multi-environment builds (`dist/ssr` + `dist/client`) with an asset manifest for `createAssetResolver()`, portable `clientEntry(import.meta.url, …)` island identities that `render({ assets })` resolves, dev serving through the app's fetch handler, prerendering, and a preview server for the production build.

# remix

Source: https://pitlane.tools/package/vite-plugin-remix/function/remix.md

> Wires Remix 3 into a Vite or Vite+ project: multi-environment builds (`dist/ssr` + `dist/client`) with an asset manifest for `createAssetResolver()`, portable `clientEntry(import.meta.url, …)` island identities that `render({ assets })` resolves, dev serving through the app's fetch handler, prerendering, and a preview server for the production build.

```ts
import { remix } from "@pitlane/vite-plugin-remix";
```

```ts
function remix(options?): PluginOption;
```

Wires Remix 3 into a Vite or Vite+ project: multi-environment builds (`dist/ssr` + `dist/client`) with an asset manifest for `createAssetResolver()`, portable `clientEntry(import.meta.url, …)` island identities that `render({ assets })` resolves, dev serving through the app's fetch handler, prerendering, and a preview server for the production build.

During `vite dev` it also installs hot module replacement: component edits swap in place through the `remix/component-hmr` transforms, and edits to modules the browser never loads broadcast a `server:update` event. An app whose browser entry passes its `run()` runtime to `revalidate` from `@pitlane/vite-plugin-remix/hmr` on that event refetches the current page through the app's fetch handler, keeping hydrated island state. Both are dev-only.

Platform-agnostic by design: deploy targets compose alongside it in the plugin array (`@cloudflare/vite-plugin`, `@netlify/vite-plugin`, `nitro/vite`), or the built fetch handler runs directly on Node, Bun, and Deno.

## Parameters

### options?

[`RemixPluginOptions`](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md) = `{}`

Entry modules, SPA mode, prerendering, assets, and dev serving; see [RemixPluginOptions](https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md)

## Returns

`PluginOption`

The plugins, passed to Vite as one entry of `plugins`

## Throws

Error when `server: false` is combined with `prerender`

## See

- [Vite plugin guide](https://pitlane.tools/guides/vite-plugin.md)
- [Hot module replacement guide](https://pitlane.tools/guides/hmr.md)
- [Single-page apps guide](https://pitlane.tools/guides/spa.md)
- [Prerendering guide](https://pitlane.tools/guides/prerendering.md)

## Examples

```ts title="vite.config.ts"
import { remix } from "@pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix()],
});
```

**SPA mode, with no server and index.html as the entry**

```ts title="vite.config.ts"
import { remix } from "@pitlane/vite-plugin-remix";
import { defineConfig } from "vite";

export default defineConfig({
    plugins: [remix({ server: false })],
});
```

# PrerenderConfig

Source: https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md

> The object form of the `prerender` option: which paths to render, plus how many to render at once and whether to follow the links they contain.

```ts
import type { PrerenderConfig } from "@pitlane/vite-plugin-remix";
```

The object form of the `prerender` option: which paths to render, plus how many to render at once and whether to follow the links they contain.

## See

[Prerendering guide: The object form](https://pitlane.tools/guides/prerendering.md#the-object-form)

## Properties

### concurrency?

```ts
optional concurrency?: number;
```

How many paths to render at once. Rendering is CPU-bound in-process, so the useful value depends on how much of a render waits on I/O.

#### Default

```ts
1
```

---

### paths?

```ts
optional paths?: PrerenderPathsOption;
```

The paths to prerender.

#### Default

```ts
true
```

---

### spider?

```ts
optional spider?: boolean;
```

Also follow the links each rendered page contains, and prerender those too. Turns the path list into a set of starting points rather than the complete answer, which suits a site whose pages all link to each other.

#### Default

```ts
false
```

# PrerenderContext

Source: https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderContext.md

> What a `prerender` function receives.

```ts
import type { PrerenderContext } from "@pitlane/vite-plugin-remix";
```

What a `prerender` function receives.

## Methods

### getStaticPaths()

```ts
getStaticPaths(): string[];
```

Every path the app's route map can serve without params — `/` and `/blog`, but not `/blog/:slug`, whose values live outside the route map.

Reads the `routes` named export of the built server entry. Throws when the server entry does not export one, since there is nothing else to enumerate.

#### Returns

`string`\[\]

# RemixPluginOptions

Source: https://pitlane.tools/package/vite-plugin-remix/interface/RemixPluginOptions.md

> The options [remix](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) accepts. Every one has a default, and most projects pass none.

```ts
import type { RemixPluginOptions } from "@pitlane/vite-plugin-remix";
```

The options [remix](https://pitlane.tools/package/vite-plugin-remix/function/remix.md) accepts. Every one has a default, and most projects pass none.

## See

[Vite plugin guide: Options](https://pitlane.tools/guides/vite-plugin.md#options)

## Properties

### assets?

```ts
optional assets?: Omit<AssetsPluginOptions, "serverEnvironments">;
```

Options for the asset plugin `remix()` installs: `include` for browser entries the server names with computed paths, `chunkImportMap`, which `remix()` turns on unless this option or Vite's own `build.chunkImportMap` says otherwise, and `allowFiles`, `allowPackages`, and `denyFiles` for the browser boundary. Server environments come from `serverEnvironments`.

Ignored when `server` is `false`.

#### Default

```ts
{}
```

---

### clientEntry?

```ts
optional clientEntry?: string | false;
```

Browser script entry, used as the client environment's build input. Pass `false` for fully server-rendered apps with no hydration: no browser script is built, while stylesheets and assets the server registers still go to `dist/client`.

#### Default

```ts
"app/entry.browser"
```

---

### prerender?

```ts
optional prerender?: PrerenderOption;
```

Render paths to static HTML at build time and write them into the client output, so a host can serve the file and skip the server entirely.

`true` prerenders every static path in the app's route map, which the server entry must export as `routes`. An array prerenders exactly those paths. A function computes them, and receives `getStaticPaths()` for the route-map half of a list that also has dynamic paths in it. The object form adds `concurrency` and `spider`.

Build-time only, and unsupported with `server: false`: prerendering renders through the server entry, and there is none.

#### Default

```ts
undefined
```

---

### server?

```ts
optional server?: boolean;
```

Whether the app has a server at all. Pass `false` for SPA mode: no server environment is configured, nothing is built to `dist/ssr`, and `vite build` emits a static site from `index.html`.

This is about the server, not about server rendering. With `false` every `server*` option below goes with it, because there is no server for them to describe, and `clientEntry` and `assets` go too: the browser entry is whatever `index.html` loads. An app that wants its UI rendered in the browser while its routes still answer per request keeps `true` and writes a server entry that serves data and a shell.

#### Default

```ts
true
```

---

### serverEntry?

```ts
optional serverEntry?: string;
```

Server entry module, built as `dist/ssr/index.js` and loaded for every dev request. Must default-export a fetch handler: an object exposing `fetch(request: Request): Response | Promise<Response>`, e.g. a `createRouter()` router.

#### Default

```ts
"app/entry.server"
```

---

### serverEnvironments?

```ts
optional serverEnvironments?: string[];
```

Environment names treated as "server": islands are discovered and stylesheets collected while they build, and hot module replacement classifies their modules as server code. Dev requests run in the first.

#### Default

```ts
["ssr"]
```

---

### serverHandler?

```ts
optional serverHandler?: boolean;
```

Serve dev-server and `vite preview` requests through the server entry's fetch handler. Set to `false` when another plugin owns request handling — `@cloudflare/vite-plugin` (workerd) or `nitro/vite` — so its own preview serves the build, even one Node could import. Keep the default with `@netlify/vite-plugin`, which emulates platform primitives around the dev server but leaves SSR to the app's fetch handler.

Ignored when `server` is `false`, which has no fetch handler.

#### Default

```ts
true
```

# PrerenderOption

Source: https://pitlane.tools/package/vite-plugin-remix/type/PrerenderOption.md

> Everything `remix({ prerender })` accepts: `true` for every static path in the route map, `false` for none, an explicit path list, a function that computes one, or a [PrerenderConfig](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md) that adds `concurrency` and `spider`.

```ts
import type { PrerenderOption } from "@pitlane/vite-plugin-remix";
```

```ts
type PrerenderOption =
  | PrerenderPathsOption
  | PrerenderConfig;
```

Everything `remix({ prerender })` accepts: `true` for every static path in the route map, `false` for none, an explicit path list, a function that computes one, or a [PrerenderConfig](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderConfig.md) that adds `concurrency` and `spider`.

## See

[Prerendering guide](https://pitlane.tools/guides/prerendering.md)

# PrerenderPaths

Source: https://pitlane.tools/package/vite-plugin-remix/type/PrerenderPaths.md

> A function that decides which paths to prerender, for path sets that need async work — a CMS query, a filesystem scan, a database read.

```ts
import type { PrerenderPaths } from "@pitlane/vite-plugin-remix";
```

```ts
type PrerenderPaths = (context: PrerenderContext) =>
  | string[]
  | Promise<string[]>
  | Iterable<string>
| Promise<Iterable<string>>;
```

A function that decides which paths to prerender, for path sets that need async work — a CMS query, a filesystem scan, a database read.

## Parameters

### context

[`PrerenderContext`](https://pitlane.tools/package/vite-plugin-remix/interface/PrerenderContext.md)

## Returns

| `string`\[\] | `Promise`\<`string`\[\]> | `Iterable`\<`string`> | `Promise`\<`Iterable`\<`string`>>

# PrerenderPathsOption

Source: https://pitlane.tools/package/vite-plugin-remix/type/PrerenderPathsOption.md

> The paths to prerender: `true` for every static path in the route map, an explicit list, or a function that computes one.

```ts
import type { PrerenderPathsOption } from "@pitlane/vite-plugin-remix";
```

```ts
type PrerenderPathsOption =
  | boolean
  | string[]
  | PrerenderPaths;
```

The paths to prerender: `true` for every static path in the route map, an explicit list, or a function that computes one.

# @pitlane/vite-plugin-remix/hmr

Source: https://pitlane.tools/package/vite-plugin-remix/hmr.md

> Browser-side half of server-data HMR. Import from `@pitlane/vite-plugin-remix/hmr` in the app's browser entry.

Browser-side half of server-data HMR. Import from `@pitlane/vite-plugin-remix/hmr` in the app's browser entry.

## See

[HMR guide: Setup](https://pitlane.tools/guides/hmr.md#setup)

## Functions

- [revalidate](https://pitlane.tools/package/vite-plugin-remix/hmr/function/revalidate.md). Applies a server update to the page: waits for initial hydration, then reloads the runtime's top frame, which refetches the current page through the app's fetch handler and reconciles it in place.

# revalidate

Source: https://pitlane.tools/package/vite-plugin-remix/hmr/function/revalidate.md

> Applies a server update to the page: waits for initial hydration, then reloads the runtime's top frame, which refetches the current page through the app's fetch handler and reconciles it in place.

```ts
import { revalidate } from "@pitlane/vite-plugin-remix/hmr";
```

```ts
function revalidate(app): void;
```

Applies a server update to the page: waits for initial hydration, then reloads the runtime's top frame, which refetches the current page through the app's fetch handler and reconciles it in place.

Call it from the browser entry's `server:update` listener:

```ts
if (import.meta.hot) {
    import.meta.hot.on("server:update", () => revalidate(app));
}
```

It returns nothing on purpose. Vite handles HMR messages one at a time and waits for the promise a listener returns, so returning the pending reload would hold back the next update until it settled. A newer reload supersedes an older one, which Remix aborts. A failed reload is logged, and the next update tries again.

## Parameters

### app

`AppRuntime`

The runtime `run()` returned

## Returns

`void`