` for the widget to land in. ```tsx title="plugins/contact/src/views/contact/contact-form.tsx" import type React from 'react' import { useCaptcha } from '@vitnode/core/hooks/use-captcha' // [!code ++] import { type MiddlewareConfig } from '@vitnode/core/tanstack/auth' import { sendMessage } from './send-message' export const ContactForm = ({ captcha, }: { captcha: MiddlewareConfig['captcha'] }) => { const { isReady, getToken, onReset } = useCaptcha(captcha) // [!code ++] const onSubmit = async (event: React.FormEvent) => { event.preventDefault() await sendMessage({ message: new FormData(event.currentTarget).get('message') as string, captchaToken: await getToken(), // [!code ++] }) onReset() // [!code ++] } return (

{/* [!code ++] */}
      <div id="vitnode_captcha" />

<button disabled={!isReady} type="submit">
        Send
      </button>
    </form>
  )
}
```

On an installation with no captcha configured, `captcha` is `undefined`,
`getToken()` resolves to `''` and `isReady` flips to `true` as soon as the
hook's effect runs - so this is one code path, not two. `isReady` starts `false`
either way, which means a server-rendered submit button is disabled in the
initial HTML and unlocks on hydration.

## The hook [#the-hook]

```ts
const { isReady, getToken, onReset } = useCaptcha(captcha)
```

It takes exactly what the API publishes on
`GET /api/@vitnode/core/middleware`, so you pass the value through rather than
building it.

<TypeTable
  type="{
  captcha: {
    description:
      "The deployment's captcha configuration, or undefined when none is configured. Read it from middlewareConfigQueryOptions().",
    type: "{ siteKey: string; type: 'cloudflare_turnstile' | 'recaptcha_v3' } | undefined",
    required: true,
  },
  isReady: {
    description:
      'Whether a token can be obtained. Starts false and becomes true on mount when no captcha is configured, when a Turnstile widget has called back, or when the reCAPTCHA script has fired its load event. Wire it to your submit button.',
    type: 'boolean',
  },
  getToken: {
    description:
      "The solved token. Turnstile returns the one the widget already handed over; reCAPTCHA v3 mints a fresh one with grecaptcha.execute at call time. Resolves to '' when there is no captcha, and when the provider script never loaded.",
    type: '() => Promise<string>',
  },
  onReset: {
    description:
      'Clears the stored token and sets isReady back to false, and on Turnstile also calls turnstile.reset() so the widget re-arms. Call it after every submission so one token cannot be replayed.',
    type: '() => void',
  },
}"
/>

## Wire it up [#wire-it-up]

<Steps>
  <Step>
    ### Gate the route [#gate-the-route]

Nothing on the client makes a route require a token - `withCaptcha: true` on the
    route does, in a [plugin](/docs/dev/plugins/create) exactly as in core.

```ts title="plugins/my-plugin/src/api/modules/contact/routes/create.route.ts"
    export const createContactRoute = buildRoute({
      pluginId: CONFIG_PLUGIN.pluginId,
      route: {
        method: 'post',
        path: '/',
        description: 'Send a message to the site owner',
        withCaptcha: true, // [!code ++]
        // ...
      },
      handler: async (c) => c.text('Message sent', 201),
    })
    ```
  </Step>

<Step>
    ### Read the deployment's config in the plugin screen [#read-the-deployments-config-in-the-plugin-screen]

The site key is public. A plugin page can read it with the shared TanStack Query
    definition before rendering its form:

```tsx title="plugins/contact/src/pages/contact-page.tsx"
    import { useSuspenseQuery } from '@tanstack/react-query'
    import { middlewareConfigQueryOptions } from '@vitnode/core/tanstack/auth'

import { ContactForm } from '../views/contact-form'

export const ContactScreen = () => {
      const { data: config } = useSuspenseQuery(middlewareConfigQueryOptions())

return <ContactForm captcha={config.captcha} />
    }
    ```
  </Step>

<Step>
    ### Mount the widget [#mount-the-widget]

`useCaptcha` finds its container by id, so the element has to exist in the DOM
    before the provider script finishes loading. Render it unconditionally inside
    the form:

```tsx
    <div id="vitnode_captcha" />
    ```

Turnstile renders into it. reCAPTCHA v3 has nothing to draw, so the `<div>` is
    harmless there and keeping it means the two providers swap without a code
    change.
  </Step>

<Step>
    ### Send the token [#send-the-token]

`captchaToken` is a first-class fetcher option, on both the browser fetcher and
    the server one, and it spells the `x-vitnode-captcha-token` header for you. An
    empty string sends no header at all.

```ts title="src/site/contact/send-message.ts"
    import type { contactModule } from '@vitnode/my-plugin/api/modules/contact/contact.module'

import { clientModule, fetcherClient } from '@vitnode/core/lib/fetcher-client'

const contact = clientModule<typeof contactModule>('@vitnode/my-plugin')

export const sendMessage = async ({
      captchaToken,
      ...body
    }: {
      captchaToken: string
      message: string
    }) =>
      await fetcherClient(contact, {
        method: 'post',
        module: 'contact',
        path: '/',
        captchaToken, // [!code ++]
        args: { body },
      })
    ```
  </Step>

<Step>
    ### Verify it is really gated [#verify-it-is-really-gated]

Call the route with no token. It answers `400` before your handler runs:

```bash
    curl -i -X POST 'http://localhost:3000/api/@vitnode/my-plugin/contact' \
      -H 'Content-Type: application/json' \
      -d '{"message":"Hello from curl"}'
    ```

```text
    HTTP/1.1 400 Bad Request

Captcha token is required
    ```

Then open the form. With Turnstile the widget appears where you put the `<div>`
    and the submit button unlocks on success; with reCAPTCHA v3 the button is
    enabled from the start and the token is minted on submit.
  </Step>
</Steps>

## Where the pieces live [#where-the-pieces-live]

A minimal captcha-gated feature is four files, and only one of them knows the
hook exists.

## Gotchas [#gotchas]

<Callout type="warn" title="One #vitnode_captcha per page">
  The container is found by id, so two captcha forms on one page fight over it:
  the challenge lands in whichever rendered first and the other's submit button
  never unlocks. Put the second form behind a dialog, a tab or its own route.
</Callout>

<Callout type="warn" title="The hook needs VitNode's providers above it">
  `useCaptcha` reads the visitor's locale and its error copy through `use-intl`,
  and the resolved theme through VitNode's `ThemeProvider` - the widget is
  rendered in both. `use-intl` throws without a provider, so the hook has to be
  mounted under `VitNodeRootProviders`, which every VitNode TanStack Start app
  already has above its route tree. Mount it outside and you get an intl context
  error, not a captcha.
</Callout>

<Callout type="warn" title="Call onReset(), but know what it costs on v3">
  Without it a visitor can submit the same token twice. With it, `isReady` goes
  back to `false` - and on reCAPTCHA v3 nothing sets it back to `true`, because
  there is no widget callback. A form that stays on screen after a failed
  submission ends up with a dead button until it remounts. Turnstile re-arms
  itself.
</Callout>

<Callout type="info" title="A missing script is not an error you can catch">
  If the provider's script is blocked, `getToken()` resolves to `''` rather than
  rejecting. Treat the API's `400` as the real signal - it is the only place
  that knows whether the token was any good.
</Callout>

## Next [#next]

# Captcha

VitNode provides built-in bot protection. When enabled in your API configuration, gated routes automatically demand and verify a challenge token before handler execution.

## Quick start [#quick-start]

### 1. Configure Captcha in API Config [#1-configure-captcha-in-api-config]

Add the `captcha` configuration to `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  captcha: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY
    ? {
        type: "cloudflare_turnstile",
        siteKey: process.env.CLOUDFLARE_TURNSTILE_SITE_KEY,
        secretKey: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY,
      }
    : undefined,
})
```

Built-in user registration and password recovery routes are protected immediately:

***

### 2. Protect Custom API Routes [#2-protect-custom-api-routes]

Enable captcha verification on any custom Hono endpoint with `withCaptcha: true`:

```ts title="plugins/blog/src/api/modules/comments/routes/create.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route"

export const createCommentRoute = buildRoute({
  pluginId: "blog",
  withCaptcha: true, // [!code ++]
  route: {
    method: "post",
    path: "/",
    responses: { 201: { description: "Comment created" } },
  },
  handler: async (c) => {
    // Execution only reaches here if the captcha token is valid
  },
})
```

***

### 3. Render the Frontend Widget [#3-render-the-frontend-widget]

Include `<Captcha />` in your form and supply the received token to `fetcherClient`:

```tsx title="plugins/blog/src/views/comment-form.tsx"
import { Captcha } from "@vitnode/core/components/captcha"
import { fetcherClient } from "@vitnode/core/lib/fetcher-client"

export const CommentForm = () => {
  const [captchaToken, setCaptchaToken] = React.useState<string>()

const handleSubmit = async () => {
    await fetcherClient(commentsModule, {
      method: "post",
      path: "/",
      captchaToken, // [!code ++]
      body: { text: "Nice article!" },
    })
  }

return (
    <form onSubmit={handleSubmit}>
      <textarea />
      <Captcha onVerify={setCaptchaToken} />
      <button disabled={!captchaToken}>Submit Comment</button>
    </form>
  )
}
```

***

## Supported Providers [#supported-providers]

## Learn More [#learn-more]

# Google reCAPTCHA v3

reCAPTCHA v3 never asks the visitor to do anything. It watches the page, scores
the request from `0.0` to `1.0`, and VitNode's API accepts anything at `0.5` or
above. Nothing to install - the provider lives in core - so the whole job is two
keys and one config block.

## Quick start [#quick-start]

If you already have a v3 site key and secret key, this is the entire
integration.

```bash title=".env"
RECAPTCHA_SITE_KEY=6Lc...
RECAPTCHA_SECRET_KEY=6Lc...
```

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:5]
  captcha: {
    type: 'recaptcha_v3',
    siteKey: process.env.RECAPTCHA_SITE_KEY,
    secretKey: process.env.RECAPTCHA_SECRET_KEY,
  },
})
```

Restart the API and `/register` starts minting a token on submit. There is no
widget to look at - a reCAPTCHA badge in the corner of the page is the only
visible change.

<Callout type="warn" title="Do not ship this block without both keys">
  An empty `secretKey` does not disable captcha - it breaks it. `captchaMiddleware`
  steps aside only when the whole `captcha` block is missing, so a deployment with
  the block and no keys **rejects** registration and password reset with `400`.
  Gate the block on the environment variable:

```ts title="src/vitnode.api.config.ts"
  export const vitNodeApiConfig = buildApiConfig({
    // [!code ++:7]
    captcha: process.env.RECAPTCHA_SECRET_KEY
      ? {
          type: 'recaptcha_v3',
          siteKey: process.env.RECAPTCHA_SITE_KEY,
          secretKey: process.env.RECAPTCHA_SECRET_KEY,
        }
      : undefined,
  })
  ```
</Callout>

<Callout title="reCAPTCHA v2 is not supported" type="error">
  `type` accepts `'cloudflare_turnstile'` and `'recaptcha_v3'`, and nothing
  else. VitNode loads Google's script with `render=<siteKey>` and mints the
  token through `grecaptcha.execute`, which a v2 key cannot do - so a v2 pair in
  this block ends as a `400`, either because no token was minted or because the
  verification came back without a score. Register a **score based (v3)** site,
  or use [Cloudflare Turnstile](/docs/dev/captcha/cloudflare) if you want a
  visible widget.
</Callout>

## Register the site [#register-the-site]

<Steps>
  <Step>
    ### Open the reCAPTCHA admin console [#open-the-recaptcha-admin-console]

Go to the [reCAPTCHA admin console](https://www.google.com/recaptcha/admin/) and
    sign in with the Google account that should own the keys.
  </Step>

<Step>
    ### Start a new registration [#start-a-new-registration]

Press the **+** button in the console's header to register another site.

<Step>
    ### Choose score based (v3) and add your domains [#choose-score-based-v3-and-add-your-domains]

Give the registration a **Label** - internal, so your site's name will do - and
    pick **Score based (v3)** as the reCAPTCHA type.

Then list every domain the form is served from. Google allows first-level
    subdomains automatically, so `your-domain.com` also covers
    `www.your-domain.com`. For local development you have to add `localhost`
    explicitly; it is not implied.

{/* Image prompt: The Google reCAPTCHA "Register a new site" form with a Label filled in, the "Score based (v3)" reCAPTCHA type radio selected, and two Domains entries reading your-domain.com and localhost, light theme, 1000x700. */}
  </Step>

<Step>
    ### Copy the site key and the secret key [#copy-the-site-key-and-the-secret-key]

Google shows both on the next screen, and they stay available under the
    registration's **Settings** tab.

The **site key** is public - the API publishes it so the browser can load
    Google's script. The **secret key** is not: it only ever travels from your API
    to Google's `siteverify` endpoint.

{/* Image prompt: The Google reCAPTCHA admin console keys screen showing the "SITE KEY" and "SECRET KEY" values with their copy buttons, values partially redacted, light theme, 1000x500. */}
  </Step>

<Step>
    ### Set the environment variables [#set-the-environment-variables]

These names are not magic - they are whatever you read in your config on the
    next step. What matters is that both are server-side variables, because the
    secret key must never reach a browser bundle.

```bash title=".env"
    RECAPTCHA_SITE_KEY=6Lc... # [!code ++]
    RECAPTCHA_SECRET_KEY=6Lc... # [!code ++]
    ```
  </Step>

<Step>
    ### Register the provider [#register-the-provider]

Add the `captcha` block to your API config with `type: 'recaptcha_v3'`.

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      plugins: [],
      // [!code ++:5]
      captcha: {
        type: 'recaptcha_v3',
        siteKey: process.env.RECAPTCHA_SITE_KEY,
        secretKey: process.env.RECAPTCHA_SECRET_KEY,
      },
    })
    ```

The config is evaluated when the process boots, so restart the API rather than
    waiting for a hot reload to notice.
  </Step>

<Step>
    ### Verify it works [#verify-it-works]

Ask the API what it thinks it has configured. The site key comes back on the
    public middleware route:

```bash
    curl http://localhost:3000/api/@vitnode/core/middleware
    # {"isEmail":false,"sso":[],"captcha":{"siteKey":"6Lc...","type":"recaptcha_v3"}}
    ```

Then open `/register`. Google's badge appears in the bottom corner of the page,
    the **Register** button is enabled as soon as the script loads, and a completed
    registration means the score cleared `0.5`.

The AdminCP confirms it from the other side: **AdminCP → System →
    Integrations** (`/admin/core/system/integrations`) shows the **Captcha** card as
    *Active*, with **reCAPTCHA v3** underneath.

Google's own console is the third view. Under the registration's analytics you
    should see the request appear, with the score it was given.
  </Step>
</Steps>

## What VitNode sends and checks [#what-vitnode-sends-and-checks]

Useful when the console's numbers and your form's behaviour disagree.

| Thing            | Value                                                                  |
| ---------------- | ---------------------------------------------------------------------- |
| Script           | `https://www.google.com/recaptcha/api.js?hl=<locale>&render=<siteKey>` |
| Token minted by  | `grecaptcha.execute(siteKey, { action: 'submit' })`                    |
| Action name      | `submit` - always, and the API does not verify it                      |
| Verify endpoint  | `https://www.google.com/recaptcha/api/siteverify`                      |
| Accepted when    | `success === true` **and** `score >= 0.5`                              |
| Threshold        | `0.5`, hardcoded in `captchaMiddleware`                                |
| Token travels as | the header `x-vitnode-captcha-token`                                   |

The visitor's IP is forwarded as `remoteip`, so the score reflects the person
filling the form rather than your server. It is read from the first proxy header
that has a value - `x-forwarded-for` first, then `x-real-ip`,
`cf-connecting-ip` and a dozen more - and falls back to `127.0.0.1` when a
request arrives with none of them.

## Gotchas [#gotchas]

<Callout type="warn" title="The 0.5 threshold is not configurable">
  It is a constant in the middleware, not a config option, so you cannot loosen
  it for a site that keeps scoring low or tighten it for one under attack. If
  you need a different number, the honest options are a pull request or
  [Cloudflare Turnstile](/docs/dev/captcha/cloudflare), which has no score in
  the first place.
</Callout>

<Callout type="warn" title="A low score looks exactly like a wrong key">
  Both come back as `400 Captcha validation failed`, because the middleware does
  not pass Google's `error-codes` through to the response. Check the
  registration's analytics in the admin console: a request that arrived with a
  low score is a scoring problem, and no request at all is a key or domain
  problem.
</Callout>

<Callout type="warn" title="A rejected submit leaves the button disabled">
  `AutoForm` calls `onReset()` after every submission, which clears `isReady` -
  and with v3 there is no widget callback to set it back. A form that stays on
  screen after a failure ("email already exists") therefore has a dead submit
  button until it is remounted. Turnstile does not have this problem, because
  `turnstile.reset()` makes the widget call back again.
</Callout>

<Callout type="info" title="Env changes need a restart">
  The API config reads `process.env` when the process starts, so a new key in
  `.env` only takes effect after you restart the dev server.
</Callout>

## Next [#next]

# Configuration

A VitNode app has two configuration files, and the line between them is one
question: **may a browser hold this?**

***

## `vitnode.config.ts` - the shared config [#vitnodeconfigts---the-shared-config]

```ts title="apps/web/src/vitnode.config.ts"
import { blogPlugin } from '@vitnode/blog/config'
import { buildConfig } from '@vitnode/core/vitnode.config'

export const vitNodeConfig = buildConfig({
  debug: false,
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'pl', name: 'Polski' },
    ],
    timeZone: 'UTC',
  },
  metadata: {
    shortTitle: 'VitNode',
    title: 'VitNode',
  },
  plugins: [blogPlugin()],
  theme: {
    defaultTheme: 'system',
  },
})
```

Three very different readers depend on this file:

1. **The document shell** renders `metadata`, `theme` and `debug` - in the
   browser as well as on the server.
2. **The locale runtime** derives routing from `i18n`.
3. **Your Vite build** loads it with `jiti` while Vite is still resolving its
   own config, to find out which plugins to generate route, navigation and
   content-registry imports for.

<Callout type="warn" title="Plain data only">
  Because of reader 3, this file is executed at build time; because of reader 1
  it is bundled for a browser. So it holds plain data and plugin *identity* -
  never a `() => import(...)` message loader, and never a module that reaches a
  database.
</Callout>

`buildConfig` keeps `locales` a tuple of literal types, so a `Locale` derived
from it is `'en' | 'pl'` rather than `string`, and `defaultLocale` is checked
against the list right beside it:

```ts title="apps/web/src/lib/i18n/shared.ts"
export type Locale = (typeof vitNodeConfig.i18n.locales)[number]['code']
```

### Enabled plugins [#enabled-plugins]

```ts
import { blogPlugin } from '@vitnode/blog/config'

plugins: [blogPlugin()]
```

The factory carries the plugin's identity, its locale barrel and its route
declarations - plain data, and nothing that renders. Its AdminCP navigation and
its Content Engine screens live in the plugin's `admin/nav` and `admin/content`
modules instead, and they never pass through this object.

What a TanStack Start app **renders** comes back through generated projections
of those modules, and that is the part worth knowing:

One literal import per configured plugin, written at build time. So a content
type's editing screen - a Tiptap field, a form layout, a table cell - arrives
with the route that renders it, not with the config that the document shell
imports. Spreading `admin/content` into the factory undoes exactly that: the
whole editing stack rides along with every public page. See
[Plugin routes](/docs/dev/plugins/routes) and
[Plugin frontend modules](/docs/dev/content-engine/plugin-registration).

<Callout type="info" title="Also register its locale files">
  The `messages` a factory carries is the plugin's own locale barrel, which loads
  its JSON with `import('./en.json', { with: { type: 'json' } })` - a specifier
  no bundler follows. VitNode reads translations from
  `src/locales/packages.ts` instead, so add a line there per language the plugin
  ships. [Languages & Localization](/docs/dev/i18n) has the detail.
</Callout>

<Callout type="warn" title="Build-time cost">
  Your Vite build executes this file with `jiti` on every regeneration pass to
  discover the plugin list. Running a plugin's registration graph in Node
  measures \~340ms per pass against \~6ms for `buildPlugin({pluginId})`, which is
  the minimum a TanStack host needs - worth knowing if a large plugin set makes
  the dev watcher feel slow.
</Callout>

***

## `vitnode.server.config.ts` - the server-only companion [#vitnodeserverconfigts---the-server-only-companion]

Message loaders read JSON out of a package's build output, which is exactly what
the shared config cannot carry. They go here instead:

```ts title="apps/web/src/vitnode.server.config.ts"
import '@tanstack/react-start/server-only'
import { buildServerConfig } from '@vitnode/core/vitnode.config'

import { appMessages } from '#/locales/app'
import { packageMessages } from '#/locales/packages'
import { vitNodeConfig } from '#/vitnode.config'

export const vitNodeServerConfig = buildServerConfig({
  config: vitNodeConfig,
  messages: appMessages,
  packageMessages,
})
```

It **holds** the shared config rather than repeating any of it, so the locale
list your message loaders are resolved against is the same object the router and
the document shell read. Hand the whole thing to the loader:

```ts title="apps/web/src/server/messages.server.ts"
export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig)
```

`packageMessages` is one line per language a package ships, and `messages` is
where you reword a string a package translates differently to how you want it.
[Languages & Localization](/docs/dev/i18n) covers both.

<Callout type="info" title="The API has its own config">
  `src/vitnode.api.config.ts` configures the Hono app at `/api/*` - the
  database, storage, email, Redis. In a single app it reads `vitNodeConfig.i18n`
  so the site and its emails agree on which languages exist. In a split
  deployment the API is a separate package and declares its own list.
</Callout>

***

## `start.ts` - the request pipeline [#startts---the-request-pipeline]

TanStack Start expects a `src/start.ts`. In a VitNode app it is one call:

```ts title="apps/web/src/start.ts"
import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '#/vitnode.config'

export const startInstance = createVitNodeStart({ config: vitNodeConfig })
```

`createVitNodeStart` installs three things, and none of them is optional:

<Callout type="warn" title="Why the factory exists">
  Start installs its own CSRF middleware *only* while an app declares no
  `requestMiddleware` at all. The moment an app writes its own list, that
  default is replaced by whatever the list holds - so an app that hand-rolls the
  pipeline and forgets CSRF exposes every server function as an unauthenticated
  cross-site endpoint, silently. Core owns the list so you cannot.
</Callout>

### Why documents are never shared-cacheable [#why-documents-are-never-shared-cacheable]

Every page VitNode renders streams a dehydrated TanStack Query cache into its
HTML, and that cache always holds the visitor's own session - inside `/admin`,
an administrator's entire permission set. So the directive is **forced**, not
defaulted: a route that sets `public, max-age=60` is overwritten rather than
obeyed, because the route is not in a position to know what is in the body it
would be publishing.

Only `text/html` responses are touched. Everything else keeps what it had.

<Callout type="info" title="API caching stays the API's">
  `/api/*` is served by the Hono bridge through this same middleware and passes
  through untouched: no locale redirect, no rewrite, and no cache directive on
  the JSON it answers with. The API decides its own policy with `c.get("cache")`

* see [Caching](/docs/dev/cache). The one exception proves the rule rather
    than bending it: Swagger UI at `/api/swagger` is HTML, so it gets the document
    directive like any other page an operator reads.
</Callout>

### Adding your own middleware [#adding-your-own-middleware]

For things your installation genuinely owns - a request id, a tracing span, a
maintenance-mode gate:

```ts title="apps/web/src/start.ts"
import { createMiddleware } from '@tanstack/react-start'
import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '#/vitnode.config'

const requestId = createMiddleware().server(async ({ next }) => {
  const result = await next()
  result.response.headers.set('x-request-id', crypto.randomUUID())

return result
})

export const startInstance = createVitNodeStart({
  config: vitNodeConfig,
  requestMiddleware: [requestId],
})
```

**Ordering is guaranteed:** CSRF first, then locale handling, then your list in
the order you declared it. You cannot get in front of either. That is not
tidiness - a locale redirect *ends* the request, so middleware running before it
would run twice for every visitor who arrives at a non-canonical URL, once for
the redirect and once for the page.

***

## `vite.config.ts` [#viteconfigts]

One VitNode plugin, which is the environment handling, the dev server's
dependency pre-bundling, the SSR externals and the plugin route generator in the
order they have to run:

```ts title="apps/web/vite.config.ts"
import { vitnode } from '@vitnode/core/framework/vite'

export default defineConfig({
  plugins: [
    vitnode({ appRoot: import.meta.dirname }),
    nitro({ compressPublicAssets: { brotli: true, gzip: true } }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
})
```

`compressPublicAssets` writes a `.br` and a `.gz` twin next to every built asset,
so the Node server from `pnpm start` serves scripts and styles compressed the
way a CDN would. The server-rendered HTML itself is not compressed by the Node
server; put a reverse proxy or a platform such as Vercel in front of it for that.

`appRoot` has to be `import.meta.dirname`: a Vite config is loaded with the
working directory set to wherever the command ran, which in a monorepo is
regularly the repository root.

Publish an extra `NEXT_PUBLIC_*` key to the browser with `clientEnv`:

```ts
vitnode({ appRoot: import.meta.dirname, clientEnv: ['NEXT_PUBLIC_MAP_KEY'] })
```

Everything named there is compiled into JavaScript anyone can read, so add a key
only when something in the browser genuinely reads it. The four plugins are
still exported individually - `vitNodeEnv`, `vitNodeOptimizeDeps`,
`vitNodeSsrExternals`, `vitNodePluginRoutes` - if you ever need to drop or
reorder one.

### What gets externalised from the server render [#what-gets-externalised-from-the-server-render]

You do not write an `ssr.external` list, because the right answer changes
between the two commands:

| Command      | `@vitnode/core` and your plugins | Why                                                                               |
| ------------ | -------------------------------- | --------------------------------------------------------------------------------- |
| `vite dev`   | inlined                          | Vite owns the modules, so a rebuilt package reaches the server render immediately |
| `vite build` | external                         | the built package goes into the output as it is, rather than being bundled again  |

Externalising in dev is the tempting mistake, and it fails quietly: an external
module is imported by Node, whose module cache lives as long as the process. The
browser hot-reloads your edit, the server render keeps the copy it loaded at
startup, and React reports a hydration mismatch on markup you already fixed. Only
a restart clears it - which is exactly the loop this plugin removes.

The build list is `@vitnode/core`, every plugin in your `vitnode.config.ts` and
`tslib`. It comes from the same configured plugin list the route generator reads,
so removing a plugin from your config is one edit, not two.

## Learn More [#learn-more]

# AdminCP Integration

Content Engine automatically builds interactive management screens in the AdminCP without writing hand-rolled pages or form components.

## Quick start [#quick-start]

```tsx title="plugins/blog/src/admin/content.tsx"
import type { ContentFrontendPluginSource } from '@vitnode/core/lib/plugin'
import { contentTypeAdmin } from '@vitnode/core/lib/plugin'
import { FileTextIcon } from 'lucide-react'
import { postContentType } from '@/content/post'

export const adminContent = {
  pluginId: 'blog',
  // [!code ++:6]
  contentTypes: [
    contentTypeAdmin({
      definition: postContentType,
      icon: <FileTextIcon />,
    }),
  ],
} satisfies ContentFrontendPluginSource
```

The screen is immediately accessible at `/admin/content/blog/post`. The build
imports this module for you through the generated content registry; keep it out
of `config.tsx`, which is bundled with every public page. See
[Plugin frontend modules](/docs/dev/content-engine/plugin-registration) for the
matching `admin/nav.tsx` sidebar entry.

***

## Customizing the Data Table [#customizing-the-data-table]

Control which columns, search inputs, and sortable headers appear in the AdminCP table:

```ts title="plugins/blog/src/content/post.ts"
export const postContentType = defineContentType({
  id: 'blog.post',
  tableName: 'blog_posts',
  fields: {/* ... */},
  // [!code ++:9]
  admin: {
    titleField: 'title', // Primary record identifier in dialogs
    list: {
      columns: ['title', 'status', 'author', 'createdAt'],
      searchableFields: ['title'],
      orderableFields: ['title', 'createdAt'],
      defaultOrderBy: { column: 'createdAt', order: 'desc' },
    },
  },
})
```

***

## Customizing Form Layouts [#customizing-form-layouts]

Group fields into visually distinct sections:

```ts title="plugins/blog/src/content/post.ts"
admin: {
  form: {
    // [!code ++:10]
    sections: [
      {
        id: "main",
        fields: ["title", "slug", "content"],
      },
      {
        id: "metadata",
        title: "Publishing Options",
        fields: ["status", "category", "author"],
      },
    ],
  },
}
```

***

## The Loading Placeholder [#the-loading-placeholder]

The create and edit screens never flash a spinner. While the form's code chunk
and the record are still on their way, Content Engine draws a skeleton in the
shape of the form you are about to get: the heading, description and back link
render for real, and every field becomes a block the size of the control that
replaces it.

The placeholder is built from the content type's definition, so it needs no
configuration - a `text` field becomes an input-sized block, a `boolean` becomes
a switch, a `file` becomes a media box, and a to-many picker becomes a list. If
you gave the content type its own layout, the placeholder renders *that* layout,
so the fields land exactly where they will a moment later.

### When an override is a different shape [#when-an-override-is-a-different-shape]

A field override can render something much bigger than its field kind suggests -
the blog's `content` is declared a `textarea` but renders a full rich-text
editor. Tell the placeholder what to draw with `skeleton`:

```tsx title="plugins/blog/src/admin/content.tsx"
contentTypeAdmin({
  ...postNav,
  fields: {
    content: {
      component: BlogArticleEditorField,
      skeleton: 'editor', // [!code ++]
    },
  },
})
```

The same block is available on its own, for a field that lazy-loads its control:

```tsx title="plugins/blog/src/views/admin/article/editor-field.tsx"
import { ContentFormFieldSkeleton } from '@vitnode/core/content/admin-form'

;<React.Suspense fallback={<ContentFormFieldSkeleton control="editor" />}>
  <AutoFormEditor label={t('content.label')} {...props} />
</React.Suspense>
```

***

## Custom Screen Overrides [#custom-screen-overrides]

For advanced layouts, replace the default screen with a custom React component:

```tsx title="plugins/blog/src/admin/content.tsx"
export const postAdminOverrides = {
  customScreen: MyCustomPostScreen, // [!code ++]
}
```

## Learn More [#learn-more]

# Content Delivery and SEO

Content delivery starts in the plugin that owns the content type. Opt into the
public API first, then let the same plugin claim the page URL. Search engines
get a stable story; future you gets fewer scattered files.

{/* Image prompt: Dark-theme flow diagram showing a Content Engine record with a slug, a plugin route tree entry for /articles/:slug, and a rendered page head containing title, description, canonical URL, Open Graph, hreflang, and sitemap symbols. 1600x900. */}

<Steps>
  <Step>
    ### Enable public delivery on the content type [#enable-public-delivery-on-the-content-type]

`publicApi` explicitly chooses exposed fields. Delivery then projects only those
    fields into metadata and sitemap entries.

```ts title="plugins/site-notes/src/content/article.ts"
    import { defineContentType, field } from '@vitnode/core/content'

export const articleContentType = defineContentType({
      id: '@acme/site-notes.article',
      tableName: 'site_notes_articles',
      publication: { enabled: true },
      editorial: { enabled: true },
      fields: {
        excerpt: field.textarea({ nullable: true }),
        slug: field.slug({ source: 'title' }),
        title: field.text({ required: true }),
      },
      // [!code ++:17]
      publicApi: {
        enabled: true,
        fields: ['id', 'title', 'slug', 'excerpt', 'publishedAt'],
        path: 'articles',
      },
      delivery: {
        enabled: true,
        redirects: { enabled: true },
        seo: {
          descriptionField: 'excerpt',
          titleField: 'title',
        },
        sitemap: { enabled: true, changeFrequency: 'weekly', priority: 0.8 },
      },
    })
    ```
  </Step>

<Step>
    ### Claim the public URL in the plugin [#claim-the-public-url-in-the-plugin]

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:3]
      page('/articles/:slug', {
        component: lazy(() => import('./pages/article-page')),
      }),
    ])
    ```
  </Step>

<Step>
    ### Render data and metadata from the plugin route [#render-data-and-metadata-from-the-plugin-route]

```tsx title="plugins/site-notes/src/pages/article-page.tsx"
    import type { PluginRoutePageProps } from '@vitnode/core/routing'
    import { definePluginRoute } from '@vitnode/core/routing'

interface Article {
      excerpt: string | null
      title: string
    }

// [!code ++:8]
    export const route = definePluginRoute({
      load: async ({ params }) => await fetchArticle(params.slug),
      head: ({ loaderData }) => ({
        description: loaderData?.excerpt,
        title: loaderData?.title,
      }),
    })

const ArticlePage = ({ loaderData }: PluginRoutePageProps<Article>) => (
      <article className="container mx-auto max-w-3xl p-4">
        <h2 className="text-3xl font-semibold">{loaderData.title}</h2>
        <p>{loaderData.excerpt}</p>
      </article>
    )

export default ArticlePage
    ```
  </Step>
</Steps>

<Callout type="success" title="Keep delivery with its plugin">
  Do not recreate the article page in the host app. The content type, slug
  rules, public API, and public route evolve together, so they belong together.
</Callout>

## What search engines receive [#what-search-engines-receive]

* Canonical URLs and optional Open Graph fields from `delivery.seo`.
* Redirect history for editorial content when a public slug changes.
* Localized alternates when you configure `hreflang`.
* Sitemap entries for public records when `sitemap.enabled` is true.

<Cards>
  <Card icon="<RouteIcon />" title="Plugin routing" description="Add a route module with loaders, metadata, and a stable URL contract." href="/docs/dev/routing" />

<Card icon="<SearchIcon />" title="Public API and caching" description="Expose deliberate fields and understand cache invalidation." href="/docs/dev/content-engine/public-api-and-caching" />
</Cards>

# Database & Migrations

Content Engine content types compile directly into standard PostgreSQL database tables via Drizzle ORM.

## Prerequisites & Context [#prerequisites--context]

Before setting up database tables, you must have a content type definition (e.g. `articleContentType`) created using `defineContentType` in `src/content/article.ts`:

```ts title="src/content/article.ts"
import { defineContentType, field } from '@vitnode/core/content'

// 1. Client-safe definition (imported by both API and AdminCP)
export const articleContentType = defineContentType({
  id: 'example.article',
  tableName: 'example_articles',
  fields: {
    title: field.text({ required: true }),
    code: field.text({ required: true }),
  },
})
```

* **`createContentModel(definition, options)`**: A backend utility from `@vitnode/core/content/server` that converts a client-safe content definition into a server-side Drizzle ORM model.
* **`articleContent`**: The compiled model object containing `.table` (raw Drizzle table), `.service(c)` (CRUD helper), and `.schemas` (Zod schemas).

***

## Step-by-Step Database Setup [#step-by-step-database-setup]

<Steps>
  <Step>
    ### Step 1: Create Database Model File [#step-1-create-database-model-file]

Create your model file under `src/database/articles.ts`. Import `createContentModel` from `@vitnode/core/content/server` and your definition `articleContentType`:

```ts title="src/database/articles.ts"
    import { createContentModel } from '@vitnode/core/content/server'
    import { articleContentType } from '@/content/article'
    import { example_categories } from './categories'

// Compile client definition into a server Drizzle model
    export const articleContent = createContentModel(articleContentType, {
      references: {
        category: () => example_categories.id,
      },
    })

// Export raw Drizzle table for migration discovery
    export const example_articles = articleContent.table
    ```
  </Step>

<Step>
    ### Step 2: Add Database Indexes [#step-2-add-database-indexes]

Add single or composite indexes inside your content definition file `src/content/article.ts`:

```ts title="src/content/article.ts"
    export const articleContentType = defineContentType({
      id: 'example.article',
      tableName: 'example_articles',
      fields: {
        title: field.text({ required: true }),
        code: field.text({ required: true }),
        status: field.enum({ values: ['draft', 'published'] }),
      },
      indexes: [
        // [!code ++]
        { on: ['status', 'createdAt'] }, // Composite index // [!code ++]
        { on: ['code'], unique: true }, // Unique constraint // [!code ++]
      ], // [!code ++]
    })
    ```
  </Step>

<Step>
    ### Step 3: Run Database Migrations [#step-3-run-database-migrations]

Compile your plugins and apply schema changes:

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']">
      <Tab value="bun">
        ```bash
        bun run build:plugins && bun run db:migrate
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm build:plugins && pnpm db:migrate
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm run build:plugins && npm run db:migrate
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## Automatic System Columns [#automatic-system-columns]

When `createContentModel` compiles a model, it automatically includes standard system columns:

If [`publication`](/docs/dev/content-engine/publication-and-editorial) is enabled, `status` and `publishedAt` columns are added.\
If [`editorial`](/docs/dev/content-engine/publication-and-editorial) is enabled, a `version` column is added for optimistic concurrency control.

# Defining a Content Type

Content Engine generates a complete CRUD ecosystem from one declaration: a PostgreSQL table, Zod validation schemas, API endpoints, staff permissions, and AdminCP management screens.

## Quick start [#quick-start]

### 1. Define the Content Type [#1-define-the-content-type]

```ts title="plugins/example/src/content/category.ts"
import { defineContentType, field } from '@vitnode/core/content'

export const categoryContentType = defineContentType({
  id: 'example.category',
  tableName: 'example_categories',
  fields: {
    name: field.text({ required: true, minLength: 2, maxLength: 100 }),
    slug: field.slug({ from: 'name', required: true }),
  },
})
```

### 2. Create the Database Model [#2-create-the-database-model]

```ts title="plugins/example/src/database/categories.ts"
import { createContentModel } from '@vitnode/core/content/server'
import { categoryContentType } from '@/content/category'

export const categoryContent = createContentModel(categoryContentType)
export const example_categories = categoryContent.table
```

### 3. Build & Run Migrations [#3-build--run-migrations]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Build and migrate">
  <Tab value="bun">
    ```bash
    bun run build:plugins && bun run db:migrate
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm build:plugins && pnpm db:migrate
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run build:plugins && npm run db:migrate
    ```
  </Tab>
</Tabs>

Your table now exists in PostgreSQL.

***

## Wire into API and AdminCP [#wire-into-api-and-admincp]

<Steps>
  <Step>
    ### 1. Register CRUD Routes on the API [#1-register-crud-routes-on-the-api]

Add the model to your plugin's `config.api.ts`:

```ts title="plugins/example/src/config.api.ts"
    import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
    import { categoryContent } from './database/categories'

export const exampleApiPlugin = () =>
      buildApiPlugin({
        pluginId: '@vitnode/example',
        // [!code ++:3]
        contentTypes: [categoryContent],
      })
    ```

This immediately registers full CRUD routes under `/api/@vitnode/example/admin/content/category`.
  </Step>

<Step>
    ### 2. Register Screens in the AdminCP [#2-register-screens-in-the-admincp]

Connect the definition in `src/admin/content.tsx`. The build imports this module
    through the generated content registry, so it never reaches a public page:

```tsx title="plugins/example/src/admin/content.tsx"
    import type { ContentFrontendPluginSource } from '@vitnode/core/lib/plugin'
    import { contentTypeAdmin } from '@vitnode/core/lib/plugin'
    import { FolderIcon } from 'lucide-react'
    import { categoryContentType } from '@/content/category'

export const adminContent = {
      pluginId: '@vitnode/example',
      // [!code ++:6]
      contentTypes: [
        contentTypeAdmin({
          definition: categoryContentType,
          icon: <FolderIcon />,
        }),
      ],
    } satisfies ContentFrontendPluginSource
    ```

The sidebar entry comes from `src/admin/nav.tsx` the same way - see
    [Plugin frontend modules](/docs/dev/content-engine/plugin-registration).
  </Step>

<Step>
    ### 3. Add Translations [#3-add-translations]

Name the record in your locale file using ICU cardinal plural:

```json title="plugins/example/src/locales/en.json"
    {
      "@vitnode/example": {
        "content": {
          "category": {
            "label": "{count, plural, one {Category} other {Categories}}",
            "title": "Categories",
            "desc": "Organize posts into categories."
          }
        }
      }
    }
    ```
  </Step>

<Step>
    ### 4. Open the Management Screen [#4-open-the-management-screen]

Visit `http://localhost:3000/admin/content/example/category`.

You have a complete AdminCP data table with search, sorting, pagination, and modal dialogs to create, edit, and delete records.
  </Step>
</Steps>

***

## `defineContentType` Options [#definecontenttype-options]

<TypeTable
  type="{
  id: {
    description: "Unique identifier formatted as '<plugin>.<name>'.",
    required: true,
    type: 'string',
  },
  tableName: {
    description: "Postgres table name (e.g. 'example_categories').",
    required: true,
    type: 'string',
  },
  fields: {
    description: 'Record containing field descriptors created with field.*.',
    required: true,
    type: 'Record<string, ContentField>',
  },
  publication: {
    description:
      'Enables draft/published workflows and publishedAt timestamps.',
    type: '{ enabled: boolean }',
  },
  indexes: {
    description: 'Custom single or composite database indexes.',
    type: 'IndexDefinition[]',
  },
}"
/>

## Learn More [#learn-more]

# Field Reference

Content Engine provides field descriptors exported from `@vitnode/core/content` via the `field` helper. Each field generates a typed Drizzle column, Zod validation schemas, and an interactive AdminCP input automatically.

## Supported Field Types [#supported-field-types]

| Field Method                     | Postgres Column               | Zod Schema            | AdminCP Form Control        |
| :------------------------------- | :---------------------------- | :-------------------- | :-------------------------- |
| `field.text()`                   | `varchar(length)`             | `z.string()`          | Text Input                  |
| `field.textarea()`               | `text()`                      | `z.string()`          | Textarea                    |
| `field.number()`                 | `integer()` / `numeric()`     | `z.number()`          | Number Input                |
| `field.boolean()`                | `boolean()`                   | `z.boolean()`         | Switch Toggle               |
| `field.enum()`                   | `varchar(length)`             | `z.enum([...])`       | Select Dropdown             |
| `field.dateTime()`               | `timestamp()`                 | `z.date()`            | Date / Time Picker          |
| `field.slug()`                   | `varchar(length)`             | `z.string()`          | Slug Generator              |
| `field.user()`                   | `integer()` (FK `core_users`) | `z.number()`          | User Combobox               |
| `field.user({ multiple: true })` | Junction table                | `z.array(z.number())` | Multi-user Combobox         |
| `field.file()`                   | `integer()` (FK `core_files`) | `z.number()`          | Drag-and-drop File Upload   |
| `field.file({ multiple: true })` | Junction table                | `z.array(z.number())` | Multi-file Gallery Uploader |

***

## Field Configurations [#field-configurations]

<Steps>
  <Step>
    ### Text and Strings [#text-and-strings]

Configure string length, required state, and multi-language support:

```ts title="plugins/blog/src/content/post.ts"
    import { defineContentType, field } from "@vitnode/core/content"

export const postContentType = defineContentType({
      id: "blog.post",
      tableName: "blog_posts",
      fields: {
        // [!code ++:10]
        title: field.text({
          required: true,
          minLength: 3,
          maxLength: 200,
          searchable: true,
          translatable: true,
        }),
        summary: field.textarea({
          maxLength: 500,
          translatable: true,
        }),
      },
    })
    ```
  </Step>

<Step>
    ### Numbers, Booleans, and Enums [#numbers-booleans-and-enums]

```ts title="plugins/blog/src/content/post.ts"
    fields: {
      // [!code ++:13]
      views: field.number({
        defaultValue: 0,
        min: 0,
        sortable: true,
      }),
      featured: field.boolean({
        defaultValue: false,
      }),
      status: field.enum({
        values: ["draft", "published", "archived"] as const,
        defaultValue: "draft",
      }),
    }
    ```
  </Step>

<Step>
    ### Slugs, Dates, and User Relations [#slugs-dates-and-user-relations]

Auto-generate SEO slugs from other fields, pick dates, or link authors:

```ts title="plugins/blog/src/content/post.ts"
    fields: {
      // [!code ++:12]
      slug: field.slug({
        from: "title", // Automatically generated from title
        required: true,
      }),
      publishedAt: field.dateTime({
        defaultValue: () => new Date(),
      }),
      author: field.user({
        required: true,
      }),
      contributors: field.user({
        multiple: true,
      }),
    }
    ```
  </Step>

<Step>
    ### Single and Multi-File Uploads [#single-and-multi-file-uploads]

VitNode connects file fields directly to `core_files` with storage adapters (Local disk, S3, Cloudflare R2):

```ts title="plugins/blog/src/content/post.ts"
    fields: {
      // Single cover image (max 5 MB)
      // [!code ++:7]
      coverImage: field.file({
        required: false,
        maxBytes: 5 * 1024 * 1024,
        allowedExtensions: ["jpg", "png", "webp"],
        allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
      }),

// Gallery of screenshots
      // [!code ++:7]
      gallery: field.file({
        multiple: true,
        maxFiles: 10,
        maxBytes: 10 * 1024 * 1024,
        allowedExtensions: ["jpg", "png", "webp"],
      }),
    }
    ```

<Callout type="info" title="Automatic Multipart Upload Pipeline">
      In the AdminCP, `AutoFormFile` uploads attachments via TanStack Query and standard multipart API routes (`POST /api/.../uploads/{field}`). Uploaded records are stored in `core_files` and assigned by ID.
    </Callout>
  </Step>
</Steps>

***

## Common Field Options [#common-field-options]

Every field descriptor accepts these standard attributes:

<TypeTable
  type="{
  required: {
    default: "false",
    description: "Whether the field must have a non-null value.",
    type: "boolean",
  },
  defaultValue: {
    description: "Fallback value for record creation.",
    type: "T | (() => T)",
  },
  searchable: {
    default: "false",
    description: "Include field in full-text and table search queries.",
    type: "boolean",
  },
  sortable: {
    default: "false",
    description: "Allow AdminCP and API consumers to order by this column.",
    type: "boolean",
  },
  translatable: {
    default: "false",
    description: "Store separate values per locale with automatic fallback.",
    type: "boolean",
  },
  description: {
    description: "Helper text rendered below the form input in AdminCP.",
    type: "string",
  },
}"
/>

## Learn More [#learn-more]

# Content Engine Overview

Content Engine eliminates boilerplate for structured data. From a single TypeScript definition, it automatically generates a PostgreSQL table, Zod validation schemas, Hono CRUD endpoints, staff permissions, and AdminCP data management screens.

## Quick start [#quick-start]

### 1. Declare the Definition [#1-declare-the-definition]

```ts title="plugins/blog/src/content/category.ts"
import { defineContentType, field } from "@vitnode/core/content"

export const categoryContentType = defineContentType({
  id: "blog.category",
  tableName: "blog_categories",
  fields: {
    name: field.text({ required: true, minLength: 2, maxLength: 100 }),
    slug: field.slug({ from: "name", required: true }),
  },
})
```

***

### 2. Compile the Database Model [#2-compile-the-database-model]

```ts title="plugins/blog/src/database/categories.ts"
import { createContentModel } from "@vitnode/core/content/server"
import { categoryContentType } from "../content/category"

export const categoryContent = createContentModel(categoryContentType)
export const blog_categories = categoryContent.table
```

***

### 3. Build & Migrate [#3-build--migrate]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Build and migrate">
  <Tab value="bun">
    ```bash
    bun run build:plugins && bun run db:migrate
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm build:plugins && pnpm db:migrate
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run build:plugins && npm run db:migrate
    ```
  </Tab>
</Tabs>

PostgreSQL now contains your table, and AdminCP screens are ready at `/admin/content/blog/categories`.

***

## Generated Features [#generated-features]

| Layer          | Output                                                                     |
| :------------- | :------------------------------------------------------------------------- |
| **Database**   | Drizzle schema table with foreign keys and index constraints               |
| **Validation** | Strongly typed Zod schemas for create, update, and filter operations       |
| **Hono API**   | Complete CRUD endpoints with staff permission protection                   |
| **AdminCP UI** | Data table with cursor pagination, sorting, search, and AutoForm dialogs   |
| **Events**     | `content.{id}.created`, `content.{id}.updated`, and `content.{id}.deleted` |

## Documentation Guides [#documentation-guides]

# Localization & Translations

Content Engine supports localized fields, storing translatable text in dedicated per-language tables (`{tableName}_translations`) while keeping shared fields in the main table.

## Prerequisites & Context [#prerequisites--context]

Multi-language support is configured in your client-safe definition file `src/content/article.ts`.

When `createContentModel` compiles a localized model, it automatically generates a separate secondary database table (`{tableName}_translations`) to hold per-language strings without altering the schema of the main table.

***

## Step-by-Step Multi-Language Setup [#step-by-step-multi-language-setup]

<Steps>
  <Step>
    ### Step 1: Mark Localized Fields in Definition [#step-1-mark-localized-fields-in-definition]

Set `localization` settings and add `localized: true` to translatable fields in `src/content/article.ts`:

```ts title="src/content/article.ts"
    export const articleContentType = defineContentType({
      id: 'example.article',
      tableName: 'example_articles',
      localization: {
        // [!code ++]
        defaultLanguage: 'en', // [!code ++]
      }, // [!code ++]
      fields: {
        code: field.text({ required: true }), // Shared field in main table
        title: field.text({ required: true, localized: true }), // Translatable field // [!code ++]
        content: field.textarea({ localized: true }), // Translatable field // [!code ++]
      },
    })
    ```
  </Step>

<Step>
    ### Step 2: Understand the Database Tables [#step-2-understand-the-database-tables]

Compiling this model automatically builds two PostgreSQL tables:

1. **Main Table** (`example_articles`): Stores `id`, `code`, timestamps, and shared non-localized columns.
    2. **Translation Table** (`example_articles_translations`): Stores `id`, foreign key `article_id`, `locale` (`varchar(10)`), `title`, and `content`.

```text
      example_articles                  example_articles_translations
      ┌─────┬────────┬──────────┐       ┌─────┬────────────┬────────┬────────┬─────────┐
      │ id  │  code  │ author   │ ◄───┐ │ id  │ article_id │ locale │ title  │ content │
      ├─────┼────────┼──────────┤     │ ├─────┼────────────┼────────┼────────┼─────────┤
      │  1  │ ART-01 │  User #5 │     └─│ 101 │     1      │   en   │ Hello  │ World   │
      └─────┴────────┴──────────┘       │ 102 │     1      │   fr   │ Bonjour│ Monde   │
                                        └─────┴────────────┴────────┴────────┴─────────┘
    ```
  </Step>

<Step>
    ### Step 3: Render Localized Content with i18n Fallbacks [#step-3-render-localized-content-with-i18n-fallbacks]

When fetching localized content via public API or `resolveContentDelivery`, translatable fields (`title`, `content`) resolve in the active locale.

For UI wrapper elements (e.g. status badges, section headers), use `useTranslations` from `use-intl`:

```tsx title="src/components/article-card.tsx"
    import { useTranslations } from 'use-intl' // [!code ++]

interface Props {
      article: {
        title: string // Already resolved to current locale by Content Engine
        content: string
      }
    }

export const ArticleCard = ({ article }: Props) => {
      const t = useTranslations('@vitnode/example') // [!code ++]

return (
        <div className="card">
          <span className="badge">{t('content.article.badge_label')}</span>{' '}
          {/* [!code ++] */}
          <h3>{article.title}</h3>
          <p>{article.content}</p>
        </div>
      )
    }
    ```

**Fallback Flow**:

1. Returns `fr` translation if published.
    2. Falls back to `defaultLanguage` (`en`) if published.
    3. Returns `404 Not Found` if no published translation exists.
  </Step>
</Steps>

***

## AdminCP Translation Features [#admincp-translation-features]

* **Language Selector Tabs**: Automatically rendered in AdminCP form dialogs.
* **Independent Status**: Each translation language manages its own draft/published lifecycle.
* **Independent Revisions**: Rollbacks can be performed per-locale without impacting other languages.

# Plugin Frontend Modules

To keep the AdminCP sidebar light while lazy-loading heavy rich text editors on demand, plugins separate frontend code into three clean modules.

## The Three Frontend Modules [#the-three-frontend-modules]

***

## 1. `admin/nav.tsx` (Sidebar Navigation) [#1-adminnavtsx-sidebar-navigation]

Kept deliberately minimal so the AdminCP shell loads navigation without pulling in heavy editing components:

```tsx title="plugins/blog/src/admin/nav.tsx"
import type { AdminNavPluginSource } from '@vitnode/core/lib/plugin'
import { FileTextIcon } from 'lucide-react'
import { postContentType } from '@/content/post'

export const postNav = {
  definition: postContentType,
  icon: <FileTextIcon />,
}

export const adminNav = {
  pluginId: 'blog',
  contentTypes: [postNav],
} satisfies AdminNavPluginSource
```

***

## 2. `admin/content.tsx` (Editing Screens & Overrides) [#2-admincontenttsx-editing-screens--overrides]

Loaded only when an administrator navigates into Content Engine screens:

```tsx title="plugins/blog/src/admin/content.tsx"
import { contentTypeAdmin } from '@vitnode/core/lib/plugin'
import { postNav } from './nav'

export const adminContent = {
  pluginId: 'blog',
  contentTypes: [
    contentTypeAdmin({
      ...postNav,
      // Optional field or layout overrides
    }),
  ],
}
```

***

## 3. `config.tsx` (Root Plugin Config) [#3-configtsx-root-plugin-config]

The factory a host registers in `vitnode.config.ts`. It is bundled for the
browser with the document shell, so it carries only what a browser may hold:
the plugin id, its locale barrel and its route declarations.

```tsx title="plugins/blog/src/config.tsx"
import { buildPlugin } from '@vitnode/core/lib/plugin'
import messages from './locales'
import { routes } from './routes'

export const blogPlugin = () =>
  buildPlugin({
    pluginId: 'blog',
    messages,
    routes,
  })
```

Do not spread `admin/nav` or `admin/content` into it. The build generates one
literal import of each per configured plugin - `admin/nav` with the AdminCP
shell, `admin/content` behind a dynamic `import()` - so an editing screen arrives
with the route that renders it. Spreading them into the factory puts the whole
editing stack, rich text editor included, into every public page's bundle. See
[Configuration](/docs/dev/configuration).

***

## Package Exports Configuration [#package-exports-configuration]

Declare the subpaths in your plugin's `package.json`:

```json title="plugins/blog/package.json"
{
  "exports": {
    "./config": "./dist/src/config.js",
    "./admin/nav": "./dist/src/admin/nav.js",
    "./admin/content": "./dist/src/admin/content.js"
  }
}
```

## Learn More [#learn-more]

# Production & Security

Deploying Content Engine models to production environments requires understanding concurrency protections, database security, performance indexing, and architectural boundaries.

## Prerequisites & Context [#prerequisites--context]

Production hardening applies to both your client definition `articleContentType` and compiled server model `articleContent`:

* **Concurrency Locks**: `ContentVersionConflict` is thrown when updating an `editorial: true` content type whose `version` has changed concurrently.
* **Staff Permissions**: Enforced automatically by `buildContentAdminModule` for all CRUD routes.
* **Diagnostics**: `getContentEngineDiagnostics()` provides startup and registered content type metrics.

***

## Step-by-Step Production Best Practices [#step-by-step-production-best-practices]

<Steps>
  <Step>
    ### Step 1: Handle Concurrency & Optimistic Lock Retries [#step-1-handle-concurrency--optimistic-lock-retries]

When `editorial` is enabled, update operations expect a matching `version` integer. Handle `ContentVersionConflict` by re-fetching and retrying:

```ts
    import { ContentVersionConflict } from '@vitnode/core/content'

try {
      await service.update(articleId, { title: 'New Title', version: 2 })
    } catch (err) {
      if (err instanceof ContentVersionConflict) {
        // [!code ++]
        // Refetch latest record version and retry update // [!code ++]
        const latest = await service.findById(articleId) // [!code ++]
        await service.update(articleId, {
          title: 'New Title',
          version: latest.version,
        }) // [!code ++]
      }
    }
    ```
  </Step>

<Step>
    ### Step 2: Enforce Staff Permissions and Public Allowlists [#step-2-enforce-staff-permissions-and-public-allowlists]

Ensure all custom administrative actions check staff permissions, and verify that `publicApi.fields` lists only non-sensitive attributes:

```ts title="src/content/article.ts"
    export const articleContentType = defineContentType({
      id: 'example.article',
      tableName: 'example_articles',
      publication: true,
      publicApi: {
        fields: ['title', 'code', 'excerpt'],
      },
      fields: {
        title: field.text({ required: true }),
        code: field.text({ required: true }),
        excerpt: field.textarea({ nullable: true }),
        internalNotes: field.textarea({ nullable: true }), // Private internal column
      },
    })
    ```
  </Step>

<Step>
    ### Step 3: Inspect Engine Diagnostics [#step-3-inspect-engine-diagnostics]

Log diagnostic info during startup or debugging:

```ts
    import { getContentEngineDiagnostics } from '@vitnode/core/content/server'

const diagnostics = getContentEngineDiagnostics()
    console.log(`Registered Content Types: ${diagnostics.totalContentTypes}`)
    ```
  </Step>
</Steps>

***

## Architectural Boundaries & System Limitations [#architectural-boundaries--system-limitations]

* **Code-First Architecture**: Content types must be declared in TypeScript source control and compiled before migrations are generated. There is no runtime no-code UI for creating tables dynamically.
* **No Direct Schema Polymorphism**: A single field cannot reference multiple unrelated tables. Use structured JSON fields or separate relation tables instead.

# Public API and Caching

Public content is an API concern owned by the plugin. Start with an explicit
allowlist; no field is public just because it looked innocent in a database
column at 2 a.m.

<Steps>
  <Step>
    ### Define the public response [#define-the-public-response]

```ts title="plugins/site-notes/src/content/article.ts"
    export const articleContentType = defineContentType({
      id: '@acme/site-notes.article',
      tableName: 'site_notes_articles',
      fields: {
        adminNotes: field.textarea({ nullable: true }),
        excerpt: field.textarea({ nullable: true }),
        slug: field.slug({ source: 'title' }),
        title: field.text({ required: true }),
      },
      // [!code ++:5]
      publicApi: {
        enabled: true,
        fields: ['id', 'title', 'slug', 'excerpt', 'publishedAt'],
        path: 'articles',
      },
    })
    ```

`adminNotes` remains private because it is not in `fields`.
  </Step>

<Step>
    ### Build the public module in the plugin API [#build-the-public-module-in-the-plugin-api]

```ts title="plugins/site-notes/src/config.api.ts"
    import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
    import { buildContentPublicModule } from '@vitnode/core/content/server'

import { CONFIG_PLUGIN } from './const'
    import { articleContent } from './database/articles'

export const siteNotesApiPlugin = () =>
      buildApiPlugin({
        pluginId: CONFIG_PLUGIN.pluginId,
        modules: [
          // [!code ++:4]
          buildContentPublicModule({
            contentTypes: [articleContent],
            pluginId: CONFIG_PLUGIN.pluginId,
          }),
        ],
      })
    ```

The module serves published records under the plugin’s public content path, for
    example `/api/@acme/site-notes/articles`.
  </Step>

<Step>
    ### Only configure revalidation when a front end caches renders [#only-configure-revalidation-when-a-front-end-caches-renders]

Content mutations already invalidate VitNode’s content tags. If a separate front
    end caches its rendered pages, add its origin so the API can notify it through
    the framework-neutral revalidation endpoint:

```ts title="apps/api/src/vitnode.api.config.ts"
    export const vitNodeApiConfig = buildApiConfig({
      content: {
        // [!code ++]
        revalidateOrigins: ['https://www.example.com'],
      },
    })
    ```

Leave this unset when the front end reads directly from the public content API.
    There is no server action to wire up in a plugin.
  </Step>
</Steps>

## Keep the public surface intentional [#keep-the-public-surface-intentional]

Use a plugin route for the page that consumes the endpoint, and add search
indexing only when users need to discover the content outside its own section.

<Cards>
  <Card icon="<NetworkIcon />" title="Plugin API modules" description="Add typed Hono modules and routes alongside the feature they serve." href="/docs/dev/plugins/api/modules" />

<Card icon="<SearchIcon />" title="Search" description="Choose Postgres or Elasticsearch search for plugin-owned records." href="/docs/dev/search" />
</Cards>

# Publication & Editorial

Content Engine includes complete editorial workflows: draft and published states, historical revisions with one-click restore, signed reviewer preview URLs, and automated scheduled publishing.

## Quick start [#quick-start]

Enable publication and editorial options in your content type:

```ts title="plugins/blog/src/content/post.ts"
import { defineContentType, field } from "@vitnode/core/content"

export const blogPostContentType = defineContentType({
  id: "blog.post",
  tableName: "blog_posts",
  // [!code ++:8]
  publication: { enabled: true },
  editorial: {
    enabled: true,
    revisions: { retention: 20 }, // Store up to 20 historical versions
    preview: { enabled: true, expiresInMinutes: 60 },
    scheduling: { enabled: true },
  },
  fields: {
    title: field.text({ required: true }),
  },
})
```

{/* Image prompt: VitNode AdminCP Article editor header with "Draft" badge, "Publish" action button, and a dropdown menu showing "Revision History", "Share Preview Link", and "Schedule Publication". Dark theme, 1440x900. */}

***

## Editorial Features [#editorial-features]

### 1. Publication Lifecycle [#1-publication-lifecycle]

When `publication: { enabled: true }` is enabled:

* Records carry a `status` column (`draft` or `published`) and a `publishedAt` timestamp.
* Unauthenticated public queries automatically filter out drafts.
* Publishing is idempotent: the first publish stamps `publishedAt`, while subsequent edits preserve original publication dates.

***

### 2. Revision History [#2-revision-history]

Each save creates an immutable snapshot in the generated revisions table:

* Editors can inspect diffs between any historical version and current state.
* One-click restore reinstates previous content while logging the change.

***

### 3. Signed Preview Links [#3-signed-preview-links]

Share unpublished drafts with stakeholders who lack AdminCP accounts:

* Generates HMAC-signed URLs valid for a customizable duration (e.g. 60 minutes).
* Public frontend routes verify the preview token and stream the draft.

***

### 4. Scheduled Publishing [#4-scheduled-publishing]

Pick a future release date and time:

* The background cron worker checks scheduled items periodically.
* Automatically transitions records to `published` at the specified timestamp.

## Learn More [#learn-more]

# Relations & Advanced Modeling

Content Engine uses real relational modeling rather than unstructured JSON blobs. To-many relations generate indexed junction tables, repeatables generate child tables with foreign keys, and groups map to structured columns.

## Quick start: To-One Relation [#quick-start-to-one-relation]

Connect an article to a single category:

### 1. Declare the Field [#1-declare-the-field]

```ts title="plugins/blog/src/content/article.ts"
import { defineContentType, field } from "@vitnode/core/content"
import { categoryContentType } from "./category"

export const articleContentType = defineContentType({
  id: "blog.article",
  tableName: "blog_articles",
  fields: {
    title: field.text({ required: true }),
    // [!code ++:5]
    category: field.relation({
      required: true,
      onDelete: "restrict",
      target: () => categoryContentType,
    }),
  },
})
```

### 2. Connect Drizzle References [#2-connect-drizzle-references]

```ts title="plugins/blog/src/database/articles.ts"
import { createContentModel } from "@vitnode/core/content/server"
import { articleContentType } from "../content/article"
import { blog_categories } from "./categories"

export const articleContent = createContentModel(articleContentType, {
  // [!code ++:3]
  references: {
    category: () => blog_categories.id,
  },
})
```

***

## Relation Shapes [#relation-shapes]

| Shape                | Declaration                                  | Database Structure                      |
| :------------------- | :------------------------------------------- | :-------------------------------------- |
| **To-One**           | `field.relation({ target })`                 | Foreign key column on table             |
| **To-Many**          | `field.relation({ target, multiple: true })` | Auto-generated junction table           |
| **Self-Referencing** | `field.relation({ self: true })`             | FK to same table (e.g. parent category) |
| **User Relation**    | `field.user({ multiple?: boolean })`         | FK / junction to `core_users`           |
| **File Relation**    | `field.file({ multiple?: boolean })`         | FK / junction to `core_files`           |

***

## To-Many Relations & Junction Tables [#to-many-relations--junction-tables]

Support multi-category selection or ordered co-authors:

```ts title="plugins/blog/src/content/post.ts"
fields: {
  // [!code ++:6]
  categories: field.relation({
    multiple: true,
    min: 1, // Enforce at least 1 selected
    target: () => categoryContentType,
  }),
  authors: field.user({
    multiple: true,
    ordered: true, // Preserves drag-and-drop order
  }),
}
```

***

## Field Groups (`field.group`) [#field-groups-fieldgroup]

Group related fields into a single nested object:

```ts
fields: {
  // [!code ++:7]
  seo: field.group({
    fields: {
      metaTitle: field.text({ maxLength: 70 }),
      metaDescription: field.textarea({ maxLength: 160 }),
      noIndex: field.boolean({ defaultValue: false }),
    },
  }),
}
```

Columns are created as `seo_meta_title`, `seo_meta_description`, and `seo_no_index` on the main table.

***

## Repeatable Child Rows (`field.repeatable`) [#repeatable-child-rows-fieldrepeatable]

Create structured arrays backed by a real child table:

```ts
fields: {
  // [!code ++:7]
  faqItems: field.repeatable({
    min: 1,
    max: 10,
    fields: {
      question: field.text({ required: true }),
      answer: field.textarea({ required: true }),
    },
  }),
}
```

***

## `field.relation` Options [#fieldrelation-options]

<TypeTable
  type="{
  target: {
    description: "Function returning the target ContentTypeDefinition.",
    type: "() => ContentTypeDefinition",
  },
  multiple: {
    default: "false",
    description: "Whether the field allows selecting multiple target records.",
    type: "boolean",
  },
  self: {
    default: "false",
    description: "Creates a recursive foreign key to this same content type.",
    type: "boolean",
  },
  onDelete: {
    default: "'restrict'",
    description: "Postgres referential action on target deletion.",
    type: "'cascade' | 'restrict' | 'set null'",
  },
  ordered: {
    default: "false",
    description: "Preserves user-defined order in junction tables.",
    type: "boolean",
  },
}"
/>

## Learn More [#learn-more]

# Content Services & API

When you compile a content type with `createContentModel`, it provides a typed service, Zod validation schemas, and database events that can be used directly inside custom Hono endpoints.

## Quick start [#quick-start]

Access the typed repository in any Hono route via `model.service(c)`:

```ts title="plugins/blog/src/api/modules/articles/routes/featured.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route"
import { articleContent } from "@/database/articles"

export const featuredRoute = buildRoute({
  pluginId: "blog",
  route: {
    method: "get",
    path: "/featured",
    responses: { 200: { description: "Featured articles" } },
  },
  handler: async (c) => {
    // [!code ++:6]
    const { edges, pageInfo } = await articleContent.service(c).findMany({
      filters: { featured: true },
      orderBy: { column: "createdAt", order: "desc" },
      query: { first: "5" },
    })

return c.json({ edges, pageInfo })
  },
})
```

`findMany` returns `{ edges, pageInfo }` formatted for cursor-based pagination.

***

## Service Methods Reference [#service-methods-reference]

The service returned by `model.service(c)` includes standard repository methods:

| Method     | Parameters                      | Returns                              |
| :--------- | :------------------------------ | :----------------------------------- |
| `findMany` | `{ query, filters?, orderBy? }` | `{ edges: T[], pageInfo: PageInfo }` |
| `findById` | `id: number`                    | `Promise<T \| null>`                 |
| `create`   | `data: CreateInput`             | `Promise<T>`                         |
| `update`   | `id: number, data: UpdateInput` | `Promise<T>`                         |
| `delete`   | `id: number`                    | `Promise<void>`                      |

***

## Generated Zod Schemas [#generated-zod-schemas]

Use generated validation schemas in custom routes:

```ts
import { articleContent } from "@/database/articles"

export const createArticleRoute = buildRoute({
  pluginId: "blog",
  route: {
    method: "post",
    path: "/",
    request: {
      body: {
        content: {
          "application/json": {
            // [!code ++:1]
            schema: articleContent.schemas.create,
          },
        },
      },
    },
  },
  handler: async (c) => {
    const data = c.req.valid("json")
    const article = await articleContent.service(c).create(data)
    return c.json(article, 201)
  },
})
```

***

## Content Engine Events [#content-engine-events]

Content modifications automatically emit typed domain events on the event bus:

```ts title="plugins/blog/src/api/lib/listeners.ts"
import { buildEventListener } from "@vitnode/core/api/lib/events"

export const onArticleCreated = buildEventListener({
  event: "content.article.created",
  name: "notify-subscribers",
  handler: async (c, payload) => {
    await c.get("queue").dispatch({
      name: "broadcast-new-article",
      payload: { articleId: payload.id },
    })
  },
})
```

Standard events include `content.{id}.created`, `content.{id}.updated`, and `content.{id}.deleted`.

## Learn More [#learn-more]

# Contributing

Contributions to VitNode - whether bug fixes, new features, or documentation improvements - are always welcome!

## Quick start [#quick-start]

Clone the repository, start local containers, and launch the dev server:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Setup VitNode monorepo">
  <Tab value="bun">
    ```bash
    bun install
    bun run docker:dev
    bun dev
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm install
    pnpm docker:dev
    pnpm dev
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm install
    npm run docker:dev
    npm run dev
    ```
  </Tab>
</Tabs>

Open `http://localhost:3000` to view the website, AdminCP, and live docs.

***

## Monorepo Layout [#monorepo-layout]

| Directory          | Role                                                                        |
| :----------------- | :-------------------------------------------------------------------------- |
| `packages/vitnode` | `@vitnode/core` package containing routing, auth, models, and UI primitives |
| `apps/web`         | Frontend TanStack Start application and documentation portal                |
| `apps/api`         | Standalone Hono REST/RPC API server                                         |
| `plugins/*`        | First-party plugins (`@vitnode/blog`, `@vitnode/example`)                   |

***

## Local Validation Checks [#local-validation-checks]

Before opening a pull request, run the same checks that execute in GitHub Actions CI:

### 1. Typecheck [#1-typecheck]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Typecheck">
  <Tab value="bun">
    ```bash
    bun run typecheck
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm typecheck
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run typecheck
    ```
  </Tab>
</Tabs>

### 2. Run Tests [#2-run-tests]

### 3. Build All Workspaces [#3-build-all-workspaces]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Build workspaces">
  <Tab value="bun">
    ```bash
    bun run build
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm build
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run build
    ```
  </Tab>
</Tabs>

***

## Pull Request Guidelines [#pull-request-guidelines]

1. **Focused PRs**: Keep changes scoped to a single feature or bug fix.
2. **Follow Conventions**: Follow repository conventions from `AGENTS.md` (no `any`, arrow function components, semantic tokens).
3. **Tests**: Add unit tests for non-trivial logic using Vitest.

## Learn More [#learn-more]

# Custom Adapter

A cron adapter is the thinnest interface in VitNode: one method, no return value,
called once while the API boots. Its whole job is to call `handleCronJobs()` on a
clock. Everything else - which jobs exist, which are due, what gets logged - is
the [cron endpoint](/docs/dev/cron/rest-api)'s business, not the adapter's.

Write one when the [Node CRON adapter](/docs/dev/cron/node-cron) is not the
scheduler you want: you already run a job runner, you need the tick to carry a
trace header, or the platform hands you a trigger of its own.

## Quick start [#quick-start]

The shortest adapter that works is a timer:

```ts title="src/adapters/interval-cron.adapter.ts"
import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'

export const IntervalCronAdapter = (): CronAdapter => ({
  schedule() {
    setInterval(() => {
      handleCronJobs().catch((error: unknown) => {
        console.error('[cron] tick failed', error)
      })
    }, 60_000)
  },
})
```

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { IntervalCronAdapter } from './adapters/interval-cron.adapter' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  cron: IntervalCronAdapter(), // [!code ++]
  // ...
})
```

That is a complete, working adapter. The rest of this page is about doing it with
a real scheduler, and about the ways it can go quietly wrong.

## The interface [#the-interface]

```ts title="packages/vitnode/src/api/lib/cron.ts"
export interface CronAdapter {
  schedule: () => void
}
```

<TypeTable
  type="{
  schedule: {
    description:
      'Called once by VitNodeAPI while the application is being built, before any request is served. Register your timer or trigger here. Synchronous and void - nothing awaits it and nothing catches it.',
    type: '() => void',
    required: true,
  },
}"
/>

`handleCronJobs()` comes from the same module and takes no arguments. It posts to
`/api/@vitnode/core/cron` on the origin in `NEXT_PUBLIC_API_URL` (falling back to
`http://localhost:3000`) with `Content-Type: application/json` and
`Authorization: Bearer $CRON_SECRET`. It resolves as soon as the response
arrives and never looks at it, so a `403` or a `500` resolves exactly like a
`200` - only a network-level failure rejects.

<Callout type="info" title="You do not have to use handleCronJobs">
  It is a convenience, not a contract. An adapter whose scheduler lives outside
  the process - a platform trigger, a separate worker - can leave `schedule()`
  empty and let that scheduler [call the endpoint
  directly](/docs/dev/cron/rest-api). The adapter still earns its place: setting
  `cron` is what makes the AdminCP report a scheduler as configured.
</Callout>

## Build one with a library [#build-one-with-a-library]

<Steps>
  <Step>
    ### Write the adapter [#write-the-adapter]

Keep it in your app rather than in a plugin - a cron adapter is a deployment
    decision, and it is registered from the API config, which only the host has.

The official package is the reference implementation, and it is short enough to
    read in one go:

```ts title="src/adapters/node-cron.adapter.ts"
    import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'
    import { schedule } from 'node-cron'

export const NodeCronAdapter = (): CronAdapter => {
      return {
        schedule() {
          schedule('*/1 * * * *', async () => {
            await handleCronJobs() // [!code highlight]
          })
        },
      }
    }
    ```

Give the factory options if your scheduler has any worth exposing - a tick
    interval, a timezone, a logger. `CronAdapter` says nothing about the factory, so
    its signature is yours.
  </Step>

<Step>
    ### Register it in the API config [#register-it-in-the-api-config]

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { NodeCronAdapter } from './adapters/node-cron.adapter' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      cron: NodeCronAdapter(), // [!code ++]
      // ...
    })
    ```
  </Step>

<Step>
    ### Restart and verify the first tick [#restart-and-verify-the-first-tick]

`schedule()` runs at boot, so a running process never picks up the change.

Open `/admin/core/advanced/cron` and watch the `process-queue` row - it is
    scheduled `* * * * *`, so a healthy adapter keeps its **Last Run** under a minute
    old. If it stays on *Never*, your `schedule()` ran but your tick is not landing:
    check the origin, then the secret, then whether the API can reach itself.
  </Step>
</Steps>

## Gotchas [#gotchas]

<Callout type="warn" title="A throw in schedule() takes the API down">
  VitNode calls `schedule()` synchronously while building the application and
  does not wrap it. An adapter that validates its own options by throwing turns
  a bad cron expression into a server that will not start. Validate, log, and
  return instead.
</Callout>

<Callout type="warn" title="schedule() can be called more than once per process">
  There is no `stop` and no teardown hook, and a dev server that re-evaluates
  its server modules can build the API again. VitNode's TanStack Start app parks
  the API instance on `globalThis` for exactly this reason - if yours does not,
  an adapter that keeps a timer should be able to notice it already has one
  instead of stacking a second.
</Callout>

<Callout type="warn" title="Ticking faster does not make a job faster">
  The endpoint runs what is due when it is called, so the tick interval is the
  floor on every job's resolution - but it is not a speed control. A tick every
  ten seconds on jobs that are all `*/5 * * * *` is five wasted requests a
  minute, and a tick every five minutes silently downgrades `* * * * *` jobs,
  [queue draining](/docs/dev/advanced/queue) included.
</Callout>

<Callout type="warn" title="Overlapping ticks are your problem, not the adapter's">
  Nothing locks a job while it runs. If your scheduler can fire again before the
  previous tick's handlers have finished, the same handler can be running twice.
  [The operational rules](/docs/dev/cron#jobs-must-be-idempotent) cover what to
  do about it.
</Callout>

## Next [#next]

# Cron Jobs

A cron job in VitNode consists of a named handler and a standard 5-field cron expression. Cron definitions are automatically registered in the `core_cron` database table and manageable through the AdminCP.

## Quick start [#quick-start]

### 1. Define a Cron Job [#1-define-a-cron-job]

Create a cron definition in your plugin:

```ts title="plugins/blog/src/api/cron/cleanup.cron.ts"
import { buildCron } from "@vitnode/core/api/lib/cron"

export const cleanupCron = buildCron({
  name: "cleanup-drafts",
  description: "Remove expired post drafts every midnight",
  schedule: "0 0 * * *", // Standard cron syntax
  handler: async (c) => {
    await c.get("log").info("Running midnight cleanup...")
  },
})
```

***

### 2. Register in an API Module [#2-register-in-an-api-module]

Attach the cron job to a module in `src/api/modules/`:

```ts title="plugins/blog/src/api/modules/posts/posts.module.ts"
import { buildModule } from "@vitnode/core/api/lib/module"
import { cleanupCron } from "../../cron/cleanup.cron"

export const postsModule = buildModule({
  name: "posts",
  routes: [listPostsRoute],
  cronJobs: [cleanupCron], // [!code ++]
})
```

When your plugin is mounted in `config.api.ts`, the cron job is automatically registered.

***

## Execution Adapters [#execution-adapters]

VitNode does not hold persistent timers in the HTTP worker. Instead, jobs are triggered via an adapter:

### Option A: In-Process Node CRON (Single Server) [#option-a-in-process-node-cron-single-server]

Best for single-instance or local development. Configure in `vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { NodeCronAdapter } from "@vitnode/core/api/adapters/cron/node-cron"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  cron: {
    adapter: NodeCronAdapter(), // [!code ++]
  },
})
```

### Option B: External Webhook (Multi-Instance / Serverless) [#option-b-external-webhook-multi-instance--serverless]

Trigger runs via external HTTP schedulers (AWS EventBridge, GitHub Actions, or crontab):

```bash
curl -X POST https://your-domain.com/api/@vitnode/core/cron   -H "Authorization: Bearer $CRON_SECRET"
```

***

## AdminCP Management [#admincp-management]

{/* Image prompt: VitNode AdminCP Cron management page at /admin/core/advanced/cron. Data table displaying scheduled jobs with columns: Name, Schedule, Status, Last Run, Next Run, and an action button "Run Now". Dark theme, 1440x900. */}

Manage and inspect cron jobs in the AdminCP at **Core → Advanced → Cron Jobs** (`/admin/core/advanced/cron`):

* View status, schedules, and last execution logs.
* Click **Run Now** to execute any job manually on demand.

***

## `buildCron` Options [#buildcron-options]

<TypeTable
  type="{
  name: {
    description: "Unique identifier within the plugin (e.g. 'cleanup-drafts').",
    required: true,
    type: "string",
  },
  schedule: {
    description: "Standard 5-part cron pattern (minute hour dom month dow).",
    required: true,
    type: "string",
  },
  handler: {
    description: "Async function executed when the job is triggered.",
    required: true,
    type: "(c: Context) => Promise<void>",
  },
  description: {
    description: "Human-readable purpose shown in AdminCP list.",
    type: "string",
  },
}"
/>

## Learn More [#learn-more]

# Node CRON

`@vitnode/node-cron` is the in-process [cron adapter](/docs/dev/cron): a
[node-cron](https://www.npmjs.com/package/node-cron) timer that lives inside your
API process and posts to the cron endpoint once a minute. No external service, no
scheduler dashboard, nothing to keep in sync - which is exactly why it only works
where your API is a long-lived process.

| Cloud (serverless) | Self-hosted | Links                                                                                                                                       |
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| ❌ Not supported    | ✅ Supported | [npm](https://www.npmjs.com/package/@vitnode/node-cron) · [source](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/node-cron) |

## Quick start [#quick-start]

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']" label="Install the Node CRON adapter">
      <Tab value="bun">
        ```bash
        bun i @vitnode/node-cron
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @vitnode/node-cron
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @vitnode/node-cron
        ```
      </Tab>
    </Tabs>

A runtime dependency, not a dev one - the adapter is imported by the server that
    serves your API, so it has to survive a production install.
  </Step>

<Step>
    ### Register it in the API config [#register-it-in-the-api-config]

`NodeCronAdapter()` takes no arguments. There is nothing to configure, because
    the schedule it keeps is not yours: each job carries its own expression, and this
    only decides how often VitNode looks.

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'
    import { NodeCronAdapter } from '@vitnode/node-cron' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      cron: NodeCronAdapter(), // [!code ++]
      // ...
    })
    ```

This repository's own standalone API does exactly that - see
    `apps/api/src/vitnode.api.config.ts`.
  </Step>

<Step>
    ### Restart the server [#restart-the-server]

`schedule()` is a boot step, not a request step: VitNode calls it once while the
    API is being built, so a running process never picks the adapter up.

<Step>
    ### Verify the first tick [#verify-the-first-tick]

Open `/admin/core/advanced/cron` and watch the `clean` row - core's hourly
    session cleanup, which every installation has. Within a minute of the restart
    **Last Run** stops saying *Never* and **Next Run** fills in.

Nothing else needs to happen for the clock to be proven: `process-queue` runs
    every minute, so its **Last Run** should never be more than a minute old while
    the adapter is alive.
  </Step>
</Steps>

## What the adapter actually does [#what-the-adapter-actually-does]

The whole package is the file below, and knowing it saves an afternoon of
debugging:

```ts title="packages/node-cron/src/index.ts"
import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'
import { schedule } from 'node-cron'

export const NodeCronAdapter = (): CronAdapter => {
  return {
    schedule() {
      schedule('*/1 * * * *', async () => {
        await handleCronJobs()
      })
    },
  }
}
```

`handleCronJobs()` is an **HTTP request to your own API** -
`POST /api/@vitnode/core/cron`, with `Content-Type: application/json` and
`Authorization: Bearer $CRON_SECRET`. The adapter never touches the database and
never calls a job handler; it only knocks on the door once a minute, and the
[cron endpoint](/docs/dev/cron/rest-api) decides what is due.

Three consequences worth writing down:

| Because the tick is an HTTP call…                     | …this is true                                                                          |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| it needs a URL                                        | the origin comes from `NEXT_PUBLIC_API_URL`, falling back to `http://localhost:3000`   |
| the API must be able to reach itself over the network | a tick dies where that origin is wrong, unreachable, or fronted by an auth proxy       |
| the request is authenticated like any other           | an unset `CRON_SECRET` means both sides use the well-known default, and the tick works |

## Gotchas [#gotchas]

<Callout type="warn" title="The tick posts to NEXT_PUBLIC_API_URL, not to the port you booted">
  `handleCronJobs()` builds its URL from `NEXT_PUBLIC_API_URL` and falls back to
  `http://localhost:3000`. This repo's standalone API listens on **8000** -
  which is exactly why `apps/api/.env.example` sets the variable - so leaving it
  unset sends every tick to port 3000, where the web app lives. Symptom: the
  scheduler is configured, the boot log is clean, and **Last Run** stays *Never*
  forever.
</Callout>

<Callout type="warn" title="A rejected tick leaves no trace">
  `handleCronJobs()` awaits the `fetch` and then discards the response, and a
  `403` is answered by middleware rather than by the route: the CSRF check runs
  before the logger even exists, and a mismatched secret raises an
  `HTTPException` that the API's error handler returns without logging. So the
  failure you are most likely to hit writes nothing to the console and nothing
  to the [Debug Panel](/docs/dev/debugging/logging). The AdminCP's **Last Run**
  column is the health check.
</Callout>

<Callout type="warn" title="Every instance runs its own timer">
  The adapter schedules per process, so four instances send four ticks a minute.
  That is safe - the endpoint runs only what is due - but it does not
  de-duplicate the work, so two ticks can start the same job at once. Write
  [idempotent handlers](/docs/dev/cron#jobs-must-be-idempotent), or move the
  clock to a single [external scheduler](/docs/dev/cron/rest-api).
</Callout>

<Callout type="warn" title="Serverless has nowhere to keep the timer">
  A function that is frozen between requests cannot hold a one-minute interval,
  so this adapter is not a deployment choice on Vercel-style hosting - it is a
  no-op with a package to maintain. Use the [REST
  endpoint](/docs/dev/cron/rest-api) there.
</Callout>

## Next [#next]

# Cron over REST

Every cron run in VitNode is one HTTP request, so the simplest adapter is no
adapter at all: point something at the endpoint once a minute. That something can
be GitHub Actions, a managed scheduler, a Kubernetes `CronJob` or a systemd
timer. Because it lives outside your app, this is also the only option that works
on serverless hosting, where nothing stays alive long enough to hold a timer.

| Cloud (serverless) | Self-hosted |
| ------------------ | ----------- |
| ✅ Supported        | ✅ Supported |

## Quick start [#quick-start]

```bash
curl -X POST https://example.com/api/@vitnode/core/cron \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CRON_SECRET"
```

```text
Cron jobs processed. Executed 2 jobs.
```

Both headers are load-bearing. The `Authorization` one is the endpoint's only
auth; the `Content-Type` one gets you past CSRF protection, which treats a
`POST` with no content type as a form submission and answers `403 Forbidden`.

## Set it up [#set-it-up]

<Steps>
  <Step>
    ### Set a real CRON\_SECRET [#set-a-real-cron_secret]

The endpoint compares the bearer token against `CRON_SECRET` and refuses
    anything else with a `403`. Leave the variable unset and VitNode falls back to
    `default-cron-secret-change-in-production` - a value published in this
    documentation, which makes the endpoint effectively open to anyone who can guess
    your domain.

```bash title=".env"
    CRON_SECRET=b7c1f0e2d9a84c53b6e1f7a02d48c9e5
    ```

<Callout type="warn" title="This is the one secret an external scheduler carries">
      Use at least 16 random characters, and store it in your scheduler as a secret
      rather than in a URL. Do not expect the AdminCP to nag you about it: the
      Integrations screen only reports the default secret once a `cron` adapter is
      registered in the API config, and an external scheduler registers none - so
      the cron card there says "No cron adapter configured" and stops. On this
      deployment shape, remembering the secret is on you.
    </Callout>
  </Step>

<Step>
    ### Point a scheduler at the endpoint [#point-a-scheduler-at-the-endpoint]

Once a minute, whatever the schedules on your jobs say. The endpoint runs what is
    due *at the moment it is called*, so the tick interval is the finest resolution
    any job can have - and core's own `process-queue` job is `* * * * *`, so a
    slower tick means [queue tasks](/docs/dev/advanced/queue) sit around waiting.

Your scheduler needs three things, and this is where providers differ:

| Requirement                     | Why                                                        |
    | ------------------------------- | ---------------------------------------------------------- |
    | `POST`                          | the route declares `method: "post"` and nothing else       |
    | a custom `Authorization` header | the bearer token is the whole of the auth                  |
    | a custom `Content-Type` header  | `application/json`, or CSRF protection rejects the request |

{/* Image prompt: A generic external cron scheduler's "new job" form, light theme, 1200x800, showing the four fields a reader has to fill in: URL set to https://example.com/api/@vitnode/core/cron, method dropdown set to POST, a schedule field reading "every minute", and a custom-headers table with two rows - "Content-Type: application/json" and "Authorization: Bearer ***". No real vendor branding. */}

A GitHub Actions workflow is the version with no account to create:

```yaml title=".github/workflows/cron.yml"
    name: VitNode cron
    on:
      schedule:
        - cron: '*/5 * * * *'
      workflow_dispatch:

jobs:
      tick:
        runs-on: ubuntu-latest
        steps:
          - run: |
              curl --fail-with-body -X POST "$API_URL/api/@vitnode/core/cron" \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer $CRON_SECRET"
            env:
              API_URL: ${{ vars.API_URL }}
              CRON_SECRET: ${{ secrets.CRON_SECRET }}
    ```

Five minutes, not one: GitHub's shortest schedule interval is five minutes, and
    runs on a busy shared queue are often later than that. It is a fine way to keep
    daily jobs honest and a poor way to drain a queue.
  </Step>

<Step>
    ### Verify it from the AdminCP [#verify-it-from-the-admincp]

Send the request by hand once. A `200` with a job count means the endpoint
    accepted you; open `/admin/core/advanced/cron` and the rows you expected to run
    now show a **Last Run** of a moment ago.

Then leave the scheduler to it and check back. **Last Run** drifting behind a
    job's schedule is the symptom of a tick that is not arriving, and it is the only
    signal that reflects an external scheduler - see the gotcha about the
    Integrations screen below.
  </Step>
</Steps>

## Endpoint reference [#endpoint-reference]

| Property         | Value                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| Method           | `POST`                                                                                                       |
| Path             | `/api/@vitnode/core/cron`                                                                                    |
| Auth             | `Authorization: Bearer $CRON_SECRET` - the prefix is stripped before comparing, so a bare secret matches too |
| Body             | none                                                                                                         |
| Calling it twice | safe: the second call runs only what has become due since the first                                          |

| Response | Body                                    | Means                                                                                               |
| -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `200`    | `Cron jobs processed. Executed N jobs.` | the tick completed; `N` counts the jobs whose handler did **not** throw                             |
| `403`    | `Forbidden`                             | CSRF: a `POST` whose content type is missing, `text/plain` or a form type, with no trusted `Origin` |
| `403`    | `Invalid cron authorization`            | the bearer token does not match `CRON_SECRET`                                                       |
| `500`    | `Error processing cron jobs`            | the bookkeeping itself failed - usually the database                                                |

## Gotchas [#gotchas]

<Callout type="warn" title="Vercel Cron Jobs cannot call this endpoint">
  Vercel triggers a cron path with a `GET`; this route only answers `POST`, so a
  `vercel.json` entry pointed straight at it never runs a job. Use a scheduler
  that can send a `POST` with headers - the [Vercel deployment
  guide](/docs/dev/deployments/cloud/vercel) says the same thing from the other
  side.
</Callout>

<Callout type="warn" title="A 200 does not mean every job succeeded">
  A handler that throws is logged and skipped - the tick still answers `200`,
  and the failed job is simply missing from the count. Worse, its `lastRun` is
  not written, so it is due again on the next tick. Read the failures in the
  [Debug Panel](/docs/dev/debugging/logging); the response only tells you the
  endpoint was reached.
</Callout>

<Callout type="warn" title="Ticking from two places doubles the ticks">
  An external scheduler and the [Node CRON adapter](/docs/dev/cron/node-cron)
  are alternatives, not layers. Configure both and two callers race for the same
  due jobs, which is the situation [idempotent
  handlers](/docs/dev/cron#jobs-must-be-idempotent) exist for.
</Callout>

<Callout type="warn" title="The Integrations screen still calls cron inactive">
  `/admin/core/system/integrations` reports cron as active when the API config
  registers a `cron` adapter - it is reading the config, not counting ticks.
  Tick from outside and that card stays grey however healthy the schedule is,
  and the queue card with it, because the queue's status is derived from cron's.
  The honest signal for an external scheduler is the **Last Run** column on
  `/admin/core/advanced/cron`.
</Callout>

<Callout type="info" title="The endpoint is public in the sense that it answers">
  There is no allowlist and no signature - a correct bearer token is the whole
  gate, and the route is mounted on your public API alongside everything else.
  If your platform can restrict the path to your scheduler's egress addresses,
  that is a second lock worth having.
</Callout>

## Next [#next]

# Data Loading

VitNode loads feature data through plugin routes. `definePluginRoute({ load })`
runs for SSR and client navigation, then hands typed data to the plugin page.

Fetch with the universal [`fetcher`](/docs/dev/fetcher): one call site serves
both, forwarding the visitor's request during SSR and calling `/api/*` directly
from the browser afterwards.

## Quick start [#quick-start]

### 1. In a Plugin Route (Recommended) [#1-in-a-plugin-route-recommended]

Plugins load data using `definePluginRoute`. The loader runs during SSR and client navigation, handing typed `loaderData` to the page component:

```tsx title="plugins/blog/src/pages/announcements-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

interface Announcement {
  id: string
  title: string
}

// [!code ++:6]
export const route = definePluginRoute({
  load: async ({ context }) => {
    return await fetchAnnouncements(context.locale)
  },
})

const AnnouncementsPage = ({
  loaderData,
}: PluginRoutePageProps<Announcement[]>) => (
  <div className="container mx-auto p-4 flex flex-col gap-4">
    {loaderData.map((item) => (
      <h2 key={item.id} className="text-xl font-semibold">
        {item.title}
      </h2>
    ))}
  </div>
)

export default AnnouncementsPage
```

## Invalidating After Mutations [#invalidating-after-mutations]

After creating, editing, or deleting a record, invalidate the query key so TanStack Query refetches fresh data:

```tsx
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { toast } from 'sonner'
import { announcementsQueryKey } from './query'

const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: createAnnouncement,
  onSuccess: async () => {
    // [!code ++:2]
    await queryClient.invalidateQueries({ queryKey: announcementsQueryKey() })
    toast.success('Announcement published!')
  },
})
```

***

## Freshness Constants [#freshness-constants]

VitNode provides standard stale times in `@vitnode/core/lib/query-freshness`:

## Learn More [#learn-more]

# Database & Migrations

VitNode uses [PostgreSQL](https://www.postgresql.org) and [Drizzle ORM](https://orm.drizzle.team). Plugins define typed schema files, compile them into SQL migrations, and query tables via `c.get("db")`.

## Quick start [#quick-start]

### 1. Define the Schema [#1-define-the-schema]

Create a database model in `plugins/{plugin}/src/database/{table}.ts`:

```ts title="plugins/reactions/src/database/reactions.ts"
import { camelCase } from "drizzle-orm/pg-core"

// [!code ++:7]
export const reactions = camelCase.table.withRLS("reactions", (t) => ({
  id: t.serial().primaryKey(),
  itemId: t.integer().notNull(),
  emoji: t.varchar({ length: 32 }).notNull(),
  createdAt: t.timestamp().notNull().defaultNow(),
}))
```

***

### 2. Query in an API Route [#2-query-in-an-api-route]

Access the typed Drizzle instance using `c.get("db")`:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route"
import { reactions } from "@/database/reactions"

export const getReactionsRoute = buildRoute({
  pluginId: "reactions",
  route: {
    method: "get",
    path: "/",
    responses: { 200: { description: "List of reactions" } },
  },
  handler: async (c) => {
    // [!code ++:2]
    const rows = await c.get("db").select().from(reactions)
    return c.json(rows)
  },
})
```

***

### 3. Build & Apply Migrations [#3-build--apply-migrations]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Build and migrate">
  <Tab value="bun">
    ```bash
    bun run build:plugins && bun run db:migrate
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm build:plugins && pnpm db:migrate
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run build:plugins && npm run db:migrate
    ```
  </Tab>
</Tabs>

`build:plugins` compiles your TypeScript models and exports, and `db:migrate` updates PostgreSQL.

***

## Migration Commands [#migration-commands]

<Callout type="info" title="Content Engine Alternative">
  If your table represents an editorial entity (articles, FAQs, products), consider [Content Engine](/docs/dev/content-engine/defining-a-content-type) to generate your Drizzle table, API routes, and AdminCP screens from one definition.
</Callout>

## Learn More [#learn-more]

# Pagination

VitNode uses cursor-based pagination rather than offset pagination. Cursors ensure stable page boundaries even while records are created or deleted, with zero database performance degradation on large tables.

## Quick start [#quick-start]

<Steps>
  <Step>
    ### Add a paginated API route [#add-a-paginated-api-route]

Use `withPagination` from `@vitnode/core/api/lib/with-pagination`:

```ts title="plugins/blog/src/api/modules/posts/routes/get.route.ts"
    import { getColumns } from 'drizzle-orm'
    import {
      withPagination,
      zodPaginationQuery,
    } from '@vitnode/core/api/lib/with-pagination'
    import { blog_posts } from '@/database/posts'

export const getPostsRoute = buildRoute({
      pluginId: 'blog',
      route: {
        method: 'get',
        path: '/',
        request: {
          query: zodPaginationQuery,
        },
      },
      handler: async (c) => {
        const data = await withPagination({
          c,
          params: { query: c.req.valid('query') },
          primaryCursor: blog_posts.id,
          table: blog_posts,
          orderBy: { column: blog_posts.createdAt, order: 'desc' },
          query: async ({ cursorSelection, limit, where, orderBy }) =>
            await c
              .get('db')
              .select({ ...getColumns(blog_posts), ...cursorSelection })
              .from(blog_posts)
              .where(where)
              .orderBy(orderBy)
              .limit(limit),
        })

return c.json(data)
      },
    })
    ```

The route automatically accepts `?cursor=...&first=10` and returns `{ edges, pageInfo }`.
  </Step>
</Steps>

## Why Cursors Over Offsets [#why-cursors-over-offsets]

| Metric                        | `LIMIT ... OFFSET`              | Keyset Cursor                          |
| ----------------------------- | ------------------------------- | -------------------------------------- |
| Insert / Delete mid-walk      | Rows shift, duplicate, or skip  | Unaffected (stable pointer)            |
| Deep pagination (Page 10,000) | Full table scan up to offset    | Single indexed B-tree lookup           |
| Sort order stability          | Prone to non-deterministic ties | Guaranteed by primaryCursor tiebreaker |

***

## `withPagination` Options [#withpagination-options]

<TypeTable
  type="{
  c: {
    description: 'Hono request context.',
    required: true,
    type: 'Context',
  },
  params: {
    description:
      'Validated query parameters: { query: { cursor, first, last, search } }.',
    required: true,
    type: 'object',
  },
  table: {
    description: 'Drizzle table being paged (used for total count).',
    required: true,
    type: 'PgTable',
  },
  primaryCursor: {
    description: 'Unique numeric column acting as deterministic tiebreaker.',
    required: true,
    type: 'PaginationCursorColumn',
  },
  orderBy: {
    description: 'Sorting column and direction.',
    required: true,
    type: "{ column: PgColumn; order: 'asc' | 'desc' }",
  },
  query: {
    description: 'Callback executing the paged Drizzle select query.',
    required: true,
    type: '(args) => Promise<Row[]>',
  },
  where: {
    description:
      'Additional SQL filter conditions applied before pagination.',
    required: false,
    type: 'SQL',
  },
  search: {
    description:
      'Array of text columns to match against ?search= with ILIKE.',
    required: false,
    type: 'PgColumn[]',
  },
}"
/>

***

## Response Structure (`pageInfo`) [#response-structure-pageinfo]

```json
{
  "edges": [
    { "id": 1, "title": "First post", "createdAt": "2026-01-01T00:00:00.000Z" }
  ],
  "pageInfo": {
    "totalCount": 120,
    "count": 10,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "eyJjIjoiY3Jl...",
    "endCursor": "eyJjIjoiY3Jl..."
  }
}
```

***

## Frontend Integration [#frontend-integration]

<Steps>
  <Step>
    ### Move through results from a plugin page [#move-through-results-from-a-plugin-page]

Plugin routes normalize their own query string with `parseSearch`, then receive
    the typed `search`, `loaderData`, and same-page `navigate` function. That is all
    a list needs—no host route file required.

```tsx title="plugins/blog/src/pages/posts-page.tsx"
    import type { PluginRoutePageProps } from '@vitnode/core/routing'
    import { definePluginRoute } from '@vitnode/core/routing'

interface PostsSearch {
      cursor?: string
      first: number
    }

// [!code ++:11]
    export const route = definePluginRoute({
      parseSearch: (input) => {
        const search = input as Record<string, unknown>
        const first = Number(search.first)

return {
          cursor: typeof search.cursor === 'string' ? search.cursor : undefined,
          first: Number.isInteger(first) && first > 0 ? first : 10,
        }
      },
      load: async ({ search }) => await fetchPosts(search),
    })

const PostsPage = ({
      loaderData,
      navigate,
      search,
    }: PluginRoutePageProps<
      Awaited<ReturnType<typeof fetchPosts>>,
      PostsSearch
    >) => (
      <button
        disabled={!loaderData.pageInfo.hasNextPage}
        onClick={() =>
          void navigate({
            resetScroll: false,
            search: {
              ...search,
              cursor: loaderData.pageInfo.endCursor ?? undefined, // [!code ++]
            },
          })
        }
        type="button"
      >
        Next page
      </button>
    )

export default PostsPage
    ```
  </Step>
</Steps>

## Custom Filtering and Search [#custom-filtering-and-search]

To add search and custom filters, pass the parameters into `withPagination`:

```ts title="plugins/blog/src/api/modules/posts/routes/get.route.ts"
import { eq } from 'drizzle-orm'

const data = await withPagination({
  c,
  params: { query: c.req.valid('query') },
  table: blog_posts,
  primaryCursor: blog_posts.id,
  orderBy: { column: blog_posts.createdAt, order: 'desc' },
  // [!code ++:3]
  search: [blog_posts.title, blog_posts.content],
  where: categoryId ? eq(blog_posts.categoryId, categoryId) : undefined,
  query: async ({ cursorSelection, limit, where, orderBy }) =>
    await c
      .get('db')
      .select({ ...getColumns(blog_posts), ...cursorSelection })
      .from(blog_posts)
      .where(where)
      .orderBy(orderBy)
      .limit(limit),
})
```

***

## Best Practices [#best-practices]

<Callout type="info" title="Opaque cursors">
  Cursors encode the specific column ordering. If the user changes sort order or
  filter criteria, reset the cursor to `undefined` so pagination starts from the
  first page.
</Callout>

<Callout type="warn" title="Always apply callback where and orderBy">
  `withPagination` injects cursor conditions directly into the callback's
  `where` and `orderBy`. Always pass those arguments straight to Drizzle's query
  methods without rebuilding them.
</Callout>

## Learn More [#learn-more]

# Search

`withPagination` includes built-in multi-column search filtering. When `search` columns are specified, incoming `?search=` query parameters automatically apply case-insensitive `ILIKE` clauses across the chosen columns.

<Callout type="info" title="Site-Wide Search">
  For site-wide search across multiple collections and models, see [Search &
  Discovery](/docs/dev/search).
</Callout>

## Quick start [#quick-start]

`ContentDataTable` is VitNode's reusable table UI: it renders rows, toolbar,
search, sorting, and pagination. It does not fetch data. See [Data
Table](/docs/ui/data-table) for the navigation provider it needs around it.

<Steps>
  <Step>
    ### Accept `search` in the route query [#accept-search-in-the-route-query]

Extend `zodPaginationQuery` to accept the optional search string:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
    import { z } from "@hono/zod-openapi"
    import { zodPaginationQuery } from "@vitnode/core/api/lib/with-pagination"

request: {
      query: zodPaginationQuery.extend({
        search: z.string().optional(), // [!code ++]
      }),
    }
    ```
  </Step>

<Step>
    ### Supply searchable columns [#supply-searchable-columns]

List the columns to filter in the `search` array:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
    const data = await withPagination({
      c,
      params: { query },
      table: reactions,
      primaryCursor: reactions.id,
      // [!code ++:1]
      search: [reactions.emoji, reactions.description], // Filters across both columns
      query: async ({ cursorSelection, limit, where, orderBy }) =>
        await c
          .get('db')
          .select({ ...getColumns(reactions), ...cursorSelection })
          .from(reactions)
          .where(where)
          .orderBy(orderBy)
          .limit(limit),
    })
    ```
  </Step>

<Step>
    ### Show the table search input [#show-the-table-search-input]

Enable the shared table UI after its route loader returns `{ edges, pageInfo }`:

```tsx title="src/views/reactions-table.tsx"
    <ContentDataTable
      id="reactions-table"
      columns={columns}
      edges={data.edges}
      pageInfo={data.pageInfo}
      order={{ defaultOrder: { column: 'emoji', order: 'asc' } }}
      search // [!code ++]
      searchPlaceholder="Search reactions..." // [!code ++]
    />
    ```

The table automatically updates the `?search=` query parameter as the user types with debouncing.
  </Step>
</Steps>

## Learn More [#learn-more]

# Debugging

Four surfaces, each answering a different question. Two of them exist only in
development - the devtools and React Scan. The other two, the AdminCP Debug
Panel and the server's own output, are how you see inside a production
deployment, which is exactly when you need to.

## Where to look first [#where-to-look-first]

| Symptom                                     | Look here                                                 |
| ------------------------------------------- | --------------------------------------------------------- |
| A request 500s in production                | [Debug Panel](#the-debug-panel) → System Logs             |
| A screen shows data that has moved on       | [Query devtools](#devtools-in-development) → find the key |
| A route loaded the wrong thing              | [Router devtools](#devtools-in-development) → loader data |
| A page feels slow to type in or scroll      | [React Scan](#react-scan) → count the re-renders          |
| A service looks configured but does nothing | **Core → System → Integrations** in the AdminCP           |
| A background job never ran                  | [Debug Panel](#the-debug-panel) → Queue Tasks             |

## The Debug Panel [#the-debug-panel]

`/admin/core/debug`, and the quickest way in is the avatar menu in the top-right
of the AdminCP: **Debug Panel**. It is also the one AdminCP screen with no
sidebar entry, so that menu (or the admin search) is how you get there.

Three sections, top to bottom:

| Section         | What it shows                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clear Cache** | A button, top-right. Marks every cached query stale and re-runs every matched route loader.                                                                            |
| **Queue Tasks** | Four counters - pending, processing, completed, failed - and a table of what is pending or processing right now, with its attempt count and when it is next available. |
| **System Logs** | Every line anything wrote with `c.get('log')`, newest first, sortable by type, plugin or date.                                                                         |

{/* Image prompt: A screenshot of the VitNode AdminCP Debug Panel at /admin/core/debug - heading "Debug Panel" with a "Clear Cache" button, below it a row of four queue counters (Pending, Processing, Completed, Failed), and below that the System Logs table with Plugin, Type, Status Code, Created At and Content columns, one row carrying a red "Error" badge. Dark theme, 1440x900. */}

Click any log row for the full record: the log id, the request method and path,
the status code, the IP address, the user agent, the user who caused it (linked
straight to their AdminCP profile) and the untruncated message. That detail
dialog is usually the whole debugging session.

The screen is gated on the `debug` staff module - `can_view` to open it,
`can_clear_cache` for the button - and Hono re-checks that on every request, so
hiding the menu entry is a courtesy rather than the boundary. See
[staff permissions](/docs/dev/working-with-users/staff-permissions).

<Callout type="warn" title="In production, the log is the only copy of the error">
  An unhandled error in a route is caught by the API's error handler, written to
  the system log as `Unhandled error: …`, and answered to the browser as the
  string `Internal Server Error` with no detail at all. In development the same
  handler returns the real message in the response body instead. So a 500 you
  cannot reproduce locally is a 500 you read in the Debug Panel.
</Callout>

## Devtools in development [#devtools-in-development]

The scaffold mounts a floating devtools button in the bottom-right corner of
every page, with two panels behind it. It comes from two places, and both are in
a generated app already:

```ts title="vite.config.ts"
import { devtools } from '@tanstack/devtools-vite'

plugins: [
  devtools(), // [!code ++]
]
```

```tsx title="src/routes/__root.tsx"
<body suppressHydrationWarning>
  {children}

{import.meta.env.DEV ? ( // [!code ++]
    <TanStackDevtools
      config={{ position: 'bottom-right' }}
      plugins={[
        { name: 'TanStack Router', render: <TanStackRouterDevtoolsPanel /> },
        { name: 'TanStack Query', render: <ReactQueryDevtoolsPanel /> },
      ]}
    />
  ) : null}

<Scripts />
</body>
```

That `import.meta.env.DEV` is why nothing ships to production: the whole block
is compiled out of a `vite build`.

| Panel               | Reach for it when                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TanStack Router** | You want the matches for the current URL, each route's loader data, and what its `head` resolved to. The answer to "why is this page rendering that". |
| **TanStack Query**  | A screen is showing stale data. Find the key, then find the mutation that should have invalidated it.                                                 |

{/* Image prompt: A screenshot of a VitNode dev server at localhost:3000 with the TanStack Devtools panel open on the TanStack Query tab - a list of cached query keys down the left, one selected, its cached JSON and a fresh/stale badge in the detail pane on the right. Dark theme, 1440x900. */}

Navigate around with the Query panel open and the shape of
[data loading](/docs/dev/data-loading) becomes obvious: a route's loader warms
its entries before React renders, and the screen reads the same ones back.

<Callout type="info" title="Server-side requests are not in the panel">
  A loader that runs during SSR runs in the Node process, so its output lands in
  the terminal running `vite dev` - not in a browser panel. The Query panel
  shows the entry once it is dehydrated into the page.
</Callout>

## React Scan [#react-scan]

[React Scan](https://react-scan.com/) draws an outline around every component as
it re-renders, which turns "this page feels heavy" into a number. It is off by
default; flip `debug` in the [shared config](/docs/dev/configuration):

```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  debug: true, // [!code ++]
  i18n: {
    defaultLocale: 'en',
    locales: [{ code: 'en', name: 'English' }],
  },
  metadata: {
    shortTitle: 'VitNode',
    title: 'VitNode',
  },
  plugins: [],
  theme: {
    defaultTheme: 'system',
  },
})
```

The provider loads `react-scan` lazily and only when `debug` is on **and**
`NODE_ENV` is `development`, so leaving `debug: true` committed cannot leak the
overlay into production. It is still worth turning back off - the outlines are
distracting once you have your answer.

Once you have found the culprit, [Performance](/docs/dev/performance) covers
what to do about it.

## Where output goes [#where-output-goes]

| Destination           | What arrives there                                                                     |
| --------------------- | -------------------------------------------------------------------------------------- |
| The `core_logs` table | Every `c.get('log')` call, with the request that made it. Read it in the Debug Panel.  |
| The server's stdout   | The same lines, colour-coded and prefixed `[VitNode] Error (@your/plugin):`.           |
| The browser console   | Client-side errors, and React Scan's own output.                                       |
| The terminal          | Vite's dev-server output, plus anything a loader or server function logged during SSR. |

There is no request logger, and no log-level switch: every level is written
every time, to both the table and the console. If you want less noise, log less.
[Logging](/docs/dev/debugging/logging) is the whole surface.

## Gotchas [#gotchas]

<Callout type="warn" title="Every log line is a database INSERT, and nothing prunes them">
  `c.get('log')` writes a row per call and no cron job deletes any of them, so a
  `debug` line in a hot request path grows the table for as long as the
  installation runs. Log events, not traffic.
</Callout>

<Callout type="warn" title="Behind a proxy, every log line says 127.0.0.1">
  The IP on a log row - and the rate-limit bucket - comes from the request's
  `X-Forwarded-For` header, falling back to `127.0.0.1` when there is none. A
  reverse proxy that does not set it makes every visitor look like the same one.
  See the [reverse proxy step](/docs/dev/deployments/self-hosted).
</Callout>

<Callout type="info" title="Clear Cache clears the front end, not Redis">
  The button invalidates the TanStack Query cache and the router's loaders,
  which is the front end's memory of the API. The API's own [Redis-backed
  cache](/docs/dev/advanced/redis) is expired by the mutations that change the
  data, not from this screen.
</Callout>

## Next [#next]

# Logging

Every VitNode request carries a logger. Call it and you get two things at once:
a row in the `core_logs` table, readable in the AdminCP
[Debug Panel](/docs/dev/debugging#the-debug-panel), and a coloured line on the
server's stdout. No setup, no adapter, no configuration.

## Quick start [#quick-start]

`c.get('log')` is available in any handler that has a Hono context - a route, a
middleware, a cron job, a queue task, an event listener:

```ts title="src/api/modules/orders/routes/refund.route.ts"
import { buildRoute } from '@vitnode/core/api/lib/route'

import { CONFIG_PLUGIN } from '@/const'

export const refundOrderRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: { method: 'post', path: '/refund' },
  handler: async (c) => {
    await c.get('log').warn('Refund requested with no matching payment') // [!code ++]

return c.json({ ok: true })
  },
})
```

Open the **Debug Panel** from the AdminCP avatar menu and the line is in
**System Logs**, with the plugin, the path, the status code and the signed-in
user already attached.

## The three levels [#the-three-levels]

There is no filtering: all three are always written, to both destinations. The
level is a label for whoever reads the log later, and it decides the badge
colour in the AdminCP and which `console` method the server uses.

<Tabs id="logging-variants" items="['Debug', 'Warn', 'Error']">
  <Tab value="Debug">
    ```ts
    await c.get('log').debug('Search index rebuilt in 412ms')
    ```
  </Tab>

<Tab value="Warn">
    ```ts
    await c.get('log').warn('Storage adapter returned no public URL')
    ```
  </Tab>

<Tab value="Error">
    ```ts
    await c.get('log').error(`Payment webhook rejected: ${reason}`)
    ```
  </Tab>
</Tabs>

| Level   | Console         | Use it for                                                          |
| ------- | --------------- | ------------------------------------------------------------------- |
| `debug` | `console.debug` | Something you want to see once while you work out what happened.    |
| `warn`  | `console.warn`  | A recoverable surprise - a fallback taken, a retry, a skipped step. |
| `error` | `console.error` | Something failed and somebody has to know.                          |

## What every line records [#what-every-line-records]

You pass a string. The logger reads the rest off the request, so a log row is
already an audit record:

| Column       | Where it comes from                                                                      |
| ------------ | ---------------------------------------------------------------------------------------- |
| `content`    | Your message.                                                                            |
| `type`       | The method you called.                                                                   |
| `pluginId`   | The `pluginId` the route was built with - `core` when there is no plugin on the context. |
| `method`     | The request method, upper-cased.                                                         |
| `path`       | The request path.                                                                        |
| `statusCode` | `c.res.status` **at the moment you call it** - see the gotcha below.                     |
| `ipAddress`  | The request's forwarded IP, or `127.0.0.1` when no proxy header is present.              |
| `userAgent`  | The `User-Agent` header.                                                                 |
| `userId`     | The signed-in user, or null for a guest.                                                 |
| `createdAt`  | Now.                                                                                     |

That is also why you should not build any of it into the message yourself: the
Debug Panel's detail dialog shows every column, and a message that repeats the
path just makes the table harder to scan.

## Read it back [#read-it-back]

Three ways, in descending order of convenience:

1. **The Debug Panel** at `/admin/core/debug` - sortable by type, plugin or
   date, with a detail dialog per row.
2. **The server console** - the same lines, live, prefixed
   `[VitNode] Error (@your/plugin):`.
3. **The API**, if you want to build your own view:
   `GET /api/@vitnode/core/admin/debug/logs`, cursor-paginated, `orderBy` one of
   `type`, `createdAt` or `pluginId`, gated on the `debug.can_view` staff
   permission.

## Gotchas [#gotchas]

<Callout type="warn" title="Nothing prunes core_logs">
  There is no retention policy and no cleanup job - the hourly `clean` cron
  removes expired sessions and tokens, and never touches logs. Every call is an
  `INSERT` that stays. So log events, not requests: a `debug` line in a handler
  that runs on every page view will outgrow the rest of your database.
</Callout>

<Callout type="warn" title="Await it">
  All three methods are `async` because they hit the database. A floating
  promise can lose the row if the response ends first, and an insert that fails
  becomes an unhandled rejection instead of an error you can see. `await` every
  call.
</Callout>

<Callout type="warn" title="The status code is the status so far">
  `statusCode` is read off `c.res` when you log, and a Hono response you have
  not built yet reads as `200`. A line written before `return c.json(…, 400)`
  records `200`. If the status is the interesting part, log after you know it,
  or put it in the message.
</Callout>

<Callout type="info" title="The plugin column follows the route, not the caller">
  It comes from the `pluginId` passed to `buildRoute`, so a plugin's cron job -
  which runs inside core's cron endpoint - is logged as `@vitnode/core`. Name
  your plugin in the message when the attribution matters.
</Callout>

<Callout type="info" title="Unhandled errors are logged for you">
  Anything a handler throws that is not an `HTTPException` is caught by the
  API's error handler, written here as `Unhandled error: …`, and answered to the
  browser as a bare `Internal Server Error` in production. You do not need a
  `try/catch` just to get a stack into the log.
</Callout>

## Next [#next]

# Vercel

A VitNode app builds with Nitro, and Nitro knows Vercel. Push the repository,
point a project at it, and the site plus the Hono API mounted at `/api/*` come
up as one serverless function - no adapter, no `vercel.json`.

Serverless is the catch, not the build. Three things VitNode can do need a
process that is still alive between requests, and Vercel does not have one - and
nothing there will run your migrations either.

## What works, and what does not [#what-works-and-what-does-not]

| Feature                                                | On Vercel     | Why                                                                         |
| ------------------------------------------------------ | ------------- | --------------------------------------------------------------------------- |
| The site, SSR, and `/api/*`                            | ✅ Works       | One Nitro function answers every route.                                     |
| Postgres, [Redis](/docs/dev/advanced/redis), email, AI | ✅ Works       | All reached over the network. Bring managed ones.                           |
| [S3 / R2](/docs/dev/storage/s3-r2) or Supabase storage | ✅ Works       | Uploads go straight to the bucket.                                          |
| [Local file storage](/docs/dev/storage/local)          | ❌ Not durable | The adapter writes to `public/uploads` on a filesystem that disappears.     |
| [WebSockets](/docs/dev/websocket)                      | ❌ Unsupported | The `/ws` upgrade needs a long-lived `serve()` with a WebSocket server.     |
| [In-process cron](/docs/dev/cron/node-cron)            | ❌ Unsupported | The adapter runs a `*/1 * * * *` timer inside the process.                  |
| Migrating on deploy                                    | ⚠️ Your job   | Nothing on Vercel runs `db:migrate` for you. See [Migrations](#migrations). |

## Deploy it [#deploy-it]

<Steps>
  <Step>
    ### Bring a managed Postgres [#bring-a-managed-postgres]

Anything reachable over the internet: Supabase, Neon, RDS, your own box. Create
    the database and keep the connection string.

Use the **pooled** connection string if your provider offers one. VitNode
    connects with `postgres.js`, which opens a pool of up to 10 connections per
    process, and a serverless platform will happily run a lot of processes at once.
    If you would rather keep the direct string, shrink the pool instead:

```ts title="src/vitnode.api.config.ts"
    export const vitNodeApiConfig = buildApiConfig({
      dbProvider: drizzle({
        connection: { url: POSTGRES_URL, max: 1 }, // [!code ++]
        relations: coreRelations,
      }),
    })
    ```
  </Step>

<Step>
    ### Set the environment variables first [#set-the-environment-variables-first]

In the Vercel project, before the first build - two of them are compiled into
    the browser bundle and cannot be changed afterwards without building again.

| Variable                     | Notes                                                                                                   |
    | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
    | `POSTGRES_URL`               | Required. Nothing works without it.                                                                     |
    | `NEXT_PUBLIC_WEB_URL`        | Your production origin. Email links, SSO callbacks and password-reset links use it.                     |
    | `CRON_SECRET`                | Required if anything schedules cron. A long random string.                                              |
    | `REDIS_URL` `REDIS_PASSWORD` | Strongly recommended - see the rate-limiter gotcha below.                                               |
    | `NEXT_PUBLIC_API_URL`        | Leave it unset. The single app answers `/api/*` itself, and both halves work that out from the request. |

<Callout type="warn" title="Do not set NEXT_PUBLIC_API_URL on preview deployments">
      A preview gets a generated hostname, so no configured value can name it. Left
      unset, the server takes the API origin off the request being rendered and the
      browser falls back to the origin the page came from - which is right on every
      deployment, including ones that did not exist when you configured the project.
      Set it only when the API genuinely lives somewhere else.
    </Callout>
  </Step>

<Step>
    ### Create the project [#create-the-project]

Import the Git repository in Vercel. Three settings matter:

| Setting             | Value                                                                      |
    | ------------------- | -------------------------------------------------------------------------- |
    | **Root Directory**  | The app folder - `apps/web` for a monorepo, the repository root otherwise. |
    | **Build Command**   | Your `build` script. For a Single App that is `vite build`.                |
    | **Node.js Version** | 22 or newer.                                                               |

Leave the output directory alone. Nitro reads `VERCEL` from the build
    environment, resolves its `vercel` preset without being told to, and writes
    `.vercel/output` in the Build Output API format that Vercel picks up on its own.
  </Step>

<Step>
    ### Migrate the database [#migrate-the-database]

Not from Vercel. Run it yourself, against the production connection string,
    from a checkout of the commit you are deploying:

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']" label="Migrate">
      <Tab value="bun">
        ```bash
        POSTGRES_URL="postgresql://…" bun db:migrate
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        POSTGRES_URL="postgresql://…" pnpm db:migrate
        ```
      </Tab>

<Tab value="npm">
        ```bash
        POSTGRES_URL="postgresql://…" npm run db:migrate
        ```
      </Tab>
    </Tabs>

See [Migrations](#migrations) for why this is not part of the build command, and
    what happens if you make it one anyway.
  </Step>

<Step>
    ### Register the first account [#register-the-first-account]

Deploy, open the site, and go to `/register`. The first account created in an
    empty database becomes the **Administrator** - so do it before you tell anybody
    the URL. Then sign in at `/admin` and open **Core → System → Integrations** to
    see which services actually came up.

{/* Image prompt: A screenshot of the VitNode AdminCP Integrations board at /admin/core/system/integrations on a production deployment - nine service cards, Redis and Storage showing "Active" badges, WebSocket and Cron showing "Inactive". Dark theme, 1440x900. */}
  </Step>
</Steps>

## Migrations [#migrations]

`start` never migrates, and on Vercel there is no `start` at all - your code is
invoked per request. So the schema has to be changed by something outside the
deployment, and there are exactly two honest ways to do it:

1. **From your own machine or CI**, pointing `POSTGRES_URL` at production, as a
   deliberate step before you promote the build. This is the one to prefer.
2. **In front of the build command** - `pnpm db:migrate && pnpm build`. It
   works, and it also runs on every preview deployment against whatever
   `POSTGRES_URL` that environment has.

<Callout type="warn" title="db:migrate can generate as well as apply">
  `db:migrate` is `vitnode migrate`, which generates a migration for any
  uncommitted schema change, then applies everything pending, then seeds. On a
  deploy there should be nothing to generate - so commit your `migrations/`
  folder, and treat a freshly generated migration on a build machine as a sign
  that something never made it into the repository.
</Callout>

## Gotchas [#gotchas]

<Callout type="warn" title="Without Redis, the rate limiter counts per instance">
  It falls back to in-memory storage, and on serverless "in memory" means one
  counter per cold start. The limit is still there; it just stops meaning
  anything. Set `REDIS_URL` and the counters become shared - the same switch
  also gives you a real cache.
</Callout>

<Callout type="warn" title="Vercel's own Cron Jobs cannot drive VitNode's cron">
  VitNode's endpoint is `POST /api/@vitnode/core/cron` with an `Authorization:
    Bearer $CRON_SECRET` header, and [Vercel Cron
  Jobs](https://vercel.com/docs/cron-jobs) invoke a path with a `GET`. Use a
  scheduler that can send a `POST` - GitHub Actions, an uptime service, anything
  on the [REST API](/docs/dev/cron/rest-api) page - and point it at that path
  once a minute.
</Callout>

<Callout type="warn" title="Leave cookieDomain unset">
  `authorization.cookieDomain` is empty by default, which makes every auth
  cookie host-only and therefore correct on a hostname nobody configured. Set it
  to your production domain and preview deployments stop being able to sign
  anyone in, because a browser rejects a `Domain` the response did not come
  from.
</Callout>

<Callout type="info" title="Swagger ships with the deployment">
  `/api/swagger` is mounted with no session check, so it is public on your
  production URL too. There is no proxy in front of a Vercel function to deny it
  at, so if that matters, keep the deployment behind Vercel's own access
  controls - see [Swagger](/docs/dev/swagger).
</Callout>

<Callout type="info" title="Need any of the three?">
  Run the app on a server instead. Long-lived WebSocket connections, an
  in-process scheduler and local disk are all ordinary there - see
  [Self-hosted](/docs/dev/deployments/self-hosted).
</Callout>

## Next [#next]

# Self-Hosted Deployment

VitNode compiles into a standard Node.js server and static assets. The only required dependency is a PostgreSQL database (Redis is optional for caching and multi-instance scaling).

## Quick start [#quick-start]

Run these 4 commands on your deployment server:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Deploy VitNode">
  <Tab value="bun">
    ```bash
    bun install --frozen-lockfile
    bun run build
    bun run db:migrate
    bun start
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm install --frozen-lockfile
    pnpm build
    pnpm db:migrate
    pnpm start
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm ci
    npm run build
    npm run db:migrate
    npm start
    ```
  </Tab>
</Tabs>

<Callout type="warn" title="Always run db:migrate before start">
  Production processes do not automatically run migrations at boot. Running
  `db:migrate` ensures the database schema matches your compiled application
  before traffic is served.
</Callout>

***

## Required Environment Variables [#required-environment-variables]

Configure these in your production `.env` file:

```bash title=".env"
# Database (PostgreSQL 15+)
POSTGRES_URL=postgresql://user:password@localhost:5432/vitnode_db

# The origin visitors reach. Email links, SSO callbacks and password-reset
# links are built from it.
NEXT_PUBLIC_WEB_URL=https://example.com

# Required if anything schedules cron. A long random string.
CRON_SECRET=change_me_to_a_long_random_secret_string

# Optional: Shared Cache & Realtime
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=change_me_redis_password
```

### Where the API lives [#where-the-api-lives]

A **Single App** answers `/api/*` itself, so leave `NEXT_PUBLIC_API_URL` unset.
The server takes the API origin off the request being rendered and the browser
falls back to the origin the page was served from, so the same build is correct
on every hostname you point at it.

A **split deployment** runs the web app and `apps/api` as two processes, and the
web app then has to be told where the API is - its own origin has no `/api/*` to
answer, so an unset value turns every server-side call into a 404, starting with
the session read on the first render. Set it in the web app's environment, and
set it before the build: it is compiled into the browser bundle too.

```bash title="apps/web/.env"
NEXT_PUBLIC_API_URL=http://localhost:8000
```

A value set here wins over the request origin, which is why a Single App must
not carry one - `http://localhost:3000` left over from development would point
production at the visitor's own machine.

***

## Reverse Proxy (Nginx Configuration) [#reverse-proxy-nginx-configuration]

Proxy traffic to VitNode while forwarding client headers and supporting WebSocket upgrades:

```nginx title="/etc/nginx/sites-available/vitnode.conf"
server {
    listen 80;
    server_name example.com;

location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;

# WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

# Forwarded identity
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

***

## Running with PM2 (Process Manager) [#running-with-pm2-process-manager]

Keep VitNode running continuously with automatic restarts on crash:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Run VitNode with PM2">
  <Tab value="bun">
    ```bash
    # Install PM2
    bun add -g pm2

# Start both web and API processes
    pm2 start "bun start" --name "vitnode-web"
    pm2 save
    pm2 startup
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    # Install PM2
    pnpm add -g pm2

# Start both web and API processes
    pm2 start "pnpm start" --name "vitnode-web"
    pm2 save
    pm2 startup
    ```
  </Tab>

<Tab value="npm">
    ```bash
    # Install PM2
    npm install -g pm2

# Start both web and API processes
    pm2 start "npm start" --name "vitnode-web"
    pm2 save
    pm2 startup
    ```
  </Tab>
</Tabs>

## Learn More [#learn-more]

# Button

`EmailButton` wraps React Email's `Button` with the variants the app's own
button uses, so a call to action in a mail looks like a call to action on the
site. It renders an `<a>`, which is the only thing every mail client agrees to
style.

## Preview [#preview]

## Usage [#usage]

```ts
import { EmailButton } from '@vitnode/core/emails/ui/button'
```

```tsx
<EmailButton href="https://vitnode.com/">Default</EmailButton>
```

Centre it the way the framework's own password-reset mail does - a `Section`
does the alignment, because margins are not to be trusted in email:

```tsx
<Section className="text-center">
  <EmailButton className="min-w-[200px]" href={resetUrl} size="lg">
    Reset your password
  </EmailButton>
</Section>
```

## Props [#props]

Everything an `<a>` takes, plus two of its own.

### Variants [#variants]

| Variant            | Looks like                     | Use it for                                 |
| ------------------ | ------------------------------ | ------------------------------------------ |
| `default`          | Solid primary fill, light text | The one action the email is asking for     |
| `secondary`        | Soft tinted fill, dark text    | A second, lesser action                    |
| `outline`          | Border, page-background fill   | A neutral action next to a primary one     |
| `ghost`            | Text only, no fill or border   | Tertiary actions                           |
| `link`             | Primary-coloured text, no fill | Inline links styled as buttons             |
| `destructive`      | Solid red fill, white text     | Delete, revoke, cancel                     |
| `destructiveGhost` | Red text, no fill              | A destructive action that should not shout |

### Sizes [#sizes]

| Size      | Padding       |
| --------- | ------------- |
| `sm`      | `px-3 py-1.5` |
| `default` | `px-4 py-2`   |
| `lg`      | `px-6 py-2.5` |

## Gotchas [#gotchas]

<Callout type="warn" title="The colours come from the template">
  `bg-primary` and friends are defined by `DefaultTemplateEmail`, which wraps
  your content in a `<Tailwind>` with VitNode's palette. Drop an `EmailButton`
  into a template that builds its own document and the classes resolve to
  nothing. [Templates](/docs/dev/email/templates#colour-tokens) lists the
  tokens.
</Callout>

<Callout type="info" title="It is a link, not a button">
  There is no `onClick` and no `type="submit"` to reach for - email has no
  JavaScript. Every action is a URL, which usually means a signed link into your
  app.
</Callout>

## Next [#next]

# Card

`EmailCard` is the container the framework's own mail puts its message in: a
white panel with a border, a rounded corner and consistent padding. Six
components, each a thin wrapper over a React Email primitive, so they compose
like the app's card does.

## Preview [#preview]

## Usage [#usage]

```ts
import {
  EmailCard,
  EmailCardContent,
  EmailCardDescription,
  EmailCardFooter,
  EmailCardHeader,
  EmailCardTitle,
} from '@vitnode/core/emails/ui/card'
import { Text } from 'react-email'
```

```tsx
<EmailCard>
  <EmailCardHeader>
    <EmailCardTitle>Card Title</EmailCardTitle>
    <EmailCardDescription>Card Description</EmailCardDescription>
  </EmailCardHeader>
  <EmailCardContent>
    <Text className="m-0">
      This is the content of the card. You can put any content here.
    </Text>
  </EmailCardContent>
  <EmailCardFooter>
    <Text className="m-0">Footer</Text>
  </EmailCardFooter>
</EmailCard>
```

Every part is optional. A card with nothing but `EmailCardContent` inside it is
a perfectly good panel.

## Components [#components]

| Component              | Renders                 | Styling it brings                                       |
| ---------------------- | ----------------------- | ------------------------------------------------------- |
| `EmailCard`            | `Section` (a `<table>`) | Card background, border, `rounded-xl`, vertical padding |
| `EmailCardHeader`      | `Section`               | Horizontal padding and space below                      |
| `EmailCardTitle`       | `Text` (a `<p>`)        | `text-xl font-semibold`, with the line height zeroed    |
| `EmailCardDescription` | `Text`                  | Muted, small, no margin                                 |
| `EmailCardContent`     | `Section`               | Horizontal padding                                      |
| `EmailCardFooter`      | `Section`               | Horizontal padding and space above                      |

## Props [#props]

Each component takes the props of the primitive it renders - so `className`,
`style` and children, plus the table or paragraph attributes underneath.

## Gotchas [#gotchas]

<Callout type="warn" title="The colours come from the template">
  `bg-card`, `border-border` and `text-muted-foreground` are defined by
  `DefaultTemplateEmail`, which wraps your content in a `<Tailwind>` carrying
  VitNode's palette. In a template that builds its own document, those classes
  resolve to nothing. [Templates](/docs/dev/email/templates#colour-tokens) lists
  the tokens.
</Callout>

<Callout type="info" title="Reset the paragraph margins">
  A React Email `Text` renders a `<p>` with its own margins, which stack oddly
  inside a padded section. That is why the snippets above pass `m-0` on the
  paragraphs they place directly in a card.
</Callout>

<Callout type="info" title="Sections are tables">
  Each of these renders a `<table>`, because that is what survives Outlook.
  Nesting them is fine and expected; floating or absolutely positioning them is
  not a thing email can do.
</Callout>

## Next [#next]

# Custom Email Adapter

You can connect any transactional email service (e.g. Postmark, AWS SES, SendGrid, Mailgun) by implementing the `EmailApiPlugin` interface. VitNode handles template rendering, i18n localization, and recipient resolution; your adapter just sends the email.

## The `EmailApiPlugin` Interface [#the-emailapiplugin-interface]

The adapter contract consists of a single `sendEmail` method:

```ts
export interface EmailApiPlugin {
  sendEmail: (args: {
    to: string
    subject: string
    html: string
    text: string
    metadata: { title: string; shortTitle?: string }
    replyTo?: string
  }) => Promise<void>
}
```

***

## Quick start: Implementing an Adapter [#quick-start-implementing-an-adapter]

### 1. Create the Adapter Factory [#1-create-the-adapter-factory]

```ts title="apps/api/src/lib/email/postmark-adapter.ts"
import type { EmailApiPlugin } from "@vitnode/core/api/models/email"

export const PostmarkEmailAdapter = ({
  serverToken,
  from,
}: {
  serverToken: string
  from: string
}): EmailApiPlugin => ({
  // [!code ++:16]
  sendEmail: async ({ to, subject, html, text, metadata }) => {
    const res = await fetch("https://api.postmarkapp.com/email", {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        "X-Postmark-Server-Token": serverToken,
      },
      body: JSON.stringify({
        From: `${metadata.shortTitle ?? metadata.title} <${from}>`,
        To: to,
        Subject: subject,
        HtmlBody: html,
        TextBody: text,
      }),
    })

if (!res.ok) throw new Error(`Postmark error: ${res.statusText}`)
  },
})
```

***

### 2. Register in API Configuration [#2-register-in-api-configuration]

Attach the adapter to `vitNodeApiConfig` in `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { PostmarkEmailAdapter } from "./lib/email/postmark-adapter"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:7]
  email: {
    adapter: PostmarkEmailAdapter({
      serverToken: process.env.POSTMARK_SERVER_TOKEN!,
      from: "notifications@yourdomain.com",
    }),
  },
})
```

***

## `sendEmail` Arguments [#sendemail-arguments]

## Learn More [#learn-more]

# Email

VitNode provides a unified transactional email service accessible via `c.get("email")`. Emails are rendered using React components, localized to the recipient's language, and delivered through your chosen provider.

## Quick start [#quick-start]

<Steps>
  <Step>
    ### Queue an email from a Hono route [#queue-an-email-from-a-hono-route]

```ts title="plugins/blog/src/api/modules/newsletter/routes/welcome.route.ts"
    import { buildRoute } from '@vitnode/core/api/lib/route'

export const sendWelcomeRoute = buildRoute({
      pluginId: 'blog',
      route: {
        method: 'post',
        path: '/welcome',
        responses: { 200: { description: 'Email sent' } },
      },
      handler: async (c) => {
        const user = c.get('user')

// [!code ++:5]
        await c.get('email').send({
          user, // Resolves email address and preferred locale
          subject: 'Welcome to VitNode!',
          content: () => 'Thank you for joining our community.',
        })

return c.json({ sent: true })
      },
    })
    ```

`send()` renders the template and queues delivery. It keeps a successful API
    response quick even when the mail provider is having a moody afternoon.
  </Step>
</Steps>

<Callout type="info" title="`build()` and `deliver()` do exist">
  Use `await c.get('email').build(args)` followed by `deliver(email)` only when
  a route truly needs immediate delivery. `send(args)` is the normal, queued
  path.
</Callout>

## Configuring Email Adapters [#configuring-email-adapters]

Configure your delivery transport in `apps/api/src/vitnode.api.config.ts`:

### 1. Resend Adapter [#1-resend-adapter]

```ts title="apps/api/src/vitnode.api.config.ts"
import { ResendEmailAdapter } from '@vitnode/core/api/adapters/email/resend'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    from: 'noreply@yourdomain.com',
    adapter: ResendEmailAdapter({
      apiKey: process.env.RESEND_API_KEY!,
    }),
  },
})
```

### 2. SMTP Adapter [#2-smtp-adapter]

```ts title="apps/api/src/vitnode.api.config.ts"
import { SmtpEmailAdapter } from '@vitnode/core/api/adapters/email/smtp'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    from: 'noreply@yourdomain.com',
    adapter: SmtpEmailAdapter({
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT ?? 587),
      user: process.env.SMTP_USER!,
      password: process.env.SMTP_PASSWORD!,
    }),
  },
})
```

***

## Testing Email in AdminCP [#testing-email-in-admincp]

{/* Image prompt: VitNode AdminCP System -> Integrations screen at /admin/core/system/integrations. Email card showing status "Configured" with a "Send Test Email" modal containing recipient address input and delivery confirmation toast. Dark theme, 1440x900. */}

Verify email configuration in the AdminCP at **System → Integrations** (`/admin/core/system/integrations`):

* Click **Test Email** on the email card.
* Enter an email address to dispatch an immediate test delivery.

## Learn More [#learn-more]

# Nodemailer (SMTP)

The Nodemailer adapter speaks plain SMTP, so it works with anything that has a
host, a port and a login: your own Postfix, a provider's relay, or a mail
catcher running on your laptop.

| Cloud                | Self-Hosted | Links                                                                                                         |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| ⚠️ Runtime-dependent | ✅ Supported | [NPM Package](https://www.npmjs.com/package/@vitnode/nodemailer) · [Nodemailer docs](https://nodemailer.com/) |

SMTP needs an outbound TCP connection, which edge runtimes cannot open and many
serverless platforms block on the usual mail ports. If that is where you deploy,
use [Resend](/docs/dev/email/resend) instead.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { NodemailerEmailAdapter } from '@vitnode/nodemailer'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    adapter: NodemailerEmailAdapter({
      from: process.env.NODE_MAILER_FROM,
      host: process.env.NODE_MAILER_HOST,
      user: process.env.NODE_MAILER_USER,
      password: process.env.NODE_MAILER_PASSWORD,
    }),
  },
})
```

`port` defaults to `587` and `secure` to `false`, which is the STARTTLS
combination almost every relay wants.

## Setup [#setup]

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

`nodemailer` itself ships as a dependency of the adapter.

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']" label="Install the Nodemailer adapter">
      <Tab value="bun">
        ```bash
        bun i @vitnode/nodemailer
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @vitnode/nodemailer
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @vitnode/nodemailer
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Get an SMTP server to talk to [#get-an-smtp-server-to-talk-to]

In development, catch the mail locally instead of posting it to strangers.
    [Mailpit](https://mailpit.axllent.org/) is one binary: an SMTP server on `1025`
    and a web inbox on `8025`.

```bash title="Catch mail locally"
    docker run -p 8025:8025 -p 1025:1025 \
      -e MP_SMTP_AUTH_ACCEPT_ANY=1 \
      -e MP_SMTP_AUTH_ALLOW_INSECURE=1 \
      axllent/mailpit
    ```

Both flags matter: the adapter always authenticates, and it does so over an
    unencrypted local connection, which Mailpit refuses by default.

In production, take the four values from your provider's SMTP page - it is
    usually called "SMTP relay", "Sending" or "Integration".

{/* Image prompt: A screenshot of a transactional email provider's SMTP credentials page, showing the server host, port 587, username and a masked password, with a copy button beside each field. Neutral light theme, 1440x900. */}
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

The adapter reads options, not the environment, so a port other than `587` has
    to be passed through as well:

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'
    import { NodemailerEmailAdapter } from '@vitnode/nodemailer' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      // [!code ++:10]
      email: {
        adapter: NodemailerEmailAdapter({
          from: process.env.NODE_MAILER_FROM,
          host: process.env.NODE_MAILER_HOST,
          user: process.env.NODE_MAILER_USER,
          password: process.env.NODE_MAILER_PASSWORD,
          port: Number(process.env.NODE_MAILER_PORT ?? 587),
          secure: process.env.NODE_MAILER_PORT === '465',
        }),
      },
      metadata: {
        title: 'My Community',
        shortTitle: 'Community',
      },
    })
    ```

Recipients see `Community <hello@example.com>`: the display name is
    `metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.
  </Step>

<Step>
    ### Set the environment variables [#set-the-environment-variables]

Mailpit accepts any credentials, so locally the username and password only have
    to be non-empty:

```bash title=".env"
    NODE_MAILER_HOST=localhost
    NODE_MAILER_PORT=1025
    NODE_MAILER_USER=dev
    NODE_MAILER_PASSWORD=dev
    NODE_MAILER_FROM=hello@localhost
    ```

Production is the same five lines with your provider's values and, on most
    relays, `NODE_MAILER_PORT=587`.
  </Step>

<Step>
    ### Send a test mail [#send-a-test-mail]

Send one from a route - the [email overview](/docs/dev/email#quick-start) has the
    `build()` plus `deliver()` form that works from any plugin - then open
    [localhost:8025](http://localhost:8025). The message appears in Mailpit's inbox,
    where you can read the rendered HTML and the raw source that left your app.

{/* Image prompt: A screenshot of the Mailpit web inbox at localhost:8025 with one captured message selected, showing the rendered HTML email in the reading pane and the HTML/Text/Raw tabs above it. Light theme, 1440x900. */}

Nothing there? `deliver()` throws inside the request, so the failing request is
    where Nodemailer's own message is - in the response body while `NODE_ENV` is
    `development`, in the log otherwise. Mail sent with the queued `send()` is a
    tick behind instead, and its story is in the row:

```sql
    select status, attempts, "lastError"
    from core_queue
    where name = 'send-email'
    order by id desc
    limit 1;
    ```
  </Step>
</Steps>

## Options [#options]

## Environment variables [#environment-variables]

The adapter takes values, not variable names, so these are yours to rename -
just keep both sides in step.

| Variable               | Maps to    | Example         | Notes                                                            |
| ---------------------- | ---------- | --------------- | ---------------------------------------------------------------- |
| `NODE_MAILER_HOST`     | `host`     | `smtp.host.com` | Required                                                         |
| `NODE_MAILER_USER`     | `user`     | `apikey`        | Required. Some providers use a fixed literal here                |
| `NODE_MAILER_PASSWORD` | `password` | -               | Required                                                         |
| `NODE_MAILER_FROM`     | `from`     | `hi@you.com`    | Required. Address only                                           |
| `NODE_MAILER_PORT`     | `port`     | `587`           | Optional - pass it through yourself, the adapter defaults to 587 |

## Gotchas [#gotchas]

<Callout type="warn" title="Missing settings fail at delivery, not at boot">
  The adapter checks `host`, `user`, `password` and `from` inside `sendEmail`,
  so a half-configured app still starts. With `deliver()` the failure is the
  route's own 500, throwing `Missing nodemailer configuration`. With the queued
  `send()` the request returns 200 and the same message turns up in
  `core_queue.lastError` three attempts later.
</Callout>

<Callout type="warn" title="Port 465 needs secure: true">
  Port 465 expects TLS immediately, while 587 negotiates it with STARTTLS.
  Leaving `secure` at its default on 465 gives you a connection that hangs and
  then times out rather than a clear error.
</Callout>

<Callout type="info" title="One connection per email">
  The transport is created inside `sendEmail`, so each message opens its own
  SMTP connection - simple and stateless, and fine at the volumes a queue
  drained once a minute produces. A relay that rate-limits connections rather
  than messages is the case to watch.
</Callout>

<Callout type="info" title="Only the HTML part is sent">
  VitNode renders both an HTML and a plain-text version of every email, but this
  adapter passes `html` alone.
</Callout>

## Next [#next]

# Resend

[Resend](https://resend.com/) sends mail over an ordinary HTTPS request, which
makes it the adapter that works everywhere your app can `fetch` - including
serverless and edge deployments where an SMTP connection would never open.

| Cloud       | Self-Hosted | Links                                                                                                 |
| ----------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| ✅ Supported | ✅ Supported | [NPM Package](https://www.npmjs.com/package/@vitnode/resend) · [Resend docs](https://resend.com/docs) |

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { ResendEmailAdapter } from '@vitnode/resend'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    adapter: ResendEmailAdapter({
      apiKey: process.env.RESEND_API_KEY,
      from: process.env.RESEND_FROM_EMAIL,
    }),
  },
})
```

That is the whole integration. The steps below are the account setup around it.

## Setup [#setup]

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

The `resend` SDK ships as a dependency of the adapter, so this is the only
    package you add.

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']" label="Install the Resend adapter">
      <Tab value="bun">
        ```bash
        bun i @vitnode/resend
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @vitnode/resend
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @vitnode/resend
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Create an API key [#create-an-api-key]

In the Resend dashboard, open **API Keys** and create one with send permission.
    The value starts with `re_` and is shown exactly once, so copy it now.

{/* Image prompt: A screenshot of the Resend dashboard API Keys page with the "Create API Key" dialog open - name field filled in, permission set to sending access, the generated re_ key partially masked. Dark theme, 1440x900. */}
  </Step>

<Step>
    ### Verify a sending domain [#verify-a-sending-domain]

Resend only delivers from a domain you own. Add yours under **Domains**, copy
    the DKIM and SPF records it gives you into your DNS, and wait for the status to
    go green.

For a first local test you can skip this and send from
    `onboarding@resend.dev`, which Resend allows for testing only - it will not
    carry your production mail.

{/* Image prompt: A screenshot of the Resend dashboard Domains page showing one domain with a green "Verified" status and its DKIM/SPF DNS records listed below. Dark theme, 1440x900. */}
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

Add the `email` block to your API config. Both values come from the
    environment, so nothing secret lives in the repository:

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'
    import { ResendEmailAdapter } from '@vitnode/resend' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      // [!code ++:6]
      email: {
        adapter: ResendEmailAdapter({
          apiKey: process.env.RESEND_API_KEY,
          from: process.env.RESEND_FROM_EMAIL,
        }),
      },
      metadata: {
        title: 'My Community',
        shortTitle: 'Community',
      },
    })
    ```

Recipients see `Community <hello@example.com>`: the display name is
    `metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.
  </Step>

<Step>
    ### Set the environment variables [#set-the-environment-variables]

```bash title=".env"
    RESEND_API_KEY=re_your_api_key
    RESEND_FROM_EMAIL=hello@your-verified-domain.com
    ```
  </Step>

<Step>
    ### Send a test mail [#send-a-test-mail]

Send one from a route - the [email overview](/docs/dev/email#quick-start) has the
    `build()` plus `deliver()` form that works from any plugin. Because `deliver()`
    runs inside the request, a rejection fails that request: the adapter rethrows
    Resend's error as `[error_name]: message`, which is the response body in
    development and a log line in production.

An accepted message appears under **Emails** in the dashboard within seconds,
    with its delivery events.

Mail sent with the queued `send()` - core's password resets, for instance - is
    one tick behind, and the row tells you where it got to:

```sql
    select status, attempts, "lastError"
    from core_queue
    where name = 'send-email'
    order by id desc
    limit 1;
    ```
  </Step>
</Steps>

## Options [#options]

## Environment variables [#environment-variables]

Both are read in `src/vitnode.api.config.ts`, so the names are yours to choose;
these are the ones this documentation uses.

| Variable            | Maps to  | Example                 | Notes                                                                      |
| ------------------- | -------- | ----------------------- | -------------------------------------------------------------------------- |
| `RESEND_API_KEY`    | `apiKey` | `re_123...`             | Created under **API Keys**. Needs sending permission                       |
| `RESEND_FROM_EMAIL` | `from`   | `hello@your-domain.com` | Must sit on a verified domain, or be `onboarding@resend.dev` while testing |

## Gotchas [#gotchas]

<Callout type="warn" title="Missing keys fail at delivery, not at boot">
  The adapter validates its own config inside `sendEmail`, so an unset
  `RESEND_API_KEY` never stops the API from starting. With `deliver()` the
  failure is the route's own 500, throwing `Missing Resend configuration`. With
  the queued `send()` the request still returns 200 and the same message turns
  up in `core_queue.lastError` three attempts later.
</Callout>

<Callout type="warn" title="An unverified From fails at delivery">
  Resend answers with an error rather than holding the mail, and the adapter
  rethrows it as `[error_name]: message`. If sends start failing the moment you
  switch from `onboarding@resend.dev` to your own domain, check the domain
  status before you check your code.
</Callout>

<Callout type="info" title="Only the HTML part is sent">
  VitNode renders both an HTML and a plain-text version of every email, but this
  adapter passes `html` alone - the `text` argument reaches it and goes unused.
</Callout>

## Next [#next]

# Email Templates

VitNode renders email templates using [React Email](https://react.email). Templates are standard React components transformed into cross-client compatible HTML tables with localized text and inline styles.

## Quick start [#quick-start]

### 1. Build the Template Component [#1-build-the-template-component]

Wrap template content inside `DefaultTemplateEmail`:

```tsx title="plugins/blog/src/emails/welcome-email.tsx"
import DefaultTemplateEmail, {
  type DefaultTemplateEmailProps,
} from "@vitnode/core/emails/default-template"
import { Button, Section, Text } from "react-email"

interface WelcomeEmailProps extends DefaultTemplateEmailProps {
  loginUrl?: string
}

export default function WelcomeEmail({
  user,
  loginUrl = "https://example.com/login",
  ...props
}: WelcomeEmailProps) {
  return (
    // [!code ++:13]
    <DefaultTemplateEmail user={user} {...props}>
      <Section className="p-4 text-center">
        <Text className="text-xl font-bold">Welcome, {user.name}!</Text>
        <Text className="text-muted-foreground">
          We are thrilled to have you in the community.
        </Text>
        <Button href={loginUrl} className="bg-primary text-primary-foreground px-4 py-2 rounded-md">
          Visit Your Account
        </Button>
      </Section>
    </DefaultTemplateEmail>
  )
}
```

***

### 2. Send the Email [#2-send-the-email]

Send or queue the email from any Hono route or task:

```ts
import WelcomeEmail from "@/emails/welcome-email"

// [!code ++:6]
await c.get("email").send({
  user: { email: user.email, name: user.name },
  subject: "Welcome to VitNode!",
  content: WelcomeEmail,
})
```

`send()` handles locale resolution, renders the JSX to HTML, and pushes the delivery to the mail transport.

***

## Preview Templates Locally [#preview-templates-locally]

Preview emails in your browser during development using the React Email preview server:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Start email dev server">
  <Tab value="bun">
    ```bash
    bun run email dev
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm exec email dev
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npx email dev
    ```
  </Tab>
</Tabs>

Visit `http://localhost:3001` to view your email rendered live with hot reloading.

***

## Localization in Emails [#localization-in-emails]

Email templates receive the recipient's preferred locale automatically:

```tsx
export default function OrderEmail({ i18n, ...props }: DefaultTemplateEmailProps) {
  return (
    <DefaultTemplateEmail i18n={i18n} {...props}>
      <Text>{i18n.t("order.confirmed")}</Text>
    </DefaultTemplateEmail>
  )
}
```

## Learn More [#learn-more]

# Built-in Events

Every event VitNode and its first-party plugins emit today, grouped by domain.
Listen to any of them from your own plugin with
[`buildEventListener`](/docs/dev/events) - no import from the emitting plugin is
needed, because the event map is global.

## Quick start [#quick-start]

Pick a name from the tables below, write a listener for it, and register the
listener on a top-level module's `events` array:

```ts title="plugins/shop/src/api/lib/events.ts"
import { buildEventListener } from '@vitnode/core/api/lib/events'

export const welcomeListener = buildEventListener({
  event: 'user.created', // [!code ++]
  name: 'send-welcome-email',
  handler: async (c, payload) => {
    await c.get('queue').dispatch({
      name: 'send-welcome-email',
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})
```

Nothing else has to change: the payload type comes from the name, and the
[delivery guarantees](/docs/dev/events#delivery-guarantees) are the same for a
core event as for one of your own.

## Core events (`@vitnode/core`) [#core-events-vitnodecore]

Six names, all declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. Every one of them fires **after**
the write it describes has committed.

| Event          | Payload                                  | Fires when                                                                |
| -------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `user.created` | `{ userId, email, name, emailVerified }` | A user row is inserted - public sign-up, AdminCP creation, or SSO sign-up |
| `user.updated` | `{ userId, email, name }`                | A user is edited in the AdminCP (profile fields and/or role assignments)  |
| `user.deleted` | `{ userId, email }`                      | Never - the name is declared for plugins, core has no deletion flow       |
| `role.created` | `{ roleId }`                             | A role is created in the AdminCP                                          |
| `role.updated` | `{ roleId }`                             | A role is edited in the AdminCP                                           |
| `role.deleted` | `{ roleId }`                             | A role is deleted in the AdminCP                                          |

<Accordions>
  <Accordion title="user.created">
    Emitted from `UserModel.signUp`, which is the one insert path into
    `core_users` - so it covers the public sign-up form, user creation in the
    AdminCP, and the first sign-in through an [SSO provider](/docs/dev/sso).

**A listener would** send a welcome or verification email (via a
    [queue task](/docs/dev/advanced/queue) so it retries), subscribe the address to
    a newsletter audience, or provision plugin-owned data such as a profile row.

```ts title="Example: welcome email listener"
    export const welcomeListener = buildEventListener({
      event: 'user.created',
      name: 'send-welcome-email',
      handler: async (c, payload) => {
        await c.get('queue').dispatch({
          name: 'send-welcome-email',
          payload: { userId: payload.userId, email: payload.email },
        })
      },
    })
    ```
  </Accordion>

<Accordion title="user.updated">
    Emitted by the AdminCP user `PATCH` after it commits - profile fields (email,
    name, name code) and/or role assignments. The payload carries the user's
    **current** values.

**A listener would** sync the identity into an external system (CRM, mailing
    list), invalidate a plugin-owned cache keyed by user, or audit-log the staff
    edit using the envelope's `actor`.
  </Accordion>

<Accordion title="user.deleted (declared, never emitted)">
    The name and payload live on the `VitNodeEvents` map so listeners type-check,
    but **core never emits it**: there is no user-deletion flow yet. It is the
    agreed-upon name for plugins that implement account deletion themselves, and
    core will emit it once deletion lands.

<Accordion title="role.created and role.updated">
    Emitted after a role is created or edited in the AdminCP, including its
    translated names - those live in `core_languages_words`, so the payload has no
    name field to carry.

**A listener would** provision plugin-side permission defaults for a new role,
    or refresh an externally-cached permission matrix when one changes.
  </Accordion>

<Accordion title="role.deleted">
    Emitted after the delete transaction commits. Its translated names are removed
    with it, and its secondary-role assignments and staff-permission entries are
    dropped by database cascade. Members point at their primary role through a
    `NOT NULL` restricted foreign key, so anyone in the role is reassigned
    **before** the delete - by the time this fires, no user references it.

**A listener would** clean up plugin-owned rows keyed by role id. The role row
    is already gone, so key the cleanup off `payload.roleId` rather than re-reading
    `core_roles`:

```ts title="Example: clean up plugin data on role deletion"
    export const roleCleanupListener = buildEventListener({
      event: 'role.deleted',
      name: 'cleanup-role-settings',
      handler: async (c, payload) => {
        await c
          .get('db')
          .delete(shop_role_settings)
          .where(eq(shop_role_settings.roleId, payload.roleId))
      },
    })
    ```
  </Accordion>
</Accordions>

## Content Engine events [#content-engine-events]

Every content type declared with the
[Content Engine](/docs/dev/content-engine) gets its own event names, built from
its id: `content.<id>.<action>`. For the example plugin's `example.article`
that means `content.example.article.created`, and for the blog's `blog.post` it
means `content.blog.post.created`.

Which actions exist depends on what the definition opts into. A content type
that declares nothing beyond its fields emits three events; one that declares
everything emits sixteen.

| The definition declares              | Events it adds                                                      |
| ------------------------------------ | ------------------------------------------------------------------- |
| nothing extra (always)               | `created`, `updated`, `deleted`                                     |
| `publication`                        | `published`, `unpublished`                                          |
| `editorial`                          | `restored`                                                          |
| `editorial.scheduling`               | `scheduled`, `schedule_cancelled`                                   |
| `localization`                       | `translation_created`, `translation_updated`, `translation_deleted` |
| `localization` **and** `publication` | `translation_published`, `translation_unpublished`                  |
| `localization` **and** `editorial`   | `translation_restored`                                              |
| `delivery`                           | `delivery_slug_changed`, `delivery_redirect_created`                |

The gating is in the types, not just at runtime: `ContentEventsFor` expands to
literal keys only for the features the definition enables. The example plugin's
`example.article` declares `editorial`, so
`content.example.article.restored` type-checks; `example.category` is one text
field and nothing else, so `content.example.category.restored` is not a key on
the map and a listener for it does not compile.

### Record events [#record-events]

| Event                | Payload                                                                     | Fires when                                                                        |
| -------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `created`            | `{ contentId }`                                                             | A record is inserted                                                              |
| `updated`            | `{ contentId, changedFields }`                                              | At least one declared field actually changed                                      |
| `deleted`            | `{ contentId }`                                                             | A record is deleted                                                               |
| `published`          | `{ contentId, publishedAt, scheduledBy?, scheduleId? }`                     | A record becomes publicly visible - interactively or when a schedule fires        |
| `unpublished`        | `{ contentId, scheduledBy?, scheduleId? }`                                  | A record is withdrawn                                                             |
| `restored`           | `{ contentId, changedFields, version, revisionId, restoredFromRevisionId }` | A record is rolled back to an earlier revision - emitted **instead of** `updated` |
| `scheduled`          | `{ contentId, action, actorUserId, scheduledFor, scheduleId }`              | A publish or unpublish is booked for later                                        |
| `schedule_cancelled` | `{ contentId, action, actorUserId, scheduleId }`                            | A pending booking is called off                                                   |

**A listener would** mirror the row into a plugin-owned projection, reindex it
    for an external search engine, or purge a CDN entry. `changedFields` is what
    lets it skip the work when the field it cares about did not move.
  </Accordion>

<Accordion title="published and unpublished">
    `publishedAt` is when the record went live for the **first** time and is never
    rewritten by a later unpublish and republish. `scheduledBy` and `scheduleId`
    are present only when a booking caused the transition; an interactive publish
    carries neither.

**A listener would** announce the record (a newsletter, a social post, a
    realtime toast), add or remove it from an external index, or expire a cache
    that only holds public rows. Because the same publish can arrive twice, key
    anything that must happen once off `scheduleId` - see
    [A scheduled event may arrive twice](#a-scheduled-event-may-arrive-twice).
  </Accordion>

<Accordion title="restored">
    A rollback to an earlier revision's field values. It carries `changedFields`
    exactly like `updated`, so porting an `updated` listener is a rename rather
    than a rewrite - which is why a restore emits one event and not both.

<TypeTable
      type="{
  contentId: {
    description: 'Id of the restored record.',
    type: 'number',
  },
  changedFields: {
    description:
      'The fields the rollback moved, in the same shape `updated` uses.',
    type: 'ContentFieldName<TDefinition>[]',
  },
  version: {
    description:
      'The version the record holds after the restore. Always a new number; the restored version is never reinstated.',
    type: 'number',
  },
  revisionId: {
    description: 'The revision this restore itself created.',
    type: 'number',
  },
  restoredFromRevisionId: {
    description: 'The revision the values were taken from.',
    type: 'number',
  },
}"
    />

**A listener would** do exactly what its `updated` listener does. A restore
    never moves `status` or `publishedAt`, so nothing watching visibility has to
    handle it.
  </Accordion>

<Accordion title="scheduled and schedule_cancelled">
    Booking a transition changes no field value, so it consumes no version and
    writes no revision - `scheduled` is a different fact from `published`. When the
    booking fires, the transition emits the ordinary `published` or `unpublished`
    with `scheduleId` and `scheduledBy` set.

**A listener would** show an editorial calendar, warn an author that two
    bookings collide, or pre-warm a render shortly before `scheduledFor`.
  </Accordion>
</Accordions>

### Translation events [#translation-events]

A content type with [`localization`](/docs/dev/content-engine/localization)
emits one event per translation mutation, in addition to the record events
above. Every one of them carries `locale` and `languageId`, so a listener never
has to go and ask which language moved.

| Event                     | Payload                                                          | Fires when                                |
| ------------------------- | ---------------------------------------------------------------- | ----------------------------------------- |
| `translation_created`     | `{ contentId, locale, languageId, version, revisionId? }`        | A language's translation row is written   |
| `translation_updated`     | `{ ...base, changedFields }`                                     | A language's localized fields changed     |
| `translation_deleted`     | `{ ...base }`                                                    | A language's translation is removed       |
| `translation_published`   | `{ ...base, publishedAt }`                                       | One language becomes publicly visible     |
| `translation_unpublished` | `{ ...base }`                                                    | One language is withdrawn                 |
| `translation_restored`    | `{ ...base, changedFields, revisionId, restoredFromRevisionId }` | One language is rolled back to a revision |

<Accordions>
  <Accordion title="The shared translation payload">
    <TypeTable
      type="{
  contentId: {
    description:
      'Id of the record the translation belongs to - the base row, not the translation row.',
    type: 'number',
  },
  locale: {
    description:
      'The canonical core_languages.code the mutation was made in. Always present.',
    type: 'string',
  },
  languageId: {
    description:
      'core_languages.id, for a listener joining against the languages table directly.',
    type: 'number',
  },
  version: {
    description:
      'The version *this translation* holds after the mutation - each language has its own.',
    type: 'number',
  },
  revisionId: {
    description:
      'The revision this mutation wrote. Absent - not null - for a localized content type without `editorial`, which keeps no history, so `"revisionId" in payload` is how a listener checks.',
    type: 'number',
  },
  changedFields: {
    description:
      'Updated and restored only - localized field names this write moved. Never a shared field.',
    type: 'ContentLocalizedFieldName<TDefinition>[]',
  },
  publishedAt: {
    description:
      'Published only - when this language first went live. Nullable, unlike its record-level counterpart.',
    type: 'Date | null',
  },
  restoredFromRevisionId: {
    description:
      "Restored only - the revision the values came from, always one of this locale's own.",
    type: 'number',
  },
}"
    />

**A listener would** invalidate one locale's cache, reindex one language's
    search document, or tell a translation vendor that the Polish copy moved.
  </Accordion>

<Accordion title="Why translations are not folded into updated">
    A shared update and a Polish translation update are different domain facts with
    different consequences: one invalidates every language, the other invalidates
    one. A listener that had to inspect `changedFields` to tell them apart would get
    it wrong the first time a field was renamed - so `changedFields` on a
    translation event names localized fields only, and never a shared one.
  </Accordion>
</Accordions>

### Delivery events [#delivery-events]

A content type with
[`delivery`](/docs/dev/content-engine/content-delivery-and-seo) emits two more
when its public URL moves. Both arrive **alongside** the lifecycle event that
moved it - `updated`, `restored`, a publication transition or a
`translation_*` - never instead of one: a field moving and a URL moving are
different facts with different audiences.

| Event                       | Payload                                                                  | Fires when                                                    |
| --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `delivery_slug_changed`     | `{ contentId, slug, previousSlug, previousPath, canonicalPath, locale }` | The canonical public path is different from what it was       |
| `delivery_redirect_created` | `{ contentId, previousSlug, previousPath, canonicalPath, locale }`       | A path that had genuinely been live now answers as a redirect |

**A listener would** purge a CDN entry, write to an edge redirect table, or tell
    an external search engine the address changed. Without this event it would have
    to inspect `changedFields` for a slug field whose name it cannot know.
  </Accordion>

<Accordion title="Why a redirect is a separate event">
    `delivery_redirect_created` fires only when the old address had genuinely been
    **publicly addressable** - the engine has a retired history row to prove it. An
    article whose slug was corrected three times while it was still a draft emits
    three `delivery_slug_changed` and not one redirect; a published article that
    moves emits one of each. That is the difference between "a URL now needs a
    redirect" and "somebody edited a field".

There is deliberately no sitemap event either: every mutation that changes a
    sitemap line already emits `published`, `unpublished`, `deleted` or one of these
    two, and a third carrying no new information would be one more thing to keep
    consistent for no listener's benefit.
  </Accordion>
</Accordions>

### A scheduled event may arrive twice [#a-scheduled-event-may-arrive-twice]

Announcements for a scheduled transition run in a durable
[queue task](/docs/dev/advanced/queue) that retries whenever the event, the
search write or a cache origin failed - and a retry re-emits an event some
listeners already received. Delivery is **at-least-once**, deliberately: the
alternative is a transactional outbox, which the engine does not have.

A listener whose work must happen exactly once keys off `scheduleId`, which is
stable across every attempt at the same booking:

```ts
handler: async (c, payload) => {
  if (payload.scheduleId && (await alreadyDone(payload.scheduleId))) return

await sendTheAnnouncement(payload.contentId)
}
```

An interactive publish is emitted once, by the route that performed it, and
carries no `scheduleId`.

### The envelope's owner is the content type's plugin [#the-envelopes-owner-is-the-content-types-plugin]

`pluginId` on the envelope answers "whose event is this", not "who was running
at the time". Those come apart the moment something happens on a schedule: core
owns the queue handler, so `c.get('plugin')` says `@vitnode/core`, while
`content.example.article.published` belongs to the example plugin as much as it
ever did.

```text
queue task owner    @vitnode/core        ← who runs the handler
event envelope      @vitnode/example     ← who owns the content type
```

The engine passes the owner explicitly on every emit, so ownership does not
depend on which route module or queue handler invoked it. Your own code can do
the same when it emits on someone else's behalf:

```ts
await c.get('events').emit('blog.post.created', payload, {
  pluginId: '@vitnode/blog', // [!code ++]
})
```

Omit the option and nothing changes: the envelope falls back to
`c.get('plugin')` and then to `@vitnode/core`.

### Failures are reported, not thrown [#failures-are-reported-not-thrown]

`emit()` reports rather than throws. Listeners run after the write it describes
has committed, and a broken listener is not a reason to tell somebody their save
failed - so a failure comes back in the result instead, and is written to
`core_logs` twice over: once per listener by the transport
(`Event listener "plugin:module:listener" for "<event>" failed: ...`), and once
as a JSON summary behind the greppable `[content-effects]` prefix by whichever
effects helper emitted it - the editorial, translation, delivery and scheduled
paths. A plain `created`/`updated`/`deleted` on a content type without
`editorial` goes straight to the transport, so it produces the first line only.

```ts
const result = await c.get('events').emit('blog.post.created', payload)

result.delivered // listeners that ran
result.failures // [{ pluginId, module, listener, error }]
```

Interactive routes ignore that result on purpose, because the mutation succeeded
either way. Background work usually should not: the scheduled-effects task
inspects `failures` and retries the whole delivery when it is non-empty.

{/* Image prompt: A screenshot of the VitNode AdminCP debug panel at /admin/core/debug, dark theme, 1440x900, showing one red "error" log row whose content is the JSON line [content-effects] {"action":"published","contentTypeId":"blog.post","delivered":1,"eventId":"6f1c...","failures":[{"error":"fetch failed","listener":"@acme/shop:orders:mirror-post"}],"itemId":42}. */}

<Callout type="warn" title="The generated routes emit, the services do not">
  A generated route emits one lifecycle event per successful mutation, after the
  database write has returned - plus the delivery pair when the URL moved with
  it. A failed validation, a delete blocked by a foreign key, a no-op update, a
  no-op publish and a restore that changed nothing all emit nothing. Calling
  `service.publish()` - or any other content service method - directly changes
  the database and emits **nothing**; that code owns its own follow-up. See
  [Services and API](/docs/dev/content-engine/services-and-api).
</Callout>

## Blog events (`@vitnode/blog`) [#blog-events-vitnodeblog]

<Callout type="warn" title="These six names are compatibility adapters">
  The blog runs on the [Content Engine](/docs/dev/content-engine), so the events
  that describe what actually happened are `content.blog.post.*` and
  `content.blog.category.*` - they carry changed fields, revision ids,
  publication transitions, per-locale translation events and slug history. The
  six names below are re-emitted from those by listeners registered on the
  plugin's own `admin` module, so existing consumers keep working. Prefer the
  `content.*` ones for anything new.
</Callout>

| Event                   | Payload                   | Re-emitted from                 |
| ----------------------- | ------------------------- | ------------------------------- |
| `blog.post.created`     | `{ postId, categoryId }`  | `content.blog.post.created`     |
| `blog.post.updated`     | `{ postId, categoryId }`  | `content.blog.post.updated`     |
| `blog.post.deleted`     | `{ postId }`              | `content.blog.post.deleted`     |
| `blog.category.created` | `{ categoryId }`          | `content.blog.category.created` |
| `blog.category.updated` | `{ categoryId }`          | `content.blog.category.updated` |
| `blog.category.deleted` | `{ categoryId, postIds }` | `content.blog.category.deleted` |

### blog.post.created and blog.post.updated [#blogpostcreated-and-blogpostupdated]

The adapter reads the article's categories back to fill in `categoryId`, so a
record deleted in between is simply not announced - and so is one with no
categories yet.

**A listener would** push a realtime "new post" notification, ping a webhook
(from a queue task) that shares the post to social media, invalidate an external
cache, or keep plugin-owned derived data such as related posts in sync.

### blog.post.deleted [#blogpostdeleted]

No `categoryId`, unlike created and updated: the row is gone by the time this is
emitted, so there is nothing left to read it from - and inventing one would put
a wrong id into an audit trail. A listener that needs the category should watch
`content.blog.post.deleted` and keep its own index.

**A listener would** remove the post from an external index or feed.

### blog.category.created and blog.category.updated [#blogcategorycreated-and-blogcategoryupdated]

**A listener would** keep a navigation menu or an externally-cached category
tree in sync, or notify an external CMS of a taxonomy change.

### blog.category.deleted [#blogcategorydeleted]

**A listener would** drop the category from a cached navigation tree. It never
has to fan out to the category's posts, because a category with posts cannot be
deleted in the first place.

## Gotchas [#gotchas]

<Callout type="warn" title="Core's user and role events are not deduplicated">
  The AdminCP user `PATCH` emits `user.updated` whenever it succeeds, even if
  every field was written with the value it already had, and the role routes
  behave the same way. Only the Content Engine's `updated` is gated on a real
  diff. A listener that does expensive work should compare before acting.
</Callout>

<Callout type="warn" title="A content type is only typed once its plugin grafts it">
  Events fire at runtime for every registered content type, but the names appear
  on `VitNodeEvents` only where the owning plugin declares
  `ContentEventsFor<typeof myContentType>`. The example plugin grafts
  `example.article` and `example.category` but not its two localized fixtures,
  so `content.example.localized-article.created` really is emitted and still
  cannot be given a type-checked listener. If your event name does not
  autocomplete, that declaration is what is missing - see
  [Plugin registration](/docs/dev/content-engine/plugin-registration).
</Callout>

<Callout type="warn" title="Editorial payloads carry more than they declare">
  A content type with `editorial` goes through the shared effects helper, which
  stamps `version` and `revisionId` onto **every** payload it emits, including
  `created` and `deleted`. Neither field is on the declared type for those
  actions, so treat them as an implementation detail rather than a contract -
  the fields you can rely on are the ones in the tables above.
</Callout>

<Callout type="warn" title="Names shift between scheduled and published">
  The person who booked a transition is `actorUserId` on `scheduled` and
  `schedule_cancelled`, and `scheduledBy` on the `published` and `unpublished`
  that the booking eventually fires. Same human, two keys.
</Callout>

## Deliberately not emitted yet [#deliberately-not-emitted-yet]

High-frequency or consumer-less events are added only when a listener needs
them, so the catalog stays meaningful. There is currently no `user.signedIn`,
`user.passwordResetRequested`, or `file.uploaded`. If you need one, open an
issue or PR - adding an event is a one-line `emit` plus an entry in the
`VitNodeEvents` map. (`user.deleted` is the special case: it is already on the
map, and waits on core growing a user-deletion flow.)

## Next [#next]

# Custom Event Adapter

By default, VitNode delivers domain events in-process on the originating machine. By implementing a custom `EventsApiPlugin`, you can forward events to an external message broker (Redis Streams, RabbitMQ, NATS) to fan them out across a distributed cluster.

## The `EventsApiPlugin` Interface [#the-eventsapiplugin-interface]

```ts
import type { Context } from "hono"
import type { EventEnvelope, EventEmitResult } from "@vitnode/core/api/models/events"

export interface EventsApiPlugin {
  name: string
  publish: (c: Context, envelope: EventEnvelope) => Promise<EventEmitResult>
}
```

***

## Quick start [#quick-start]

### 1. Build the Adapter [#1-build-the-adapter]

```ts title="apps/api/src/lib/events/redis-stream-adapter.ts"
import type { EventsApiPlugin } from "@vitnode/core/api/models/events"

export const RedisStreamEventsAdapter = (): EventsApiPlugin => ({
  name: "redis-stream",
  // [!code ++:13]
  publish: async (c, envelope) => {
    const redis = c.get("redis")
    if (redis) {
      await redis.xadd("vitnode:events", "*", "payload", JSON.stringify(envelope))
    }

return {
      eventId: envelope.eventId,
      status: "queued",
      delivered: 0,
      failures: [],
    }
  },
})
```

***

### 2. Register in API Configuration [#2-register-in-api-configuration]

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { RedisStreamEventsAdapter } from "./lib/events/redis-stream-adapter"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:3]
  events: {
    adapter: RedisStreamEventsAdapter(),
  },
})
```

All calls to `c.get("events").emit()` will now publish events through your custom adapter.

## Learn More [#learn-more]

# Events

VitNode includes an in-process event bus accessible via `c.get("events")`. Events decouple features across plugins (e.g. sending a welcome email when a user registers) without direct inter-plugin dependencies.

## Quick start [#quick-start]

### 1. Emit an Event [#1-emit-an-event]

Emit events from any Hono route or service after a database write:

```ts
await c.get("events").emit("user.created", {
  userId: user.id,
  email: user.email,
  name: user.name,
  emailVerified: user.emailVerified,
})
```

***

### 2. Subscribe with an Event Listener [#2-subscribe-with-an-event-listener]

Define a listener in your plugin:

```ts title="plugins/shop/src/api/lib/events.ts"
import { buildEventListener } from "@vitnode/core/api/lib/events"

export const welcomeListener = buildEventListener({
  event: "user.created",
  name: "send-welcome-email",
  handler: async (c, payload) => {
    await c.get("queue").dispatch({
      name: "send-welcome-email",
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})
```

```ts title="plugins/shop/src/api/modules/orders/orders.module.ts"
import { buildModule } from "@vitnode/core/api/lib/module"
import { welcomeListener } from "../../lib/events"

export const ordersModule = buildModule({
  name: "orders",
  routes: [listOrdersRoute],
  events: [welcomeListener], // [!code ++]
})
```

***

## Declare Custom Event Types [#declare-custom-event-types]

Extend VitNode's global `EventMap` interface in your plugin so payload types are strictly enforced and autocompleted:

```ts title="plugins/shop/src/api/lib/events.ts"
export interface OrderPlacedPayload {
  orderId: number
  userId: number
  total: number
}

// [!code ++:7]
declare module "@vitnode/core/lib/events" {
  interface EventMap {
    "shop.order.placed": OrderPlacedPayload
  }
}
```

Now `emit("shop.order.placed", ...)` and `buildEventListener({ event: "shop.order.placed", ... })` are strictly type-checked.

***

## Delivery Guarantees [#delivery-guarantees]

## Learn More [#learn-more]

# Fetcher

<Callout type="info" title="Use this by default">
  In a TanStack Start app, use `fetcher` through a plugin API client. The same
  request works during SSR and browser navigation.
</Callout>

During SSR, VitNode forwards the visitor’s request to the API. In the browser,
it calls `/api/*` directly. You do not need to write `createIsomorphicFn()` or
choose a transport.

## Create your API client once [#create-your-api-client-once]

<Steps>
  <Step>
    ### Define it in your plugin [#define-it-in-your-plugin]

Keep this in one plugin file. Features import `notesApi`; they never set up a
    module reference themselves.

```ts title="plugins/site-notes/src/api/client.ts"
    import type { notesModule } from "../api/notes.module"

import { createApiClient } from "@vitnode/core/tanstack/fetcher"

export const notesApi = createApiClient<typeof notesModule>("@acme/site-notes")
    ```
  </Step>

<Step>
    ### Fetch data [#fetch-data]

```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
    import { queryOptions } from "@tanstack/react-query"

import { notesApi } from "../../api/client"

export const notesQueryKey = ["@acme/site-notes", "notes"] as const

export const notesQuery = () =>
      queryOptions({
        queryKey: notesQueryKey,
        queryFn: async ({ signal }) => {
          const response = await notesApi.fetch({
            method: "get",
            module: "notes",
            options: { signal },
            path: "/",
          })

if (!response.ok) {
            throw new Error(`The notes API answered ${response.status}.`)
          }

return await response.json()
        },
      })
    ```
  </Step>
</Steps>

## Use it on a page or in a mutation [#use-it-on-a-page-or-in-a-mutation]

<Tabs items="["Initial page", "Mutation"]">
  <Tab value="Initial page">
    Warm the query in the route loader. The component reads that same cache entry
    with `useQuery(notesQuery())`.

```ts title="plugins/site-notes/src/routes/notes.tsx"
    import { definePluginRoute } from "@vitnode/core/routing"

import { notesQuery } from "../features/notes/notes-query"

export const route = definePluginRoute({
      load: async ({ context }) =>
        await context.queryClient.ensureQueryData(notesQuery()),
    })
    ```
  </Tab>

<Tab value="Mutation">
    Use the same API client, then invalidate the data that changed.

```tsx title="plugins/site-notes/src/features/notes/create-note.tsx"
    import { useMutation, useQueryClient } from "@tanstack/react-query"

import { notesApi } from "../../api/client"
    import { notesQueryKey } from "./notes-query"

export const useCreateNote = () => {
      const queryClient = useQueryClient()

return useMutation({
        mutationFn: async (title: string) => {
          const response = await notesApi.fetch({
            args: { body: { title } },
            method: "post",
            module: "notes",
            path: "/",
          })

if (!response.ok) throw new Error("Could not create the note.")

return await response.json()
        },
        onSuccess: async () =>
          await queryClient.invalidateQueries({ queryKey: notesQueryKey }),
      })
    }
    ```
  </Tab>
</Tabs>

## Server-only work [#server-only-work]

Use `@vitnode/core/tanstack/fetcher/server` only for a server function, cookie
relay, cron/job, secret, or a custom API origin.

<Callout type="warn" title="Keep it server-only">
  Put code that imports this fetcher in a `*.server.ts` file, or call it only
  from a server function.
</Callout>

## What the types do [#what-the-types-do]

* `method`, `module`, and `path` are always required.
* `args` is required when the route declares a body, params, or query.
* TypeScript infers the valid route, arguments, response status, and JSON body.

Generated Content Engine modules have no static module type, so use
`rawFetcher` for them instead.

# Languages & Localization

VitNode provides full internationalization out of the box. Every package (`@vitnode/core` and plugins) maintains its own locale files, which VitNode merges per request: core strings first, plugin strings second, and your host app overrides last.

{/* Image prompt: Layered merge diagram showing @vitnode/core strings, plugin strings, and app overrides merging into a unified message tree with defaultLocale fallback. Dark theme, 1600x700. */}

## Quick start [#quick-start]

Add a new language in two CLI commands:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Add a language">
  <Tab value="bun">
    ```bash
    bun run vitnode i18n:create de Deutsch
    bun run vitnode i18n:check
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm vitnode i18n:create de Deutsch
    pnpm vitnode i18n:check
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npx vitnode i18n:create de Deutsch
    npx vitnode i18n:check
    ```
  </Tab>
</Tabs>

`i18n:create` adds the language to `src/vitnode.config.ts`, seeds a translation file per installed package, and registers the loaders in `src/locales/app.ts`. `i18n:check` scans for missing or untranslated keys - including a file nobody imports, which is the usual reason a translation "does not apply".

***

## Language Configuration [#language-configuration]

Locale metadata is plain data, so it lives in the browser-safe [shared config](/docs/dev/configuration) - one declaration, read by the router, the document shell and (in a single app) the API that sends your emails:

```ts title="apps/web/src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      // [!code ++:1]
      { code: 'de', name: 'Deutsch' },
    ],
    timeZone: 'UTC',
  },
  // ...
})
```

`timeZone` is explicit on purpose: your app renders on a server, and without one `use-intl` formats dates in whatever zone the server happens to run in - then warns that the client will disagree.

Because `buildConfig` keeps those codes as literal types, `'de'` is now part of your `Locale` union and a typo in `defaultLocale` is a type error.

***

## Where the loaders go [#where-the-loaders-go]

A `() => import('./de.json')` reads a file out of a package's build output, so it is the one part of i18n that must never reach a browser. Two files own it, and both are registered through the **server-only** config:

```ts title="apps/web/src/vitnode.server.config.ts"
export const vitNodeServerConfig = buildServerConfig({
  config: vitNodeConfig, // the locale list above
  messages: appMessages, // src/locales/app.ts
  packageMessages, // src/locales/packages.ts
})
```

<Callout type="warn" title="Not in vitnode.config.ts">
  Putting a loader in the shared config puts every plugin's AdminCP copy in your
  browser bundle, and makes your Vite build execute it. `vitnode i18n:create`
  writes to the right file for you.
</Callout>

Adding a language to a package that ships it needs one line in `src/locales/packages.ts`:

```ts title="apps/web/src/locales/packages.ts"
[CORE.pluginId]: {
  en: async () => await import('@vitnode/core/locales/en.json'),
  de: async () => await import('@vitnode/core/locales/de.json'), // [!code ++]
},
```

***

## Overriding Strings [#overriding-strings]

To customize existing text from core or a third-party plugin, add an override file in `apps/web/src/locales/{pluginId}/{locale}.json` and register it in `src/locales/app.ts`:

```json title="apps/web/src/locales/@vitnode/core/en.json"
{
  "core": {
    "global": {
      "save": "Update Changes"
    }
  }
}
```

```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
  // [!code ++:3]
  en: {
    '@vitnode/core': async () => await import('./@vitnode/core/en.json'),
  },
}
```

Because your app overrides are merged last, only the keys you specify are overwritten. Everything else continues to fall back to the package defaults.

***

## Translation Architecture [#translation-architecture]

| Source               | Role                                               | Order                   |
| :------------------- | :------------------------------------------------- | :---------------------- |
| `@vitnode/core`      | Base strings for auth, admin shells, and dialogs   | Base layer              |
| **Plugins**          | Domain strings declared in `plugins/*/src/locales` | Second layer            |
| **Host Application** | Custom overrides in `apps/web/src/locales`         | Highest priority (wins) |

Missing keys automatically fall back to `defaultLocale` (`en`), preventing raw key paths from displaying in production.

## Learn More [#learn-more]

# Messages & ICU Syntax

VitNode localizes strings using standard ICU MessageFormat, parsed and rendered through [`use-intl`](https://use-intl.dev).

## Quick start [#quick-start]

### 1. Define Message Strings [#1-define-message-strings]

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog": {
    "welcome": "Welcome back, {name}!",
    "articles_count": "{count, plural, =0 {No articles} one {1 article} other {# articles}}",
    "terms_notice": "By clicking continue, you agree to our <link>Terms of Service</link>."
  }
}
```

***

### 2. Render in React Components [#2-render-in-react-components]

```tsx title="plugins/blog/src/views/blog-header.tsx"
import { useTranslations } from "use-intl"
import { Link } from "@tanstack/react-router"

export const BlogHeader = ({ count, name }: { count: number; name: string }) => {
  const t = useTranslations("@vitnode/blog")

return (
    <header className="flex flex-col gap-2">
      <h1>{t("welcome", { name })}</h1>
      <p>{t("articles_count", { count })}</p>

{/* Rich text with custom tags */}
      <small className="text-muted-foreground">
        {t.rich("terms_notice", {
          link: (chunks) => <Link to="/terms" className="underline">{chunks}</Link>,
        })}
      </small>
    </header>
  )
}
```

***

## ICU Syntax Reference [#icu-syntax-reference]

### 1. Variables & Numbers [#1-variables--numbers]

```json
{
  "price": "Total: {amount, number, ::currency/USD}",
  "date": "Published on {date, date, medium}"
}
```

### 2. Cardinal Pluralization [#2-cardinal-pluralization]

```json
{
  "unread": "{count, plural, =0 {No unread messages} one {1 unread message} other {# unread messages}}"
}
```

### 3. Select / Enums [#3-select--enums]

```json
{
  "status": "{status, select, draft {Draft} published {Published} other {Archived}}"
}
```

***

## Where Message Files Live [#where-message-files-live]

| Folder                          | Audience       | Purpose                                            |
| :------------------------------ | :------------- | :------------------------------------------------- |
| `src/locales/{locale}.json`     | **Frontend**   | Browser UI, page text, and AdminCP navigation      |
| `src/locales/api/{locale}.json` | **API Server** | Transactional emails and backend validation errors |

## Learn More [#learn-more]

# Namespaces

A namespace is a dotted path into the merged message tree - `core.global`,
`@vitnode/blog.admin.article`. It is the unit of two things at once: what
`useTranslations` reads from, and what a page is allowed to download. The merged
tree holds every installed plugin's copy, and no page should ship all of it, so a
page names the branches it renders and gets exactly those.

## Example [#example]

```json title="plugins/my-plugin/src/locales/en.json"
{
  "my-plugin": {
    "home": { "title": "Hello World" },
    "admin": { "overview": { "title": "My plugin" } }
  }
}
```

```tsx
const t = useTranslations('my-plugin.home')
```

Two namespaces exist there - `my-plugin.home` and `my-plugin.admin.overview` -
and a page that renders the public one never downloads the admin one.

## The tree [#the-tree]

Everything sits under the id of the package that owns it. Core owns three
branches; a plugin owns exactly one, named after itself.

| Namespace         | Owner           | What is in it                                               |
| ----------------- | --------------- | ----------------------------------------------------------- |
| `core.global`     | core            | Design-system strings every VitNode page needs              |
| `core.*`          | core            | Auth, files, search, content - the public site              |
| `admin.*`         | core            | The AdminCP: `admin.global`, `admin.user`, `admin.staff`, … |
| `@vitnode/blog.*` | `@vitnode/blog` | Everything that plugin ships                                |
| `{your-plugin}.*` | your plugin     | Everything yours ships                                      |

`core.global` is special only in that it is provided above every route, so any
shared component can translate itself wherever it is mounted. Everything else is
asked for.

## The per-plugin prefix rule [#the-per-plugin-prefix-rule]

**Every top-level key a plugin ships is the plugin's own id.** A key outside it
collides with core and with every other plugin, so VitNode ignores it rather than
letting two packages fight over one path.

```json title="plugins/my-plugin/src/locales/en.json"
{
  "my-plugin": {
    "hello": "Hello World" // [!code ++]
  },
  "world": "World" // [!code --]
}
```

Scoped ids work exactly the same way - `@vitnode/blog` is one path segment even
though it contains a slash, so `@vitnode/blog.admin` is a legal two-segment
namespace.

<Callout title="Permission labels are the one exception" type="info">
  A staff permission's label is a **flat top-level key**, not a branch:
  `@vitnode/blog:posts:can_view`. There is nothing to slice a namespace out of,
  so the AdminCP asks for those keys as if they were namespaces and has to chunk
  the request to stay under the limit below. If you are writing them, see [Staff
  permissions](/docs/dev/working-with-users/staff-permissions).
</Callout>

## Asking for a namespace [#asking-for-a-namespace]

Declare the exact branches a plugin page renders as the route's `messages`.
VitNode loads them with the route chunk, so public pages do not download a
plugin’s AdminCP copy just because it exists.

```ts title="plugins/my-plugin/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/reports', {
    component: lazy(() => import('./pages/reports-page')),
    // [!code ++]
    messages: ['my-plugin.reports'],
  }),
])
```

A route inherits every namespace its layouts declare, so a shared frame can name
them once for a whole subtree. The route module then calls
`useTranslations('my-plugin.reports')`; if a key renders as its own name, confirm
the route declared the matching namespace.

## Limits [#limits]

A namespace list reaches the server through a server function, which is a public
`POST` endpoint once the app is built. So the rules are enforced rather than
assumed, and the same rules validate a plugin's build-time declaration - one
definition, in `@vitnode/core/routing`, so a route tree cannot accept something the
server refuses.

On top of the numbers: a namespace must be a non-empty string, must not contain
an empty segment (`core..global`, a leading or trailing dot), and must not
contain `__proto__`, `constructor` or `prototype` in any segment. All three are
rejected outright rather than filtered away - a namespace containing one is not a
namespace with a typo in it.

Import the constants if you need to budget against them:

```ts
import { MAX_NAMESPACES } from '@vitnode/core/tanstack/i18n'
```

## Gotchas [#gotchas]

<Callout title="Every string renders as its own key" type="error">
  The symptom of a namespace that was never asked for. Check that the route
  declares it in the plugin's `routes.ts`.
</Callout>

<Callout title="Over sixteen namespaces means chunking, not raising the cap" type="warn">
  `At most 16 namespaces may be requested.` is a thrown error, not a truncation.
  If you genuinely need more - a screen rendering one flat key per permission -
  split the request the way the staff screens do and merge the results, rather
  than reaching for a bigger number.
</Callout>

<Callout title="Namespaces are per route, not per plugin" type="info">
  Name what the page renders. Declaring your plugin's whole tree on every route
  puts your AdminCP copy in the bundle of a public page nobody logged in is
  looking at.
</Callout>

<Callout title="A pendingComponent renders above its own provider" type="warn">
  A layout route's `pendingComponent` renders *in place of* the layout, so it is
  outside the `RouteMessages` that layout mounts. Either keep it free of
  translated text or mount a provider inside it. A child route's
  `pendingComponent` is fine - it renders into the layout's `<Outlet />
    `, which only exists once the provider has.
</Callout>

## Next [#next]

# Translating Pages

VitNode uses [`use-intl`](https://use-intl.dev) for frontend translations. To keep initial payloads small, pages only download the translation namespaces they explicitly declare.

## Quick start [#quick-start]

### 1. In a Plugin Route (Recommended) [#1-in-a-plugin-route-recommended]

Plugin routes declare their namespaces as `messages` in `routes.ts`. VitNode loads the strings in parallel with the route chunk automatically:

```ts title="plugins/blog/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/blog/about', {
    component: lazy(() => import('./pages/about-page')),
    messages: ['@vitnode/blog.about'], // [!code ++]
  }),
])
```

Read strings directly with `useTranslations`:

```tsx title="plugins/blog/src/pages/about-page.tsx"
import { useTranslations } from 'use-intl'

const AboutPage = () => {
  const t = useTranslations('@vitnode/blog.about')

return <h1>{t('title')}</h1>
}

export default AboutPage
```

And define the messages in `plugins/blog/src/locales/en.json`:

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog": {
    "about": {
      "title": "About Our Blog"
    }
  }
}
```

<Callout type="idea" title="Keep feature copy in the plugin">
  Host messages are for the site shell. A product page should declare its plugin
  namespace as the route's `messages` and keep its locale JSON beside the route.
</Callout>

## Placeholders and Pluralization [#placeholders-and-pluralization]

VitNode supports ICU message syntax out of the box:

```json title="plugins/blog/src/locales/en.json"
{
  "cart": {
    "greeting": "Hello, {name}!",
    "items": "{count, plural, =0 {No items} one {1 item} other {# items}}"
  }
}
```

In your React component:

```tsx
const t = useTranslations('cart')

return (
  <div>
    <p>{t('greeting', { name: 'Alex' })}</p>
    <p>{t('items', { count: 3 })}</p>
  </div>
)
```

<Callout type="info" title="Global namespaces">
  `core.global` is provided by the root shell to every route, supplying shared
  strings for dialogs, toasts, and buttons.
</Callout>

## Learn More [#learn-more]

# API i18n

The API gets the same message tree the frontend does, reachable in any route as `c.get("i18n")`.

```ts
const t = await c.get('i18n').getTranslator()

return c.json({ message: t('core.global.save') })
```

<Callout title="Nothing is copied" type="info">
  The API reads locale files straight out of `node_modules`. There is no build
  step to remember and no `src/locales/` folder to keep in sync - install a
  plugin and its translations are available on the server immediately.
</Callout>

The server loads a different, smaller set of strings than the frontend. Packages ship two trees - the frontend's UI copy in `src/locales/`, and the server's strings (emails) in `src/locales/api/` - and the API only ever loads the second. An API-only app never pulls in the admin UI's messages.

## Which locale a request gets [#which-locale-a-request-gets]

`resolveLocale` walks four options in order and takes the first one your app actually lists in `i18n.locales`:

<Steps>
  <Step>
    ### An explicit choice [#an-explicit-choice]

`getTranslator("pl")`, or the `locale` you passed to `email.send()`. Use it when the language is a property of the thing you are rendering rather than of the caller.
  </Step>

<Step>
    ### The signed-in user's language [#the-signed-in-users-language]

`core_users.language`, already loaded on `c.get("user")`.
  </Step>

<Step>
    ### The `Accept-Language` header [#the-accept-language-header]

Parsed with its `q` weights, matched exactly first and then on the primary subtag - so `pl-PL` still finds `pl`.
  </Step>

<Step>
    ### `defaultLocale` [#defaultlocale]

`en` unless your `i18n` config says otherwise.
  </Step>
</Steps>

Anything not in `i18n.locales` is skipped rather than used, so a stale language code on a user row cannot produce a half-English page.

### Rendering for someone else [#rendering-for-someone-else]

That chain describes the *caller*. When the language belongs to whoever you are rendering for rather than to whoever made the request - an email recipient, a queued job's target - reach for `resolveSupportedLocale` instead:

```ts
const locale = c.get('i18n').resolveSupportedLocale(recipient.language)
```

It takes the language you hand it when the app ships it and `defaultLocale` when it doesn't, and it never touches the request. Dropping a language from `i18n.locales` should send that user English, not the language of the admin who clicked the button.

## The API [#the-api]

<TypeTable
  type="{
  getTranslator: {
    description:
      'use-intl translator for the resolved locale. Pass a locale to override the resolution.',
    type: '(locale?: string) => Promise<Translator>',
  },
  getMessages: {
    description: 'The merged message tree, if you need the raw object.',
    type: '(locale?: string) => Promise<Messages>',
  },
  resolveLocale: {
    description:
      'Runs the resolution above for the caller, without loading anything.',
    type: '(explicit?: string) => string',
  },
  resolveSupportedLocale: {
    description:
      'A locale you already have, or defaultLocale if the app does not ship it. Never reads the request.',
    type: '(preferred?: string) => string',
  },
  locales: {
    description: 'Every locale the app accepts.',
    type: 'LocaleConfig[]',
  },
  defaultLocale: {
    description: 'The fallback locale.',
    type: 'string',
  },
}"
/>

Merged trees are cached per locale for the life of the process, so only the first call per language touches the filesystem.

## Emails [#emails]

Emails run through `resolveSupportedLocale`, so they render in the recipient's language or `defaultLocale` - never in the sender's. You rarely call the translator yourself:

```ts title="src/api/modules/users/routes/welcome.route.ts"
await c.get("email").send({
  user, // `user.language` decides the locale
  subject: ({ i18n }) => createTranslator(i18n)("welcome.email.subject"),
  content: props => <WelcomeEmail {...props} />,
});
```

Sending to a bare address instead of a user? Pass `locale` explicitly:

```ts
await c.get("email").send({
  to: "hello@example.com",
  locale: "pl", // [!code highlight]
  subject: "Cześć",
  content: props => <WelcomeEmail {...props} />,
});
```

The template receives `i18n` as a prop and turns it into a translator with `createTranslator` from `use-intl`:

```tsx title="src/emails/welcome.tsx"
import { createTranslator } from 'use-intl' // [!code ++]

export default function WelcomeEmail({ i18n }: DefaultTemplateEmailProps) {
  const t = createTranslator(i18n)

return <Text>{t('welcome.email.body')}</Text>
}
```

## Shipping translations with a plugin [#shipping-translations-with-a-plugin]

A plugin owns its languages, and it splits them the same way the framework does: frontend strings in `src/locales/`, server strings (emails) in `src/locales/api/`. Each tree gets a barrel and is registered with the matching config - the frontend tree with `buildPlugin` in `config.tsx`, the server tree with `buildApiPlugin` in `config.api.ts`.

Most plugins render nothing server-side, so they ship only the frontend tree and register `messages` in `config.tsx` alone. Add the `api/` tree only when your plugin sends email:

```ts title="plugins/{your_plugin}/src/locales/api/index.ts"
import type { LocaleMessagesMap } from '@vitnode/core/lib/i18n/types'

const messages: LocaleMessagesMap = {
  en: async () => await import('./en.json', { with: { type: 'json' } }),
}

export default messages
```

```ts title="plugins/{your_plugin}/src/config.api.ts"
import messages from './locales/api' // [!code ++]

export const yourApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    messages, // [!code ++]
    modules: [postsModule],
  })
```

Adding a language later is a new file plus one line in the barrel - apps pick it up on their next install, and can translate your plugin without forking it by dropping a file in their own `src/locales/{your_plugin}/`.

## Typing the keys [#typing-the-keys]

`t()` autocompletes from a `global.d.ts` that augments use-intl's `Messages`. Import the tree an app actually uses: an API-only app types against the server tree alone, a frontend-only app against the frontend tree, and a single app - one that serves the frontend and runs the API together - against both.

```ts title="global.d.ts (single app)"
/// <reference types="use-intl" />

import coreApi from '@vitnode/core/locales/api/en.json' with { type: 'json' }
import core from '@vitnode/core/locales/en.json' with { type: 'json' }

declare module 'use-intl' {
  interface AppConfig {
    Messages: typeof core & typeof coreApi // [!code highlight]
  }
}
```

<Callout title="Keys must be namespaced" type="warn">
  Everything a plugin ships belongs under its own namespace, or it will collide
  with core. See [Namespaces](/docs/dev/i18n/namespaces).
</Callout>

## When a translation goes missing [#when-a-translation-goes-missing]

VitNode says so, once per package and locale, rather than quietly rendering raw keys:

```
[VitNode i18n] Could not load "pl" messages for "@vitnode/blog" - its strings will render as raw keys.
```

Run [`vitnode i18n:check`](/docs/dev/i18n) to find gaps before your users do.

# Introduction

VitNode is a **TanStack Start** front end, a **Hono** API, Postgres, and an
AdminCP. Its important rule is pleasantly simple: product features live in
**plugins**. A plugin owns its pages, APIs, data, translations, and AdminCP
extensions, so your host app does not become a drawer full of mystery cables.

{/* Image prompt: Clean dark-theme architecture diagram. A TanStack Start application and Hono API sit in the center, Postgres below, and three colorful plugin packages connect to routes, API modules, data, and AdminCP. Keep labels large and legible, 1600x900. */}

<Callout type="info" title="Canary documentation">
  These pages follow VitNode 2.0 on the `canary` branch. It moves quickly; when
  code and prose disagree, trust the code and send the prose a friendly PR.
</Callout>

## Start with a running app [#start-with-a-running-app]

<Cards>
  <Card icon="<RocketIcon />" title="Get an app running" description="Scaffold VitNode, migrate Postgres, and enter AdminCP." href="/docs/dev/setup" />

<Card icon="<PackagePlusIcon />" title="Create a plugin" description="Make the package that will own your first feature." href="/docs/dev/plugins/create" />

<Card icon="<ServerIcon />" title="Deploy VitNode" description="Build, migrate, and run your app on a server or container." href="/docs/dev/deployments/self-hosted" />
</Cards>

## Create an app [#create-an-app]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Create a VitNode app">
  <Tab value="bun">
    ```bash
    bun create vitnode-app@canary
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm create vitnode-app@canary
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm create vitnode-app@canary
    ```
  </Tab>
</Tabs>

Choose **Single App** for one TanStack Start app with Hono at `/api`, or a
monorepo when web and API deploy separately. If you plan to create plugins,
enable **Turborepo** during setup: the generator needs a workspace root.

## The five-minute path [#the-five-minute-path]

1. Start Postgres (Docker is the low-drama local choice).
2. Run `db:migrate` to create core tables and your first administrator.
3. Run `dev`, then visit `http://localhost:3000/admin`.
4. Create a plugin for your first product page, API endpoint, content type, or
   dashboard widget.

Every command above is expanded in [Getting started](/docs/dev/setup). From
there, [Build your first plugin](/docs/guides/first-plugin) gives you a real
route to visit—not just a philosophical plugin.

## Find the right reference [#find-the-right-reference]

<Cards>
  <Card icon="<PackagePlusIcon />" title="Plugin routes" description="Claim public or AdminCP URLs without adding host route files." href="/docs/dev/plugins/routes" />

<Card icon="<ServerIcon />" title="Admin Control Panel" description="Add plugin-owned screens, navigation, permissions, and widgets." href="/docs/dev/plugins/admin" />

<Card icon="<BookOpenIcon />" title="Content Engine" description="Define content once and receive data, API, and AdminCP tools." href="/docs/dev/content-engine" />
</Cards>

# Performance

TanStack Start splits components into separate lazy chunks by default, keeping the initial entry bundle light. Follow these key practices to maintain instant page loads.

## Performance Checklist [#performance-checklist]

1. **Keep `head` metadata isolated**: Never import UI components into route `head`.
2. **Lazy-load heavy dialogs**: Use `React.lazy` + `Suspense` for complex editors and dialogs.
3. **Dynamic imports inside loaders**: Lazy-load heavy server/client utilities with `await import(...)`.
4. **Optimize images**: Use `loading="lazy"`, responsive widths, and explicit dimensions.
5. **Analyze your bundle**: Regularly check client chunk sizes.

***

## What Lands in the Client Entry Bundle [#what-lands-in-the-client-entry-bundle]

TanStack Router automatically extracts route `component`, `errorComponent`, and `notFoundComponent` into lazy chunks:

***

## Best Practices [#best-practices]

### 1. Isolate Metadata from Components [#1-isolate-metadata-from-components]

Because `head` is evaluated in the main route bundle, importing strings from component files accidentally pulls entire component trees into the initial download:

```tsx title="plugins/home/src/pages/home-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

// BAD: Pulls HomeRouteContent and all its heavy icons/charts into main entry
import { HOME_TITLE, HomeRouteContent } from '../views/home-content' // [!code --]

// GOOD: Metadata strings live in a lightweight leaf file
import { HomeRouteContent } from '../views/home-content' // [!code ++]
import { HOME_DESCRIPTION, HOME_TITLE } from '../views/metadata' // [!code ++]

export const route = definePluginRoute({
  head: () =>
    pageHead({
      title: HOME_TITLE,
      description: HOME_DESCRIPTION,
    }),
})

export default HomeRouteContent
```

### 2. Lazy Dialogs and Heavy Form Editors [#2-lazy-dialogs-and-heavy-form-editors]

Heavy editors (like Tiptap) or complex modals should be lazy-loaded with `React.lazy` and `Suspense`:

```tsx title="plugins/blog/src/views/admin/article-editor.tsx"
import React, { Suspense } from 'react'
import { Loader } from '@vitnode/core/components/ui/loader'

// [!code ++:6]
const RichEditor = React.lazy(async () =>
  import('@vitnode/core/components/form/fields/editor').then((mod) => ({
    default: mod.AutoFormEditor,
  })),
)

export const ArticleEditor = (props) => (
  <Suspense fallback={<Loader />}>
    <RichEditor {...props} />
  </Suspense>
)
```

### 3. Dynamic Imports Inside Loaders [#3-dynamic-imports-inside-loaders]

When a route loader requires a heavy calculation or parsing library, import it dynamically:

```tsx title="plugins/stats/src/pages/stats-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async () => {
    // Only downloaded when visitor navigates to /stats
    const { calculateStats } = await import('../features/stats/calculator') // [!code ++]
    return calculateStats()
  },
})
```

### 4. Lazy Images Below the Fold [#4-lazy-images-below-the-fold]

Always specify explicit aspect ratios and `loading="lazy"` on images outside the initial viewport, and ship WebP with a `srcSet` so a phone never downloads the desktop rendition:

```tsx
<img
  src={photo.large}
  srcSet={`${photo.small} 800w, ${photo.large} 1600w`}
  sizes="(min-width: 1024px) 1024px, 100vw"
  alt="Community event"
  width={1600}
  height={866}
  loading="lazy"
  decoding="async"
  className="aspect-video object-cover rounded-lg"
/>
```

The one image that is the page's largest element on arrival - a hero screenshot - is the exception: give it `loading="eager"` and `fetchPriority="high"` so the browser asks for it first.

### 5. Skip Rendering Work for Offscreen Sections [#5-skip-rendering-work-for-offscreen-sections]

A long marketing page can carry a hundred CSS animations, most of them below the fold. Give each section `content-visibility: auto` with a `contain-intrinsic-size` estimate and the browser skips style, layout and animation work for everything not near the viewport:

```css title="apps/web/src/site/marketing/marketing.css"
.mk-section-anchor {
  scroll-margin-top: 5rem;
  content-visibility: auto;
  contain-intrinsic-size: auto 48rem;
}
```

The home page went from 133 running animations to 42 on arrival with this one rule, and the pages still scroll and deep-link normally.

### 6. Keep the Plugin Factory Light [#6-keep-the-plugin-factory-light]

`vitnode.config.ts` is bundled with the document shell, so everything a plugin factory imports ships to every visitor. A factory that spreads `admin/content` or `admin/nav` drags the AdminCP editing stack - AutoForm, schemas, dialogs - into the public bundle. Keep it to `pluginId`, `messages` and `routes`; see [Plugin frontend modules](/docs/dev/content-engine/plugin-registration).

### 7. Route-Scoped Stylesheets [#7-route-scoped-stylesheets]

Tailwind emits one utility per class it finds in the sources you list. A documentation UI kit scanned globally pays its CSS on the home page too. Give it a stylesheet of its own and load it from the layout route that renders it:

```css title="apps/web/src/docs/docs.css"
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css';
@import '../theme.css' theme(reference);
@import 'tailwindcss/utilities.css' layer(utilities) source(none);
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

@source '../../node_modules/fumadocs-ui/dist/**/*.js';
```

```tsx title="apps/web/src/routes/_docs.tsx"
import docsCss from '#/docs/docs.css?url'

export const Route = createFileRoute('/_docs')({
  loader: async () => ({ pageTree: await getDocsPageTree() }),
  head: () => ({ links: [{ href: docsCss, rel: 'stylesheet' }] }),
  // ...
})
```

`theme(reference)` makes the app's design tokens available to the second stylesheet without emitting them twice, and `source(none)` stops it from scanning the whole app again.

### 8. Group Shared Vendor Modules [#8-group-shared-vendor-modules]

Rolldown splits every module shared by two routes into its own file, which for an icon library means dozens of 300-byte requests per page. Group the libraries that are shared by design into one chunk each:

```ts title="apps/web/vite.config.ts"
build: {
  rolldownOptions: {
    output: {
      advancedChunks: {
        groups: [
          { name: 'icons', test: /node_modules[\\/].*lucide-react/, minShareCount: 2 },
        ],
      },
    },
  },
},
```

Group only libraries whose shared surface is small. A UI primitive library shared by every AdminCP screen turns into a single 280 KB chunk that public pages then download for a tooltip.

***

## Measuring Bundle Size [#measuring-bundle-size]

Analyze your client bundle with Vite:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Build and analyze">
  <Tab value="bun">
    ```bash
    bun run build
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm build
    ```
  </Tab>

<Tab value="npm">
    ```bash
    npm run build
    ```
  </Tab>
</Tabs>

Inspect the output chunk sizes in `apps/web/.output/public/assets/`, then load a page in the browser's network panel and check what the document shell actually requests - a chunk the manifest never preloads can still arrive through a static import. Keep any single lazy chunk below **150 KB** for optimal mobile performance.

## Learn More [#learn-more]

# Dashboard Widgets

Dashboard widgets are **AdminCP plugin extensions**. Define the component and
register it in the same plugin factory that owns the feature; the host dashboard
then discovers it automatically.

{/* Image prompt: VitNode AdminCP dashboard with a “Site notes” statistics widget in a draggable grid. Show the widget drawer, resize affordance, and settings gear. Dark theme, 1600x900. */}

<Steps>
  <Step>
    ### Build the widget component [#build-the-widget-component]

```tsx title="plugins/site-notes/src/views/admin/widgets/stats-widget.tsx"
    import type { AdminDashboardWidgetProps } from '@vitnode/core/lib/plugin'

export const StatsWidget = ({ settings }: AdminDashboardWidgetProps) => (
      <div className="flex flex-col gap-1 p-2">
        <span className="text-muted-foreground text-sm">Published notes</span>
        <strong className="text-3xl tabular-nums">
          {String(settings.total ?? 42)}
        </strong>
      </div>
    )
    ```
  </Step>

<Step>
    ### Register it in the existing plugin factory [#register-it-in-the-existing-plugin-factory]

```tsx title="plugins/site-notes/src/config.tsx"
    import { BarChart3Icon } from 'lucide-react'

import { StatsWidget } from './views/admin/widgets/stats-widget'

export const siteNotesPlugin = () =>
      buildPlugin({
        admin: {
          dashboard: {
            widgets: [
              // [!code ++:9]
              {
                component: StatsWidget,
                defaultEnabled: true,
                defaultRows: 1,
                defaultSpan: 1,
                icon: <BarChart3Icon />,
                id: 'stats',
              },
            ],
          },
        },
        messages,
        pluginId: '@acme/site-notes',
        routes,
      })
    ```

The full widget id is namespaced by the plugin, so `stats` will not collide with
    another plugin’s idea of a stats card. A good thing—statistics are dramatic
    enough already.
  </Step>

<Step>
    ### Add a permission or settings UI when needed [#add-a-permission-or-settings-ui-when-needed]

Add `permission` to hide a widget from staff who should not see it. Add
    `settingsComponent` when administrators need to save preferences; both stay in
    the plugin alongside the widget.

```tsx title="plugins/site-notes/src/config.tsx"
    {
      component: StatsWidget,
      // [!code ++:4]
      permission: { module: 'site_notes', permission: 'can_view_stats' },
      settingsComponent: StatsSettings,
      id: 'stats',
    }
    ```
  </Step>
</Steps>

## Widget options [#widget-options]

| Option                        | What it controls                                  |
| ----------------------------- | ------------------------------------------------- |
| `defaultSpan` / `defaultRows` | Initial grid size from 1 to 3 columns or rows.    |
| `minSpan`                     | Narrowest allowed width.                          |
| `defaultEnabled`              | Whether a new dashboard receives the widget.      |
| `allowMultiple`               | Whether an admin may place more than one copy.    |
| `permission`                  | Staff permission required to see the widget.      |
| `settingsComponent`           | Plugin form shown by the widget settings control. |

<Cards>
  <Card icon="<Settings2Icon />" title="AdminCP pages" description="Add plugin-owned routes and browser-safe sidebar navigation." href="/docs/dev/plugins/admin" />

<Card icon="<BarChart3Icon />" title="Staff permissions" description="Define permissions before exposing staff-only capabilities." href="/docs/dev/working-with-users/staff-permissions" />
</Cards>

# AdminCP Pages

AdminCP is a plugin surface. Give the plugin an `area: 'admin'` route and a
browser-safe navigation declaration. The host supplies the panel shell; your
plugin supplies the useful bit.

<Steps>
  <Step>
    ### Claim an AdminCP route [#claim-an-admincp-route]

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:4]
      page('/admin/site-notes/settings', {
        area: 'admin',
        component: lazy(() => import('./pages/admin-settings-page')),
      }),
    ])
    ```
  </Step>

<Step>
    ### Render the plugin page [#render-the-plugin-page]

```tsx title="plugins/site-notes/src/pages/admin-settings-page.tsx"
    const AdminSettingsPage = () => (
      <div className="flex flex-col gap-2 p-4">
        <h2 className="text-2xl font-semibold">Site notes settings</h2>
        <p className="text-muted-foreground">Manage the notes plugin.</p>
      </div>
    )

export default AdminSettingsPage
    ```
  </Step>

<Step>
    ### Add a sidebar entry [#add-a-sidebar-entry]

Export `adminNav` from the plugin. Its small browser-safe shape is what the
    generated AdminCP registry imports—do not edit `admin-nav.gen.ts` yourself.

```tsx title="plugins/site-notes/src/admin/nav.tsx"
    import type { AdminNavPluginSource } from '@vitnode/core/lib/plugin'
    import { SettingsIcon } from 'lucide-react'

export const adminNav = {
      pluginId: '@acme/site-notes',
      admin: {
        nav: [
          // [!code ++:6]
          {
            href: '/admin/site-notes/settings',
            icon: <SettingsIcon />,
            id: 'settings',
            permission: { module: 'site_notes', permission: 'can_manage_settings' },
          },
        ],
      },
    } satisfies AdminNavPluginSource
    ```

The generator’s `./*` package export already exposes `admin/nav`; no manual
    `package.json` export is required, and nothing changes in `config.tsx`. The
    generated `admin-nav.gen.ts` imports `admin/nav` directly, and keeping the
    factory to plain data is what keeps the sidebar registration out of every
    public page's bundle.
  </Step>

<Step>
    ### Verify the screen [#verify-the-screen]

Visit `http://localhost:3000/admin/site-notes/settings` as a staff account with
    the declared permission.

{/* Image prompt: VitNode AdminCP settings page contributed by a plugin. Show the existing admin sidebar with “Site notes” selected, a compact settings screen, breadcrumb, and staff-permission badge. Dark theme, 1440x900. */}
  </Step>
</Steps>

## Extend the panel [#extend-the-panel]

<Cards>
  <Card icon="<LayoutDashboardIcon />" title="Dashboard widgets" description="Add a plugin widget to the admin dashboard’s configurable grid." href="/docs/dev/plugins/admin/dashboard-widgets" />

<Card icon="<ShieldCheckIcon />" title="Staff permissions" description="Define the permissions that gate staff actions and navigation." href="/docs/dev/working-with-users/staff-permissions" />

<Card icon="<RouteIcon />" title="Plugin routes" description="Configure route areas, namespaces, guards, and parameters." href="/docs/dev/plugins/routes" />
</Cards>

# API Modules

Start with [a plugin](/docs/dev/plugins/create), not a host endpoint. A module
groups the plugin's Hono routes under one URL prefix and gives OpenAPI a tidy
place to describe them.

{/* Image prompt: Dark-theme API ownership diagram. A Site notes plugin contains a Hono route, notes module, and config.api file; the app API configuration composes the plugin once. Show resulting GET endpoint, 1600x900. */}

<Steps>
  <Step>
    ### Define one plugin endpoint [#define-one-plugin-endpoint]

```ts title="plugins/site-notes/src/api/modules/notes/list.route.ts"
    import { z } from '@hono/zod-openapi'
    import { buildRoute } from '@vitnode/core/api/lib/route'

export const listNotesRoute = buildRoute({
      pluginId: '@acme/site-notes',
      route: {
        method: 'get',
        path: '/',
        responses: {
          // [!code ++:7]
          200: {
            content: {
              'application/json': {
                schema: z.object({ notes: z.array(z.string()) }),
              },
            },
            description: 'Published site notes.',
          },
        },
      },
      handler: (c) => c.json({ notes: ['Hello plugin'] }),
    })
    ```
  </Step>

<Step>
    ### Group it and export the plugin API [#group-it-and-export-the-plugin-api]

```ts title="plugins/site-notes/src/api/modules/notes/notes.module.ts"
    import { buildModule } from '@vitnode/core/api/lib/module'

import { listNotesRoute } from './list.route'

export const notesModule = buildModule({
      name: 'notes',
      pluginId: '@acme/site-notes',
      routes: [listNotesRoute], // [!code ++]
    })
    ```

```ts title="plugins/site-notes/src/config.api.ts"
    import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { notesModule } from './api/modules/notes/notes.module'

export const siteNotesApiPlugin = () =>
      buildApiPlugin({
        modules: [notesModule], // [!code ++]
        pluginId: '@acme/site-notes',
      })
    ```
  </Step>

<Step>
    ### Compose it in the app API config [#compose-it-in-the-app-api-config]

The app decides which installed plugins are active. Add the factory to the Hono
    config that serves your app (`apps/web` for a single app, or `apps/api` when it
    is separate):

```ts title="apps/web/src/vitnode.api.config.ts"
    import { siteNotesApiPlugin } from '@acme/site-notes/config.api' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      plugins: [siteNotesApiPlugin()], // [!code ++]
    })
    ```

The endpoint is now `GET /api/@acme/site-notes/notes`. OpenAPI picks it up too;
    one less hand-written map to maintain.
  </Step>
</Steps>

<Cards>
  <Card icon="<RouteIcon />" title="Validate inputs" description="Use Zod schemas for params, queries, request bodies, and typed responses." href="/docs/dev/plugins/api/routes" />

<Card icon="<ShieldCheckIcon />" title="Protect staff APIs" description="Require a staff permission before an AdminCP action reaches its handler." href="/docs/dev/working-with-users/staff-permissions" />

<Card icon="<NetworkIcon />" title="Call the API" description="Use VitNode's typed fetcher from a plugin-owned page or component." href="/docs/dev/fetcher" />
</Cards>

# API Routes

Create [the plugin](/docs/dev/plugins/create) and its [API module](/docs/dev/plugins/api/modules)
first. Then put the endpoint in that module so its validation, permission, and
OpenAPI record travel together.

<Steps>
  <Step>
    ### Validate input and response [#validate-input-and-response]

```ts title="plugins/site-notes/src/api/modules/notes/get.route.ts"
    import { z } from '@hono/zod-openapi'
    import { buildRoute } from '@vitnode/core/api/lib/route'

export const getNoteRoute = buildRoute({
      pluginId: '@acme/site-notes',
      route: {
        method: 'get',
        path: '/{id}',
        request: {
          params: z.object({ id: z.coerce.number().int().positive() }),
        },
        responses: {
          // [!code ++:7]
          200: {
            content: {
              'application/json': {
                schema: z.object({ id: z.number(), title: z.string() }),
              },
            },
            description: 'One site note.',
          },
        },
      },
      handler: (c) => {
        const { id } = c.req.valid('param')
        return c.json({ id, title: 'Plugin-owned note' })
      },
    })
    ```
  </Step>

<Step>
    ### Gate an AdminCP action [#gate-an-admincp-action]

Add `adminStaffPermission` to an action that only staff should call. The API
    still authorizes server-side; a hidden button is merely good manners.

```ts title="plugins/site-notes/src/api/modules/notes/publish.route.ts"
    import { z } from '@hono/zod-openapi'
    import { buildRoute } from '@vitnode/core/api/lib/route'

export const publishNoteRoute = buildRoute({
      // [!code ++:13]
      adminStaffPermission: {
        module: 'site_notes',
        permission: 'can_publish',
      },
      pluginId: '@acme/site-notes',
      route: {
        method: 'post',
        path: '/{id}/publish',
        responses: {
          200: {
            content: {
              'application/json': {
                schema: z.object({ published: z.literal(true) }),
              },
            },
            description: 'The note was published.',
          },
        },
      },
      handler: async (c) => c.json({ published: true }),
    })
    ```
  </Step>
</Steps>

{/* Image prompt: Dark-theme API documentation screenshot. Show an OpenAPI endpoint for a plugin route with path parameter validation, a successful JSON response, and a staff-permission lock badge. 1440x900. */}

<Callout type="idea" title="One route, one plugin owner">
  Keep handlers with the feature that owns the data. The host API config only
  composes plugins; it should not become a surprise sequel to your business
  logic.
</Callout>

<Cards>
  <Card icon="<BoxIcon />" title="API modules" description="Register a module and its plugin API factory with the Hono application." href="/docs/dev/plugins/api/modules" />

<Card icon="<ShieldCheckIcon />" title="Staff permissions" description="Define the permission catalog that gates AdminCP actions." href="/docs/dev/working-with-users/staff-permissions" />

<Card icon="<ZapIcon />" title="Typed fetcher" description="Call validated plugin endpoints from the TanStack Start UI." href="/docs/dev/fetcher" />
</Cards>

# Breadcrumbs

VitNode renders a breadcrumb trail in both the AdminCP header and the public
site layout. **Every matched route contributes one crumb**, parent to child:

```text
Home / Catalog / Products / Laptops / MacBook Pro
```

So a route says what it is called and nothing else. VitNode owns the separators,
the `nav` and `aria-current` semantics, and the locale-aware link to each
route's own URL—a plugin never builds a router link, and never restates the
crumbs of the layouts above it.

## Quick start [#quick-start]

### A static, translated crumb [#a-static-translated-crumb]

Declare a component on `definePluginRoute`. It renders inside the message
namespaces the route declared, so `useTranslations` just works:

```tsx title="plugins/catalog/src/pages/products-layout.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'

function ProductsBreadcrumb() {
  const t = useTranslations('@acme/catalog')

return t('breadcrumbs.products')
}

// [!code ++:3]
export const route = definePluginRoute({
  breadcrumb: ProductsBreadcrumb,
})
```

### A crumb read from the loader [#a-crumb-read-from-the-loader]

The crumb is handed **its own** match's data, so a dynamic route can name itself
with what it fetched—no second request, and no guessing from the URL:

```tsx title="plugins/catalog/src/pages/category-layout.tsx"
import type { PluginRouteBreadcrumbProps } from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

interface Category {
  name: string
}

function CategoryBreadcrumb({
  loaderData,
}: PluginRouteBreadcrumbProps<Category>) {
  return loaderData.name
}

export const route = definePluginRoute({
  load: async ({ params }) => await fetchCategory(params.categorySlug),
  breadcrumb: CategoryBreadcrumb,
})
```

`PluginRouteBreadcrumbProps<TData, TSearch>` carries `loaderData`, `params` and
`search`—the same three names the loader, `head` and the page component receive.

### Leaving a route out [#leaving-a-route-out]

A route that declares no `breadcrumb` contributes nothing, and its parents' crumbs
stay exactly where they were. `false` says the same thing on purpose, which is
worth doing when a page's frame already names the screen:

```tsx title="plugins/catalog/src/pages/products-index-page.tsx"
export const route = definePluginRoute({
  breadcrumb: false, // [!code ++]
})
```

## Rules [#rules]

| Declaration       | What the trail does                                  |
| ----------------- | ---------------------------------------------------- |
| A component       | One crumb, given this route's loader data and params |
| `false`           | This route is left out; its parents' crumbs remain   |
| Nothing at all    | The same, said by omission                           |
| The last crumb    | Rendered as the current page, not as a link          |
| Every other crumb | A locale-aware link to that route's own URL          |

<Callout type="info" title="AdminCP labels come from the navigation">
  An AdminCP screen's trail is named by the sidebar this administrator can
  actually see, so a plugin that adds a nav entry gets its label for free—in
  every language. Keep the route, the sidebar entry and the translations in the
  same package.
</Callout>

<Callout type="warn" title="Return a label, not a trail">
  A crumb returns text or an element. Do not render a `<Breadcrumb>`, a
  separator, or a link: the shell draws the trail *above* the page outlet and
  needs each crumb as one item so it can put them in one navigation landmark.
</Callout>

## Learn More [#learn-more]

# Create a Plugin

A plugin is the starting point for a VitNode feature. It keeps routes, API
modules, data, translations, and AdminCP extensions together in one installable
package. Nice boundaries; fewer archaeological digs later.

<Callout type="warn" title="Plugins need a workspace">
  Run the generator from a repository with `turbo.json`. When creating an app,
  turn on Turborepo first; a plain single-folder app has nowhere for
  `plugins/*`.
</Callout>

<Steps>
  <Step>
    ### Generate the package [#generate-the-package]

Run this at the workspace root and enter a package name such as
    `@acme/site-notes` when prompted:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Create a VitNode plugin">
      <Tab value="bun">
        ```bash
        bun create vitnode-app@canary --plugin
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm create vitnode-app@canary --plugin
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm create vitnode-app@canary -- --plugin
        ```
      </Tab>
    </Tabs>

The CLI creates `plugins/site-notes`, adds it as a workspace dependency, and
    gives it a route, locale, and config skeleton. It does **not** enable the
    feature for the host—that explicit switch is next.
  </Step>

<Step>
    ### Keep the route in the plugin [#keep-the-route-in-the-plugin]

The generated `routes.ts` is the public contract. Add another `page()` here when
    the plugin needs another URL; never copy its page into `apps/web/src/routes`.

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:3]
      page('/site-notes', {
        component: lazy(() => import('./pages/home-page')),
      }),
    ])
    ```
  </Step>

<Step>
    ### Register the plugin with the host [#register-the-plugin-with-the-host]

Import the plugin factory in the host config and add it to `plugins`:

```ts title="apps/web/src/vitnode.config.ts"
    import { siteNotesPlugin } from '@acme/site-notes/config' // [!code ++]
    import { buildConfig } from '@vitnode/core/vitnode.config'

export const vitNodeConfig = buildConfig({
      plugins: [
        siteNotesPlugin(), // [!code ++]
      ],
    })
    ```

That is the only composition step - the factory carries the plugin's routes,
    content types and AdminCP navigation, and the feature stays in its package. Your
    build reads this list and generates one literal import per plugin for each of
    those, so a page or an editing screen loads with the route that needs it rather
    than with the config. See [Configuration](/docs/dev/configuration).

Its translations need one more line, in `src/locales/packages.ts` - see
    [Languages & Localization](/docs/dev/i18n).
  </Step>

<Step>
    ### Run it and visit the route [#run-it-and-visit-the-route]

Open `http://localhost:3000/site-notes`. The page comes from the plugin, gets
    its own chunk, and never moves house. Tiny victory dance optional.

{/* Image prompt: Split-screen developer tutorial image. Left shows a plugin folder with routes.ts, locale, and pages files. Right shows the resulting /site-notes page in a VitNode app. Dark theme, precise code-like labels, 1600x900. */}
  </Step>
</Steps>

## Add the next capability [#add-the-next-capability]

<Cards>
  <Card icon="<RouteIcon />" title="Plugin routes" description="Add nested layouts, dynamic URLs, loaders, metadata, and guards." href="/docs/dev/plugins/routes" />

<Card icon="<DatabaseIcon />" title="Database models" description="Put Drizzle models and migrations beside the feature that owns them." href="/docs/dev/database" />

<Card icon="<LayoutDashboardIcon />" title="Admin Control Panel" description="Ship staff screens, navigation, permissions, and dashboard widgets." href="/docs/dev/plugins/admin" />
</Cards>

# Plugin Routes

Start by [creating a plugin](/docs/dev/plugins/create). A plugin's `src/routes.ts`
is its promise to the app: which URLs it owns, and which module renders each one.
The host turns that promise into lazy TanStack Start routes—no copied page files,
no drama.

{/* Image prompt: Dark-theme developer diagram: a plugin routes.ts tree (layout → index → dynamic page) on the left, each node pointing at a lazily loaded page chunk on the right, then into a TanStack Start route inside the app shell. Emphasize “plugin owns feature”, “one chunk per page”, “host composes”. Clean labels, 1600x900. */}

<Steps>
  <Step>
    ### Declare the URL in the plugin [#declare-the-url-in-the-plugin]

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:3]
      page('/notes/:slug', {
        component: lazy(() => import('./pages/note-page')),
      }),
    ])
    ```

Use `:slug` for dynamic segments. VitNode converts it to TanStack Start's
    internal `$slug` spelling while keeping your plugin portable.
  </Step>

<Step>
    ### Keep behavior beside the page [#keep-behavior-beside-the-page]

```tsx title="plugins/site-notes/src/pages/note-page.tsx"
    import type { PluginRoutePageProps } from '@vitnode/core/routing'
    import { definePluginRoute } from '@vitnode/core/routing'

interface Note {
      title: string
    }

// [!code ++:8]
    export const route = definePluginRoute({
      load: async ({ params }) => ({ title: `Note: ${params.slug}` }),
      head: ({ loaderData }) => ({
        description: 'A note delivered by the Site notes plugin.',
        title: loaderData?.title,
      }),
    })

const NotePage = ({ loaderData }: PluginRoutePageProps<Note>) => (
      <article className="container mx-auto max-w-3xl p-4">
        <h2 className="text-3xl font-semibold">{loaderData.title}</h2>
      </article>
    )

export default NotePage
    ```
  </Step>

<Step>
    ### Run the plugin route [#run-the-plugin-route]

Visit `http://localhost:3000/notes/hello`. The page's code, data, and SEO stay
    with the feature that needs them. A surprisingly polite route.
  </Step>
</Steps>

## What `lazy(() => import('./pages/note-page'))` means [#what-lazy--importpagesnote-page-means]

It names the module VitNode loads **when the route is needed**—on a navigation,
or a moment earlier when the visitor hovers a link and the router preloads it.

Nothing about that import runs while your app boots. `lazy` stores the callback;
Vite reads the literal `import()` inside it at build time and Rollup gives that
page a chunk of its own. So `routes.ts` stays a few lines of data the app can
hold cheaply, and a visitor downloads a page only if they open it.

<Callout type="warn" title="component: NotePage is rejected on purpose">
  Importing the component at the top of `routes.ts` would put it in the initial
  bundle of *every* page on the site, and route-level splitting would be gone.
  VitNode refuses it in the types and again at build time, with the replacement
  in the message:

```ts
  import NotePage from './pages/note-page'

page('/notes/:slug', {
    component: NotePage, // [!code --]
    component: lazy(() => import('./pages/note-page')), // [!code ++]
  })
  ```
</Callout>

Keep the `import()` literal. A specifier built from a variable is not something
a bundler can follow, so the page never gets a chunk and the build cannot tell
you the module is missing:

```ts
page('/notes/:slug', {
  component: lazy(() => import(`./pages/${slug}-page`)), // [!code --]
  component: lazy(() => import('./pages/note-page')), // [!code ++]
})
```

## Nest routes with `layout()` and `index()` [#nest-routes-with-layout-and-index]

A `layout()` renders a frame around its `children` and claims no URL of its own.
`index()` is the route that renders at the layout's own URL. Every path inside a
layout is **relative** to it, so moving a subtree is one edit:

```ts title="plugins/catalog/src/routes.ts"
import {
  definePluginRoutes,
  index,
  layout,
  lazy,
  page,
} from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  layout('/catalog', {
    component: lazy(() => import('./pages/catalog-layout')),
    messages: ['@acme/catalog'],
    children: [
      page('dashboard', {
        component: lazy(() => import('./pages/dashboard-page')),
      }),

layout('products', {
        component: lazy(() => import('./pages/products-layout')),
        children: [
          index({
            component: lazy(() => import('./pages/products-index-page')),
          }),

layout(':categorySlug', {
            component: lazy(() => import('./pages/category-layout')),
            children: [
              index({
                component: lazy(() => import('./pages/category-index-page')),
              }),

page(':productId', {
                component: lazy(() => import('./pages/product-page')),
              }),
            ],
          }),
        ],
      }),
    ],
  }),
])
```

That tree serves `/catalog/dashboard`, `/catalog/products`,
`/catalog/products/laptops` and `/catalog/products/laptops/42`, and a page opens
inside every frame above it.

| Rule                      | What VitNode does                                        |
| ------------------------- | -------------------------------------------------------- |
| Top-level path            | Absolute: `page('/catalog', …)`                          |
| Nested path               | Relative: `page('dashboard', …)` joins onto its parent   |
| `index()`                 | The child at the layout's exact URL—no path of its own   |
| Layout with no `children` | A build error: nothing could ever render it              |
| Route ids                 | Derived by VitNode while flattening. You never write one |

A layout's frame is a component with `children`:

```tsx title="plugins/catalog/src/pages/catalog-layout.tsx"
const CatalogLayout = ({ children }: { children: React.ReactNode }) => (
  <div className="container mx-auto flex max-w-5xl flex-col gap-6 p-4">
    <h1 className="text-2xl font-semibold tracking-tight">Catalog</h1>
    {children}
  </div>
)

export default CatalogLayout
```

`children`, not an `<Outlet />`: a plugin layout that imported a router's outlet
could only be installed into one kind of app.

## Choose the route shape [#choose-the-route-shape]

| Need                | Add to the tree                                           |
| ------------------- | --------------------------------------------------------- |
| Public feature page | `page('/notes', { component })`—`area` defaults to `main` |
| Staff screen        | `area: 'admin'` and a full path such as `/admin/notes`    |
| Signed-in visitor   | `requires: 'authenticated'`                               |
| Shared frame        | `layout()` with `children`                                |
| Translated strings  | `messages: ['@acme/catalog']`                             |
| URL-as-state        | `search: productsSearchSchema`                            |

## An AdminCP route [#an-admincp-route]

`area: 'admin'` picks the shell—the sidebar, the breadcrumb area, the command
palette, and the admin session guard. It never changes the path, so write the
`/admin/…` URL in full:

```ts title="plugins/site-notes/src/routes.ts"
page('/admin/notes', {
  area: 'admin', // [!code ++]
  component: lazy(() => import('./pages/admin-notes-page')),
  messages: ['@acme/site-notes.admin'],
})
```

`area` belongs to top-level routes only. Everything inside a layout renders in
the shell that layout renders in, and `requires` is refused in the admin
area—the AdminCP has its own session, and a staff permission gates the page's
*content*. See [AdminCP pages](/docs/dev/plugins/admin).

## Route messages [#route-messages]

`messages` lists the translation namespaces the route renders. VitNode warms
them **alongside** the page's chunk instead of after it, which is the whole
reason they are declared on the route rather than inside the module:

```ts
layout('/catalog', {
  component: lazy(() => import('./pages/catalog-layout')),
  messages: ['@acme/catalog'], // [!code ++]
  children: [index({ component: lazy(() => import('./pages/index-page')) })],
})
```

A route inherits every namespace its layouts declare, so naming them once on the
frame is enough for the whole subtree. Inside the module, read them with
`use-intl`:

```tsx
import { useTranslations } from 'use-intl'

const CatalogIndexPage = () => {
  const t = useTranslations('@acme/catalog')

return <p>{t('index.intro')}</p>
}
```

See [namespaces](/docs/dev/i18n/namespaces) for how a namespace is named and
where its JSON lives.

## `search` is the one eager field [#search-is-the-one-eager-field]

TanStack Router validates a URL's query string **while it matches the URL**,
before any chunk is fetched. A schema inside the lazy page module would arrive
too late, so a route declares it in `routes.ts`:

```ts title="plugins/catalog/src/routes.ts"
import { productsSearchSchema } from './pages/products-search'

page('/catalog/products', {
  component: lazy(() => import('./pages/products-page')),
  search: productsSearchSchema, // [!code ++]
})
```

```ts title="plugins/catalog/src/pages/products-search.ts"
export interface ProductsSearch {
  page: number
}

export const productsSearchSchema = (
  input: Record<string, unknown>,
): ProductsSearch => {
  const parsed = Number.parseInt(String(input.page ?? ''), 10)

// Total, never throwing: the router calls this on whatever somebody pasted.
  return { page: Number.isFinite(parsed) ? Math.max(parsed, 1) : 1 }
}
```

The page then gets a typed `search` and a `navigate` that changes it:

```tsx title="plugins/catalog/src/pages/products-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

import type { ProductsSearch } from './products-search'

const ProductsPage = ({
  navigate,
  search,
}: PluginRoutePageProps<undefined, ProductsSearch>) => (
  <button
    onClick={() => void navigate({ search: { page: search.page + 1 } })}
    type="button"
  >
    Page {search.page}
  </button>
)

export default ProductsPage
```

TypeScript checks the two halves against each other: the schema has to return
what the page says it reads, even though the page itself is lazy.

<Callout type="info" title="Why this one is eager, and what it costs">
  `search` is a function, so it lives in `routes.ts`—which the app imports
  statically. Everything that file imports is in the initial bundle with it, so
  keep the schema module small: no React, no component, no import of the page it
  belongs to.

Declare it only for a screen whose URL *is* its state—a paginated list whose
  `?page=999` has to be clamped, a filter whose links must be typed. For a page
  that merely reads a parameter, use the module's own lazy `parseSearch`
  instead; it normalises in the loader and adds nothing to the initial bundle.
</Callout>

## Dynamic breadcrumbs [#dynamic-breadcrumbs]

Every matched route contributes **one crumb**, parent to child, and VitNode owns
the separators, the accessibility semantics, and the locale-aware links. A crumb
returns a label:

```tsx title="plugins/catalog/src/pages/product-page.tsx"
import type {
  PluginRouteBreadcrumbProps,
  PluginRoutePageProps,
} from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

interface Product {
  description: string
  name: string
}

function ProductBreadcrumb({ loaderData }: PluginRouteBreadcrumbProps<Product>) {
  return loaderData.name
}

export const route = definePluginRoute({
  load: async ({ params }) =>
    await fetchProduct({
      categorySlug: params.categorySlug,
      productId: params.productId,
    }),

head: ({ loaderData }) => ({
    description: loaderData?.description,
    title: loaderData?.name,
  }),

breadcrumb: ProductBreadcrumb,
})

export default function ProductPage({
  loaderData,
}: PluginRoutePageProps<Product>) {
  return (
    <article>
      <h1>{loaderData.name}</h1>
      <p>{loaderData.description}</p>
    </article>
  )
}
```

With the catalog tree above, that renders `Catalog / Products / Laptops /
MacBook Pro`—each crumb from the route that owns it. See
[breadcrumbs](/docs/dev/plugins/breadcrumbs) for static crumbs, `breadcrumb:
false`, and how the trail is assembled.

<Callout type="idea" title="The host is the exception">
  Use host routes only for shells, docs, or site-wide infrastructure. A product
  page belongs in its plugin, even when it starts life as one brave little URL.
</Callout>

## How the app picks this up [#how-the-app-picks-this-up]

The `vitnode:plugin-routes` Vite plugin reads the plugins in
`src/vitnode.config.ts`, imports each one's `routes` module in Node, validates
and flattens every tree, refuses two routes that claim one URL—including one of
the app's own—and writes a single `src/plugin-routes.gen.ts`:

```ts title="apps/web/src/plugin-routes.gen.ts"
import { routes as pluginRoutes0 } from '@acme/catalog/routes'

export const pluginRouteSources = [
  { pluginId: '@acme/catalog', routes: pluginRoutes0 },
] as const satisfies readonly PluginRouteDeclarationSource[]
```

That is the only generated file, it names no page module, and it is committed
like any other generated artefact. Your pages stay in your package's own
`dist`, one chunk each.

<Cards>
  <Card icon="<DatabaseIcon />" title="Load data" description="Use plugin loaders with cache-aware data and query state." href="/docs/dev/data-loading" />

<Card icon="<MilestoneIcon />" title="Breadcrumbs" description="Contribute one crumb per route, translated or read from a loader." href="/docs/dev/plugins/breadcrumbs" />

<Card icon="<LayoutDashboardIcon />" title="AdminCP pages" description="Mount a plugin screen in the staff-only Admin Control Panel." href="/docs/dev/plugins/admin" />
</Cards>

# Routing

VitNode uses TanStack Start, but feature routes begin in a plugin. A plugin's
`routes.ts` is a small tree of declarations - a path, and the module that renders
it - so the package owns the page without copying files into
`apps/web/src/routes`.

| Put it in        | Use it for                                                      | Default  |
| ---------------- | --------------------------------------------------------------- | -------- |
| **Plugin route** | Product pages, feature flows, content delivery, AdminCP screens | Yes      |
| **Host route**   | Shell, framework wiring, docs, or a truly site-wide integration | Rare     |
| **Core route**   | Login, AdminCP frame, search, and other VitNode system screens  | Built in |

<Steps>
  <Step>
    ### Declare the plugin URL [#declare-the-plugin-url]

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:3]
      page('/notes', {
        component: lazy(() => import('./pages/notes-page')),
      }),
    ])
    ```

Use `:slug` for a dynamic segment, such as `page('/notes/:slug', …)`. VitNode
    maps it to TanStack Start’s internal `$slug` spelling for you.

`lazy` names the page module without importing it: the literal `import()` is
    what Vite follows to give the page a chunk of its own, and it does not run until
    somebody opens the route.
  </Step>

<Step>
    ### Add the page module [#add-the-page-module]

```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
    const NotesPage = () => (
      <div className="container mx-auto flex max-w-3xl flex-col gap-4 p-4">
        <h2 className="text-3xl font-semibold">Site notes</h2>
        <p className="text-muted-foreground">
          A route that lives with its feature.
        </p>
      </div>
    )

export default NotesPage
    ```
  </Step>

<Step>
    ### Run it [#run-it]

Open `http://localhost:3000/notes`.
  </Step>
</Steps>

## Load data and set metadata [#load-data-and-set-metadata]

Export `route` from the same plugin module. Declare `load` before `head` so
TypeScript carries the inferred data into your metadata:

```tsx title="plugins/site-notes/src/pages/note-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

interface Note {
  body: string
  title: string
}

// [!code ++:9]
export const route = definePluginRoute({
  load: async ({ params }) => await fetchNote(params.slug),
  head: ({ loaderData }) => ({
    description: loaderData?.body.slice(0, 155),
    title: loaderData?.title,
  }),
})

const NotePage = ({ loaderData }: PluginRoutePageProps<Note>) => (
  <article className="container mx-auto max-w-3xl p-4">
    <h2 className="text-3xl font-semibold">{loaderData.title}</h2>
    <p>{loaderData.body}</p>
  </article>
)

export default NotePage
```

<Callout type="idea" title="The host is the exception">
  Keep host routes for app-wide framing or infrastructure. If a route belongs to
  a feature, make a plugin first—even when the feature starts small. Small
  things have a habit of bringing friends.
</Callout>

## Continue from the route [#continue-from-the-route]

<Cards>
  <Card icon="<RouteIcon />" title="Plugin routes reference" description="Configure areas, layouts, messages, guards, search, and dynamic paths." href="/docs/dev/plugins/routes" />

<Card icon="<DatabaseIcon />" title="Data loading" description="Use loader data with TanStack Query and server-aware caching." href="/docs/dev/data-loading" />

<Card icon="<FileTextIcon />" title="Metadata and SEO" description="Set useful titles, descriptions, robots, and social metadata." href="/docs/dev/routing/metadata" />
</Cards>

# Loading States

While a route's loader runs or its code chunk downloads, TanStack Router displays a pending component. VitNode provides pre-built skeleton layouts matching common UI patterns.

## Quick start [#quick-start]

### Use Suspense in a plugin component [#use-suspense-in-a-plugin-component]

Plugin routes load dynamically. Use React `Suspense` with VitNode's pending skeletons:

```tsx title="plugins/blog/src/pages/posts-page.tsx"
import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import React, { Suspense } from 'react'

const PostsList = () => {
  // Data loading component
  return <div>Posts List</div>
}

const PostsPage = () => (
  // [!code ++:3]
  <Suspense fallback={<FeedPendingSkeleton />}>
    <PostsList />
  </Suspense>
)

export default PostsPage
```

## Pre-Built Pending Skeletons [#pre-built-pending-skeletons]

Import these shapes from `@vitnode/core/tanstack/pending`:

***

## Skeleton Props [#skeleton-props]

Standard skeleton shapes accept custom classes and row counts:

## Learn More [#learn-more]

# Metadata & SEO

VitNode plugin routes declare their own metadata through `head`. Keep it short,
specific, and useful enough that a search result does not sound like it was
written by a toaster.

## Quick start [#quick-start]

### 1. In a Plugin Route (Recommended) [#1-in-a-plugin-route-recommended]

Plugins declare metadata using `definePluginRoute`. Metadata can read dynamically from `loaderData`:

```tsx title="plugins/blog/src/pages/article-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async ({ params }) => await fetchArticle(params.slug),
  // [!code ++:6]
  head: ({ loaderData }) => ({
    title: loaderData?.title,
    description: loaderData?.summary,
    robots: 'index, follow',
  }),
})
```

The browser tab automatically displays **Article Title - VitNode**.

## Plugin metadata fields [#plugin-metadata-fields]

| Field         | Use it for                                                                |
| ------------- | ------------------------------------------------------------------------- |
| `title`       | A specific, human-readable page title.                                    |
| `description` | A concise search snippet that explains the page’s value.                  |
| `robots`      | `index, follow` for public pages or `noindex, nofollow` for private ones. |

For canonical URLs, redirects, Open Graph fields, and XML sitemaps on Content
Engine records, configure [Content delivery and SEO](/docs/dev/content-engine/content-delivery-and-seo)
inside the plugin that owns those records.

## Learn More [#learn-more]

# Navigation

Inside the app, use TanStack Router's `Link`. It builds the href, applies the
locale prefix, and preloads the destination on hover. You write the logical
path; the router writes the language.

## Example [#example]

```tsx
import { Link } from '@tanstack/react-router'

const DiscoverLink = () => <Link to="/discover">Discover</Link>
```

That renders `/discover` for an English reader and `/pl/discover` for a Polish
one. Same component, same `to`, no branch and no `useLocale()` call.

## One route, two URLs [#one-route-two-urls]

`/discover` and `/pl/discover` are **one route**. The router's `rewrite` is what
makes that work, and it runs in both directions:

| Stage                                         | Value            |
| --------------------------------------------- | ---------------- |
| The address bar                               | `/pl/discover`   |
| What the route tree matches (`rewrite.input`) | `/discover`      |
| What you write                                | `to="/discover"` |
| What React renders (`rewrite.output`)         | `/pl/discover`   |

`input` is why no route file anywhere in the app mentions a locale - there is no
`routes/pl/` directory and there is not going to be one. `output` reads the
locale off the router's own current location rather than off `window`, so the
href rendered during SSR is byte-identical to the one rendered after hydration.

So write the logical path. Two things that look reasonable and are not:

* **Building the prefix yourself.** ``to={`/${locale}/discover`}`` does not
  double up, because `localizeUrl` de-localizes before it prefixes and is
  therefore idempotent. What it does instead is discard the prefix you wrote and
  re-apply the reader's *current* locale, so an English reader following your
  `/pl/discover` link lands on `/discover`. Not honoured; overwritten.
* **Naming a prefixed route.** `to="/pl/discover"` is not a path in the route
  tree, so the router's typed `to` refuses it.

<Callout type="info" title="`/admin` and `/api` carry no prefix at all">
  Both sit outside the localized URL space, so nothing is stripped from them and
  nothing is added. `/pl/admin/core` is therefore a mistake rather than a Polish
  page, and the app's request middleware 308-redirects it to `/admin/core` while
  storing `pl` in the language cookie - so the AdminCP still renders in the
  language the visitor just asked for. The same middleware canonicalises
  `/en/discover` to `/discover`, because the default locale is unprefixed and
  two indexable URLs for one page is one too many.
</Callout>

<Callout type="warn" title="An unknown prefix is a 404, not a fallback">
  Only a prefix the app would itself emit gets stripped, so `/xx/discover`
  reaches the route tree intact and matches nothing. That is deliberate: a
  silent fallback would serve the same page at infinitely many URLs.
</Callout>

## Update query state from a plugin page [#update-query-state-from-a-plugin-page]

Plugin route props expose a narrow `navigate` function for filters, sorting, and
pagination on the page already being viewed. It keeps the plugin independent of
the host router’s entire route tree.

```tsx title="plugins/catalog/src/pages/catalog-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

interface CatalogSearch {
  page: number
}

const CatalogPage = ({
  navigate,
  search,
}: PluginRoutePageProps<undefined, CatalogSearch>) => (
  <button
    onClick={() =>
      void navigate({
        resetScroll: false,
        search: { page: search.page + 1 }, // [!code ++]
      })
    }
    type="button"
  >
    Next page
  </button>
)

export default CatalogPage
```

## Plugin route modules [#plugin-route-modules]

A plugin route should not import the host router. Use its `navigate` prop for
same-page filters, sort order, and pagination. For links to another internal
screen, let the host render a link component; a plain `<a>` is for another
origin only.

<Callout type="info" title="Keep plugins portable">
  `navigate` only changes this plugin page's query string. That small boundary
  is intentional—and saves future hosts from router spaghetti.
</Callout>

## Next [#next]

# 404 Not Found

In TanStack Start, 404 handling is configured as a route option via `notFoundComponent` rather than a static file. VitNode provides localized 404 layouts with history-aware navigation buttons out of the box — and mounts the one your visitors actually hit for you.

{/* Image prompt: VitNode 404 error page showing the site header above large 404 typography, localized "Page Not Found" title, descriptive message, and "Go back" / "Back to home" action buttons. Dark theme, 1440x900. */}

## Mistyped URLs get the full site [#mistyped-urls-get-the-full-site]

A URL no route claims is answered by a catch-all that `withCoreMainRoutes` mounts **inside your main shell**. So a visitor who mistypes a link gets the site header, the same `<main>` landmark every page renders in, and a way back — plus a real `404` status for the crawlers, because the route answers `notFound()` from `beforeLoad` rather than quietly rendering a `200`.

You do not wire this up. It arrives with the mount your `router.tsx` already has:

```tsx title="apps/web/src/router.tsx"
const routeTree = withCoreMainRoutes(fileRouteTree, {
  localeRouting,
  mountUnder: mainShellRoute,
  pageHead,
})
```

<Callout type="info">
  Why a route and not a `notFoundComponent` on `_main`? Because a pathless shell
  is only in the match branch when something below it matched. When *nothing*
  matches, the router hands back the root route on its own — so a boundary on
  the shell would never run, and the 404 would be the one screen on your site
  without a header.
</Callout>

## Root 404 Handler [#root-404-handler]

Your `apps/web/src/routes/__root.tsx` still defines a boundary, and it is the
last resort: a `notFound()` thrown where no closer route declared one.

```tsx title="apps/web/src/routes/__root.tsx"
import { createRootRouteWithContext } from '@tanstack/react-router'
import { ErrorActions, NotFound } from '@vitnode/core/tanstack/layout'

export const Route = createRootRouteWithContext<RootRouterContext>()({
  // [!code ++:4]
  notFoundComponent: () => <NotFound actions={<ErrorActions />} />,
  component: RootComponent,
})
```

`NotFound` automatically renders translated text from `core.global.errors.404`. `ErrorActions` renders **Go Back** (`history.back()`) and **Back to Home** (`/`) buttons.

***

## Triggering 404 in Loaders [#triggering-404-in-loaders]

When a requested resource (like an article slug or user ID) is not found in the database, throw `notFound()` inside the loader:

```tsx title="plugins/blog/src/pages/article-page.tsx"
import { notFound } from '@tanstack/react-router'
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async ({ params }) => {
    const post = await fetchPost(params.slug)
    // [!code ++:3]
    if (!post) {
      throw notFound()
    }
    return post
  },
  component: PostPage,
})
```

***

## Keep the fallback in the host [#keep-the-fallback-in-the-host]

The root 404 boundary is host infrastructure, so configure it once. Feature
routes should throw `notFound()` from their plugin loader and let that shared,
localized fallback do its work.

## Learn More [#learn-more]

# Elasticsearch

Use Elasticsearch when your site-wide search needs fuzzy matching, custom
ranking, or a search cluster separate from Postgres. VitNode keeps Postgres as
the canonical index; this adapter mirrors it, so switching is pleasantly boring.

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

Run this in the app or API workspace that owns `vitnode.api.config.ts`.

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Install Elasticsearch support">
      <Tab value="bun">
        ```bash
        bun add @vitnode/elasticsearch@canary
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm add @vitnode/elasticsearch@canary
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm install @vitnode/elasticsearch@canary
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Add the cluster URL and adapter [#add-the-cluster-url-and-adapter]

Set `ELASTICSEARCH_NODE` to your Elasticsearch or OpenSearch endpoint, then
    register the adapter in the API config.

```bash title=".env"
    ELASTICSEARCH_NODE=http://localhost:9200
    ```

```ts title="apps/api/src/vitnode.api.config.ts"
    import { ElasticsearchSearchAdapter } from '@vitnode/elasticsearch' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      // [!code ++:5]
      search: {
        adapter: ElasticsearchSearchAdapter({
          node: process.env.ELASTICSEARCH_NODE,
          index: 'vitnode',
        }),
      },
      plugins: [blogApiPlugin()],
    })
    ```

For Elastic Cloud, use `cloudId` and `apiKey` instead of `node`. The adapter
    also accepts `username` and `password` for a self-hosted secured cluster.
  </Step>

<Step>
    ### Rebuild the mirror [#rebuild-the-mirror]

Restart the API, then open **Core → Advanced → Search** in the AdminCP and run
    **Rebuild index**. New changes are mirrored automatically; the rebuild fills
    the historical records already in Postgres.

{/* Image prompt: VitNode AdminCP search page showing Elasticsearch as connected, one “Rebuild index” button, a progress state, and collection counts. Dark theme, 1440x900. */}
  </Step>
</Steps>

<Callout type="warn" title="Keep Postgres">
  Do not delete `core_search_index`. It remains VitNode's source of truth and
  lets you switch providers without losing your map back home.
</Callout>

## Next [#next]

# Search & Discovery

VitNode includes a unified site-wide search and discovery engine. Searchable records across all plugins are projected into the `core_search_index` table, powering `/search` and `/discover`.

<Callout type="info" title="Single table filtering">
  This guide covers **site-wide search**. For search boxes on individual tables,
  see [Search](/docs/dev/database/search).
</Callout>

## Quick start [#quick-start]

<Steps>
  <Step>
    ### Index when a record changes [#index-when-a-record-changes]

Index or update an item from any Hono route handler via `c.get("search")`:

```ts
    // [!code ++:10]
    await c.get('search').index({
      itemType: 'article',
      itemId: article.id,
      title: article.title,
      content: article.content, // HTML automatically stripped to plain text
      url: `/articles/${article.slug}`,
      authorId: article.authorId,
      createdAt: article.createdAt,
    })
    ```
  </Step>

<Step>
    ### Delete removed records [#delete-removed-records]

When an item is deleted, remove it from the index:

```ts
    await c.get('search').delete('article', article.id)
    ```
  </Step>

<Step>
    ### Register a rebuild indexer [#register-a-rebuild-indexer]

To allow admins to re-index all historical content from the AdminCP, register a search indexer in your plugin's `config.api.ts`:

```ts title="plugins/blog/src/api/indexers/post.indexer.ts"
    import { buildSearchIndexer } from '@vitnode/core/api/lib/search'
    import { blog_posts } from '@/database/posts'

export const postSearchIndexer = buildSearchIndexer({
      itemType: 'article',
      totalCount: async (c) => {
        return await c.get('db').$count(blog_posts)
      },
      batch: async (c, { limit, offset }) => {
        const posts = await c
          .get('db')
          .select()
          .from(blog_posts)
          .limit(limit)
          .offset(offset)

return posts.map((post) => ({
          itemType: 'article',
          itemId: post.id,
          title: post.title,
          content: post.content,
          url: `/articles/${post.slug}`,
          authorId: post.authorId,
          createdAt: post.createdAt,
        }))
      },
    })
    ```

```ts title="plugins/blog/src/config.api.ts"
    export const blogApiPlugin = () =>
      buildApiPlugin({
        pluginId: 'blog',
        searchIndexers: [postSearchIndexer], // [!code ++]
      })
    ```
  </Step>
</Steps>

## Pluggable Search Engines [#pluggable-search-engines]

VitNode supports two search engines:

1. **PostgreSQL Full-Text Search (Default)**:
   * Uses native `tsvector` + GIN indexes with weighted ranking (`title` weighted above `content`).
   * Zero additional infrastructure required.
2. **Elasticsearch (`@vitnode/elasticsearch`)**:
   * Offloads indexing and search to an Elasticsearch or OpenSearch cluster.
   * Unlocks fuzzy matching, phrase boosts, and decay scoring.

For setup, credentials, configuration, and the first rebuild, follow the
[Elasticsearch tutorial](/docs/dev/search-elasticsearch).

***

## AdminCP Search Management [#admincp-search-management]

{/* Image prompt: VitNode AdminCP Search settings screen at /admin/core/advanced/search. Dashboard displaying search index statistics, engine status (PostgreSQL / Elasticsearch), registered item types with indexed document counts, and a "Rebuild Index" button. Dark theme, 1440x900. */}

Manage search status at **Core → Advanced → Search** (`/admin/core/advanced/search`):

* View indexed record counts across all collections.
* Trigger background rebuilds of specific collections or the entire site.

***

## Search Document Reference [#search-document-reference]

## Learn More [#learn-more]

# Server Functions & Isomorphic Fetching

VitNode keeps backend business logic in Hono API routes. The frontend's only job
is to call them - and for that, one universal fetcher covers SSR and browser
navigation at once.

## Decision Matrix [#decision-matrix]

| Goal                           | Recommended tool                                | Rationale                                                                                     |
| :----------------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Route data fetching**        | `fetcher` from `@vitnode/core/tanstack/fetcher` | One call site. SSR forwards the request; the browser calls `/api/*` directly.                 |
| **API endpoints & mutations**  | Hono API routes                                 | Enforces staff permissions, validation schemas, and database transactions.                    |
| **Cookie minting on the host** | `createServerFn` + the server fetcher           | Only code inside the host request can set response headers directly.                          |
| **Plugin server code**         | Hono API modules                                | **Plugins must never declare `createServerFn`** (uncompiled handlers resolve to `undefined`). |

<Callout type="warn" title="No createServerFn in plugins">
  A plugin package may declare `createIsomorphicFn`, but never `createServerFn`.
  Server functions belong exclusively to the host application.
</Callout>

***

## Fetching does not need `createIsomorphicFn` [#fetching-does-not-need-createisomorphicfn]

TanStack Router loaders run on the server for the first paint and in the browser
for every navigation after it. That used to mean writing both halves by hand:

```ts
// [!code --:3]
export const fetchDevices = createIsomorphicFn()
  .server(fetchDevicesOnServer)
  .client(fetchDevicesInBrowser)
```

The universal `fetcher` already is that boundary, so a feature writes the fetch
once:

```ts title="plugins/devices/src/lib/fetch-devices.ts"
import type { usersModule } from '@vitnode/core/api/modules/users/users.module'

import { clientModule } from '@vitnode/core/lib/fetcher-client'
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const users = clientModule<typeof usersModule>('@vitnode/core')

// [!code ++:8]
export const fetchDevices = async () => {
  const response = await fetcher(users, {
    method: 'get',
    module: 'users',
    path: '/devices',
  })

return await response.json()
}
```

```tsx title="plugins/devices/src/pages/devices-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async () => await fetchDevices(), // [!code ++]
})
```

The initial render forwards the visitor's cookie, user-agent and IP through the
request-aware transport; later navigations are a direct same-origin `fetch` to
Hono. See [Fetcher](/docs/dev/fetcher) for the full contract.

`createIsomorphicFn` is still the right tool when the *two implementations
genuinely differ* - reading a cookie from the request on the server and from
`document.cookie` in the browser, for instance. It is no longer how you fetch.

***

## When to use `createServerFn` (host app only) [#when-to-use-createserverfn-host-app-only]

Use `createServerFn` when your host application has to touch the response
itself - which in practice means cookies:

```ts title="apps/web/src/lib/auth.ts"
import { createServerFn } from '@tanstack/react-start'
import { usersModule } from '@vitnode/core/api/modules/users/users.module'
import { fetcher } from '@vitnode/core/tanstack/fetcher/server'

export const signIn = createServerFn({ method: 'POST' })
  .validator((body: { email: string; password: string }) => body)
  .handler(async ({ data }) => {
    const response = await fetcher(usersModule, {
      // [!code ++]
      allowSaveCookies: true,
      args: { body: data },
      method: 'post',
      module: 'users',
      path: '/sign_in',
    })

return { ok: response.ok }
  })
```

Two things make this the exception rather than the rule:

* it needs `allowSaveCookies`, which only the **server** fetcher offers;
* it costs an extra hop - browser → server function → API. Reads should not pay
  it, which is exactly why they use the universal `fetcher` instead.

## Learn More [#learn-more]

# Getting Started

You need Node.js 22+, Postgres (or Docker), and your favorite package manager.
Choose a workspace with Turborepo if you will create plugins; plugins are the
home for product work, not an optional side quest.

<Steps>
  <Step>
    ### Scaffold the app [#scaffold-the-app]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Create VitNode app">
      <Tab value="bun">
        ```bash
        bun create vitnode-app@canary
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm create vitnode-app@canary
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm create vitnode-app@canary
        ```
      </Tab>
    </Tabs>

Pick **Single App** for TanStack Start plus Hono at `/api`. Turn on
    **Turborepo** if you intend to use `--plugin`; it gives the generator a
    workspace root and a place for `plugins/*`.
  </Step>

<Step>
    ### Start the database [#start-the-database]

If you selected Docker, start Postgres and Redis locally:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Start local services">
      <Tab value="bun">
        ```bash
        bun run docker:dev
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm docker:dev
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm run docker:dev
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Start VitNode [#start-vitnode]

Open `http://localhost:3000`.
  </Step>
</Steps>

## Keep going [#keep-going]

<Cards>
  <Card icon="<SettingsIcon />" title="Configuration" description="Locales, plugins, request middleware, and what a browser may hold." href="/docs/dev/configuration" />

<Card icon="<PackagePlusIcon />" title="Create a plugin" description="Scaffold, register, and visit an installable feature package." href="/docs/dev/plugins/create" />

<Card icon="<ServerIcon />" title="Deployments" description="Move your TanStack Start and Hono app to production." href="/docs/dev/deployments/self-hosted" />

<Card icon="<BookOpenIcon />" title="First plugin tutorial" description="Follow a compact example that adds a real plugin page." href="/docs/guides/first-plugin" />
</Cards>

# Custom SSO Adapter

VitNode includes built-in SSO adapters for Google, Discord, and Facebook. You can connect any other OAuth2 provider (e.g. GitHub, Apple, Slack) by implementing the `SSOApiPlugin` interface. State cookie generation, user session linking, and login buttons are handled automatically.

## Quick start: GitHub SSO Adapter [#quick-start-github-sso-adapter]

Implement the 5 interface methods and register the adapter in `vitnode.api.config.ts`:

### 1. Build the Adapter [#1-build-the-adapter]

```ts title="apps/api/src/utils/sso/github.ts"
import type { SSOApiPlugin } from "@vitnode/core/api/models/sso"
import { getRedirectUri } from "@vitnode/core/api/models/sso"

export const GitHubSSOApiPlugin = ({
  clientId,
  clientSecret,
}: {
  clientId: string
  clientSecret: string
}): SSOApiPlugin => {
  const id = "github"
  const redirectUri = getRedirectUri(id)

return {
    id,
    name: "GitHub",
    // 1. Build Authorization URL
    getUrl: ({ state }) =>
      `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&scope=read:user,user:email&state=${state}`,

// 2. Exchange Authorization Code for Token
    fetchToken: async (code) => {
      const response = await fetch("https://github.com/login/oauth/access_token", {
        method: "POST",
        headers: {
          Accept: "application/json",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          client_id: clientId,
          client_secret: clientSecret,
          code,
          redirect_uri: redirectUri,
        }),
      })

return await response.json()
    },

// 3. Retrieve User Profile & Email
    fetchUser: async ({ access_token, token_type }) => {
      const headers = { Authorization: `${token_type} ${access_token}` }

// Fetch Profile
      const userRes = await fetch("https://api.github.com/user", { headers })
      const user = await userRes.json()

// Fetch Primary Email
      const emailRes = await fetch("https://api.github.com/user/emails", { headers })
      const emails: Array<{ email: string; primary: boolean; verified: boolean }> =
        await emailRes.json()
      const primaryEmail = emails.find((e) => e.primary && e.verified)?.email ?? user.email

return {
        id: String(user.id),
        email: primaryEmail,
        username: user.login,
        avatarUrl: user.avatar_url,
      }
    },
  }
}
```

***

### 2. Register in API Configuration [#2-register-in-api-configuration]

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { GitHubSSOApiPlugin } from "./utils/sso/github"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GitHubSSOApiPlugin({
        clientId: process.env.GITHUB_CLIENT_ID!,
        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      }),
    ],
  },
})
```

A **GitHub** login button automatically renders on `/login` and `/register`, and `/login/sso/github` routes incoming authentication requests.

***

## `SSOApiPlugin` Interface Reference [#ssoapiplugin-interface-reference]

<TypeTable
  type="{
  id: {
    description: "Unique slug for the provider (e.g. 'github', 'slack'). Used in callback URLs.",
    required: true,
    type: "string",
  },
  name: {
    description: "Display name shown on the login button.",
    required: true,
    type: "string",
  },
  getUrl: {
    description: "Returns the provider authorization redirect URL.",
    required: true,
    type: "({ state: string }) => string",
  },
  fetchToken: {
    description: "Exchanges code for access_token.",
    required: true,
    type: "(code: string) => Promise<{ access_token: string; token_type: string }>",
  },
  fetchUser: {
    description: "Fetches user profile (id, email, username, avatarUrl).",
    required: true,
    type: "(token: TokenResponse) => Promise<SSOUser>",
  },
}"
/>

## Built-in SSO Adapters [#built-in-sso-adapters]

# Discord

Discord is the quickest of the three to set up: no consent screen review, no app
modes, no verification. Create an application, add one redirect URL, copy two
values.

## Quick start [#quick-start]

If you already have a client ID and secret, this is the entire integration.

```bash title=".env"
DISCORD_CLIENT_ID=1234567890123456789
DISCORD_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { DiscordSSOApiPlugin } from '@vitnode/core/api/adapters/sso/discord' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      DiscordSSOApiPlugin({
        clientId: process.env.DISCORD_CLIENT_ID,
        clientSecret: process.env.DISCORD_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Discord** button appears on `/login`.

## Set up the application [#set-up-the-application]

<Steps>
  <Step>
    ### Sign in to the Discord Developer Portal [#sign-in-to-the-discord-developer-portal]

Go to the [Discord Developer Portal](https://discord.com/developers/applications)
    and sign in with the Discord account that should own the application.
  </Step>

<Step>
    ### Create a new application [#create-a-new-application]

Press **New Application**, give it the name visitors will see on the
    authorization screen, and accept the terms.

{/* Image prompt: The Discord Developer Portal applications list with the "New Application" dialog open and a name typed into the field, dark theme, 1100x600. */}
  </Step>

<Step>
    ### Add the redirect URL [#add-the-redirect-url]

Open **OAuth2** in the left navigation and, under **Redirects**, press **Add
    Redirect**. Paste the URI for the origin you are running and save.

VitNode builds this URI from `NEXT_PUBLIC_WEB_URL`, so it has to match exactly -
    no trailing slash, no locale prefix.

| Environment                               | Redirect URL                                |
    | ----------------------------------------- | ------------------------------------------- |
    | Development (`NEXT_PUBLIC_WEB_URL` unset) | `http://localhost:3000/login/sso/discord`   |
    | Production                                | `https://your-domain.com/login/sso/discord` |

Add both entries so one application covers local development and your live site.

{/* Image prompt: The Discord Developer Portal OAuth2 page with the "Redirects" section showing one entry reading http://localhost:3000/login/sso/discord and the "Save Changes" bar at the bottom, dark theme, 1100x500. */}

<Callout type="warn" title="Invalid OAuth2 redirect_uri">
      Discord rejects the authorization request outright if the URL is not in this
      list, before the visitor sees anything. If pressing the button lands you on a
      Discord error page rather than an authorization prompt, this is why.
    </Callout>
  </Step>

<Step>
    ### Copy the client ID and secret [#copy-the-client-id-and-secret]

Still on the **OAuth2** page, the **Client ID** and **Client Secret** are in the
    client information block at the top. Press **Reset Secret** if the secret was
    never revealed or you have lost it - Discord shows it once.

{/* Image prompt: The Discord Developer Portal OAuth2 page client information block showing "Client ID" with a Copy button and "Client Secret" with a Reset Secret button, values redacted, dark theme, 1100x450. */}
  </Step>

<Step>
    ### Set the environment variables [#set-the-environment-variables]

Server-side variables, so **no** `NEXT_PUBLIC_` prefix - that prefix is what
    marks a value for the browser bundle, and a client secret in the browser bundle
    is a client secret you have published.

```bash title=".env"
    DISCORD_CLIENT_ID=1234567890123456789 # [!code ++]
    DISCORD_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # [!code ++]
    ```
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

Add `DiscordSSOApiPlugin` to `authorization.ssoAdapters`. It is a plain factory
    function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
    import { DiscordSSOApiPlugin } from '@vitnode/core/api/adapters/sso/discord' // [!code ++]
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      plugins: [],
      // [!code ++:8]
      authorization: {
        ssoAdapters: [
          DiscordSSOApiPlugin({
            clientId: process.env.DISCORD_CLIENT_ID,
            clientSecret: process.env.DISCORD_CLIENT_SECRET,
          }),
        ],
      },
    })
    ```

The redirect URI is computed when this file is evaluated, so restart the API
    rather than relying on a hot reload:

<Step>
    ### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
    curl http://localhost:3000/api/@vitnode/core/middleware
    # {"isEmail":false,"sso":[{"id":"discord","name":"Discord"}]}
    ```

Then open `/login` and press **Discord**. You should see Discord's "connect to"
    authorization prompt listing your username and email, get bounced back to
    `/login/sso/discord?code=...&state=...`, and land on the front page signed in.

{/* Image prompt: The VitNode /login page with the email and password fields above a divider reading "Or continue With" and an outline button labelled Discord beneath it, dark theme, 900x850. */}
  </Step>
</Steps>

## What the adapter asks Discord for [#what-the-adapter-asks-discord-for]

Useful when you are debugging an authorization prompt that lists the wrong
permissions.

| Setting       | Value                                  |
| ------------- | -------------------------------------- |
| Authorize URL | `https://discord.com/oauth2/authorize` |
| Token URL     | `https://discord.com/api/oauth2/token` |
| Profile URL   | `https://discord.com/api/users/@me`    |
| Scopes        | `identify email`                       |
| Provider id   | `discord`                              |
| Fields read   | `id`, `email`, `username`              |

Both scopes are required: `identify` for the id and username, `email` for the
address the account is created with.

## Gotchas [#gotchas]

<Callout type="warn" title="An account with no email cannot sign in">
  The adapter requires `email` in Discord's profile response and answers `400`
  when it is absent - which is what happens if the `email` scope is dropped, or
  if the Discord account genuinely has no address on it. The visitor sees the
  generic error screen.
</Callout>

<Callout type="warn" title="Discord's email verification flag is not checked">
  Unlike the Google adapter, which rejects an unverified address, this one takes
  Discord's `email` at face value and never reads Discord's `verified` field. If
  you need that guarantee, copy the adapter into your own project and add the
  check - see [Custom adapter](/docs/dev/sso/custom-adapter).
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `DiscordSSOApiPlugin` whose `clientId` is `undefined` registers happily -
  the button renders and the provider is listed - and throws `Missing Discord
    client ID` the moment somebody presses it. A button that only raises an error
  toast is an environment problem, not a portal problem.
</Callout>

## Next [#next]

# Facebook

Facebook sign-in goes through a Meta app with the **Facebook Login** use case
switched on. Meta calls the two credentials an **App ID** and an **App Secret**;
VitNode calls them `clientId` and `clientSecret`, and they are the same two
strings.

## Quick start [#quick-start]

If you already have an App ID and App Secret, this is the entire integration.

```bash title=".env"
FACEBOOK_CLIENT_ID=1234567890123456
FACEBOOK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { FacebookSSOApiPlugin } from '@vitnode/core/api/adapters/sso/facebook' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      FacebookSSOApiPlugin({
        clientId: process.env.FACEBOOK_CLIENT_ID,
        clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Facebook** button appears on `/login`. The rest of this
page is how to get those two values.

## Set up the Meta app [#set-up-the-meta-app]

<Steps>
  <Step>
    ### Sign in to Meta for Developers [#sign-in-to-meta-for-developers]

Go to [developers.facebook.com](https://developers.facebook.com/) and sign in
    with the Facebook account that should own the app. Meta walks you through
    registering as a developer the first time, which means confirming your contact
    details before you can create anything.
  </Step>

<Step>
    ### Create an app [#create-an-app]

From **My Apps**, press **Create App**. The first screen wants an **App name** -
    this is what visitors read on the login dialog - and an **App contact email**.

<Step>
    ### Choose the Facebook Login use case [#choose-the-facebook-login-use-case]

On the **Use cases** step, tick **Authenticate and request data from users with
    Facebook Login**. This is the one that gives the app an OAuth dialog; the others
    (Ads Manager, Threads, games) do not, and Meta will not let you combine some of
    them on one app.

Finish the wizard - the **Business** step lets you skip connecting a business
    portfolio, and **Finalize** creates the app.
  </Step>

<Step>
    ### Add the OAuth redirect URI [#add-the-oauth-redirect-uri]

In the app dashboard, open the Facebook Login use case's settings - **Use cases →
    Authenticate and request data from users with Facebook Login → Customize →
    Settings** on a new app, or **Products → Facebook Login → Settings** on an older
    one. Paste your URI into **Valid OAuth Redirect URIs** and save.

VitNode builds this URI itself, from `NEXT_PUBLIC_WEB_URL`, so it has to match
    character for character - no trailing slash, no locale prefix.

| Environment                               | Valid OAuth Redirect URI                     |
    | ----------------------------------------- | -------------------------------------------- |
    | Development (`NEXT_PUBLIC_WEB_URL` unset) | `http://localhost:3000/login/sso/facebook`   |
    | Production                                | `https://your-domain.com/login/sso/facebook` |

{/* Image prompt: The Meta app dashboard Facebook Login Settings panel with "Valid OAuth Redirect URIs" holding one entry reading https://your-domain.com/login/sso/facebook, the "Client OAuth login" and "Web OAuth login" toggles visible above it, light theme, 1200x700. */}

<Callout type="warn" title="Meta wants HTTPS in production">
      **Valid OAuth Redirect URIs** rejects a plain `http://` URL for a public
      domain, so a production entry has to be `https://`. `http://localhost` is the
      exception Meta makes for development, which is why the table above has two
      rows rather than one.
    </Callout>
  </Step>

<Step>
    ### Copy the App ID and App Secret [#copy-the-app-id-and-app-secret]

Go to **App settings → Basic** in the left navigation. The **App ID** is in plain
    text; the **App Secret** is behind a **Show** button and your password.

<Step>
    ### Set the environment variables [#set-the-environment-variables]

Server-side variables, so **no** `NEXT_PUBLIC_` prefix - that prefix is what
    marks a value for the browser bundle, and an app secret in the browser bundle is
    an app secret you have published.

```bash title=".env"
    FACEBOOK_CLIENT_ID=1234567890123456 # [!code ++]
    FACEBOOK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # [!code ++]
    ```
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

Add `FacebookSSOApiPlugin` to `authorization.ssoAdapters` in your API config. It
    is a plain factory function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
    import { FacebookSSOApiPlugin } from '@vitnode/core/api/adapters/sso/facebook' // [!code ++]
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      plugins: [],
      // [!code ++:8]
      authorization: {
        ssoAdapters: [
          FacebookSSOApiPlugin({
            clientId: process.env.FACEBOOK_CLIENT_ID,
            clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
          }),
        ],
      },
    })
    ```

The redirect URI is computed when this file is evaluated, so restart the API
    rather than relying on a hot reload:

<Step>
    ### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
    curl http://localhost:3000/api/@vitnode/core/middleware
    # {"isEmail":false,"sso":[{"id":"facebook","name":"Facebook"}]}
    ```

Then open `/login` and press **Facebook**. You should get Meta's "Continue as
    ..." dialog, be bounced back to `/login/sso/facebook?code=...&state=...`, and
    land on the front page signed in. Your account now has a row in `core_users_sso`
    with `providerId` `facebook`.

{/* Image prompt: The VitNode /login page with the password form above a divider reading "Or continue With" and two outline buttons labelled Google and Facebook side by side, dark theme, 900x800. */}
  </Step>

<Step>
    ### Publish the app [#publish-the-app]

While the app is **Unpublished** (the badge next to **Publish** in the
    screenshot above), only people with a role on it - admins, developers, testers -
    can sign in. Everyone else is turned away at Meta's dialog before VitNode ever
    sees a callback. Go to **Publish** and switch the app live once the round trip
    works.

`public_profile` and `email` are both standard-access permissions, so this does
    not require App Review. Ask for anything beyond them and it will.

{/* Image prompt: The Meta app dashboard Publish page showing the app status as Unpublished with the requirements checklist and the go-live button, light theme, 1100x600. */}
  </Step>
</Steps>

## What the adapter asks Facebook for [#what-the-adapter-asks-facebook-for]

Useful when you are debugging a login dialog that shows more or fewer
permissions than you expected.

| Setting       | Value                                                      |
| ------------- | ---------------------------------------------------------- |
| Authorize URL | `https://www.facebook.com/v22.0/dialog/oauth`              |
| Token URL     | `https://graph.facebook.com/v22.0/oauth/access_token`      |
| Profile URL   | `https://graph.facebook.com/v22.0/me?fields=id,name,email` |
| Scopes        | `public_profile,email`                                     |
| Provider id   | `facebook`                                                 |
| Fields read   | `id`, `name`, `email`                                      |

The account name VitNode creates comes from Facebook's `name` field, stripped of
characters that cannot appear in a profile URL. The Graph API version is pinned
to `v22.0` in the adapter, so a Meta version bump never changes what this
install sends.

## Gotchas [#gotchas]

<Callout type="warn" title="An account with no email cannot sign in">
  The adapter requires `email` in the Graph response and answers `400` when it
  is missing - which happens if the visitor unticks the email permission on the
  login dialog, or if the account was created with a phone number and has no
  address at all. The visitor sees the generic error screen, not an explanation.
</Callout>

<Callout type="warn" title="Facebook's own email verification is not checked">
  Unlike the [Google adapter](/docs/dev/sso/google), which rejects an unverified
  address, this one takes the Graph API's `email` at face value. If you need a
  stronger guarantee, copy the adapter into your own project and add the check -
  see [Custom adapter](/docs/dev/sso/custom-adapter).
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `FacebookSSOApiPlugin` whose `clientId` is `undefined` registers happily -
  the button renders and the provider is listed - and throws `Missing Facebook
    client ID` the moment somebody presses it. A button that only raises an error
  toast is an environment problem, not a dashboard problem.
</Callout>

<Callout type="warn" title="An email that already has a password account is a dead end">
  If someone registered with the same address using the password form, the
  callback answers `409` and offers them the login page instead. There is no
  link-an-existing-account screen yet - see [how the callback handles
  accounts](/docs/dev/sso#what-the-callback-does-with-the-account).
</Callout>

## Next [#next]

# Google

Google is the provider most people want first. The whole job is: create an OAuth
client in the Google Auth Platform, give it the redirect URI VitNode already
decided on, and pass the two credentials to `GoogleSSOApiPlugin`.

## Quick start [#quick-start]

If you already have a client ID and secret, this is the entire integration.

```bash title=".env"
GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { GoogleSSOApiPlugin } from '@vitnode/core/api/adapters/sso/google' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GoogleSSOApiPlugin({
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Google** button appears on `/login`. The rest of this
page is how to get those two values.

## Set up the OAuth client [#set-up-the-oauth-client]

<Steps>
  <Step>
    ### Sign in to Google Cloud [#sign-in-to-google-cloud]

Go to the [Google Cloud Console](https://console.cloud.google.com/) and sign in
    with the account that should own the OAuth client. It does not have to be the
    account you sign in to your own site with.
  </Step>

<Step>
    ### Pick or create a project [#pick-or-create-a-project]

An OAuth client belongs to a project, so select one from the project picker in
    the top bar - or create one if this is a fresh account. Name it after your site;
    the name is internal and never shown to visitors.

{/* Image prompt: The Google Cloud Console project picker dialog open, showing the "Select a project" list with a "New project" button in the top right, light theme, 1200x700. */}
  </Step>

<Step>
    ### Open the Google Auth Platform [#open-the-google-auth-platform]

Type `Google Auth Platform` into the console's search bar and open the first
    result. This is the section that used to be called "OAuth consent screen", and
    it is where both the consent details and the clients live.

{/* Image prompt: The Google Cloud Console top search bar with "Google Auth Platform" typed in and the matching product result highlighted in the dropdown, light theme, 1200x400. */}
  </Step>

<Step>
    ### Fill in the consent details [#fill-in-the-consent-details]

Google will not issue a client until it knows what to show on the consent
    screen. Provide the **App name** - this is the name visitors read in "Sign in to
    continue to ..." - and a **Support email**.

Then, under **Audience**, choose **External** so anyone with a Google account can
    sign in. **Internal** restricts sign-in to a single Google Workspace
    organisation, which is almost never what a public site wants.

{/* Image prompt: The Google Auth Platform "Audience" step with the "External" radio option selected and the "Internal" option visible above it, light theme, 1000x600. */}
  </Step>

<Step>
    ### Create the client and set the redirect URI [#create-the-client-and-set-the-redirect-uri]

Go to **Clients** in the left navigation and press **Create client**.

1. Application type: **Web application**.
    2. Name: anything - this one is internal too.
    3. Under **Authorized redirect URIs**, add the URI for every origin you run.

VitNode builds this URI itself, from `NEXT_PUBLIC_WEB_URL`, so it has to match
    character for character - no trailing slash, no locale prefix.

| Environment                               | Authorized redirect URI                    |
    | ----------------------------------------- | ------------------------------------------ |
    | Development (`NEXT_PUBLIC_WEB_URL` unset) | `http://localhost:3000/login/sso/google`   |
    | Production                                | `https://your-domain.com/login/sso/google` |

Add both. Google allows several redirect URIs per client, and one client for dev
    and prod is fine while you are getting started.

{/* Image prompt: The Google Auth Platform "Create OAuth client" form with Application type set to "Web application" and one entry under "Authorized redirect URIs" reading http://localhost:3000/login/sso/google, light theme, 1000x700. */}

<Callout type="warn" title="redirect_uri_mismatch">
      This is the error you will get if the URI differs by so much as a trailing
      slash. It comes from Google, not from VitNode, and it is always this field.
    </Callout>
  </Step>

<Step>
    ### Copy the client ID and secret [#copy-the-client-id-and-secret]

Open the client you just created from the **Clients** list. The **Client ID** and
    **Client secret** are on the right-hand side of the detail panel. Copy both -
    Google will let you see the secret again, but you may as well paste it straight
    into `.env`.

{/* Image prompt: The Google Auth Platform OAuth client detail panel with the "Client ID" and "Client secret" fields visible on the right, values redacted, light theme, 1100x600. */}
  </Step>

<Step>
    ### Set the environment variables [#set-the-environment-variables]

These names are not magic - they are whatever you read in your config on the
    next step. What matters is that they are server-side variables, so **no**
    `NEXT_PUBLIC_` prefix: that prefix is what marks a value for the browser bundle,
    and a client secret in the browser bundle is a client secret you have published.

```bash title=".env"
    GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com # [!code ++]
    GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx # [!code ++]
    ```
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

Add `GoogleSSOApiPlugin` to `authorization.ssoAdapters` in your API config.
    Note that it is a plain factory function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
    import { GoogleSSOApiPlugin } from '@vitnode/core/api/adapters/sso/google' // [!code ++]
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      plugins: [],
      // [!code ++:8]
      authorization: {
        ssoAdapters: [
          GoogleSSOApiPlugin({
            clientId: process.env.GOOGLE_CLIENT_ID,
            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
          }),
        ],
      },
    })
    ```

The redirect URI is computed when this file is evaluated, so restart the API
    rather than relying on a hot reload:

<Step>
    ### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
    curl http://localhost:3000/api/@vitnode/core/middleware
    # {"isEmail":false,"sso":[{"id":"google","name":"Google"}]}
    ```

Then open `/login` and press **Google**. You should be sent to Google's consent
    screen, bounced back to `/login/sso/google?code=...&state=...`, and land on the
    front page signed in. Your account now has a row in `core_users_sso` with
    `providerId` `google`.

{/* Image prompt: The VitNode /login page with the email and password fields above a divider reading "Or continue With" and an outline button labelled Google beneath it, light theme, 900x850. */}
  </Step>

<Step>
    ### Publish the app [#publish-the-app]

While the client is unpublished, Google restricts sign-in to the test users you
    listed and shows an "unverified app" warning. Once the round trip works, go to
    **Google Auth Platform → Audience** and press **Publish app**.

{/* Image prompt: The Google Auth Platform "Audience" page showing publishing status "Testing" with the "Publish app" button highlighted, light theme, 1000x500. */}
  </Step>
</Steps>

## What the adapter asks Google for [#what-the-adapter-asks-google-for]

Useful when you are debugging a consent screen that shows more or fewer
permissions than you expected.

| Setting       | Value                                           |
| ------------- | ----------------------------------------------- |
| Authorize URL | `https://accounts.google.com/o/oauth2/auth`     |
| Token URL     | `https://oauth2.googleapis.com/token`           |
| Profile URL   | `https://www.googleapis.com/oauth2/v1/userinfo` |
| Scopes        | `openid profile email`                          |
| Provider id   | `google`                                        |
| Fields read   | `id`, `email`, `name`, `verified_email`         |

The account name VitNode creates comes from Google's `name` field, stripped of
characters that cannot appear in a profile URL.

## Gotchas [#gotchas]

<Callout type="warn" title="Unverified Google emails are rejected">
  The adapter reads `verified_email` and throws a `400` when it is `false`, so a
  Google account with an unconfirmed address cannot sign in at all. The visitor
  sees the generic error screen rather than an explanation, which is the one
  place this is worth knowing about in advance.
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `GoogleSSOApiPlugin` whose `clientId` is `undefined` registers happily - the
  button renders and the provider is listed - and throws `Missing Google client
    ID` the moment somebody presses it. If the button is there but does nothing
  except raise an error toast, check the environment before you check the
  console.
</Callout>

## Next [#next]

# Single Sign-On (SSO)

VitNode provides built-in OAuth2 single sign-on. Register an adapter in your API configuration, and authentication buttons automatically appear on `/login` and `/register`.

## Quick start [#quick-start]

```ts title="apps/api/src/vitnode.api.config.ts"
import { GoogleSSOApiPlugin } from "@vitnode/core/api/adapters/sso/google"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GoogleSSOApiPlugin({
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      }),
    ],
  },
})
```

A **Continue with Google** button automatically renders on your login and registration forms.

***

## Supported Providers [#supported-providers]

***

## Callback URLs [#callback-urls]

When configuring OAuth2 applications in provider developer consoles, use the following redirect URI pattern:

```text
https://your-domain.com/login/sso/{provider_id}
```

For example: `https://your-domain.com/login/sso/google`.

***

## How Accounts Link [#how-accounts-link]

When a user signs in via SSO:

1. **Existing Email Match**: If an existing account shares the verified email, the SSO identity is automatically linked.
2. **New Visitor**: A new user is created with their social display name, email, and avatar.

## Learn More [#learn-more]

# Custom adapter

A storage adapter is a plain factory that returns three functions. VitNode has
already validated the file, re-encoded the image and built a collision-free key
before it calls you - your job is to put bytes somewhere and be able to name
their URL afterwards.

## Quick start [#quick-start]

The whole contract is one interface, and there is nothing to install to
implement it:

```ts title="packages/vitnode/src/api/models/storage.ts"
export interface StorageApiPlugin {
  delete: (key: string) => Promise<void>
  getUrl: (key: string) => string
  static?: StorageStaticConfig
  upload: (args: StorageUploadArgs) => Promise<StorageUploadResult>
}
```

Return an object of that shape from a factory, set it as `storage.adapter` in
your API config, and VitNode stores files through it. The
[working skeleton](#write-one) below is about 60 lines.

## The three methods [#the-three-methods]

| Method                               | Gets                                                   | Must return                     | Rules                                                                        |
| :----------------------------------- | :----------------------------------------------------- | :------------------------------ | :--------------------------------------------------------------------------- |
| `upload({ key, body, contentType })` | A Node `Buffer`, the media type, and a pre-built `key` | `{ key, url }`                  | Store `body` **at that exact key**. The key is written to the database as-is |
| `delete(key)`                        | The key from the `core_files` row                      | `Promise<void>`                 | An object that is already gone is a success, not an error                    |
| `getUrl(key)`                        | The same key                                           | A public URL, **synchronously** | Build a string. No network, no `await` - it runs once per row in a listing   |

`StorageUploadArgs` and `StorageUploadResult` are exported from the same module,
so you never have to restate them:

```ts title="packages/vitnode/src/api/models/storage.ts"
export interface StorageUploadArgs {
  body: Buffer
  contentType?: string
  key: string
}

export interface StorageUploadResult {
  key: string
  url: string
}
```

## Write one [#write-one]

<Steps>
  <Step>
    ### Write the adapter [#write-the-adapter]

A complete adapter, against any object store that answers `PUT` and `DELETE` and
    serves the objects back from a public base URL. Both official cloud adapters
    default their arguments to `""` and check them lazily, so a missing environment
    variable fails on the first upload with a sentence rather than at import time
    with a stack trace.

```ts title="src/utils/storage/http-storage.ts"
    import type {
      StorageApiPlugin,
      StorageUploadArgs,
      StorageUploadResult,
    } from '@vitnode/core/api/models/storage'

export const HttpStorageAdapter = ({
      apiKey = '',
      endpoint = '',
      publicUrl = '',
    }: {
      apiKey: string | undefined
      endpoint: string | undefined
      publicUrl: string | undefined
    }): StorageApiPlugin => {
      const requireConfig = () => {
        if (!(apiKey && endpoint && publicUrl)) {
          throw new Error('Missing HTTP storage configuration')
        }

return { apiKey, endpoint: endpoint.replace(/\/$/, '') }
      }

const getUrl = (key: string): string =>
        `${publicUrl.replace(/\/$/, '')}/${key}`

return {
        getUrl,
        delete: async (key: string): Promise<void> => {
          const { apiKey, endpoint } = requireConfig()

const res = await fetch(`${endpoint}/${key}`, {
            method: 'DELETE',
            headers: { Authorization: `Bearer ${apiKey}` },
          })
          if (!res.ok && res.status !== 404) {
            throw new Error(`Storage delete failed with ${res.status}`)
          }
        },
        upload: async ({
          body,
          contentType,
          key,
        }: StorageUploadArgs): Promise<StorageUploadResult> => {
          const { apiKey, endpoint } = requireConfig()

const res = await fetch(`${endpoint}/${key}`, {
            method: 'PUT',
            headers: {
              Authorization: `Bearer ${apiKey}`,
              'Content-Type': contentType ?? 'application/octet-stream',
            },
            body: new Uint8Array(body),
          })
          if (!res.ok) {
            throw new Error(`Storage upload failed with ${res.status}`)
          }

return { key, url: getUrl(key) }
        },
      }
    }
    ```

Two details worth copying rather than reinventing. `delete` treats a `404` as
    done, because `deleteFile` has already removed the database row by the time it
    runs - throwing there turns a finished delete into a failed request. And
    `upload` returns the key it was handed, never a rewritten one.
  </Step>

<Step>
    ### Register it [#register-it]

An adapter needs no registry, no manifest and no plugin entry. It is a value on
    the API config:

```ts title="src/vitnode.api.config.ts"
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { HttpStorageAdapter } from './utils/storage/http-storage' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      storage: {
        // [!code ++:5]
        adapter: HttpStorageAdapter({
          apiKey: process.env.STORAGE_API_KEY,
          endpoint: process.env.STORAGE_ENDPOINT,
          publicUrl: process.env.STORAGE_PUBLIC_URL,
        }),
      },
    })
    ```
  </Step>

<Step>
    ### Verify it round-trips [#verify-it-round-trips]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`)
    and click **Test storage** on the Storage card. It uploads an image through your
    adapter, then the row shows up in **AdminCP → Core → System → Files** with a
    working thumbnail - which is `getUrl` proving itself, since the browser loads
    that URL directly.

If the thumbnail is broken but the upload succeeded, `upload` and `getUrl`
    disagree about the URL. If the upload itself failed, the API log has your own
    error message in it.
  </Step>
</Steps>

<Callout type="info" title="Keys are pre-built for you">
  The framework builds `month_{month}_{year}/{folder}/<uuid>.<ext>` before
  calling `upload`, checks every folder segment against the traversal guard, and
  stores that key on the `core_files` row. So an adapter stores `body` at the
  key it was handed and never invents path logic - see [storage
  keys](/docs/dev/storage#storage-keys).
</Callout>

## The optional static descriptor [#the-optional-static-descriptor]

Disk-backed adapters can expose a fourth field, and only they should:

```ts
export interface StorageStaticConfig {
  mountPath: string
  root: string
  stripPrefix: string
}
```

It is not read by the storage layer at all - the app that boots the API reads it
to mount Hono's `serveStatic` for the stored files, which is how the
[Local adapter](/docs/dev/storage/local#serve-the-stored-files) serves what it
writes. A cloud adapter omits it, and the mount is then skipped.

| Field         | The Local adapter's value                              |
| :------------ | :----------------------------------------------------- |
| `mountPath`   | `publicPath` with a leading `/api` stripped, plus `/*` |
| `root`        | `./public/uploads`                                     |
| `stripPrefix` | `publicPath`, e.g. `/api/uploads`                      |

## Gotchas [#gotchas]

<Callout type="warn" title="A thrown error becomes a 500">
  Your errors are not `HTTPException`s, so the API's error handler answers `500`

* with your message in the body during development and a bare "Internal Server
    Error" in production, where only the log has the reason. That is the same deal
    the official adapters get. Throw an `HTTPException` from `hono/http-exception`
    instead when the person uploading can act on the cause - a quota, say, rather
    than a broken token.
</Callout>

<Callout type="warn" title="getUrl runs once per row">
  The AdminCP Files table calls it for every file on the page, and it is
  declared synchronous, so a signed URL that needs a round trip does not fit
  here. Put a CDN or a public base URL in front of the store and build a string.
</Callout>

<Callout type="warn" title="Never rewrite the key">
  Returning a different `key` than you were given stores that value on the row -
  and every later read, download and delete uses it. If your provider mangles
  the path (a leading slash, a normalised case), return the key **as the
  provider will accept it back**, not as you wish it were.
</Callout>

<Callout type="info" title="Sizes and dimensions are already decided">
  `body.length` is what lands in `core_files.size`, and the image pipeline has
  already run. An adapter that compresses further would make the database
  disagree with the object, so leave the bytes alone.
</Callout>

## Publish it [#publish-it]

If the adapter is useful to more than one installation, publish it as a package.
Both official adapters are small enough to read in one sitting and are the best
starting template:

* [`@vitnode/s3`](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/s3) -
  a lazily created SDK client, a URL built from three rules
* [`@vitnode/supabase-storage`](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/supabase-storage) -
  the shortest possible adapter, at under 60 lines

Keep `@vitnode/core` a dev dependency (you only import types from it) and ship
your provider's SDK as a real dependency, the way both of those do.

## Next [#next]

# Storage

VitNode provides an integrated storage layer accessible via `c.get("storage")`. It handles file validation, automatic WebP image optimization, database indexing in `core_files`, and persistent storage across multiple backends.

## Quick start [#quick-start]

### 1. Register a Storage Adapter [#1-register-a-storage-adapter]

In `apps/api/src/vitnode.api.config.ts`, configure the local disk adapter:

```ts title="apps/api/src/vitnode.api.config.ts"
import { LocalStorageAdapter } from "@vitnode/core/api/adapters/storage/local"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    adapter: LocalStorageAdapter(), // [!code ++]
  },
})
```

### 2. Upload Files in an API Route [#2-upload-files-in-an-api-route]

Handle uploads in a Hono route using `c.get("storage").upload()`:

```ts title="plugins/blog/src/api/modules/posts/routes/upload-cover.route.ts"
import { z } from "@hono/zod-openapi"
import { buildRoute } from "@vitnode/core/api/lib/route"

export const uploadCoverRoute = buildRoute({
  pluginId: "blog",
  route: {
    method: "post",
    path: "/cover",
    request: {
      body: {
        content: {
          "multipart/form-data": {
            schema: z.object({
              file: z.instanceof(File),
            }),
          },
        },
      },
    },
  },
  handler: async (c) => {
    const { file } = await c.req.parseBody()

// [!code ++:7]
    const uploaded = await c.get("storage").upload({
      file: file as File,
      folder: "covers",
      maxBytes: 5 * 1024 * 1024, // 5 MB
      allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
    })

return c.json(uploaded)
  },
})
```

`upload()` saves the file, creates a record in `core_files`, and returns `{ id, url, width, height, size }`.

***

## Supported Storage Adapters [#supported-storage-adapters]

***

## Image Optimization [#image-optimization]

The storage service can automatically convert uploaded images to WebP and constrain dimensions:

```ts
const uploaded = await c.get("storage").upload({
  file,
  folder: "avatars",
  convertImagesToWebp: true, // [!code ++]
  maxDimensions: { width: 1200, height: 1200 }, // [!code ++]
})
```

***

## Deleting Files [#deleting-files]

Remove files and clean up storage using `delete()`:

```ts
await c.get("storage").delete({ fileId: 42 })
```

This removes the file from the configured storage bucket and deletes its row from `core_files`.

***

## Verifying in AdminCP [#verifying-in-admincp]

{/* Image prompt: VitNode AdminCP System -> Integrations screen at /admin/core/system/integrations. Storage integration card shows "Active" with a "Test file storage" button and modal demonstrating test file upload. Dark theme, 1440x900. */}

Test your storage adapter anytime in the AdminCP:

1. Navigate to **System → Integrations** (`/admin/core/system/integrations`).
2. On the **Storage** card, click **Test Storage** to verify bucket credentials and upload capabilities.
3. Inspect uploaded files anytime under **System → Files** (`/admin/core/system/files`).

## Learn More [#learn-more]

# Local (disk)

The Local adapter is the one that needs no account, no keys and no extra package:
it writes uploads into `public/uploads` next to your API and serves them back as
static files. Perfect for development and for a single self-hosted server, and
the wrong choice on serverless.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { LocalStorageAdapter } from '@vitnode/core/api/adapters/storage/local' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    adapter: LocalStorageAdapter(), // [!code ++]
  },
})
```

That is enough to store files. Serving them back is one more step, and it depends
on which app runs the API - keep reading.

## Set it up [#set-it-up]

<Steps>
  <Step>
    ### Register the adapter [#register-the-adapter]

There is nothing to install - the adapter lives in `@vitnode/core`, which you
    already depend on. Import it and set `storage.adapter`, exactly as in the
    [Quick start](#quick-start) above.

Uploads then land under the current working directory of the API process:

<Step>
    ### Serve the stored files [#serve-the-stored-files]

Writing a file is not the same as answering a request for it. The adapter exposes
    a `static` descriptor - `mountPath`, `root` and `stripPrefix` - so the mount is
    derived from your `publicPath` instead of hardcoded in two places.

<Tabs groupId="storage-host" items="['Standalone API', 'TanStack Start app']">
      <Tab value="Standalone API">
        ```ts  title="apps/api/src/index.ts"
        import { serveStatic } from '@hono/node-server/serve-static'
        import { mkdirSync } from 'node:fs'

// [!code ++:14]
        const staticStorage = vitNodeApiConfig.storage?.adapter?.static
        if (staticStorage) {
          mkdirSync(staticStorage.root, { recursive: true })
          app.get(
            staticStorage.mountPath,
            serveStatic({
              root: staticStorage.root,
              rewriteRequestPath: (path) =>
                path.startsWith(staticStorage.stripPrefix)
                  ? path.slice(staticStorage.stripPrefix.length)
                  : path,
            }),
          )
        }

VitNodeAPI({ app, vitNodeApiConfig })
        ```
      </Tab>

<Tab value="TanStack Start app">
        ```ts  title="src/server/vitnode-api.server.ts"
        import { serveStatic } from '@hono/node-server/serve-static'
        import { mkdirSync } from 'node:fs'

const createVitNodeApi = () => {
          const app = new OpenAPIHono().basePath('/api')

// [!code ++:14]
          const staticStorage = vitNodeApiConfig.storage?.adapter?.static
          if (staticStorage) {
            mkdirSync(staticStorage.root, { recursive: true })
            app.get(
              staticStorage.mountPath,
              serveStatic({
                root: staticStorage.root,
                rewriteRequestPath: (path) =>
                  path.startsWith(staticStorage.stripPrefix)
                    ? path.slice(staticStorage.stripPrefix.length)
                    : path,
              }),
            )
          }

VitNodeAPI({ app, vitNodeApiConfig })

return app
        }
        ```
      </Tab>
    </Tabs>

Mount `serveStatic` **before** `VitNodeAPI` on the standalone API: the request
    then skips the CORS, CSRF, rate-limiter and global middleware, which a static
    image has no use for. `mkdirSync` is only there so `serveStatic` does not warn
    about a missing root before the first upload.

The TanStack Start app is the same code in a different file, because `/api/*` on
    that app is one catch-all route handing the request to the very same Hono
    application - so the mount belongs inside it, not in the router. `serveStatic`
    comes from `@hono/node-server`, which that app does not depend on yet:

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']">
      <Tab value="bun">
        ```bash
        bun i @hono/node-server
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @hono/node-server
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @hono/node-server
        ```
      </Tab>
    </Tabs>

<Callout type="warn" title="Vite's public/ is a build-time snapshot">
      During `vite dev` the app's `public/` directory is served at the site root, so
      setting `publicPath: "/uploads"` looks like it works with no mount at all.
      `vite build` copies `public/` into the build output **once**, so files
      uploaded at runtime are written somewhere the production server never reads
      from. Keep the default `publicPath` and mount the `static` descriptor as
      above, or use a cloud adapter - which is the honest answer for anything with
      more than one instance.
    </Callout>
  </Step>

<Step>
    ### Point the URLs at the right origin [#point-the-urls-at-the-right-origin]

The adapter builds absolute URLs as `{baseUrl}/{publicPath}/{key}`. `baseUrl`
    defaults to the configured API origin, so this env var is what decides whether
    your file URLs are reachable:

| Variable              | Required    | What it is for                                                                                                                                                             |
    | :-------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `NEXT_PUBLIC_API_URL` | Recommended | The public origin of the API. Used as the default `baseUrl`, so a wrong value produces URLs that 404. Falls back to the browser's own origin, then `http://localhost:3000` |

```bash title=".env"
    NEXT_PUBLIC_API_URL=http://localhost:8000
    ```

Pass `baseUrl` explicitly if the files are fronted by a different hostname than
    the API itself.
  </Step>

<Step>
    ### Upload something and verify [#upload-something-and-verify]

Open **AdminCP → Core → System → Integrations** and use **Test storage** on the
    Storage card: it uploads an image and tells you whether the round trip worked.

Then check the file is really on disk and really served:

```bash
    ls public/uploads
    curl -I http://localhost:8000/api/uploads/month_9_2026/admin-storage-test/<uuid>.webp
    ```

A `200` means the mount is right. A `404` with the file present on disk means the
    `publicPath` and the mount disagree.
  </Step>
</Steps>

## Options [#options]

The default `publicPath` is `/api/uploads` because the API mounts everything under
`/api`, and `mountPath` strips that prefix back off so the route is registered
once, in the right place. Change `publicPath` and the descriptor follows it - but
keep it under `/api`: `stripPrefix` is the whole `publicPath`, so a `publicPath`
outside the API's own base path strips nothing and every file answers `404`.

## Gotchas [#gotchas]

<Callout type="warn" title="Not durable on serverless">
  Serverless platforms give every instance an ephemeral filesystem. Files
  written by one instance are invisible to the next and gone after a deploy,
  which shows up as images that worked this morning. Use [S3 or
  R2](/docs/dev/storage/s3-r2) or [Supabase Storage](/docs/dev/storage/supabase)
  there.
</Callout>

<Callout type="warn" title="Relative to the process, not to the file">
  The upload path is resolved from `process.cwd()`, so starting the API from a
  different directory points it at a different `public/uploads`. Old files do
  not disappear - the keys on the `core_files` rows still name them - but the
  new directory answers the requests.
</Callout>

<Callout type="warn" title="A missing file is a 404, not a repaired row">
  Deleting a file from disk by hand leaves its `core_files` row behind, and the
  AdminCP Files table will keep listing it with a broken preview. Delete through
  the table (or `deleteFile`) so the row and the bytes go together.
</Callout>

<Callout type="info" title="Back it up like a database">
  `public/uploads` is state. A container that recreates its filesystem on deploy
  loses every upload, and no `core_files` row can bring the bytes back. Mount a
  volume, or move to a cloud adapter.
</Callout>

## Next [#next]

# AWS S3 / Cloudflare R2

`@vitnode/s3` puts your uploads in an object store instead of on the API's disk,
which is what you want the moment there is more than one server - or no server
you own at all. R2 is S3-compatible, so the same adapter covers both: you add an
`endpoint` and you are done.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { S3StorageAdapter } from '@vitnode/s3' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    // [!code ++:6]
    adapter: S3StorageAdapter({
      bucket: process.env.S3_BUCKET,
      region: process.env.S3_REGION,
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    }),
  },
})
```

## Set it up [#set-it-up]

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']">
      <Tab value="bun">
        ```bash
        bun i @vitnode/s3
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @vitnode/s3
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @vitnode/s3
        ```
      </Tab>
    </Tabs>

It is a runtime dependency of the app that serves your API, not a dev
    dependency - the API imports it on every boot. `@aws-sdk/client-s3` comes with
    it, so there is nothing else to add.
  </Step>

<Step>
    ### Create the bucket and an access key [#create-the-bucket-and-an-access-key]

<Tabs groupId="s3-provider" items="['AWS S3', 'Cloudflare R2']">
      <Tab value="AWS S3">
        1. In the S3 console, create a bucket and note its **name** and **region**.
        2. In IAM, create a user (or role) with `s3:PutObject`, `s3:DeleteObject` and
           `s3:GetObject` on `arn:aws:s3:::your-bucket/*`, then create an access key.
        3. Copy the **Access key ID** and **Secret access key**. The secret is shown once.

{/* Image prompt: The AWS IAM console "Retrieve access key" screen after creating an access key, with the Access key ID visible and the Secret access key revealed but the characters replaced by asterisks, plus the Download .csv button. Light theme, 1440x900. */}
      </Tab>

<Tab value="Cloudflare R2">
        1. In the Cloudflare dashboard, open **R2** and create a bucket.
        2. Open **Manage R2 API Tokens** and create a token with **Object Read & Write**
           for that bucket.
        3. Copy the **Access Key ID**, the **Secret Access Key** and the
           **S3 API endpoint** - the last one looks like
           `https://<account_id>.r2.cloudflarestorage.com` and is what makes R2 work
           through an S3 client.

{/* Image prompt: The Cloudflare dashboard R2 API token success screen, showing the "Use the following credentials" panel with Access Key ID, Secret Access Key (masked) and the S3 API endpoint URL https://<account_id>.r2.cloudflarestorage.com clearly readable. Dark theme, 1440x900. */}
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Put the credentials in the environment [#put-the-credentials-in-the-environment]

The adapter takes plain arguments, so the names are yours to choose. These are
    the ones VitNode's own `.env.example` uses, and the ones the snippets here read:

```bash title=".env"
    S3_BUCKET=your-bucket
    S3_REGION=us-east-1
    S3_ACCESS_KEY_ID=your_access_key_id
    S3_SECRET_ACCESS_KEY=your_secret_access_key
    # Cloudflare R2 only
    # S3_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
    # Optional CDN or custom domain in front of the bucket
    # S3_PUBLIC_URL=https://cdn.example.com
    ```
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

For AWS S3, the four values above are all it needs:

```ts title="src/vitnode.api.config.ts"
    import { S3StorageAdapter } from '@vitnode/s3' // [!code ++]
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      storage: {
        // [!code ++:6]
        adapter: S3StorageAdapter({
          bucket: process.env.S3_BUCKET,
          region: process.env.S3_REGION,
          accessKeyId: process.env.S3_ACCESS_KEY_ID,
          secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        }),
      },
    })
    ```

For Cloudflare R2, keep the same adapter and add the endpoint - the region stays
    at its `auto` default:

```ts title="src/vitnode.api.config.ts"
    adapter: S3StorageAdapter({
      bucket: process.env.S3_BUCKET,
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
      endpoint: process.env.S3_ENDPOINT, // [!code ++:2]
      publicUrl: process.env.S3_PUBLIC_URL,
    }),
    ```
  </Step>

<Step>
    ### Upload a test file [#upload-a-test-file]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`).
    The Storage card now reads active; click **Test storage** and upload an image.

On success the dialog says the image is stored in your adapter, and the object
    appears in the bucket under `month_{month}_{year}/admin-storage-test/…`. On
    failure, check the API logs: the SDK's own error names the cause, and the two
    usual suspects are a bucket in a different region than `S3_REGION` and a token
    without write permission.

The file also shows up in **AdminCP → Core → System → Files** with its size and
    pixel dimensions - proof that both the object and its `core_files` row were
    written.
  </Step>
</Steps>

## How the public URL is built [#how-the-public-url-is-built]

`getUrl` never asks the provider - it builds a string, and the first rule that
applies wins:

| Condition          | Resulting URL                                      |
| :----------------- | :------------------------------------------------- |
| `publicUrl` is set | `{publicUrl}/{key}`                                |
| `endpoint` is set  | `{endpoint}/{bucket}/{key}`                        |
| Neither            | `https://{bucket}.s3.{region}.amazonaws.com/{key}` |

For R2 that middle row matters: the S3 API endpoint is **not** a public read
domain, so a bucket without a public `r2.dev` or custom domain gives URLs that
only your credentials can read. Enable public access on the bucket and put that
hostname in `publicUrl`.

{/* Image prompt: The Cloudflare R2 bucket "Settings" tab with the "Public Development URL" / custom domain section expanded, showing the r2.dev hostname enabled and a "Connect Domain" button beside it. Dark theme, 1440x900. */}

## Options [#options]

## Gotchas [#gotchas]

<Callout type="warn" title="Misconfiguration surfaces on the first upload, not at boot">
  The S3 client is created lazily, so a missing bucket or key throws `Missing S3
    configuration` the first time somebody uploads - not when the server starts.
  The Integrations card only knows an adapter is *registered*. Run **Test
  storage** after any credential change.
</Callout>

<Callout type="warn" title="A private bucket breaks previews and downloads">
  VitNode serves files by URL, and the built-in download routes fetch that URL
  server-side before re-streaming it. If neither the bucket nor `publicUrl` is
  publicly readable, thumbnails never load and both download routes turn the
  refused fetch into a `404`. Front the bucket with CloudFront, an R2 custom
  domain, or make it public.
</Callout>

<Callout type="warn" title="A provider error reaches the browser as a 500">
  The adapter lets the SDK's own error propagate, and it is not an
  `HTTPException` - so a denied `PutObject` or a bucket in the wrong region
  answers `500`, with the useful sentence in the API log rather than in the
  uploader. Catch it in your route if the person uploading deserves better than
  "something went wrong".
</Callout>

<Callout type="info" title="Objects are overwritten, never appended">
  Keys contain a UUID, so a collision is not a practical concern - but a
  `PutObject` to an existing key replaces it. If you enable versioning on the
  bucket, remember that `deleteFile` removes the current version only; lifecycle
  rules are how old versions actually go away.
</Callout>

## Next [#next]

# Supabase Storage

`@vitnode/supabase-storage` puts your uploads in a bucket on your Supabase
project. If Supabase is already your database, this is the shortest path off the
local disk: no IAM policy, no endpoint, three values and you are done.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { SupabaseStorageAdapter } from '@vitnode/supabase-storage' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    // [!code ++:5]
    adapter: SupabaseStorageAdapter({
      url: process.env.SUPABASE_URL,
      secretKey: process.env.SUPABASE_SECRET_KEY,
      bucket: process.env.SUPABASE_STORAGE_BUCKET,
    }),
  },
})
```

## Set it up [#set-it-up]

<Steps>
  <Step>
    ### Install the adapter [#install-the-adapter]

<Tabs groupId="package-manager" items="['bun', 'pnpm', 'npm']">
      <Tab value="bun">
        ```bash
        bun i @vitnode/supabase-storage
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm i @vitnode/supabase-storage
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm i @vitnode/supabase-storage
        ```
      </Tab>
    </Tabs>

A runtime dependency of the app that serves your API, not a dev dependency - the
    API imports it on every boot. `@supabase/storage-js` comes with it, so there is
    nothing else to add.
  </Step>

<Step>
    ### Create the bucket [#create-the-bucket]

In the Supabase dashboard, open **Storage → Buckets → New bucket**, give it a
    name and turn **Public bucket** on. Public is not optional here for anything a
    visitor has to see: VitNode serves files by URL, and so do the built-in download
    routes - see [the private-bucket gotcha](#gotchas) below.

{/* Image prompt: The Supabase dashboard "New bucket" panel open over the Storage → Buckets list, with a bucket name typed in, the "Public bucket" toggle switched on, and the collapsed "Additional configuration" section showing file size limit and allowed MIME types. Dark theme, 1440x900. */}

Leave the bucket's own **file size limit** and **allowed MIME types** generous
    and enforce your real limits in your route with `maxBytes` and
    `allowedMimeTypes` - the bucket rejects a file with a Supabase error, your route
    rejects it with a sentence somebody can act on.
  </Step>

<Step>
    ### Copy the secret key [#copy-the-secret-key]

Open **Project Settings → API Keys** and copy a **secret key** - the value
    starting `sb_secret_`. That is the modern replacement for the legacy
    `service_role` key; a still-valid legacy key works too, because the adapter sends
    whatever you give it verbatim as the `apikey` and `Authorization: Bearer` header.

{/* Image prompt: The Supabase dashboard Project Settings → API Keys page, showing the publishable key in full and a secret key row with its value masked behind a "Reveal" control and a copy button. Light theme, 1440x900. */}

<Callout type="error" title="A secret key is a server-only key">
      It bypasses row level security, which is exactly why the API can write to the
      bucket. Never put it in client code, a `VITE_*` variable or anything else that
      reaches a browser: a secret key that ships to a visitor is a secret key you
      have to rotate.
    </Callout>
  </Step>

<Step>
    ### Put the credentials in the environment [#put-the-credentials-in-the-environment]

The adapter takes plain arguments, so the names are yours. These are the ones the
    API configs in this repository read, and the ones the snippets here use:

```bash title=".env"
    SUPABASE_URL=https://your-project.supabase.co
    SUPABASE_SECRET_KEY=sb_secret_...
    SUPABASE_STORAGE_BUCKET=your-bucket
    ```

Miss any one of the three and the first upload throws
    `Missing Supabase Storage configuration` - the client is created lazily, so a
    typo waits for a file rather than failing at boot.
  </Step>

<Step>
    ### Register the adapter [#register-the-adapter]

```ts title="src/vitnode.api.config.ts"
    import { SupabaseStorageAdapter } from '@vitnode/supabase-storage' // [!code ++]
    import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
      storage: {
        // [!code ++:5]
        adapter: SupabaseStorageAdapter({
          url: process.env.SUPABASE_URL,
          secretKey: process.env.SUPABASE_SECRET_KEY,
          bucket: process.env.SUPABASE_STORAGE_BUCKET,
        }),
        image: {
          quality: 85,
        },
      },
    })
    ```

That is the config `apps/web` in this repository actually runs, image pipeline
    included.
  </Step>

<Step>
    ### Upload a test file [#upload-a-test-file]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`).
    The Storage card now reads active; click **Test storage** and upload an image.

On success the object appears in the bucket under
    `month_{month}_{year}/admin-storage-test/…`, and the row appears in
    **AdminCP → Core → System → Files** with its size and pixel dimensions - proof
    that both the object and its `core_files` row were written. On failure the API log
    carries the Supabase error, and the two usual suspects are a bucket name that does
    not exist and a key pasted with its `sb_secret_` prefix trimmed.
  </Step>
</Steps>

## How the public URL is built [#how-the-public-url-is-built]

`getUrl` asks `@supabase/storage-js` for the bucket's public URL, which is a
string it builds rather than a request it makes:

```txt
{SUPABASE_URL}/storage/v1/object/public/{bucket}/{key}
```

So every file URL in the installation is that shape, and on a private bucket
Supabase's object API refuses it rather than serving the file - which is why
public matters more here than it looks.

## Options [#options]

## Gotchas [#gotchas]

<Callout type="warn" title="A private bucket breaks previews and downloads">
  `getUrl` returns the bucket's public URL, and the built-in download routes
  fetch that URL server-side before re-streaming it. On a private bucket
  Supabase refuses that URL, so the thumbnails in the AdminCP Files table never
  load and both download routes turn the refused fetch into a `404`. Make the
  bucket public, or front it with a CDN.
</Callout>

<Callout type="warn" title="The bucket's own limits answer with a 500">
  A bucket configured with a file size limit or an allowed-MIME-type list
  rejects the upload inside Supabase, and that error is not an `HTTPException` -
  so it reaches the browser as a `500` with the useful sentence in the API log.
  Set `maxBytes` and `allowedMimeTypes` on your `upload()` call so the refusal
  happens in VitNode, where the message is written for a person.
</Callout>

<Callout type="info" title="Uploads upsert">
  The adapter uploads with `upsert: true`, so writing to an existing key
  replaces it instead of failing. Keys carry a UUID, so this is not a collision
  risk - it is what makes a retried upload idempotent rather than a duplicate.
</Callout>

## Next [#next]

# Swagger

VitNode's API is built on [`@hono/zod-openapi`](https://hono.dev/examples/zod-openapi),
so the Zod schemas a route declares are its documentation. Nothing is written
twice and nothing can drift: if the schema changes, the spec changes, and the
request that no longer matches it is rejected.

## Quick start [#quick-start]

Start the dev server and open Swagger UI in a browser:

| App shape        | Swagger UI                                                             |
| ---------------- | ---------------------------------------------------------------------- |
| **Single App**   | [http://localhost:3000/api/swagger](http://localhost:3000/api/swagger) |
| **Monorepo App** | [http://localhost:8000/api/swagger](http://localhost:8000/api/swagger) |
| **Only API**     | [http://localhost:8000/api/swagger](http://localhost:8000/api/swagger) |

Whichever origin serves `/api/*` serves the UI, because it is a route on the
same Hono app. The raw document is one path deeper, at `/api/swagger/doc` -
OpenAPI 3.0.0, titled `VitNode API`, versioned with the `@vitnode/core` release
you have installed. Point any OpenAPI tool at that URL.

{/* Image prompt: A screenshot of Swagger UI at http://localhost:3000/api/swagger for the VitNode API - the "VitNode API" title bar at the top, and below it collapsed tag groups reading "(Core) - Users", "(Core) - Admin / Users", "(Core) - Admin / Debug" and "(Example) - Content / Articles", with the first group expanded to show a GET and a POST operation. Light theme, 1440x900. */}

Every path reads `/api/{pluginId}/{module}/{route}`, which is why core's session
endpoint is `/api/@vitnode/core/users/session`. That is not a Swagger
convention - it is how the app is mounted, and
[Architecture](/docs/dev/architecture) walks the whole request path.

## Where the spec comes from [#where-the-spec-comes-from]

You never register anything with Swagger. Four steps in the API's own build
produce the document as a side effect:

| Step             | What it contributes                                                                |
| ---------------- | ---------------------------------------------------------------------------------- |
| `buildRoute`     | The operation: method, path, `request` and `responses` schemas, `description`.     |
| `buildModule`    | Registers it on the module's Hono app, and names the group it lands in.            |
| `buildApiPlugin` | Mounts each module under its name and collects the group list for the document.    |
| `VitNodeAPI`     | Mounts each plugin under its `pluginId` and serves `/swagger` plus `/swagger/doc`. |

## Put a plugin route in the spec [#put-a-plugin-route-in-the-spec]

There is no extra work - the same three files that make a route reachable make
it documented. What you control is how good the documentation is.

<Steps>
  <Step>
    ### Describe the route as you build it [#describe-the-route-as-you-build-it]

`description` becomes the operation's summary line, and every schema field can
    carry an `example`. This is the whole difference between a spec people use and a
    spec people ignore:

```ts title="src/api/modules/orders/routes/show.route.ts"
    import { z } from '@hono/zod-openapi'
    import { buildRoute } from '@vitnode/core/api/lib/route'

import { CONFIG_PLUGIN } from '@/const'

export const showOrderRoute = buildRoute({
      pluginId: CONFIG_PLUGIN.pluginId,
      route: {
        method: 'get',
        path: '/{id}',
        description: 'Get one order by id', // [!code ++]
        request: {
          params: z.object({
            id: z.string().openapi({ example: '1' }), // [!code ++]
          }),
        },
        responses: {
          200: {
            content: {
              'application/json': {
                schema: z.object({ id: z.string(), total: z.number() }),
              },
            },
            description: 'The order',
          },
        },
      },
      handler: async (c) => c.json({ id: '1', total: 42 }),
    })
    ```
  </Step>

<Step>
    ### Register it in a module [#register-it-in-a-module]

```ts title="src/api/modules/orders/orders.module.ts"
    import { buildModule } from '@vitnode/core/api/lib/module'

import { CONFIG_PLUGIN } from '@/const'
    import { showOrderRoute } from './routes/show.route'

export const ordersModule = buildModule({
      pluginId: CONFIG_PLUGIN.pluginId,
      name: 'orders', // [!code ++]
      routes: [showOrderRoute], // [!code ++]
    })
    ```

The `name` is the second half of the group heading, so pick the word you want to
    read in the sidebar.
  </Step>

<Step>
    ### Mount the module in the plugin [#mount-the-module-in-the-plugin]

```ts title="src/config.api.ts"
    import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { ordersModule } from '@/api/modules/orders/orders.module'
    import { CONFIG_PLUGIN } from '@/const'

export const shopApiPlugin = () =>
      buildApiPlugin({
        pluginId: CONFIG_PLUGIN.pluginId,
        modules: [ordersModule], // [!code ++]
      })
    ```
  </Step>

<Step>
    ### Reload the UI [#reload-the-ui]

Restart the dev server and refresh `/api/swagger`. A new group is at the bottom
    of the list - **(Shop) - Orders** - with `GET /api/@acme/shop/orders/{id}` in
    it, and "Try it out" sends a real request with your cookies attached.
  </Step>
</Steps>

## Grouping [#grouping]

Swagger has exactly one grouping mechanism - the tag - so the tag carries both
halves of "where does this endpoint live". The plugin comes from `pluginId` with
its scope dropped and title-cased, the module from the `name` you gave
`buildModule`:

```ts
buildModule({
  pluginId: '@vitnode/core', // (Core)
  name: 'users', // - Users
  routes: [sessionRoute],
})
```

A nested module is named after its whole chain, so `(Core) - Admin / Users`
stays a separate group from the top-level `(Core) - Users`:

```ts
buildModule({
  pluginId: '@vitnode/core',
  name: 'admin',
  routes: [],
  modules: [usersAdminModule], // (Core) - Admin / Users
})
```

The chain matters because module names repeat across the tree - core has a
`users` module and an `admin/users` one, plus `cron`, `queue` and `files` twice
over. A leaf-only tag would merge the public and admin halves of each into one
group.

Groups appear in the order the plugins declared their modules, with core first.

<Callout title="Your own tags are kept">
  A route may add `tags` of its own. They survive, after the generated one - so
  the same operation can also show up under a tag you name yourself.
</Callout>

## Gotchas [#gotchas]

<Callout type="warn" title="Swagger has no login, and it is mounted in production">
  `/api/swagger` and `/api/swagger/doc` are registered unconditionally, before
  the session middleware, and neither checks anything. Anyone who can reach your
  API can read every route it serves, including the admin ones. Deny both paths
  at your reverse proxy if that is not what you want - see
  [Self-hosted](/docs/dev/deployments/self-hosted).
</Callout>

<Callout type="warn" title="A response with no content widens res.json() to unknown">
  The [fetcher](/docs/dev/fetcher) infers its return type from the same
  `responses` block Swagger reads. Declare a status with no `content` - a bare
  `401: { description: 'Unauthorized' }` - and there is no response format to
  infer from, so `await res.json()` resolves to `unknown` at every call site.
  Give every documented response a `content` schema, or leave the status
  undeclared and let `HTTPException` produce it.
</Callout>

<Callout type="info" title="The spec is per-installation, not per-package">
  The document lists the plugins **this** app has in its
  `vitnode.api.config.ts`. Install a plugin and its groups appear; remove it and
  they are gone. So `/api/swagger` is a truthful inventory of one deployment
  rather than a catalogue of what VitNode can do.
</Callout>

## Next [#next]

# WebSocket

VitNode provides a unified, multiplexed WebSocket connection at `/api/ws`. Browsers share a single connection across tabs via a Web Lock leader election, authenticated by session cookies.

## Quick start [#quick-start]

### 1. Send User Notification [#1-send-user-notification]

Push real-time notifications to any signed-in user from any Hono route or service:

```ts
import { notificationsChannel } from "@vitnode/core/ws/notifications"

// [!code ++:6]
c.get("realtime").sendToUser(userId, notificationsChannel, {
  title: "New Comment",
  description: "Alex commented on your post.",
  type: "info",
})
```

The user receives an immediate `sonner` toast in all open tabs across devices.

***

### 2. Broadcast to Everyone [#2-broadcast-to-everyone]

Broadcast live updates to all connected visitors:

```ts
c.get("realtime").broadcast(myChannel, {
  count: 142,
})
```

***

## Define a Custom Channel [#define-a-custom-channel]

Create typed channels in your plugin:

```ts title="plugins/chat/src/ws/chat.channel.ts"
import { defineWebSocketChannel } from "@vitnode/core/ws"
import { z } from "zod"

export interface MessagePayload {
  roomId: string
  message: string
  senderId: number
}

// [!code ++:6]
export const chatChannel = defineWebSocketChannel<MessagePayload>({
  id: "chat_room_messages",
  schema: z.object({
    roomId: z.string(),
    message: z.string(),
    senderId: z.number(),
  }),
})
```

***

## Client-Side Consumption [#client-side-consumption]

Listen for incoming channel messages with `useWebSocketChannel`:

```tsx title="plugins/chat/src/views/chat-room.tsx"
import { useWebSocketChannel } from "@vitnode/core/hooks/use-websocket-channel"
import { chatChannel } from "../ws/chat.channel"

export const ChatRoom = ({ roomId }: { roomId: string }) => {
  const [messages, setMessages] = React.useState<string[]>([])

// [!code ++:6]
  useWebSocketChannel(chatChannel, (payload) => {
    if (payload.roomId === roomId) {
      setMessages((prev) => [...prev, payload.message])
    }
  })

return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>{msg}</p>
      ))}
    </div>
  )
}
```

***

## Architectural Highlights [#architectural-highlights]

* **Single Connection**: Only one `/api/ws` socket is opened per client. All features share it via message multiplexing.
* **Tab Leader Election**: When a user opens multiple tabs, a Web Lock elects one leader tab to hold the socket, distributing messages across tabs via `BroadcastChannel`.
* **Automatic Reconnect**: Backoff retry automatically re-establishes dropped connections within seconds.

## Learn More [#learn-more]

# Roles

In VitNode, a role groups users together for display styles (e.g. colored username badges) and staff permission grants.

## Quick start [#quick-start]

Resolve a user's complete set of role IDs (primary + secondary) on the API:

```ts
import { getUserRoleIds } from "@vitnode/core/api/lib/check-staff-permission"

const user = c.get("user")
// [!code ++:1]
const roleIds = user ? await getUserRoleIds(c, user) : []
```

***

## Seeded Default Roles [#seeded-default-roles]

VitNode automatically seeds four protected system roles upon installation:

<Callout type="info" title="First Account is Root">
  The first user to register during site initialization is automatically assigned the Administrator role.
</Callout>

***

## Role Model Attributes [#role-model-attributes]

`core_roles` defines group styling and properties:

* `color`: CSS color string (e.g. `#ff0000`, `hsl(210, 100%, 50%)`) applied to member usernames across the UI.
* `root`: When `true`, user bypasses all staff permission checks.
* `default`: The role automatically assigned to newly registered members.
* `guest`: Reserved for unauthenticated requests.

***

## Primary vs Secondary Roles [#primary-vs-secondary-roles]

Every user has exactly one **primary role** (stored in `core_users.roleId`). Users may additionally hold multiple **secondary roles** (stored in `core_users_secondary_roles`), inheriting combined staff permissions across all assigned groups.

***

## AdminCP Role Management [#admincp-role-management]

{/* Image prompt: VitNode AdminCP Roles management page at /admin/core/roles. Table showing custom roles with colored name badges, member counts, and action buttons to reorder, edit, or delete roles. Dark theme, 1440x900. */}

Create, color-code, and organize user groups under **Core → Roles** (`/admin/core/roles`).

## Learn More [#learn-more]

# Staff Permissions

VitNode separates staff into two groups: **Moderators** and **Administrators**. Plugins declare granular permissions that restrict what staff members or roles can access.

<Callout type="warn" title="New Admin APIs Require Staff Permissions">
  Routes under `/admin/` are automatically gated by the admin session, but you must declare an explicit staff permission tuple to restrict specific actions.
</Callout>

## Quick start [#quick-start]

### 1. Declare Permissions in Plugin API Config [#1-declare-permissions-in-plugin-api-config]

```ts title="plugins/blog/src/config.api.ts"
import { buildApiPlugin } from "@vitnode/core/api/lib/plugin"

export const blogApiPlugin = () =>
  buildApiPlugin({
    pluginId: "@vitnode/blog",
    // [!code ++:8]
    permissionStaff: {
      admin: {
        posts: [
          "can_view",
          { permission: "can_delete", dependsOn: ["can_view"] },
        ],
      },
    },
  })
```

### 2. Enforce on Hono Route [#2-enforce-on-hono-route]

Add `adminStaffPermission` to automatically return `403 Forbidden` if unauthorized:

```ts title="plugins/blog/src/api/modules/admin/posts/routes/delete.route.ts"
export const deletePostRoute = buildRoute({
  pluginId: "@vitnode/blog",
  // [!code ++:1]
  adminStaffPermission: { module: "posts", permission: "can_delete" },
  route: {
    method: "delete",
    path: "/{id}",
    responses: {
      200: { description: "Post deleted" },
      403: { description: "Forbidden" },
    },
  },
  handler: async (c) => {
    // Execution only reaches here if caller has permission
  },
})
```

***

## Add Permissions Step by Step [#add-permissions-step-by-step]

<Steps>
  <Step>
    ### 1. Define Translation Labels [#1-define-translation-labels]

Add flat labels in `plugins/blog/src/locales/en.json`:

```json title="plugins/blog/src/locales/en.json"
    {
      "@vitnode/blog": { "title": "Blog" },
      "@vitnode/blog:posts": "Articles",
      "@vitnode/blog:posts:can_view": "View articles list",
      "@vitnode/blog:posts:can_create": "Create articles",
      "@vitnode/blog:posts:can_delete": "Delete articles"
    }
    ```
  </Step>

<Step>
    ### 2. Gate UI Controls [#2-gate-ui-controls]

Hide buttons or panels from unauthorized staff with `AdminStaffPermissionGate`:

```tsx title="plugins/blog/src/admin/delete-post-button.tsx"
    import { AdminStaffPermissionGate } from "@vitnode/core/components/staff-permission/provider"

export const DeletePostButton = () => (
      // [!code ++:5]
      <AdminStaffPermissionGate
        plugin="@vitnode/blog"
        module="posts"
        permission="can_delete"
      >
        <button className="text-destructive">Delete</button>
      </AdminStaffPermissionGate>
    )
    ```

Or check permissions imperatively with `useStaffPermissions`:

```tsx
    const { hasPermission } = useStaffPermissions()
    const canDelete = hasPermission({ module: "posts", permission: "can_delete" })
    ```
  </Step>

<Step>
    ### 3. Gate Sidebar Navigation [#3-gate-sidebar-navigation]

Attach `permission` to navigation items in `src/admin/nav.tsx`:

```tsx title="plugins/blog/src/admin/nav.tsx"
    export const adminNav: PluginAdminNav = {
      nav: [
        {
          id: "posts",
          href: "/admin/blog/posts",
          icon: <ListIcon />,
          permission: { module: "posts", permission: "can_view" }, // [!code ++]
        },
      ],
    }
    ```
  </Step>

<Step>
    ### 4. Grant Permissions in AdminCP [#4-grant-permissions-in-admincp]

{/* Image prompt: VitNode AdminCP staff permission editor at /admin/core/staff/admins. Left sidebar lists plugins (Core, Blog). Right panel displays permission toggles grouped by module ("Articles") with dependency locks and an Unrestricted / Restricted level switcher. Dark theme, 1440x900. */}

1. Go to **Staff → Administrators** (`/admin/core/staff/admins`).
    2. Select a User or Role and click **Edit**.
    3. Choose **Restricted**, toggle the desired permissions, and click **Save Changes**.
  </Step>
</Steps>

***

## Permission Dependencies [#permission-dependencies]

When a permission depends on another (e.g. creating posts requires viewing them), declare `dependsOn`:

```ts title="plugins/blog/src/config.api.ts"
permissionStaff: {
  admin: {
    posts: [
      "can_view",
      { permission: "can_create", dependsOn: ["can_view"] },
      { permission: "can_delete", dependsOn: ["can_view"] },
    ],
  },
}
```

The AdminCP permission editor automatically disables child toggles until prerequisites are checked.

## Learn More [#learn-more]

# Users & Sessions

Every incoming request in VitNode resolves the session cookie prior to route execution. The current user profile is accessible on both server handlers and frontend components.

## Quick start [#quick-start]

### 1. In Hono API Routes [#1-in-hono-api-routes]

Access the authenticated user via `c.get("user")`:

```ts title="plugins/blog/src/api/modules/posts/routes/create.route.ts"
import { HTTPException } from "hono/http-exception"

handler: async (c) => {
  // [!code ++:4]
  const user = c.get("user")
  if (!user) {
    throw new HTTPException(401, { message: "Unauthorized" })
  }

const newPost = await createPost({ authorId: user.id })
  return c.json(newPost)
}
```

***

### 2. In Frontend Components [#2-in-frontend-components]

Consume the user session via TanStack Query:

```tsx title="src/components/user-greeting.tsx"
import { useQuery } from "@tanstack/react-query"
import { sessionQueryOptions } from "@vitnode/core/tanstack/auth"

export const UserGreeting = () => {
  // [!code ++:2]
  const { data } = useQuery(sessionQueryOptions())
  const user = data?.user

if (!user) return <span>Welcome, guest!</span>

return <span>Welcome back, {user.name}!</span>
}
```

***

## User Model (`core_users`) [#user-model-core_users]

The canonical user table contains:

***

## AdminCP User Management [#admincp-user-management]

{/* Image prompt: VitNode AdminCP User management screen at /admin/core/users. Data table listing registered accounts with columns for Avatar, Name, Email, Primary Role badge, Status, and action dropdowns (Edit, Ban, Delete). Dark theme, 1440x900. */}

Administrators can view, edit, ban, and assign roles to users at **Core → Users** (`/admin/core/users`).

## Learn More [#learn-more]

# Install the Blog Plugin

`@vitnode/blog` is the Content Engine reference plugin. It brings articles,
categories, editorial screens, revisions, public delivery data, and search
indexing—without making your host app impersonate a blog plugin.

<Steps>
  <Step>
    ### Install the package [#install-the-package]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Install @vitnode/blog">
      <Tab value="bun">
        ```bash
        bun add @vitnode/blog@canary
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm add @vitnode/blog@canary
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm install @vitnode/blog@canary
        ```
      </Tab>
    </Tabs>
  </Step>

<Step>
    ### Enable the API plugin [#enable-the-api-plugin]

For a Single App, edit `apps/web/src/vitnode.api.config.ts`; a split deployment
    uses the same change in `apps/api/src/vitnode.api.config.ts`.

```ts title="apps/web/src/vitnode.api.config.ts"
    import { blogApiPlugin } from '@vitnode/blog/config.api' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
      plugins: [
        blogApiPlugin(), // [!code ++]
      ],
    })
    ```
  </Step>

<Step>
    ### Enable the web plugin and its messages [#enable-the-web-plugin-and-its-messages]

The host registers the lightweight plugin identity and static locale loaders:

```ts title="apps/web/src/locales/packages.ts"
    import { CONFIG_PLUGIN as BLOG } from '@vitnode/blog/const' // [!code ++]

export const packageMessages = {
      // [!code ++:3]
      [BLOG.pluginId]: {
        en: async () => await import('@vitnode/blog/locales/en.json'),
      },
    }
    ```

```ts title="apps/web/src/vitnode.config.ts"
    import { blogPlugin } from '@vitnode/blog/config' // [!code ++]

export const vitNodeConfig = buildConfig({
      plugins: [
        blogPlugin(), // [!code ++]
      ],
    })
    ```
  </Step>

<Step>
    ### Migrate, run, and publish [#migrate-run-and-publish]

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Prepare and start the blog">
      <Tab value="bun">
        ```bash
        bun run db:migrate
        bun dev
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm db:migrate
        pnpm dev
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm run db:migrate
        npm run dev
        ```
      </Tab>
    </Tabs>

In AdminCP, create a category at **Blog → Categories**, then publish an article
    at **Blog → Articles**. The plugin owns the editorial work so the host can stay
    boringly reliable.

{/* Image prompt: VitNode AdminCP Blog article management screen. Show categories in a side navigation, article list with draft and published badges, and a prominent “Create article” button. Dark theme, 1440x900. */}
  </Step>
</Steps>

## Deliver it from a plugin [#deliver-it-from-a-plugin]

Build the public article page in a plugin too, then use the Content Engine
delivery guide for loaders and SEO. That keeps the data model and its public URL
together.

<Cards>
  <Card icon="<RouteIcon />" title="Build your first plugin" description="Create the plugin that will own your site’s public blog route." href="/docs/guides/first-plugin" />

<Card icon="<CompassIcon />" title="Content delivery and SEO" description="Add plugin routes, redirects, canonical metadata, and sitemaps." href="/docs/dev/content-engine/content-delivery-and-seo" />

<Card icon="<LayoutDashboardIcon />" title="Admin Control Panel" description="Extend the staff experience with pages, navigation, and widgets." href="/docs/dev/plugins/admin" />
</Cards>

# Build Your First Plugin

This tutorial builds `@acme/site-notes`, a tiny plugin with a page at
`/site-notes`. Start from a VitNode workspace with Turborepo enabled; it gives
the plugin generator a shared home.

<Steps>
  <Step>
    ### Generate `@acme/site-notes` [#generate-acmesite-notes]

Run the generator from the workspace root and enter `@acme/site-notes` when it
    asks for a name:

<Tabs groupId="package-manager" items="["bun", "pnpm", "npm"]" label="Generate the plugin">
      <Tab value="bun">
        ```bash
        bun create vitnode-app@canary --plugin
        ```
      </Tab>

<Tab value="pnpm">
        ```bash
        pnpm create vitnode-app@canary --plugin
        ```
      </Tab>

<Tab value="npm">
        ```bash
        npm create vitnode-app@canary -- --plugin
        ```
      </Tab>
    </Tabs>

The result has `routes.ts`, `pages/home-page.tsx`, `locales/en.json`, and
    `config.tsx`. The CLI adds a workspace dependency but leaves activation to you,
    which makes installed plugins predictable.
  </Step>

<Step>
    ### Claim the page URL [#claim-the-page-url]

The route tree belongs to the plugin and is all the host needs to discover a
    route. `lazy` names the page module without importing it, so the page gets a
    chunk of its own:

```ts title="plugins/site-notes/src/routes.ts"
    import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
      // [!code ++:3]
      page('/site-notes', {
        component: lazy(() => import('./pages/home-page')),
      }),
    ])
    ```
  </Step>

<Step>
    ### Render a translated page [#render-a-translated-page]

Edit the generated route module. It stays framework-neutral and is lazily
    loaded by the TanStack Start host:

```tsx title="plugins/site-notes/src/pages/home-page.tsx"
    import { useTranslations } from 'use-intl'

const HomePage = () => {
      const t = useTranslations('@acme/site-notes') // [!code ++]

return (
        <div className="container mx-auto flex max-w-2xl flex-col gap-4 p-4">
          <h2 className="text-2xl font-semibold">{t('home.title')}</h2>
          <p className="text-muted-foreground">{t('home.desc')}</p>
        </div>
      )
    }

export default HomePage
    ```

```json title="plugins/site-notes/src/locales/en.json"
    {
      "@acme/site-notes": {
        "home": {
          "title": "Site notes",
          "desc": "This page ships from a plugin. Neat, right?"
        }
      }
    }
    ```
  </Step>

<Step>
    ### Enable it in the host [#enable-it-in-the-host]

The package must be in the host's `plugins` array. This is the only composition
    step; routes and pages remain inside `plugins/site-notes`:

```ts title="apps/web/src/vitnode.config.ts"
    import { siteNotesPlugin } from '@acme/site-notes/config' // [!code ++]

export const vitNodeConfig = buildConfig({
      plugins: [
        siteNotesPlugin(), // [!code ++]
      ],
    })
    ```
  </Step>

<Step>
    ### Run and inspect the result [#run-and-inspect-the-result]

Visit `http://localhost:3000/site-notes`.

{/* Image prompt: Tutorial verification screenshot for a VitNode app at /site-notes. Show a simple “Site notes” page, browser address bar, and a compact visual hint that it is loaded from a plugin package. Dark theme, 1440x900. */}
  </Step>
</Steps>

## Grow the same plugin [#grow-the-same-plugin]

<Cards>
  <Card icon="<RouteIcon />" title="Add route behavior" description="Use loaders, metadata, breadcrumbs, and parameters in the plugin route." href="/docs/dev/routing" />

<Card icon="<NetworkIcon />" title="Add an API module" description="Keep typed Hono routes beside the page that needs them." href="/docs/dev/plugins/api/modules" />

<Card icon="<LayoutDashboardIcon />" title="Add AdminCP tools" description="Give staff a plugin-owned screen or dashboard widget." href="/docs/dev/plugins/admin" />
</Cards>

# Guides

Guides are the shortest trustworthy path from an empty workspace to a feature
you can click. They start in a plugin on purpose: reusable code deserves a
proper home before it acquires a spare drawer in the host app.

<Cards>
  <Card icon="<PackagePlusIcon />" href="/docs/guides/first-plugin" title="Build your first plugin" description="Generate a plugin, add a page, register it, and visit its route." />

<Card icon="<NotebookPenIcon />" href="/docs/guides/blog" title="Install the Blog plugin" description="Enable @vitnode/blog, publish an article in AdminCP, and deliver it from a plugin." />
</Cards>

Already have an app? Great. If not, [Getting started](/docs/dev/setup) prepares
the database and your first AdminCP account. Need a precise option instead of a
walkthrough? The [development reference](/docs/dev) is close by, wearing its
tiny lab coat.

# Accordion

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from '@vitnode/core/components/ui/accordion'
```

```tsx
<Accordion className="w-full" defaultValue={['item-1']}>
  <AccordionItem value="item-1">
    <AccordionTrigger>Product Information</AccordionTrigger>
    <AccordionContent className="flex flex-col gap-4 text-balance">
      <p>
        Our flagship product combines cutting-edge technology with sleek design.
        Built with premium materials, it offers unparalleled performance and
        reliability.
      </p>
      <p>
        Key features include advanced processing capabilities, and an intuitive
        user interface designed for both beginners and experts.
      </p>
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="item-2">
    <AccordionTrigger>Shipping Details</AccordionTrigger>
    <AccordionContent className="flex flex-col gap-4 text-balance">
      <p>
        We offer worldwide shipping through trusted courier partners. Standard
        delivery takes 3-5 business days, while express shipping ensures
        delivery within 1-2 business days.
      </p>
      <p>
        All orders are carefully packaged and fully insured. Track your shipment
        in real-time through our dedicated tracking portal.
      </p>
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="item-3">
    <AccordionTrigger>Return Policy</AccordionTrigger>
    <AccordionContent className="flex flex-col gap-4 text-balance">
      <p>
        We stand behind our products with a comprehensive 30-day return policy.
        If you're not completely satisfied, simply return the item in its
        original condition.
      </p>
      <p>
        Our hassle-free return process includes free return shipping and full
        refunds processed within 48 hours of receiving the returned item.
      </p>
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

## API Reference [#api-reference]

[Base UI - Accordion](https://base-ui.com/react/components/accordion)

# Alert Dialog

A modal dialog that interrupts the user with important content and expects a
response. Unlike a regular [Dialog](/docs/ui/dialog), it can only be dismissed
through one of its actions.

## Preview [#preview]

## Usage [#usage]

```ts
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@vitnode/core/components/ui/alert-dialog'
import { Button } from '@vitnode/core/components/ui/button'
```

```tsx
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="outline">Show Dialog</Button>} />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## API Reference [#api-reference]

[Base UI - Alert Dialog](https://base-ui.com/react/components/alert-dialog#api-reference)

# Alert

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from '@vitnode/core/components/ui/alert'
import { TriangleAlertIcon } from 'lucide-react'
```

```tsx
<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>Something needs your attention.</AlertDescription>
</Alert>
```

An optional leading icon is picked up automatically - render any icon as the
first child and the layout aligns it with the title and description.

## Variants [#variants]

* `default` - neutral, informational messages.
* `warning` - a non-blocking caution the user should act on (amber).
* `destructive` - an error or a failed action (red).

## Dismissible [#dismissible]

Wrap a control in `AlertAction` to pin it to the top-right corner, e.g. a close
button. The alert reserves space for it automatically.

```tsx
import { AlertAction } from '@vitnode/core/components/ui/alert'
import { Button } from '@vitnode/core/components/ui/button'
import { XIcon } from 'lucide-react'

;<Alert variant="warning">
  <TriangleAlertIcon />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>Something needs your attention.</AlertDescription>
  <AlertAction>
    <Button aria-label="Dismiss" size="icon" variant="ghost">
      <XIcon />
    </Button>
  </AlertAction>
</Alert>
```

## Props [#props]

# Auto Form

`AutoForm` creates interactive, accessible forms automatically from a Zod schema. It handles validation, error messages, and submits without boilerplate.

## Preview [#preview]

***

## Quick start [#quick-start]

Define a Zod validation schema and pass it with field descriptors to `<AutoForm />`:

```tsx
import { AutoForm } from "@vitnode/core/components/form/auto-form"
import { AutoFormInput } from "@vitnode/core/components/form/fields/input"
import { AutoFormSelect } from "@vitnode/core/components/form/fields/select"
import { AutoFormTextarea } from "@vitnode/core/components/form/fields/textarea"
import { toast } from "sonner"
import { z } from "zod"

const formSchema = z.object({
  username: z.string().min(3, "Username must be at least 3 characters"),
  email: z.string().email("Invalid email address"),
  role: z.enum(["admin", "editor", "viewer"]).default("editor"),
  bio: z.string().optional(),
})

export const UserForm = () => {
  return (
    // [!code ++:24]
    <AutoForm
      formSchema={formSchema}
      onSubmit={async (values) => {
        await saveUser(values)
        toast.success("User saved successfully!")
      }}
      fields={[
        {
          id: "username",
          component: (props) => <AutoFormInput {...props} label="Username" />,
        },
        {
          id: "email",
          component: (props) => <AutoFormInput {...props} label="Email Address" />,
        },
        {
          id: "role",
          component: (props) => (
            <AutoFormSelect
              {...props}
              label="Role"
              labels={[
                { value: "admin", label: "Admin" },
                { value: "editor", label: "Editor" },
                { value: "viewer", label: "Viewer" },
              ]}
            />
          ),
        },
        {
          id: "bio",
          component: (props) => <AutoFormTextarea {...props} label="Bio" />,
        },
      ]}
    />
  )
}
```

***

## Supported Field Components [#supported-field-components]

***

## Common Features [#common-features]

### 1. Dynamic Lists (`AutoFormArray`) [#1-dynamic-lists-autoformarray]

Render dynamic, repeatable sets of fields:

```tsx
const formSchema = z.object({
  links: z.array(
    z.object({
      label: z.string().min(1),
      url: z.string().url(),
    })
  ),
})

// In fields configuration:
{
  id: "links",
  component: (props) => (
    <AutoFormArray
      {...props}
      label="External Links"
      fields={[
        { id: "label", component: (p) => <AutoFormInput {...p} label="Label" /> },
        { id: "url", component: (p) => <AutoFormInput {...p} label="URL" /> },
      ]}
    />
  ),
}
```

### 2. Labels, Descriptions & Placeholders [#2-labels-descriptions--placeholders]

Configure input helpers directly in the component:

```tsx
{
  id: "username",
  component: (props) => (
    <AutoFormInput
      {...props}
      label="Username"
      placeholder="e.g. jdoe"
      description="Your unique public identifier."
    />
  ),
}
```

***

## `<AutoForm>` Props [#autoform-props]

<TypeTable
  type="{
  formSchema: {
    description: "Zod object schema describing validation rules.",
    required: true,
    type: "ZodObject",
  },
  fields: {
    description: "Array of field configurations matching schema keys.",
    required: true,
    type: "AutoFormField[]",
  },
  onSubmit: {
    description: "Async callback executed upon valid form submission.",
    required: true,
    type: "(values: z.infer<T>) => Promise<void>",
  },
  defaultValues: {
    description: "Initial form values.",
    type: "Partial<z.infer<T>>",
  },
  submitButtonProps: {
    description: "Custom props passed to the submit button (e.g. label).",
    type: "ButtonProps",
  },
}"
/>

## Learn More [#learn-more]

# Badge

## Preview [#preview]

## Usage [#usage]

```ts
import { Home } from 'lucide-react'
import { Badge } from '@vitnode/core/components/ui/badge'
```

```tsx
<Badge>
  <Home /> Default
</Badge>
```

## Props [#props]

# Button

A [Base UI](https://base-ui.com/react/components/button) button with VitNode's
variants painted on top. It handles the two things a hand-rolled `<button>`
always gets wrong: a pending state that does not resize the button, and being
something other than a `<button>` when it needs to be a link.

## Preview [#preview]

## Quick start [#quick-start]

```tsx
import { Button } from '@vitnode/core/components/ui/button'
import { HomeIcon } from 'lucide-react'

;<Button>
  <HomeIcon />
  Default
</Button>
```

Icons are children, not a prop. The button spaces them, sizes them to match its
own size, and marks them `pointer-events-none` so a click always lands on the
button.

## Variants [#variants]

| `variant`     | Use it for                                                  |
| ------------- | ----------------------------------------------------------- |
| `default`     | The one action you want clicked on this screen              |
| `secondary`   | A second action of equal weight                             |
| `outline`     | Toolbars, filters, anything sitting on a card               |
| `ghost`       | Icon buttons and row actions, where a border would be noise |
| `link`        | A button that must look like prose                          |
| `destructive` | Delete, ban, revoke - tinted rather than filled, on purpose |

## Sizes [#sizes]

| `size`    | Height  | Notes                          |
| --------- | ------- | ------------------------------ |
| `sm`      | 2rem    |                                |
| `default` | 2.25rem |                                |
| `lg`      | 2.5rem  |                                |
| `icon-xs` | 1.5rem  | Square. `aria-label` required. |
| `icon-sm` | 2rem    | Square. `aria-label` required. |
| `icon`    | 2.25rem | Square. `aria-label` required. |
| `icon-lg` | 2.5rem  | Square. `aria-label` required. |

```tsx
<Button aria-label="Delete" size="icon" variant="destructive">
  <Trash2Icon />
</Button>
```

## Loading [#loading]

Pass `isLoading` and the label fades out while a spinner springs in over it. The
button is disabled for the duration and keeps its width, so nothing around it
moves:

```tsx
const [isLoading, setIsLoading] = React.useState(false)

;<Button isLoading={isLoading} onClick={save}>
  Save changes
</Button>
```

While it is `true` and the button has no `aria-label` of its own, the accessible
name becomes the translated "loading" string - so a spinner in place of a label
still announces itself. An `aria-label` you pass is spread on last and keeps
winning, in both states.

## Render as a link [#render-as-a-link]

A button that navigates should be an `<a>`, not a `<button>` with an `onClick`.
Use `render` to swap the element and `nativeButton={false}` to tell Base UI what
it is now:

```tsx
import { Link } from '@tanstack/react-router' // [!code ++]
import { Button } from '@vitnode/core/components/ui/button'

;<Button nativeButton={false} render={<Link to="/settings" />}>
  Settings
</Button>
```

Inside a shared VitNode view that takes a `LinkComponent`, pass that instead -
it is the same thing with `href` in place of `to`, and it is what lets one
component render correctly in a host that mounts VitNode under a path prefix:

```tsx
<Button nativeButton={false} render={<LinkComponent href="/settings" />}>
  Settings
</Button>
```

## Props [#props]

Everything [Base UI's Button](https://base-ui.com/react/components/button#api-reference)
accepts, plus:

<TypeTable
  type="{
  variant: {
    description: 'The visual weight of the button.',
    type: 'default | secondary | outline | ghost | link | destructive',
    default: 'default',
  },
  size: {
    description:
      'The size of the button. The four icon sizes are square and make aria-label required.',
    type: 'default | sm | lg | icon | icon-xs | icon-sm | icon-lg',
    default: 'default',
  },
  isLoading: {
    description:
      'Fades the label out, springs a spinner in over it, and disables the button. It also names the button "loading" for a screen reader, unless you pass an `aria-label` of your own.',
    type: 'boolean',
  },
  disabled: {
    description:
      'Disables the button. It is applied after `isLoading`, so an explicit `disabled={false}` keeps a loading button clickable - leave it off and let `isLoading` do the disabling.',
    type: 'boolean',
  },
  focusableWhenDisabled: {
    description:
      'Keeps a disabled button in the tab order, so a screen reader can still find it and read why it is disabled.',
    type: 'boolean',
    default: 'false',
  },
  render: {
    description:
      'What to render instead of the default `<button>` - a router link, most often. An element is cloned with the button props; a function receives them.',
    type: 'ReactElement | ((props, state) => ReactElement)',
  },
  nativeButton: {
    description:
      'Whether the rendered element is a native button. Set it to false whenever `render` supplies something that is not one.',
    type: 'boolean',
    default: 'true',
  },
  className: {
    description:
      'Merged over the variant classes, so a token you set here wins.',
    type: 'string',
  },
}"
/>

## Gotchas [#gotchas]

<Callout type="warn" title="An icon-only button will not compile without a label">
  The props type is a union: choosing any of the four `icon*` sizes makes
  `aria-label` **required**. That is deliberate - an icon button has no text
  node, so without it the accessible name is empty - and it is `tsc` that stops
  you, not a lint rule you can suppress.
</Callout>

<Callout type="warn" title="`xs` is a stylesheet variant, not a prop">
  `buttonVariants` defines an `xs` size, but the component's props type does not
  accept it: `<Button size="xs">` is a type error. Use `sm`, or call
  `buttonVariants({ size: 'xs' })` yourself if you need that geometry on
  something else.
</Callout>

<Callout type="warn" title="`render` without `nativeButton={false}`">
  Base UI keeps applying native-button semantics - so an anchor gets attributes
  a `<button>` would want and behaves subtly wrong for keyboard users. If the
  rendered element is not a `<button>`, say so.
</Callout>

## Next [#next]

# Card

## Preview [#preview]

## Usage [#usage]

```tsx
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@vitnode/core/components/ui/card'
```

```tsx
<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card Description</CardDescription>
  </CardHeader>
  <CardContent>
    This is the content of the card. You can put any content here.
  </CardContent>
  <CardFooter>
    <CardAction>Action Button</CardAction>
  </CardFooter>
</Card>
```

# Checkbox

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod'
    import { AutoForm } from '@vitnode/core/components/form/auto-form'
    import { AutoFormCheckbox } from '@vitnode/core/components/form/fields/checkbox'
    ```

```ts
    const formSchema = z.object({
      acceptTerms: z.boolean().refine((val) => val, {
        message: 'You must accept the terms and conditions',
      }),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'acceptTerms',
          component: (props) => (
            <AutoFormCheckbox
              {...props}
              label="I accept the terms and conditions"
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { Checkbox } from '@vitnode/core/components/ui/checkbox';
    ```

```tsx
    <Checkbox onCheckedChange={onCheckedChange} checked={checked} />
    ```
  </Tab>
</Tabs>

## Props [#props]

## API Reference [#api-reference]

[Base UI - Checkbox](https://base-ui.com/react/components/checkbox#api-reference)

# Color

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from "zod";
    import { AutoForm } from "@vitnode/core/components/form/auto-form";
    import { AutoFormColor } from "@vitnode/core/components/form/fields/color";
    ```

```ts
    const formSchema = z.object({
      color: z.string().default('hsl(240, 80%, 60%)'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'color',
          component: (props) => <AutoFormColor {...props} label="Color" />,
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { ColorPicker } from "@vitnode/core/components/ui/color-picker";
    ```

The `ColorPicker` is controlled - pass the current `value` (an HSL string) and
    handle `onChange`, which receives the new HSL string:

```tsx
    const [color, setColor] = useState('hsl(240, 80%, 60%)')

;<ColorPicker value={color} onChange={setColor} />
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Output format">
  Dragging the picker produces an HSL string such as `hsl(240, 80%, 60%)`. Below
  the picker is a text field where you can paste or type a color in any CSS
  format - hex (`#22c55e`), `rgb(...)`, `hsl(...)`, or a named color - so the
  stored value is whatever you enter. The picker is powered by
  [react-colorful](https://github.com/omgovich/react-colorful) and is
  lazy-loaded, so its bundle only ships once the popover is opened.
</Callout>

## Props [#props]

# Colors

<Callout type="warn" title="This documentation is under construction! 🚧">
  We're working hard to bring you the best documentation experience.
</Callout>

# Combobox

A combobox provides a searchable dropdown interface, ideal for long lists such as categories, users, or tags.

## Preview [#preview]

***

## 1. Static Options (AutoForm) [#1-static-options-autoform]

Use `AutoFormCombobox` inside an `AutoForm` with a predefined set of choices:

```tsx
import { AutoForm } from "@vitnode/core/components/form/auto-form"
import { AutoFormCombobox } from "@vitnode/core/components/form/fields/combobox"
import { z } from "zod"

const formSchema = z.object({
  category: z.enum(["tech", "news", "design"]),
})

export const CategorySelect = () => (
  // [!code ++:16]
  <AutoForm
    formSchema={formSchema}
    fields={[
      {
        id: "category",
        component: (props) => (
          <AutoFormCombobox
            {...props}
            label="Category"
            labels={[
              { value: "tech", label: "Technology" },
              { value: "news", label: "News & Releases" },
              { value: "design", label: "UI / UX Design" },
            ]}
          />
        ),
      },
    ]}
  />
)
```

***

## 2. Async API Search [#2-async-api-search]

For large datasets, query the API dynamically as the user types:

```tsx
import { AutoFormCombobox } from "@vitnode/core/components/form/fields/combobox"
import { fetcherClient } from "@vitnode/core/lib/fetcher-client"

const searchUsers = async ({ search }: { search: string }) => {
  const res = await fetcherClient(usersModule, {
    method: "get",
    module: "users",
    path: "/search",
    args: { query: { search } },
  })
  const json = await res.json()
  return json.map((u) => ({ value: String(u.id), label: u.name }))
}

// In field configuration:
{
  id: "author",
  component: (props) => (
    // [!code ++:7]
    <AutoFormCombobox
      {...props}
      label="Author"
      fetchData={searchUsers}
      searchPlaceholder="Search users by name..."
    />
  ),
}
```

***

## 3. Multiple Selection [#3-multiple-selection]

Allow picking multiple options by specifying `multiple: true`:

```tsx
{
  id: "tags",
  component: (props) => (
    <AutoFormCombobox
      {...props}
      multiple // [!code ++]
      label="Tags"
      labels={[
        { value: "react", label: "React" },
        { value: "tanstack", label: "TanStack" },
      ]}
    />
  ),
}
```

***

## `AutoFormCombobox` Props [#autoformcombobox-props]

<TypeTable
  type="{
  labels: {
    description: "Array of static { label, value } options.",
    type: "{ label: string; value: string }[]",
  },
  fetchData: {
    description: "Async search function returning options based on user typing.",
    type: "({ search: string }) => Promise<{ label: string; value: string }[]>",
  },
  multiple: {
    default: "false",
    description: "Enable multi-option badge selection.",
    type: "boolean",
  },
  searchPlaceholder: {
    default: "'Search...'",
    description: "Placeholder text shown in the search input.",
    type: "string",
  },
}"
/>

## Learn More [#learn-more]

# Confirm Action Alert Dialog

The Confirm Action Alert Dialog is a specialized dialog component built on top of the [Alert Dialog](/docs/ui/alert-dialog) that provides a consistent way to confirm potentially destructive or irreversible actions before they're executed.

It's particularly useful for:

* Deleting items (e.g., categories, posts, users)
* Performing actions that cannot be undone (e.g., clearing data, resetting settings)
* Confirming critical operations (e.g., account deletion, data migration)
* Any action where user confirmation is necessary to prevent accidental execution

## Preview [#preview]

## Usage [#usage]

```tsx
import { ConfirmActionAlertDialog } from '@vitnode/core/components/confirm-action/confirm-action-alert-dialog'
import { Button } from '@vitnode/core/components/ui/button'
```

```tsx
<ConfirmActionAlertDialog
  onSubmit={async ({ onClose }) => {
    const result = await deleteCategoryApi(id)

if (result?.error) {
      toast.error(tGlobal('errors.title'), {
        description: tGlobal('errors.internal_server_error'),
      })
      return // Keep dialog open on error
    }

toast.success(t('success'), {
      description: title,
    })
    onClose() // Close dialog on success
  }}
>
  <Button variant="destructive">Delete Category</Button>
</ConfirmActionAlertDialog>
```

## Props [#props]

<TypeTable
  type="{
  children: {
    description:
      'The trigger element that opens the dialog. This should be a button or clickable element.',
    type: 'ReactNode',
    required: true,
  },
  onSubmit: {
    description:
      'Function called when the user confirms the action. Receives an object with `onClose` callback.',
    type: '(params: { onClose: () => void }) => Promise<void>',
    required: true,
  },
  title: {
    description:
      'Custom title for the dialog. Defaults to translated "Are you sure?"',
    type: 'string',
    default: 'Are you sure?',
  },
  description: {
    description:
      'Custom description explaining what will happen when the action is confirmed.',
    type: 'ReactNode',
    default: 'This action cannot be undone.',
  },
  textSubmit: {
    description:
      'Custom text for the submit button. Defaults to translated "Confirm".',
    type: 'string',
    default: 'Confirm',
  },
}"
/>

# Data Table

`ContentDataTable` is the core data table component powering VitNode AdminCP lists. Every user interaction - page navigation, column sorting, search queries, and filters - writes directly to the URL query string, making table state fully bookmarkable and shareable.

## Preview [#preview]

***

## Quick start [#quick-start]

Render the table inside a `DataTableNavigationProvider`:

```tsx title="plugins/members/src/views/members-table.tsx"
import type { ColumnDef } from '@vitnode/core/components/table/data-table-content'
import { ContentDataTable } from '@vitnode/core/components/table/content'
import { DataTableNavigationProvider } from '@vitnode/core/components/table/provider'

interface Member {
  id: number
  name: string
  email: string
  role: string
}

const columns: ColumnDef<Member>[] = [
  { accessorKey: 'name', header: 'Name', enableSorting: true },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'role', header: 'Role' },
]

interface MembersSearch {
  cursor?: string
}

interface MembersTableProps {
  data: Member[]
  navigate: (options: { search: MembersSearch }) => Promise<void>
  search: MembersSearch
}

export const MembersTable = ({ data, navigate, search }: MembersTableProps) => {
  return (
    // [!code ++:13]
    <DataTableNavigationProvider navigate={navigate} search={search}>
      <ContentDataTable
        id="members-table"
        columns={columns}
        data={data}
        order={{
          defaultOrder: { column: 'name', order: 'asc' },
        }}
        search={{ placeholder: 'Search members...' }}
      />
    </DataTableNavigationProvider>
  )
}
```

***

## Plugin Route Integration [#plugin-route-integration]

Give an AdminCP route to the plugin, then pass its typed `search` and `navigate`
props into the table. The table remains reusable and the host stays out of it.

```tsx title="plugins/members/src/pages/admin-members-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

import { MembersTable } from '../views/members-table'

interface MembersSearch {
  cursor?: string
}

export const route = definePluginRoute({
  parseSearch: (input) => {
    const search = input as Record<string, unknown>
    return {
      cursor: typeof search.cursor === 'string' ? search.cursor : undefined,
    }
  },
  load: async ({ search }) => await fetchMembers(search),
})

const AdminMembersPage = ({
  loaderData,
  navigate,
  search,
}: PluginRoutePageProps<Member[], MembersSearch>) => (
  <MembersTable data={loaderData} navigate={navigate} search={search} />
)

export default AdminMembersPage
```

***

## Filters [#filters]

Add static or asynchronous dropdown filters to the table toolbar:

```tsx
<ContentDataTable
  id="members-table"
  columns={columns}
  data={data}
  // [!code ++:12]
  filters={[
    {
      id: 'role',
      title: 'Role',
      options: [
        { label: 'Admin', value: 'admin' },
        { label: 'Member', value: 'member' },
      ],
    },
  ]}
/>
```

***

## Bulk Selection & Actions [#bulk-selection--actions]

Enable row checkboxes and execute bulk operations with `useDataTableSelection`:

```tsx
import { useDataTableSelection } from '@vitnode/core/components/table/hooks/use-data-table-selection'

export const BulkActionsToolbar = () => {
  const { selectedRows, resetSelection } = useDataTableSelection()

if (!selectedRows.length) return null

return (
    <div className="flex items-center gap-2 p-2 bg-muted rounded-md">
      <span>{selectedRows.length} selected</span>
      <button onClick={() => deleteSelected(selectedRows)}>Delete</button>
    </div>
  )
}
```

***

## `ContentDataTable` Props [#contentdatatable-props]

<TypeTable
  type="{
  id: {
    description: 'Unique identifier used to isolate table state.',
    required: true,
    type: 'string',
  },
  columns: {
    description: 'TanStack Table column definitions.',
    required: true,
    type: 'ColumnDef<TData, TValue>[]',
  },
  data: {
    description: 'Paginated payload containing edges and pageInfo.',
    required: true,
    type: '{ edges: TData[]; pageInfo: PageInfo }',
  },
  search: {
    description: 'Search input configuration ({ placeholder }).',
    type: '{ placeholder?: string }',
  },
  filters: {
    description: 'Array of toolbar filter descriptors.',
    type: 'DataTableFilter[]',
  },
  order: {
    description: 'Default sort column and direction.',
    type: "{ defaultOrder?: { column: string; order: 'asc' | 'desc' } }",
  },
  defaultPageSize: {
    default: '10',
    description: 'Rows per page when not specified in URL.',
    type: 'number',
  },
}"
/>

## Learn More [#learn-more]

# Dialog

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@vitnode/core/components/ui/dialog'
```

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline">Open</Button>} />
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Are you absolutely sure?</DialogTitle>
      <DialogDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose render={<Button variant="outline">Cancel</Button>} />
      <Button variant="destructive">Yes, delete account</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## API Reference [#api-reference]

[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)

# Drawer

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@vitnode/core/components/ui/drawer'
```

```tsx
<Drawer>
  <DrawerTrigger>Open</DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Are you absolutely sure?</DrawerTitle>
      <DrawerDescription>This action cannot be undone.</DrawerDescription>
    </DrawerHeader>

<DrawerFooter>
      <Button>Submit</Button>
      <DrawerClose asChild>
        <Button variant="outline">Cancel</Button>
      </DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

## Documentation [#documentation]

[Vaul - Documentation](https://vaul.emilkowal.ski/getting-started)

# Dropdown Menu

## Preview [#preview]

## Usage [#usage]

```ts
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from '@vitnode/core/components/ui/dropdown-menu'
```

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
    Open
  </DropdownMenuTrigger>
  <DropdownMenuContent className="w-56" align="start">
    <DropdownMenuLabel>My Account</DropdownMenuLabel>
    <DropdownMenuGroup>
      <DropdownMenuItem>
        Profile
        <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
      </DropdownMenuItem>
      <DropdownMenuItem>
        Billing
        <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
      </DropdownMenuItem>
      <DropdownMenuItem>
        Settings
        <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
      </DropdownMenuItem>
      <DropdownMenuItem>
        Keyboard shortcuts
        <DropdownMenuShortcut>⌘K</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuGroup>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuSub>
        <DropdownMenuSubTrigger>Invite users</DropdownMenuSubTrigger>
        <DropdownMenuSubContent>
          <DropdownMenuItem>Email</DropdownMenuItem>
          <DropdownMenuItem>Message</DropdownMenuItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem>More...</DropdownMenuItem>
        </DropdownMenuSubContent>
      </DropdownMenuSub>
      <DropdownMenuItem>
        New Team
        <DropdownMenuShortcut>⌘+T</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuItem>GitHub</DropdownMenuItem>
    <DropdownMenuItem>Support</DropdownMenuItem>
    <DropdownMenuItem disabled>API</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      Log out
      <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## API Reference [#api-reference]

[Base UI - Menu](https://base-ui.com/react/components/menu#api-reference)

# Editor

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod'
    import { AutoForm } from '@vitnode/core/components/form/auto-form'
    import { AutoFormEditor } from '@vitnode/core/components/form/fields/editor'
    ```

```ts
    const formSchema = z.object({
      content: z
        .string()
        .min(1, 'Content is required')
        .default('<p>Write your content here...</p>'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'content',
          component: (props) => (
            <AutoFormEditor
              {...props}
              description="Rich text content powered by the Editor."
              label="Content"
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { Editor } from '@vitnode/core/components/ui/editor'
    ```

The `Editor` is uncontrolled by default - pass `value` as the initial HTML and
    listen for changes with `onChange`, which receives the current HTML string:

```tsx
    const [content, setContent] = useState('<p>Hello World! 🌎️</p>')

;<Editor value={content} onChange={setContent} />
    ```
  </Tab>
</Tabs>

## Multi-language [#multi-language]

Set the `multiLang` prop to edit the content in every enabled language. A
language **select** (shown only when more than one language is enabled) switches
which language you are editing - it does **not** change the app-wide locale,
only the content inside this editor.

The value becomes an array matching the `core_languages_words` table:

```ts
;[
  { languageCode: 'en', value: '<p>Hello</p>' },
  { languageCode: 'pl', value: '<p>Cześć</p>' },
]
```

Declare the field with the `multiLangValueSchema` helper and enable `multiLang`:

```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'

const formSchema = z.object({
  content: multiLangValueSchema({ minLength: 1 }).min(1),
})
```

```tsx
{
  id: "content",
  component: props => <AutoFormEditor {...props} label="Content" multiLang />,
}
```

Persist the array on the backend with `saveLanguageWords`. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).

## Rendering Content [#rendering-content]

Use `EditorContent` to render the stored HTML as read-only content outside of
the editor (e.g. on a public page):

```ts
import { EditorContent } from '@vitnode/core/components/ui/editor-content'
```

```tsx
<EditorContent content="<h2>Title</h2><p>Hello World! 🌎️</p>" />
```

## Props [#props]

<TypeTable
  type="{
  value: {
    description: 'Initial HTML content rendered inside the editor.',
    type: 'string',
    default: '""',
  },
  onChange: {
    description:
      'Called on every change with the current content as an HTML string.',
    type: '(value: string) => void',
    default: '',
  },
  disableScroll: {
    description:
      'Disables the internal max-height scroll area so the editor grows with its content.',
    type: 'boolean',
    default: 'false',
  },
  className: {
    description: 'Additional classes applied to the editor wrapper.',
    type: 'string',
    default: '',
  },
  multiLang: {
    description:
      'Edit the content per language. The value becomes a { languageCode, value }[] array and a language select is shown when more than one language is enabled.',
    type: 'boolean',
    default: 'false',
  },
}"
/>

# useBeforeUnload

## Example [#example]

```tsx
import { useBeforeUnload } from '@vitnode/core/hooks/use-before-unload'
```

```tsx
export const CustomMessageExample = () => {
  const [isEditing, setIsEditing] = useState(false)

// [!code ++:4]
  useBeforeUnload(
    isEditing,
    'You have unsaved changes. Are you sure you want to leave?',
  )

return (
    <div>
      <button onClick={() => setIsEditing(true)}>Start editing</button>
      <p>Note: Modern browsers may not show the custom message</p>
    </div>
  )
}
```

# useMobile

## Example [#example]

```tsx
import { useIsMobile } from '@vitnode/core/hooks/use-mobile'
```

```tsx
import { useIsMobile } from '@vitnode/core/hooks/use-mobile'

export const ExampleComponent = () => {
  const isMobile = useIsMobile() // [!code ++]

return (
    <div>
      {isMobile ? (
        <p>You are using a mobile device.</p>
      ) : (
        <p>You are using a desktop device.</p>
      )}
    </div>
  )
}
```

# Hover Card

## Preview [#preview]

## Usage [#usage]

```ts
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from '@vitnode/core/components/ui/hover-card'
```

```tsx
<HoverCard>
  <HoverCardTrigger>Hover</HoverCardTrigger>
  <HoverCardContent>
    The React Framework - created and maintained by @vercel.
  </HoverCardContent>
</HoverCard>
```

## API Reference [#api-reference]

[Base UI - Preview Card](https://base-ui.com/react/components/preview-card#api-reference)

# UI Components Overview

VitNode provides an accessible component suite built on [Base UI](https://base-ui.com) and styled with Tailwind CSS in the shadcn `base-vega` design language.

## Quick start [#quick-start]

Import components directly from `@vitnode/core/components/ui/*`:

```tsx title="src/components/action-button.tsx"
import { Button } from "@vitnode/core/components/ui/button"
import { ArrowRightIcon } from "lucide-react"

export const ActionButton = () => (
  // [!code ++:4]
  <Button variant="default">
    Get Started
    <ArrowRightIcon className="size-4" />
  </Button>
)
```

No copy-pasting is required: all primitives and form components are exported ready-to-use from `@vitnode/core`.

***

## Component Layers [#component-layers]

| Layer             | Import Path                              | Examples                                              |
| :---------------- | :--------------------------------------- | :---------------------------------------------------- |
| **Primitives**    | `@vitnode/core/components/ui/*`          | `Button`, `Dialog`, `DropdownMenu`, `Card`, `Badge`   |
| **Form Inputs**   | `@vitnode/core/components/form/fields/*` | `AutoFormInput`, `AutoFormSelect`, `AutoFormCombobox` |
| **Complex Views** | `@vitnode/core/components/*`             | `AutoForm`, `ContentDataTable`                        |

***

## Design Tokens & Semantic Styling [#design-tokens--semantic-styling]

VitNode adheres strictly to semantic Tailwind tokens for dark/light mode parity:

* **Backgrounds**: `bg-background`, `bg-card`, `bg-muted`, `bg-popover`
* **Text & Foreground**: `text-foreground`, `text-muted-foreground`, `text-primary`
* **Borders & Rings**: `border-border`, `ring-ring`

<Callout type="info" title="Color Palette Convention">
  VitNode uses exactly 3-5 colors across the UI, avoiding prominent purple/violet styling in favor of modern, high-contrast semantic palettes.
</Callout>

## Key Components [#key-components]

# Input Group

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod';
    import { AutoForm } from '@vitnode/core/components/form/auto-form';
    import { AutoFormInput } from '@vitnode/core/components/form/fields/input';
    import { AutoFormTextarea } from '@vitnode/core/components/form/fields/textarea';
    import { InputGroupAddon, InputGroupText } from "@vitnode/core/components/ui/input-group";
    ```

```ts
    const formSchema = z.object({
      search: z.string().min(1, 'Search is required'),
      description: z
        .string()
        .max(500, 'Description must be less than 500 characters'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'search',
          component: (props) => (
            <AutoFormInput {...props} placeholder="Search..." label="Search">
              <InputGroupAddon>
                <Search />
              </InputGroupAddon>
              <InputGroupAddon align="inline-end">12 results</InputGroupAddon>
            </AutoFormInput>
          ),
        },
        {
          id: 'description',
          component: (props) => (
            <AutoFormTextarea
              {...props}
              className="min-h-24 resize-none"
              placeholder="I'm having an issue with the login button on mobile."
              rows={6}
            >
              <InputGroupAddon align="block-end">
                <InputGroupText className="tabular-nums">
                  {props.field.value?.toString().length ?? 0} of 500 characters
                </InputGroupText>
              </InputGroupAddon>
            </AutoFormTextarea>
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import {
      InputGroup,
      InputGroupAddon,
      InputGroupInput,
      InputGroupText,
      InputGroupTextarea,
    } from "@vitnode/core/components/ui/input-group";
    import { Search } from "lucide-react";
    ```

```tsx
    <div className="flex flex-col gap-8">
      <InputGroup className="max-w-xs">
        <InputGroupInput placeholder="Search..." />
        <InputGroupAddon>
          <Search />
        </InputGroupAddon>
        <InputGroupAddon align="inline-end">12 results</InputGroupAddon>
      </InputGroup>

<InputGroup>
        <InputGroupTextarea
          className="min-h-24 resize-none"
          placeholder="I'm having an issue with the login button on mobile."
          rows={6}
        />
        <InputGroupAddon align="block-end">
          <InputGroupText className="tabular-nums">
            0 of 500 characters
          </InputGroupText>
        </InputGroupAddon>
      </InputGroup>
    </div>
    ```
  </Tab>
</Tabs>

## API Reference [#api-reference]

[Shadcn UI - Input Group](https://ui.shadcn.com/docs/components/radix/input-group#api-reference)

# Input

## Preview [#preview]

## Usage [#usage]

```ts
    const formSchema = z.object({
      username: z.string().min(3, 'Username must be at least 3 characters'),
      email: z.email('Please enter a valid email address'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'username',
          component: (props) => (
            <AutoFormInput
              {...props}
              description="This is the username for your application. It should be unique and not shared with anyone."
              label="Username"
            />
          ),
        },
        {
          id: 'email',
          component: (props) => (
            <AutoFormInput
              {...props}
              description="We'll use this email to contact you."
              label="Email Address"
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { Input } from '@vitnode/core/components/ui/input';
    ```

```tsx
    <Input />
    ```
  </Tab>
</Tabs>

## Multi-language [#multi-language]

Set the `multiLang` prop to collect the value in every enabled language. The
field renders a language **select** (shown only when more than one language is
enabled) that switches which language you are editing - it does **not** change
the app-wide locale, only the value inside this input.

The value becomes an array matching the `core_languages_words` table, one entry
per language you edited:

```ts
;[
  { languageCode: 'en', value: 'Category' },
  { languageCode: 'pl', value: 'Kategoria' },
]
```

Declare the field with the `multiLangValueSchema` helper so the schema matches
the array shape (its `minLength` / `maxLength` apply to each language's value):

```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'

const formSchema = z.object({
  name: multiLangValueSchema({ minLength: 1, maxLength: 255 }).min(1),
})
```

```tsx
{
  id: "name",
  component: props => <AutoFormInput {...props} label="Name" multiLang />,
}
```

On the backend, persist the array with `saveLanguageWords` - it fills the
remaining `core_languages_words` columns. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).

## Props [#props]

# Nullable Number

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormNullableNumber } from '@vitnode/core/components/form/fields/nullable-number'
```

```ts
const formSchema = z.object({
  max_members: z.number().int().min(1).nullable().default(10),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'max_members',
      component: (props) => (
        <AutoFormNullableNumber
          {...props}
          label="Maximum members"
          toggleLabel="Unlimited"
        />
      ),
    },
  ]}
/>
```

<Callout type="info" title="Value shape">
  The field value is `number | null`. A number is whatever is typed in the
  input; `null` means the checkbox is checked and the input is disabled. Back it
  with a `z.number().nullable()` schema, and keep it optional or give it a
  `default` when the field can be
  [hidden](/docs/ui/auto-form#conditional-fields) so it never blocks submission.
  Unchecking the box restores the last number you entered.
</Callout>

## Adapting the labels [#adapting-the-labels]

The three label props are plain text, so the same field works for any domain -
an unlimited storage cap, a session that never expires, an uncapped rate limit,
and so on:

* `unitLabel` - shown right after the input (e.g. `kB`, `minutes`, `%`).
* `orLabel` - an optional connector rendered before the checkbox (e.g. `or`).
* `toggleLabel` - the checkbox label; checking it sets the value to `null`.

```tsx
<AutoFormNullableNumber
  {...props}
  label="Auto-logout"
  unitLabel="minutes"
  orLabel="or"
  toggleLabel="Never"
/>
```

Any other props (`min`, `max`, `step`, `placeholder`, …) are forwarded to the
underlying number input; validation constraints come from the Zod schema.

## Props [#props]

# Popover

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from '@vitnode/core/components/ui/popover'
```

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline">Open</Button>} />
  <PopoverContent>Place content for the popover here.</PopoverContent>
</Popover>
```

## API Reference [#api-reference]

[Base UI - Popover](https://base-ui.com/react/components/popover#api-reference)

# Progress

## Preview [#preview]

## Usage [#usage]

```ts
import { Progress } from '@vitnode/core/components/ui/progress'
```

```tsx
<Progress value={50} />
```

## API Reference [#api-reference]

[Base UI - Progress](https://base-ui.com/react/components/progress#api-reference)

# Radio Group

## Preview [#preview]

## Usage [#usage]

```ts
    const formSchema = z.object({
      options: z.enum(['option1', 'option2', 'option3']),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'options',
          component: (props) => (
            <AutoFormRadioGroup
              {...props}
              description="By checking this box, you agree to the terms and conditions."
              label="I agree to the terms and conditions"
              labels={[
                {
                  value: 'option1',
                  label: 'Option 1',
                  description: 'This is the description for option 1',
                },
                {
                  value: 'option2',
                  label: 'Option 2',
                },
                {
                  value: 'option3',
                  label: 'Option 3',
                  description: 'This is the description for option 3',
                  disabled: true,
                },
              ]}
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import {
      RadioGroup,
      RadioGroupItem,
    } from '@vitnode/core/components/ui/radio-group';
    import { Field, FieldLabel } from "@vitnode/core/components/ui/field"
    ```

```tsx
    <RadioGroup defaultValue="option-one">
      <Field orientation="horizontal">
        <RadioGroupItem value="option-one" id="option-one" />
        <FieldContent>
          <FieldLabel htmlFor="option-one">Option One</FieldLabel>
          <FieldDescription>
            This is the description for option one. It provides more information
            about the option.
          </FieldDescription>
        </FieldContent>
      </Field>

<Field orientation="horizontal">
        <RadioGroupItem value="option-two" id="option-two" />
        <FieldContent>
          <FieldLabel htmlFor="option-two">Option Two</FieldLabel>
        </FieldContent>
      </Field>

<Field orientation="horizontal" data-disabled>
        <RadioGroupItem value="option-three" id="option-three" disabled />
        <FieldContent>
          <FieldLabel htmlFor="option-three">Option Three</FieldLabel>
          <FieldDescription>
            This is the description for option three. It provides more information
            about the option.
          </FieldDescription>
        </FieldContent>
      </Field>
    </RadioGroup>
    ```
  </Tab>
</Tabs>

### variant="block" [#variantblock]

You can also use the `block` variant to display the radio buttons in a block style.

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'options',
      component: (props) => (
        <AutoFormRadioGroup
          {...props}
          description="By checking this box, you agree to the terms and conditions."
          label="I agree to the terms and conditions"
          // [!code ++]
          variant="block"
          labels={[
            {
              value: 'option1',
              label: 'Option 1',
              description: 'This is the description for option 1',
            },
            {
              value: 'option2',
              label: 'Option 2',
            },
            {
              value: 'option3',
              label: 'Option 3',
              description: 'This is the description for option 3',
              disabled: true,
            },
          ]}
        />
      ),
    },
  ]}
/>
```

## Props [#props]

## API Reference [#api-reference]

[Base UI - Radio Group](https://base-ui.com/react/components/radio#api-reference)

# Roles

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormRoles } from '@vitnode/core/components/form/fields/input-roles'
```

One component covers both shapes, because the difference is the value and
nothing else - the search, the colour, the language resolution and the empty
state are identical, and two copies is how they drift.

<Tabs items="['Single', 'Multiple']">
  <Tab value="Single">
    ```ts
    const formSchema = z.object({
      roleId: z.number(),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'roleId',
          component: (props) => (
            <AutoFormRoles
              {...props}
              description="One role, replaced each time you pick."
              label="Primary role"
              placeholder="Select a role"
            />
          ),
        },
      ]}
    />
    ```

The value is a single id, and picking again replaces it.
  </Tab>

<Tab value="Multiple">
    ```ts
    const formSchema = z.object({
      roleIds: z.array(z.number()).min(1),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'roleIds',
          component: (props) => (
            <AutoFormRoles
              {...props}
              label="Additional roles"
              multiple
              placeholder="Add a role"
            />
          ),
        },
      ]}
    />
    ```

The value is an array of ids. Chosen roles appear above the picker as removable
    chips, and the picker **appends** rather than replaces - picking one that is
    already chosen removes it, which is what the tick beside it in the list means.
  </Tab>
</Tabs>

Out of the box it searches the AdminCP roles list. The **guest** role is never
offered: it is the role a request has when it has no account, so it is not
something to assign to anybody.

## Editing an existing record [#editing-an-existing-record]

Same rule as [User](/docs/ui/user): the picker can only name ids it has seen, so
an edit form passes the roles it already knows about.

```tsx
<AutoFormRoles {...props} multiple label="Roles" selected={user.roles} />
```

## Keeping a role out of the list [#keeping-a-role-out-of-the-list]

`excludeIds` drops options another field already owns - a primary-role picker
and a secondary-role picker should not both offer the same one:

```tsx
<AutoFormRoles
  {...props}
  multiple
  excludeIds={[primaryRoleId]}
  label="Additional roles"
/>
```

## Names are resolved per reader [#names-are-resolved-per-reader]

A role carries one name per language. The field renders the active locale's, and
falls back to the first translation rather than to the id - a role with no
translation in your language is still a role somebody named:

```ts
import { roleOptionName } from '@vitnode/core/components/form/fields/input-roles'

roleOptionName(role, 'pl') // "Administrator PL", or the first name it has
```

## Props [#props]

| Prop                | Type                                       | Default            | What it does                                 |
| ------------------- | ------------------------------------------ | ------------------ | -------------------------------------------- |
| `multiple`          | `boolean`                                  | `false`            | `number[]` instead of `number`, with chips   |
| `label`             | `ReactNode`                                | -                  | Field label                                  |
| `description`       | `ReactNode`                                | -                  | Help text under the control                  |
| `placeholder`       | `string`                                   | `Select an option` | Shown while nothing is chosen                |
| `searchPlaceholder` | `string`                                   | `Search...`        | Placeholder inside the search box            |
| `selected`          | `RoleOption[]`                             | `[]`               | Roles the field opens on                     |
| `excludeIds`        | `number[]`                                 | `[]`               | Roles the picker must not offer              |
| `search`            | `(value: string) => Promise<RoleOption[]>` | AdminCP roles list | Replaces the lookup                          |
| `disabled`          | `boolean`                                  | `false`            | Blocks opening the picker and removing chips |

`RoleOption` is `{ id, color, name }`, where `name` is the raw
`{ languageCode, name }[]` - the server has no business deciding which language
the person clicking reads in.

## See also [#see-also]

* [User](/docs/ui/user) - the same idea for people.
* [Combobox](/docs/ui/combobox) - when the options are strings rather than records.

# Scroll Area

## Preview [#preview]

## Usage [#usage]

```ts
import { ScrollArea } from '@vitnode/core/components/ui/scroll-area'
import { Separator } from '@vitnode/core/components/ui/separator'
import React from 'react'
```

```tsx
const tags = Array.from({ length: 50 }).map(
  (_, i, a) => `v1.2.0-beta.${a.length - i}`,
)

export function ScrollAreaDemo() {
  return (
    <ScrollArea className="h-72 w-48 rounded-md border">
      <div className="p-4">
        <h4 className="mb-4 text-sm leading-none font-medium">Tags</h4>
        {tags.map((tag) => (
          <React.Fragment key={tag}>
            <div className="text-sm">{tag}</div>
            <Separator className="my-2" />
          </React.Fragment>
        ))}
      </div>
    </ScrollArea>
  )
}
```

## API Reference [#api-reference]

[Base UI - Scroll Area](https://base-ui.com/react/components/scroll-area#api-reference)

# Select

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod'
    import { AutoForm } from '@vitnode/core/components/form/auto-form'
    import { AutoFormSelect } from '@vitnode/core/components/form/fields/select'
    ```

```ts
    const formSchema = z.object({
      options: z.enum(['option1', 'option2', 'option3']).default('option1'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'options',
          component: (props) => (
            <AutoFormSelect
              {...props}
              description="Choose one of the options."
              label="Select an option"
              labels={[
                {
                  value: 'option1',
                  label: 'Option 1',
                },
                {
                  value: 'option2',
                  label: 'Option 2',
                },
                {
                  value: 'option3',
                  label: 'Option 3',
                },
              ]}
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import {
      Select,
      SelectContent,
      SelectItem,
      SelectTrigger,
      SelectValue,
    } from '@vitnode/core/components/ui/select';
    ```

```tsx
    const items = [
      { label: 'Option One', value: 'option-one' },
      { label: 'Option Two', value: 'option-two' },
    ]

;<Select items={items}>
      <SelectTrigger>
        <SelectValue placeholder="Select example" />
      </SelectTrigger>
      <SelectContent>
        {items.map((item) => (
          <SelectItem key={item.value} value={item.value}>
            {item.label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
    ```

> Pass an `items` array to `Select` so `SelectValue` can render the selected
    > option's label. Without it, the raw `value` is displayed instead.
  </Tab>
</Tabs>

## Props [#props]

## API Reference [#api-reference]

[Base UI - Select](https://base-ui.com/react/components/select#api-reference)

# Separator

## Preview [#preview]

## Usage [#usage]

```ts
import { Separator } from '@vitnode/core/components/ui/separator'
```

```tsx
<div>
  <div className="space-y-1">
    <h4 className="text-sm leading-none font-medium">Base UI</h4>
    <p className="text-muted-foreground text-sm">
      An open-source UI component library.
    </p>
  </div>
  <Separator className="my-4" />
  <div className="flex h-5 items-center space-x-4 text-sm">
    <div>Blog</div>
    <Separator orientation="vertical" />
    <div>Docs</div>
    <Separator orientation="vertical" />
    <div>Source</div>
  </div>
</div>
```

## API Reference [#api-reference]

[Base UI - Separator](https://base-ui.com/react/components/separator#api-reference)

# Sheet

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from '@vitnode/core/components/ui/sheet'
```

```tsx
<Sheet>
  <SheetTrigger render={<Button variant="outline">Open</Button>} />
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Are you absolutely sure?</SheetTitle>
      <SheetDescription>
        This action cannot be undone. This will permanently delete your account
        and remove your data from our servers.
      </SheetDescription>
    </SheetHeader>
    <SheetFooter>
      <Button variant="destructive">Yes, delete account</Button>
      <SheetClose render={<Button variant="outline">Cancel</Button>} />
    </SheetFooter>
  </SheetContent>
</Sheet>
```

## API Reference [#api-reference]

[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)

# Skeleton

## Preview [#preview]

## Usage [#usage]

```ts
import { Skeleton } from '@vitnode/core/components/ui/skeleton'
```

```tsx
<div className="flex items-center space-x-4">
  <Skeleton className="h-12 w-12 rounded-full" />
  <div className="space-y-2">
    <Skeleton className="h-4 w-[250px]" />
    <Skeleton className="h-4 w-[200px]" />
  </div>
</div>
```

# Sonner

## Preview [#preview]

## Usage [#usage]

```ts
import { toast } from 'sonner'
```

```ts
toast('Event has been created', {
  description: 'Sunday, December 03, 2023 at 9:00 AM',
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo'),
  },
})
```

```ts
toast.error('An error occurred.')
```

```ts
toast.success('Operation was successful.')
```

```ts
toast.info('Here is some information.')
```

```ts
toast.warning('This is a warning.')
```

## Documentation [#documentation]

[Sonner Documentation](https://sonner.emilkowal.ski/)

# Switch

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod'
    import { AutoForm } from '@vitnode/core/components/form/auto-form'
    import { AutoFormSwitch } from '@vitnode/core/components/form/fields/switch'
    ```

```ts
    const formSchema = z.object({
      acceptTerms: z.boolean().refine((val) => val, {
        message: 'You must accept the terms and conditions',
      }),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'acceptTerms',
          component: (props) => (
            <AutoFormSwitch {...props} label="I accept the terms and conditions" />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { Switch } from '@vitnode/core/components/ui/switch';
    ```

```tsx
    <Switch checked={value} onCheckedChange={onChange} />
    ```
  </Tab>
</Tabs>

## API Reference [#api-reference]

[Base UI - Switch](https://base-ui.com/react/components/switch#api-reference)

# Textarea

## Preview [#preview]

## Usage [#usage]

<Tabs items="['Auto Form', 'Manual']">
  <Tab value="Auto Form">
    ```ts
    import { z } from 'zod'
    import { AutoForm } from '@vitnode/core/components/form/auto-form'
    import { AutoFormTextarea } from '@vitnode/core/components/form/fields/textarea'
    ```

```ts
    const formSchema = z.object({
      desc: z.string().min(10, 'Description must be at least 10 characters'),
    })
    ```

```tsx
    <AutoForm
      formSchema={formSchema}
      fields={[
        {
          id: 'desc',
          component: (props) => (
            <AutoFormTextarea
              {...props}
              description="Write a short description of your application."
              placeholder="My application is..."
              label="Description"
            />
          ),
        },
      ]}
    />
    ```
  </Tab>

<Tab value="Manual">
    ```ts
    import { Textarea } from '@vitnode/core/components/ui/textarea';
    ```

```tsx
    <Textarea />
    ```
  </Tab>
</Tabs>

## Props [#props]

# Toggle Group

## Preview [#preview]

## Usage [#usage]

```ts
import { Bold, Italic, Underline } from 'lucide-react'

import {
  ToggleGroup,
  ToggleGroupItem,
} from '@vitnode/core/components/ui/toggle-group'
```

```tsx
<ToggleGroup variant="outline" multiple>
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <Italic className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="strikethrough" aria-label="Toggle strikethrough">
    <Underline className="size-4" />
  </ToggleGroupItem>
</ToggleGroup>
```

## API Reference [#api-reference]

[Base UI - Toggle Group](https://base-ui.com/react/components/toggle-group)

# Toggle

## Preview [#preview]

## Usage [#usage]

```ts
import { Bold } from 'lucide-react'

import { Toggle } from '@vitnode/core/components/ui/toggle'
```

```tsx
<Toggle aria-label="Toggle italic">
  <Bold className="size-4" />
</Toggle>
```

## API Reference [#api-reference]

[Base UI - Toggle](https://base-ui.com/react/components/toggle)

# Tooltip

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from '@vitnode/core/components/ui/tooltip'
```

```tsx
<Tooltip>
  <TooltipTrigger render={<Button variant="outline">Hover</Button>} />
  <TooltipContent>
    <p>Add to library</p>
  </TooltipContent>
</Tooltip>
```

### Faster Tooltips [#faster-tooltips]

If you don't need custom props for components like `TooltipTrigger` or `TooltipContent`, you can use the `TooltipWithContent` component to enable faster tooltips.

```ts
import { Button } from '@vitnode/core/components/ui/button'
import { TooltipWithContent } from '@vitnode/core/components/ui/tooltip'
import { PlayIcon } from 'lucide-react'
```

```tsx
<TooltipWithContent text="Now">
  <Button variant="ghost" size="icon" aria-label="Now">
    <PlayIcon />
  </Button>
</TooltipWithContent>
```

## API Reference [#api-reference]

[Base UI - Tooltip](https://base-ui.com/react/components/tooltip)

# Typography

<Callout type="warn" title="This documentation is under construction! 🚧">
  We're working hard to bring you the best documentation experience.
</Callout>

| Style     | Example                                                               |
| --------- | --------------------------------------------------------------------- |
| Heading 1 | <h1 className="text-4xl font-bold">Heading 1</h1>                     |
| Heading 2 | <h2 className="text-3xl font-semibold">Heading 2</h2>                 |
| Heading 3 | <h3 className="text-2xl font-medium">Heading 3</h3>                   |
| Paragraph | <p className="text-base">This is a paragraph with base text size.</p> |

# User

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormUser } from '@vitnode/core/components/form/fields/input-users'
```

The value is the **user id**, so the schema is a plain number and the payload
needs no unwrapping:

```ts
const formSchema = z.object({
  authorId: z.number(),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'authorId',
      component: (props) => (
        <AutoFormUser
          {...props}
          description="Search by name, pick one person."
          label="Author"
          placeholder="Select an author"
        />
      ),
    },
  ]}
/>
```

Out of the box it searches the AdminCP users list, which means it answers with
whatever that route lets the signed-in admin see - the permission check lives
there and is not repeated in the component.

## Editing an existing record [#editing-an-existing-record]

A picker cannot show a name it has never fetched. An edit form starts holding an
id, so pass the person it already knows about as `selected`:

```tsx
<AutoFormUser
  {...props}
  label="Author"
  selected={{
    id: article.author.id,
    name: article.author.name,
    nameCode: article.author.nameCode,
    avatarColor: article.author.avatarColor,
  }}
/>
```

Without it the field opens on the placeholder, as though nobody were chosen.
Whatever the search returns afterwards is remembered on top of that, so a person
picked a moment ago still reads as their name.

<Callout type="info" title="Optional fields">
  A nullable author is `z.number().nullable()`. The field renders the
  placeholder for `null` and never invents a value - clearing one is up to your
  own control, because "no author" and "author not chosen yet" are the same
  state here.
</Callout>

## Searching somewhere else [#searching-somewhere-else]

`search` replaces the lookup entirely - a plugin scoping to its own members, a
different endpoint, or fixtures in a test:

```tsx
<AutoFormUser
  {...props}
  label="Reviewer"
  search={async (value) => await searchReviewers(value)}
/>
```

It runs on every open with an empty string, and again - debounced - as the
person types. That is deliberate: the list is a live view of who exists, and a
cached one offers somebody who was deleted since.

## Props [#props]

| Prop                | Type                                       | Default            | What it does                                     |
| ------------------- | ------------------------------------------ | ------------------ | ------------------------------------------------ |
| `label`             | `ReactNode`                                | -                  | Field label                                      |
| `description`       | `ReactNode`                                | -                  | Help text under the control                      |
| `placeholder`       | `string`                                   | `Select an option` | Shown while nothing is chosen                    |
| `searchPlaceholder` | `string`                                   | `Search...`        | Placeholder inside the search box                |
| `selected`          | `PartialUserOption \| null`                | -                  | The person the field opens on                    |
| `search`            | `(value: string) => Promise<UserOption[]>` | AdminCP users list | Replaces the lookup                              |
| `clearable`         | `boolean`                                  | `false`            | Adds a button that sets the field back to nobody |
| `disabled`          | `boolean`                                  | `false`            | Blocks opening the picker                        |

`UserOption` is `{ id, name, nameCode, avatarColor }` - the columns it takes to
recognise a person on sight. `selected` accepts a **partial** one, because the
caller often knows only an id and a name.

A generated avatar needs a colour, and that is the column a caller who resolved
only a *name* does not have. Rather than invent one - the wrong colour reads as a
different person - the field draws a neutral placeholder in the same box, so the
name stays where it is when a search fills the real avatar in.

## In the Content Engine [#in-the-content-engine]

A [`field.user()`](/docs/dev/content-engine/fields) renders this field
automatically - the author picker on a blog post is this component. Its options
come from the content type's own picker route rather than from the users list,
so an editor who may write articles can choose an author without also being
trusted to browse the member list.

## See also [#see-also]

* [Roles](/docs/ui/roles) - the same idea for roles, single or multiple.
* [Combobox](/docs/ui/combobox) - when the options are strings rather than people.