`) | Card background, border, `rounded-xl`, vertical padding |
| `EmailCardHeader` | `Section` | Horizontal padding and space below |
| `EmailCardTitle` | `Text` (a ``) | `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.
`bg-card`, `border-border` and `text-muted-foreground` are defined by
`DefaultTemplateEmail`, which wraps your content in a `` 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.
A React Email `Text` renders a `` 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.
Each of these renders a ``, because that is what survives Outlook.
Nesting them is fine and expected; floating or absolutely positioning them is
not a thing email can do.
## Next [#next]
# Custom Email Adapter (/docs/dev/email/custom-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
idempotencyKey?: string
}) => Promise
}
export interface EmailSendResult {
id?: string // the provider's message id
}
```
---
## 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]
# Email (/docs/dev/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]
### 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 '@/api/builders'
export const sendWelcomeRoute = buildRoute({
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. The
queued email is handed to the provider right after the response goes out, so
a sign-up or password-reset link doesn't wait for the next cron tick; if that
attempt fails, the queue worker retries it as usual.
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.
`deliver()` takes an optional `idempotencyKey` and returns what the provider
reported, such as its message id:
```ts
const email = await c.get('email').build(args)
const { id } = await c.get('email').deliver(email, {
idempotencyKey: `order-receipt:${order.id}`, // same key on every retry
})
```
Adapters whose provider deduplicates on a key, like Resend, forward it - so a
retry after an unconfirmed send is not delivered twice. SMTP has no such
feature and ignores it. [Notification emails](/docs/dev/notifications/email-and-digests)
use this for every send.
## Configuring Email Adapters [#configuring-email-adapters]
Configure your delivery transport in `apps/api/src/vitnode.api.config.ts`:
Each provider ships as its own package. Install one, then pass it as `email.adapter` - the sender address belongs to the adapter.
### 1. Resend Adapter [#1-resend-adapter]
```ts title="apps/api/src/vitnode.api.config.ts"
import { ResendEmailAdapter } from '@vitnode/resend'
export const vitNodeApiConfig = buildApiConfig({
email: {
adapter: ResendEmailAdapter({
apiKey: process.env.RESEND_API_KEY,
from: process.env.RESEND_FROM_EMAIL,
}),
},
})
```
See [Resend](/docs/dev/email/resend) for installation and setup.
### 2. SMTP Adapter (Nodemailer) [#2-smtp-adapter-nodemailer]
```ts title="apps/api/src/vitnode.api.config.ts"
import { NodemailerEmailAdapter } from '@vitnode/nodemailer'
export const vitNodeApiConfig = buildApiConfig({
email: {
adapter: NodemailerEmailAdapter({
from: process.env.NODE_MAILER_FROM,
host: process.env.NODE_MAILER_HOST,
port: Number(process.env.NODE_MAILER_PORT ?? 587),
user: process.env.NODE_MAILER_USER,
password: process.env.NODE_MAILER_PASSWORD,
}),
},
})
```
`port` defaults to `587` and `secure` to `false`. See [Nodemailer](/docs/dev/email/nodemailer) for installation and setup.
---
## 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) (/docs/dev/email/nodemailer)
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]
### Install the adapter [#install-the-adapter]
`nodemailer` itself ships as a dependency of the adapter.
```bash tab="bun"
bun i @vitnode/nodemailer
```
```bash tab="pnpm"
pnpm i @vitnode/nodemailer
```
```bash tab="npm"
npm i @vitnode/nodemailer
```
### 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. */}
### 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 `: the display name is
`metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.
### 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`.
### 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;
```
## Options [#options]
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.
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.
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.
VitNode renders both an HTML and a plain-text version of every email, but this
adapter passes `html` alone.
## Next [#next]
# Resend (/docs/dev/email/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]
### Install the adapter [#install-the-adapter]
The `resend` SDK ships as a dependency of the adapter, so this is the only
package you add.
```bash tab="bun"
bun i @vitnode/resend
```
```bash tab="pnpm"
pnpm i @vitnode/resend
```
```bash tab="npm"
npm i @vitnode/resend
```
### 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. */}
### 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. */}
### 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 `: the display name is
`metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.
### 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
```
### 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;
```
## Options [#options]
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.
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.
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.
## Next [#next]
# Email Templates (/docs/dev/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]
Welcome, {user.name}!
We are thrilled to have you in the community.
Visit Your Account
)
}
```
---
### 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:
```bash tab="bun"
bun run email dev
```
```bash tab="pnpm"
pnpm exec email dev
```
```bash tab="npm"
npx email dev
```
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 (
{i18n.t("order.confirmed")}
)
}
```
## Learn More [#learn-more]
# Built-in Events (/docs/dev/events/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]
Seventeen 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, or a member saves their own profile or time zone in **Settings → Overview** |
| `user.deleted` | `{ userId, email }` | Never - the name is declared for plugins, core has no deletion flow |
| `user.email.verified` | `{ userId, email }` | An address is [confirmed](/docs/dev/working-with-users/email-verification) - by its link, a completed reset, or by staff |
| `user.password.updated` | `{ userId }` | A password is set - by a member completing a reset, or by staff on the AdminCP user page |
| `user.sessions.revoked` | `{ userId, deviceId, sessions }` | A user is signed out remotely - one device or all of them, by the member or by staff, or after a password change |
| `user.sso.linked` | `{ userId, email, providerId }` | An SSO identity is linked to an existing account - at login with its password, or from **Settings → Connected accounts** |
| `user.sso.unlinked` | `{ userId, providerId }` | A provider is disconnected - by the member in **Settings → Connected accounts**, or by staff in the AdminCP |
| `user.sso.preferences_updated` | `{ userId, sources, sync }` | Profile-field sources or sync-on-sign-in settings are saved - by the member or by staff |
| `user.sso.profile_synced` | `{ userId, providerId, fields, trigger }` | Profile fields were copied from a provider - by **Sync now**, **Import** or an opted-in sign-in |
| `user.passkey.created` | `{ userId, passkeyId }` | A member adds a [passkey](/docs/dev/passkeys) in **Settings → Security** |
| `user.passkey.updated` | `{ userId, passkeyId, name }` | A passkey is renamed - by its owner or by staff |
| `user.passkey.deleted` | `{ userId, passkeyId }` | A passkey is removed - by its owner or by staff |
| `user.avatar.updated` | `{ userId, fileId }` | An avatar is uploaded or removed - by the user on their profile, or by staff in the AdminCP |
| `user.cover.updated` | `{ userId, fileId }` | A profile cover is uploaded or removed - by the user on their profile, or by staff in the AdminCP |
| `file.editor.uploaded` | `{ fileId, userId, kind }` | An image or attachment is dropped, pasted or inserted into an [editor that allows uploads](/docs/ui/editor-images) |
| `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 |
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).
Emitted by the AdminCP user `PATCH` after it commits - profile fields (email,
name, name code) and/or role assignments - and when a member saves their own
profile fields or time zone. The payload carries the user's **current** values.
Emitted after an avatar is stored and attached to the user, or after it is
removed. The same event covers the profile page and the AdminCP - the envelope's
`actor` tells the two apart.
The cover image's twin of `user.avatar.updated`, with the same payload and the
same two triggers.
Emitted after an editor image or attachment is stored in `core_files`, from the member route
(`POST /users/files/editor`) or the AdminCP one (`POST /admin/files/editor`).
The file is not part of any saved document yet, and the person may still remove
it before saving.
Emitted after the `core_users_sso` row is committed, from two places:
- `SSOModel.link` - a social identity that arrived with an already-registered
email is tied to that account once its password checks out;
- `SsoConnectionModel.callback` - a signed-in member connects a provider from
[Connected accounts](/docs/dev/sso/connected-accounts). The provider's email
may differ from the account's; `email` is always the VitNode account's.
It does not fire on the first sign-in through a provider (that is a
`user.created`) or on a later sign-in through an identity that is already
linked.
Emitted by `SsoConnectionModel.disconnect` after the connection and its profile
sync settings are deleted. Nothing is revoked at the provider - the member still
has to remove the app there if they want to.
Emitted when at least one profile field actually changed because of a provider.
Fields that were missing, not allowed or already equal are left out, and an
avatar that failed to download never counts. A name change also emits
`user.updated`, and an avatar change emits `user.avatar.updated`.
Emitted once an unconfirmed address becomes confirmed: when a member clicks
the link from their sign-up email, when they complete a password reset (the
reset link went to the same mailbox), or when staff press **Verify Email** on
the AdminCP user page. A reset on an account that was already confirmed emits
nothing here. See
[Email Verification](/docs/dev/working-with-users/email-verification).
Emitted after a new password hash is stored - when a member completes a
password reset, or when staff set one from the AdminCP user page. The staff
route answers `403` while password sign-in is turned off, so this never fires
for a password nobody could use. Both paths then sign the account out
everywhere, so `user.sessions.revoked` follows right after.
Emitted by `revokeSessions` once a user's sessions are deleted and their cached
copies dropped. It covers both session kinds - the site session and the AdminCP
session - and fires from every place that signs somebody out remotely: a member
ending one of their own devices, staff ending one device or all of them, and a
password change.
Emitted by `SsoConnectionModel.savePreferences` after the profile-field sources
and the per-provider sync switches are saved - from **Settings → Connected
accounts** or from the AdminCP user page. It fires on every successful save,
even when nothing changed.
>",
},
sync: {
description: 'The submitted sync-on-sign-in switch per provider id.',
type: 'Record',
},
}}
/>
**A listener would** audit-log who changed where an account's profile comes
from.
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.
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.
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.
## Notification events [#notification-events]
Eight names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. Seven of them fire **after** an
administrator's change in [AdminCP → Notifications](/docs/dev/notifications/admincp)
has been saved, and the envelope's `actor` is that administrator.
`notifications.preferences_updated` is about one member: it fires when their
own preferences are saved, by them or by staff on their AdminCP user page.
| Event | Payload | Fires when |
| ----------------------------------- | --------------------- | -------------------------------------------------------------------------- |
| `notifications.type.updated` | `{ typeId }` | What a type does by default (list, push, email, member can edit) changes |
| `notifications.preferences_updated` | `{ userId, typeIds }` | One member's preferences are saved - `typeIds` are the types in the save |
| `notifications.preferences_reset` | `{ members }` | **Reset all members to defaults** ran - `members` is how many were reset |
| `notifications.paused` | `{}` | Notifications were paused from the danger zone |
| `notifications.resumed` | `{ requeuedEvents }` | Notifications were resumed - `requeuedEvents` waited while paused |
| `notifications.emails_cancelled` | `{ count }` | Queued emails were cancelled - `count` is how many deliveries were skipped |
| `notifications.read_all` | `{ items, members }` | Everything was marked as read for everyone |
| `notifications.deleted_all` | `{ items }` | Every member's notifications were deleted |
**A listener would** post an audit entry to your staff channel when someone
pauses, deletes or resets everything, or note when staff changed how a single
member is notified.
## Moderation events [#moderation-events]
Eleven names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts` and emitted by core with
`pluginId: "@vitnode/core"`. Each fires **after** its database write
commits. The envelope's `actor` is the reporter for `created`, the
administrator for `report_reason.*` and the moderator for the rest. Adding an internal note emits nothing. See
[Moderation](/docs/dev/moderation).
| Event | Payload | Fires when |
| ---------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| `moderation.report.created` | `{ reportId, pluginId, targetType, targetId, reason }` | A signed-in user files a report. `reason` is the reason's `code` |
| `moderation.report.assigned` | `{ reportId, assigneeId, previousAssigneeId }` | A moderator takes, reassigns or unassigns a report. `assigneeId` may be `null` |
| `moderation.report.action` | `{ reportId, action, pluginId, targetType, targetId }` | A content action from the ModCP changed the content. `action` is `hide` or `unhide` |
| `moderation.report.resolved` | `{ reportId, resolution }` | A report is closed with an outcome |
| `moderation.report.reopened` | `{ reportId }` | A closed report is reopened |
| `moderation.report.note_updated` | `{ reportId, noteId }` | A moderator edits an internal note |
| `moderation.report.note_deleted` | `{ reportId, noteId }` | A moderator deletes an internal note |
| `moderation.report_reason.created` | `{ reasonId, code }` | An admin adds a [report reason](/docs/dev/moderation/manage-report-reasons) |
| `moderation.report_reason.updated` | `{ reasonId, code }` | An admin edits a report reason |
| `moderation.report_reason.deleted` | `{ reasonId, code }` | An admin deletes a report reason. Its reports stay |
| `moderation.report_reason.reordered` | `{ reasonIds }` | An admin saves a new order. `reasonIds` lists every reason in that order |
A hide or restore from the ModCP also emits the content type's own
`content.{id}.hidden` or `unhidden` event, because it goes through the same
visibility service as the AdminCP.
**A listener would** notify a staff channel when a report arrives, or keep a
per-moderator count of resolved reports.
## AI events [#ai-events]
Declared in `VitNodeEvents` in `packages/vitnode/src/api/models/events.ts`.
The two `ai.run.*` events are emitted by the shared AI runner (see
[AI Actions](/docs/dev/ai/actions)). They fire **after** the run was settled,
so its cost and points are already in the history when a listener reads it. A
failing listener never breaks the run - or the ALT write.
| Event | Payload | Fires when |
| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ai.run.completed` | `{ actionKey, actorType, runId, userId }` | A managed AI run delivered a valid result |
| `ai.run.failed` | `{ actionKey, actorType, errorCode, runId, userId }` | A run ended without a valid result: provider failure, cancel, bad output |
| `files.alt.updated` | `{ fileId, languageCodes, origin }` | An image's default ALT text was written - by [automatic ALT text](/docs/dev/ai/automatic-alt) or by a person |
`userId` is `null` for system work such as automatic ALT text. Prompts and
outputs are never part of the payload.
`files.alt.updated` fires after the `core_files_alt` rows were written.
`languageCodes` lists only the languages that actually changed, and `origin` is
`"ai"` for the background job or `"human"` for `PUT /admin/files/{id}/alt`.
Removing a language's ALT text emits nothing.
**A listener would** post a notice when an editor's AI suggestion fails, count
AI usage per plugin in your own analytics, or purge cached pages that render an
image whose ALT text just changed.
## Page layout events [#page-layout-events]
One name, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. It fires **after** the layout row
has been written, and not at all when a save changed nothing.
| Event | Payload | Fires when |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| `core.page-layout.updated` | `{ pageId, changedZones }` | Somebody saves widget changes on an [editable page](/docs/dev/widgets/editable-pages) |
Emitted by `PUT /pages/layout` once the one `core_page_layouts` row for that
page has been written. A page's layout is stored as overrides only, so
`changedZones` names the zones whose override actually moved - not every zone
the editor happened to send, and not the zones still sitting on the defaults
their `defineEditablePage` declaration ships.
A save that changes nothing writes nothing and emits nothing, so a listener
never fires for a no-op. Saving a zone back to its shipped default removes that
override, which counts as a change and is reported here.
## Content Engine events [#content-engine-events]
Every content type declared with the
[Content Engine](/docs/content-engine) gets its own event names, built from
its id: `content..`. 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`.
Every payload's `contentId` (and `sourceId` and `duplicatedFromId`) has the
content type's [id type](/docs/content-engine/id-strategy): a `number` for the
default `serial` strategy, a `string` for `uuid` and `bigint`. A bigint id
arrives as its exact decimal string, so never pass it through `Number()`.
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 nineteen.
| 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` |
| `duplication` | `duplicated` |
| `visibility` | `hidden`, `unhidden` |
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 |
| `duplicated` | `{ actorUserId, contentId, contentTypeId, sourceId }` | A record was copied into a new draft, right after the copy's own `created` |
| `hidden` | `{ actorUserId, contentId, hiddenAt }` | A visible record is taken off the public site without being unpublished |
| `unhidden` | `{ actorUserId, contentId }` | A hidden record is made visible again |
',
},
changedFields: {
description:
"Update only - the fields whose value actually changed, narrowed to this content type's own field names. An update that changes nothing emits no event at all.",
type: 'ContentFieldName[]',
},
duplicatedFromId: {
description:
'Set on the `created` of a duplicate, with the id of the record it was copied from. Absent for an ordinary create, so a listener can tell copies apart without waiting for `duplicated`.',
type: 'ContentIdOf',
},
}}
/>
**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.
`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.
',
},
publishedAt: {
description:
'Published only - when the record first went live. Declared as a Date, but omitted when the engine could not read one back off the row, so guard for undefined.',
type: 'Date',
},
scheduledBy: {
description:
'Only when a schedule fired this - the staff member who booked it. Absent on an interactive publish, because the actor of a scheduled run genuinely is the system.',
type: 'null | number',
},
scheduleId: {
description:
'Only when a schedule fired this - the booking, which doubles as the idempotency key across the effects task retries.',
type: 'number',
},
}}
/>
**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).
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.
',
},
changedFields: {
description:
'The fields the rollback moved, in the same shape `updated` uses.',
type: 'ContentFieldName[]',
},
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`, `publishedAt` or `hiddenAt`, so nothing watching
visibility has to handle it.
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.
',
},
action: {
description: 'Which transition was booked, or cancelled.',
type: '"publish" | "unpublish"',
},
actorUserId: {
description:
'The staff member who booked or cancelled it. Note the name: the same person is called `scheduledBy` on the published/unpublished payloads.',
type: 'null | number',
},
scheduledFor: {
description: 'Scheduled only - when the transition will happen.',
type: 'Date',
},
scheduleId: {
description:
'The schedule row. Always present on both events, and the id the eventual published/unpublished will carry.',
type: 'number',
},
}}
/>
**A listener would** show an editorial calendar, warn an author that two
bookings collide, or pre-warm a render shortly before `scheduledFor`.
A [duplicate](/docs/content-engine/duplicate-content) first emits the copy's
ordinary `created` (with `duplicatedFromId`) and one `translation_created` per
copied language, then `duplicated`. Indexing already ran for `created`, so
`duplicated` is a notification only.
',
},
contentTypeId: {
description: 'The content type id, such as `blog.post`.',
type: 'string',
},
sourceId: {
description:
'Id of the record that was copied. It is only read, never changed.',
type: 'ContentIdOf',
},
}}
/>
**A listener would** credit the original author in an audit log, or link the
copy to its source in a plugin-owned table.
[Hiding](/docs/content-engine/content-visibility) takes a record off the public
site without touching `status` or `publishedAt`, so a hidden record emits
neither `unpublished` nor, when unhidden, `published`. Hiding a record that is
already hidden emits nothing.
',
},
hiddenAt: {
description: 'When the record was hidden. Sent with `hidden` only.',
type: 'Date',
},
}}
/>
**A listener would** purge a CDN entry, pull the record from an external
search engine, or tell the author that a moderator took their article down.
Hiding a draft emits the event too, though nothing public changed.
### Translation events [#translation-events]
A content type with [`localization`](/docs/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 |
',
},
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[]',
},
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.
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.
### Delivery events [#delivery-events]
A content type with
[`delivery`](/docs/content-engine/public-pages) 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 |
',
},
slug: {
description: 'Slug changed only - the slug the record answers to now.',
type: 'string',
},
previousSlug: {
description:
'The slug it answered to before. Declared nullable, but populated on both events in practice: neither fires unless the slug moved from one real value to another, so a record arriving at its first slug emits neither of them.',
type: 'null | string',
},
previousPath: {
description:
'The public path it answered to before, spelled by the localized URL rules, e.g. /pl/artykuly/stary-slug (or /artykuly/stary-slug on a Polish domain). A path, never an origin. Nullable on delivery_slug_changed for the same declared reason, populated for the same real one, and always a string on delivery_redirect_created.',
type: 'null | string',
},
canonicalPath: {
description:
'The public path it answers to now, and where the historical one redirects. Same shape as previousPath: locale prefix and translated segments applied, no origin.',
type: 'string',
},
locale: {
description:
'The language this URL belongs to, or null when the slug is shared - a content type that is not localized, or a localized one whose slug lives on the base row.',
type: 'null | string',
},
}}
/>
**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.
`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.
### 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 other way out is an idempotency key on whatever the listener writes. A
notification published with `` idempotencyKey: `post:${payload.contentId}` ``
turns a second run into a no-op. See
[Idempotency keys](/docs/dev/notifications/publishing#choose-an-idempotency-key).
### 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 "" 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/logs (Log explorer section), 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}. */}
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/content-engine/services).
## Content container events [#content-container-events]
Four names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts` and shared by every
[container collection](/docs/content-engine/containers). Each fires **after**
the write's transaction has committed. A refused write, such as deleting a board
that still has discussions, emits nothing, and so does an update that changes
nothing.
| Event | Payload | Fires when |
| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `content.container.created` | `{ definitionId, pluginId, containerId, parentId }` | A container is created |
| `content.container.updated` | `{ definitionId, pluginId, containerId, parentId, changedFields }` | Its name, slug, a metadata field or its publishing policies actually changed |
| `content.container.moved` | `{ definitionId, pluginId, containerId, parentId, fromParentId, position }` | It moved to another parent, another position, or both |
| `content.container.deleted` | `{ definitionId, pluginId, containerId, parentId }` | An empty container is deleted |
Emitted by `createContentContainerService`, so the AdminCP routes and your own
code that uses the service emit the same events. Siblings renumbered by a move
or a delete do not get events of their own.
## Content approval events [#content-approval-events]
Three names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts` and shared by every content type
that waits for [approval](/docs/content-engine/approvals) under a container's
[publishing policy](/docs/content-engine/container-policies). Each fires
**after** its transaction commits. A refused decision, such as a `409 stale`,
emits nothing.
| Event | Payload | Fires when |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `content.approval.submitted` | `{ submissionId, replacedSubmissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId }` | A member's create or edit starts waiting, including a resubmission or a newer proposal |
| `content.approval.approved` | `{ submissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId, reviewerId }` | A moderator approves a submission |
| `content.approval.rejected` | `{ submissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId, reviewerId, reason }` | A moderator rejects a submission |
The record's own events are never duplicated. A pending create emits the
content type's `created` when it is stored, and its `published` only when it is
approved. Approving an edit emits one `updated`, with the changed fields.
Rejecting emits nothing from the content type, because nothing on the record
changed.
Emitted by the public write service when a submission opens, and by
`decideContentSubmission` when a moderator decides, so the ModCP and your own
code that calls it emit the same events. Updating a draft whose create is
already pending refreshes that submission and emits no approval event.
## Blog events (`@vitnode/blog`) [#blog-events-vitnodeblog]
The blog runs on the [Content Engine](/docs/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. A duplicated article re-emits
`blog.post.created` once; `duplicated`, `hidden` and `unhidden` have no blog
adapter.
| 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.
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.
Events fire at runtime for every registered content type, but the names appear
on `VitNodeEvents` only where the owning plugin declares
`ContentEventsFor`. 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/content-engine/plugin-files).
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.
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.
## 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.)
Live editing is quiet on the bus too. Taking or giving back a field lock,
autosaving the shared draft and every keystroke in a co-edited rich text field
happen many times a minute and change nothing anyone outside the form relies
on, so none of them is an event. What does reach the bus is the commit: when
someone presses **Save**, the record emits its usual `updated` (and its
translations theirs), exactly as it would without live editing.
## Next [#next]
# Custom Event Adapter (/docs/dev/events/custom-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
}
```
---
## 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 (/docs/dev/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 },
})
},
})
```
Register the listener in your module's `events` array:
```ts title="plugins/shop/src/api/modules/orders/orders.module.ts"
import { buildModule } from "@/api/builders"
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]
| Feature | Local Transport |
| :--- | :--- |
| **Execution** | Runs in-process on the emitting instance. |
| **Ordering** | Sequential execution in registration order. |
| **Error Isolation** | Per listener. An exception in one listener does not affect others. |
| **Durability** | In-memory. For distributed brokers, see [Custom Adapter](/docs/dev/events/custom-adapter). |
## Learn More [#learn-more]
# Data Fetching (/docs/dev/fetcher)
In TanStack Start, data fetching bridges two execution environments: server-side rendering during SSR and in-app client navigation afterwards.
VitNode's universal `fetcher` from `@vitnode/core/tanstack/fetcher` eliminates duplicate transport logic. During SSR, it relays visitor cookies, IP addresses, and headers to the API; in the browser, it calls `/api/*` directly with `credentials: "include"`. One call, end-to-end type inference, zero drama.
## The universal call [#the-universal-call]
Call `fetcher` inline at the call site. The router automatically infers available modules, HTTP methods, arguments, and return types from your plugin's API registry:
```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'
const response = await fetcher({
plugin: '@acme/site-notes',
method: 'get',
module: 'notes',
path: '/',
})
if (response.ok) {
const { notes } = await response.json()
}
```
Four fields identify an endpoint:
| Field | Description | Inferred from |
| :------- | :------------------------------------------------------------- | :----------------------------------- |
| `plugin` | Package name of the target plugin | App-configured plugin registry |
| `module` | Module path under the plugin (e.g. `'notes'`, `'admin/notes'`) | Plugin's `buildApiPlugin` definition |
| `path` | Route path declared inside the module (`'/'`, `'/{id}'`) | Module's route declarations |
| `method` | HTTP method declared for that path (`'get'`, `'post'`, etc.) | Declared routes for that path |
## Arguments: body, params, and query [#arguments-body-params-and-query]
The `args` object is required whenever a route declares Zod schemas for parameters, queries, or request bodies:
```ts title="plugins/site-notes/src/features/notes/pin-note.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'
export const pinNote = async (id: string, pinned: boolean) => {
const response = await fetcher({
plugin: '@acme/site-notes',
// [!code ++:4]
args: {
body: { pinned },
params: { id },
},
method: 'post',
module: 'notes',
path: '/{id}/pin',
})
if (response.status === 404) return null
// Narrowed to 200: typed as the pinned Note object
return await response.json()
}
```
- `params` — Interpolated into path parameters like `/{id}`.
- `query` — Serialized into the URL query string (e.g. `?search=term&page=1`).
- `body` — Serialized as JSON.
- `formData` — Pass `formData` instead of `args.body` for file uploads.
- `captchaToken` — Pass `captchaToken` for captcha-protected endpoints.
## Type inference & compile checks [#type-inference--compile-checks]
The fetcher validates endpoints through `ApiPluginRegistry`. An invalid method, typo in the path, or missing parameter produces an immediate compile-time error:
```ts
await fetcher({
plugin: '@acme/site-notes',
// @ts-expect-error Type '"delete"' is not assignable to type '"get"'.
method: 'delete',
module: 'notes',
path: '/',
})
```
The response is status-aware: `response.status` is typed as a union of declared HTTP codes (e.g. `200 | 404`). Once you narrow on `response.status`, `response.json()` automatically narrows to that status code's specific schema. The body is typed as the JSON the route sends, the same way Hono types `c.json()`: a `z.date()` field arrives as its ISO `string`, so convert it with `new Date(value)` when you need a date.
## How the registry types your calls [#how-the-registry-types-your-calls]
Each plugin exports a lightweight contract type from its `config.api.ts`:
```ts title="plugins/site-notes/src/config.api.ts"
import type { ApiPluginContract } from '@vitnode/core/api/lib/plugin'
export type VitNodeApiPlugin = ApiPluginContract<
ReturnType
>
```
`ApiPluginContract` strips away runtime internals (Hono handlers, database connections, and background workers) and extracts only what the compiler needs: the plugin ID, module paths, route endpoints, methods, and Zod schemas.
When you run `vite dev` or `vite build`, the `vitnode:plugin-routes` plugin automatically updates your app's `src/api-registry.gen.ts`:
```ts title="apps/web/src/api-registry.gen.ts"
import type { VitNodeApiPlugin as ApiPlugin0 } from '@acme/site-notes/config.api'
declare module '@vitnode/core/lib/fetcher/registry' {
interface ApiPluginRegistry {
'@acme/site-notes': ApiPlugin0
}
}
export type { ApiPluginRegistry } from '@vitnode/core/lib/fetcher/registry'
```
All imports in the registry use `import type`. This guarantees that
server-side code, database credentials, and internal handlers never leak into
the browser bundle. The actual API factory executes exclusively in
`vitnode.api.config.ts`.
## Loading data in plugin routes [#loading-data-in-plugin-routes]
Plugin routes load data using `defineRoute({ load })` from `@vitnode/core/tanstack/plugin-routes`. The loader runs during SSR and client navigation, handing typed `loaderData` to the page component. Its context includes `queryClient`; the framework-neutral `definePluginRoute` from `@vitnode/core/routing` only receives `locale`:
```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { defineRoute } from '@vitnode/core/tanstack/plugin-routes'
import { notesQuery } from '../features/notes/notes-query'
interface Note {
id: string
title: string
}
// [!code ++:8]
export const route = defineRoute({
load: async ({ context }) => {
return await context.queryClient.query({
...notesQuery(),
staleTime: 'static',
})
},
})
const NotesPage = ({ loaderData }: PluginRoutePageProps) => {
return (
{loaderData.map((note) => (
{note.title}
))}
)
}
export default NotesPage
```
`staleTime: "static"` makes the loader reuse an entry that is already cached instead of fetching again on every navigation. The entry refreshes when a mutation invalidates it, as shown below. See [Cache app data](/docs/dev/cache/app) for the full pattern.
## Mutations & cache invalidation [#mutations--cache-invalidation]
After creating, editing, or deleting records, call `queryClient.invalidateQueries` to refetch fresh data, then display a `sonner` toast notification:
```tsx title="plugins/site-notes/src/features/notes/use-create-note.ts"
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { fetcher } from '@vitnode/core/tanstack/fetcher'
import { toast } from 'sonner'
import { notesQueryKey } from './notes-query'
export const useCreateNote = () => {
const queryClient = useQueryClient()
return useMutation({
mutationFn: async (title: string) => {
const response = await fetcher({
plugin: '@acme/site-notes',
args: { body: { title } },
method: 'post',
module: 'notes',
path: '/',
})
if (!response.ok) {
throw new Error('Failed to create note.')
}
return await response.json()
},
onSuccess: async () => {
// Invalidate cache and trigger sonner toast
await queryClient.invalidateQueries({ queryKey: notesQueryKey })
toast.success('Note created successfully!')
},
})
}
```
## Built-in system queries [#built-in-system-queries]
Core provides three pre-warmed query hooks for common application state:
| Hook | Import | Suspends | Description |
| :--------------------------- | :----------------------------- | :------- | :--------------------------------------------- |
| `useSessionQuery()` | `@vitnode/core/tanstack/auth` | No | Signed-in visitor session, or `null` |
| `useAdminSessionQuery()` | `@vitnode/core/tanstack/admin` | Yes | AdminCP staff identity and permissions |
| `useMiddlewareConfigQuery()` | `@vitnode/core/tanstack/auth` | Yes | Public deployment configuration before sign-in |
### Deployment configuration [#deployment-configuration]
`useMiddlewareConfigQuery()` reads public server capabilities without requiring an active session, allowing login and registration screens to adapt dynamically:
```tsx title="plugins/site-notes/src/pages/login-page.tsx"
import { useMiddlewareConfigQuery } from '@vitnode/core/tanstack/auth'
const LoginPage = () => {
const { data: config } = useMiddlewareConfigQuery()
return (
{config.captcha ?
Captcha enabled
: null}
{config.sso?.length ?
Social sign-in available
: null}
Import from `@vitnode/core/tanstack/fetcher/server` only inside `*.server.ts`
files or `createServerFn` handlers. Value imports of backend factories or
server fetchers should never reach client bundles.
### SSR skips the network when the API lives next door [#ssr-skips-the-network-when-the-api-lives-next-door]
When your app mounts the API in its own process (the default single app does,
via `configureInProcessApi` from
`@vitnode/core/lib/fetcher/in-process-api.server`), server-side calls hand the
request straight to it - no HTTP round trip, no trip through your proxy or
CDN, same cookies, headers and signed visitor IP. Set `VITNODE_API_URL` to a
different origin, or pass `origin` on a call, and the request goes over the
network as before. Without `VITNODE_API_URL` and without an in-process API,
that network call goes to `VITNODE_WEB_URL` - never to the incoming request's
`Host`, which a visitor controls.
## Browser-only requests with fetcherClient [#browser-only-requests-with-fetcherclient]
For client code that **never** executes on the server—such as browser event listeners, interactive dialogs, or framework-neutral utilities—call `fetcherClient` from `@vitnode/core/lib/fetcher-client`:
```ts title="plugins/site-notes/src/features/notes/client-actions.ts"
import { fetcherClient } from '@vitnode/core/lib/fetcher-client'
export const deleteNote = async (id: string) => {
const response = await fetcherClient({
plugin: '@acme/site-notes',
args: { params: { id } },
method: 'delete',
module: 'notes',
path: '/{id}',
})
return response.ok
}
```
`fetcherClient` shares the exact same call signature and type inference as the universal `fetcher`, but is built exclusively for the browser with `credentials: "include"` and automatic rate-limiting notifications.
## Content Engine routes [#content-engine-routes]
Public routes created via [Content Engine](/docs/content-engine) (`publicApi`) are automatically typed under `module: "content/"`:
```ts
const response = await fetcher({
plugin: '@vitnode/blog',
args: { params: { slug: 'welcome' } },
method: 'get',
module: 'content/posts',
path: '/{slug}',
})
```
For generated AdminCP content modules where schemas are dynamic, use `rawFetcher` from `@vitnode/core/tanstack/fetcher` instead. See [Content Engine](/docs/content-engine) for defining content types, schema modeling, and generating CRUD APIs.
# Languages & Localization (/docs/dev/i18n)
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:
```bash tab="bun"
bun run vitnode i18n create de Deutsch
bun run vitnode i18n check
```
```bash tab="pnpm"
pnpm vitnode i18n create de Deutsch
pnpm vitnode i18n check
```
```bash tab="npm"
npx vitnode i18n create de Deutsch
npx vitnode i18n check
```
`vitnode 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`. `vitnode i18n check` scans for missing or untranslated keys - including a file nobody imports, which is the usual reason a translation "does not apply".
| Command | What it does |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `vitnode i18n create` | Add a language: seed its files and wire them into the config |
| `vitnode i18n check` | Report missing, unknown and unloaded translations (`--ci` fails on missing keys) |
| `vitnode i18n update` | Sync translation files with the default language's keys |
| `vitnode i18n update-ai` | Translate strings still in the default language with an AI model (`--model`, `--concurrency`) |
| `vitnode i18n delete` | Remove a language (`--yes` to skip the question) |
Arguments skip their questions, so every command works in a script: without a terminal, a missing argument is an error (exit code `2`) rather than a prompt that waits forever. The older `i18n:create`-style names still work.
---
## 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:
| File | Holds | Who writes it |
| :---------------------------- | :--------------------------------------------------- | :------------ |
| `src/package-messages.gen.ts` | one loader per language each installed package ships | your build |
| `src/locales/app.ts` | your own rewordings, merged last | you |
```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/package-messages.gen.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.
### The generated half [#the-generated-half]
Registering a plugin is the whole step. Every VitNode build reads the `plugins` in your `vitnode.config.ts`, takes the `localeFiles` each factory declares, and writes `src/package-messages.gen.ts` - core's own languages plus one block per plugin:
```ts title="apps/web/src/package-messages.gen.ts"
export const packageMessages: Record = {
'@vitnode/core': {
en: async () => await import('@vitnode/core/locales/en.json'),
},
'@acme/blog': {
en: async () => await import('@acme/blog/locales/en.json'),
},
}
```
Don't edit it - it is rewritten on every `dev` and `build`, which is why it sits in your `.gitignore`. Every specifier is a literal because that is the only kind a bundler can resolve: `import(pkg + '/locales/' + locale + '.json')` resolves to nothing. Every loader stays dynamic, so a language's JSON is a chunk of its own and the server loads only the locale a request asked for.
`@vitnode/core` and the plugins in this repository ship `en` and nothing else.
Every other language is the install's own, which is what the next section is
for - and it is why a language you add is a file in **your** app rather than a
pull request against a package.
---
## Overriding Strings [#overriding-strings]
Your own translations live in `apps/web/src/locales/{pluginId}/{locale}.json`, registered in `src/locales/app.ts`. The same file does both jobs: a whole language a package does not ship, and a reword of a string it does.
One file per package per language, holding that package's web **and** email strings together - an app keeps them in one tree where a package ships two, so the copy in an email cannot drift from the copy on the page.
To reword something core already says:
```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.
A whole language looks exactly the same, because it is the same mechanism - this repository's own Polish is a pair of files nobody's `node_modules` contains:
```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
pl: {
'@vitnode/blog': async () => await import('./@vitnode/blog/pl.json'),
'@vitnode/core': async () => await import('./@vitnode/core/pl.json'),
},
}
```
If your app also serves the API, register the same map there so emails speak the language too - `i18n.messages` in `vitnode.api.config.ts`:
```ts title="apps/web/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
i18n: { ...vitNodeConfig.i18n, messages: appMessages }, // [!code highlight]
// ...
})
```
---
### Your app's own strings [#your-apps-own-strings]
Copy that belongs to no package - your landing page, say - gets a namespace of its own. Pick an id no package uses, put the tree under it, and register it like any other file:
```json title="apps/web/src/locales/site/en.json"
{
"site": {
"home": { "title": "A home for your people" }
}
}
```
```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
en: { site: async () => await import('./site/en.json') },
pl: { site: async () => await import('./site/pl.json') },
}
```
`vitnode i18n check` treats it like a package: your default-locale file is the source of truth, and every other language is checked against it for missing and leftover keys. No default-locale file at all is an error - there would be nothing to translate from.
---
## 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** | Your own languages and rewordings in `apps/web/src/locales` | Highest priority (wins) |
Missing keys automatically fall back to `defaultLocale` (`en`), preventing raw key paths from displaying in production.
---
## Localized URLs [#localized-urls]
Strings aren't the only thing you can translate. The same `i18n` block decides how public URLs look in each language: a prefix (`/pl/...`), a domain per language (`vitnode.pl`), and translated paths such as `/pl/odkrywaj` for `/discover`:
```ts title="apps/web/src/vitnode.config.ts"
i18n: {
defaultLocale: 'en',
// [!code ++:3]
routePaths: {
pl: { '/discover': '/odkrywaj' },
},
},
```
[Localized URLs](/docs/dev/i18n/localized-urls) covers the rules, domains, redirects and SEO.
## Learn More [#learn-more]
# Localized URLs (/docs/dev/i18n/localized-urls)
Plugins declare their pages in English. Your app decides how each page is spelled in every other language. So `/discover` stays `/discover` for English readers and becomes `/pl/odkrywaj` for Polish ones. It's the same route, the same component and the same `
### Find the English path [#find-the-english-path]
Every plugin documents the paths its pages answer to. Core's are `/discover`, `/search`, `/users/:nameCode`, `/login`, `/settings` and friends. Those English paths are the keys you translate. Your app's own routes work the same way.
### Translate it in `vitnode.config.ts` [#translate-it-in-vitnodeconfigts]
```ts title="apps/web/src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
i18n: {
defaultLocale: 'en',
locales: [
{ code: 'en', name: 'English' },
{ code: 'pl', name: 'Polski' },
],
// [!code ++:8]
routePaths: {
pl: {
'/blog/article/:slug': '/wpisy/:slug',
'/discover': '/odkrywaj',
'/search': '/szukaj',
'/users/:nameCode': '/uzytkownicy/:nameCode',
},
},
timeZone: 'UTC',
},
})
```
This is the configuration this site runs on.
### Restart `dev` [#restart-dev]
Every link, redirect, canonical URL and sitemap line now uses the new spelling. You don't touch any route file.
| Page | English | Polish before | Polish after |
| :-------- | :-------------- | :----------------- | :------------------------- |
| A post | `/blog/article/hello` | `/pl/blog/article/czesc` | `/pl/wpisy/czesc` |
| Discover | `/discover` | `/pl/discover` | `/pl/odkrywaj` |
| Search | `/search` | `/pl/search` | `/pl/szukaj` |
| A profile | `/users/jane-1` | `/pl/users/jane-1` | `/pl/uzytkownicy/jane-1` |
| Login | `/login` | `/pl/login` | `/pl/login` (untranslated) |
## One route, many spellings [#one-route-many-spellings]
A translation never creates a route. The router's URL rewrite does the work in both directions:
- **Coming in**, `/pl/odkrywaj` is read as the Polish version of `/discover`, so the route tree matches `/discover`.
- **Going out**, `
Pass `/articles/witaj-swiecie`, not `/pl/artykuly/witaj-swiecie`. `alternates`
are always read as internal paths, so a public one would be translated a
second time. The delivery API gives you both: each alternate has a public
`path` and an `internalPath`, and metadata has `canonicalInternalPath`.
A page backed by the Content System doesn't write any of this by hand. `@vitnode/core/tanstack/content` turns a delivery response into page data and a head. That covers redirects, 404s, the SEO title and description, and the internal alternates of every published translation. Blog's own post page is built this way:
```tsx title="plugins/blog/src/pages/post-page.tsx"
const loadBlogPost = async ({
locale,
slug,
}: {
locale: string
slug: string
}) => {
const [resolution, detail] = await Promise.all([
fetcher({
plugin: '@vitnode/blog',
method: 'get',
module: 'content/blog',
path: '/delivery/resolve/{slug}',
args: { params: { slug: encodeURIComponent(slug) }, query: { locale } },
}),
fetcher({
plugin: '@vitnode/blog',
method: 'get',
module: 'content/blog',
path: '/{slug}',
args: { params: { slug: encodeURIComponent(slug) }, query: { locale } },
}),
])
return contentDeliveryPage({
item: detail.status === 200 ? zodBlogPost.parse(await detail.json()) : null,
resolution: await resolution.json(),
})
}
export const route = definePluginRoute({
load: async ({ context, params }) =>
await loadBlogPost({ locale: context.locale, slug: params.slug }),
head: ({ loaderData }) =>
contentDeliveryPageHead(loaderData?.metadata, {
title: loaderData?.item.title,
}),
})
```
A retired slug answers with a 308 to the current one, and an unknown slug is a 404.
App routes can do the same with `pageHead` or `localeAlternateLinks` from `@vitnode/core/tanstack/metadata`:
```tsx title="apps/web/src/routes/pricing.tsx"
import { localeAlternateLinks } from '@vitnode/core/tanstack/metadata'
export const Route = createFileRoute('/pricing')({
head: ({ match }) => ({
links: localeAlternateLinks({
internalPathname: '/pricing',
locale: match.context.locale,
}),
}),
})
```
`internalPathname` means "the same page in every locale". Pass `alternates: { en: '...', pl: '...' }` instead when the path differs per language.
## Translated segments vs localized slugs [#translated-segments-vs-localized-slugs]
Two different things change in a URL, and they're owned by different people:
| Part of the URL | Owned by | Example (Blog) |
| :------------------------------------------------- | :---------------------------------- | :-------------------------------- |
| Static segments (`blog` → `wpisy`) | Your app, `routePaths` | `/blog/…` → `/pl/wpisy/…` |
| Parameter values (`hello-world` → `witaj-swiecie`) | The content, a localized slug field | each translation has its own slug |
Put together, Blog's `/blog/article/hello-world` in English is `/pl/wpisy/witaj-swiecie` in Polish. The translation table never touches `witaj-swiecie`, and the content never touches `wpisy`.
## Content, sitemaps and search follow along [#content-sitemaps-and-search-follow-along]
Content Engine builds every URL with the same rules as the router, so nothing drifts:
- Canonical URLs, hreflang, `x-default`, sitemap lines, preview links and slug-history redirects all use your `localePrefix`, `domains` and `routePaths`.
- Only published translations become alternates. A Polish request that falls back to English content keeps the **English** canonical URL, so fallback text is never labelled as Polish.
- Slug-history redirects stay within their language.
- Search result URLs are built from `search.pathTemplate` (like `/blog/article/{slug}`) the same way, and they're absolute once domains are configured.
### Content URLs need a page [#content-urls-need-a-page]
A content type publishes URLs from `delivery.path` (default `/{publicApi.path}/:slug`) and `search.pathTemplate`. Both are English route paths, and **a page route has to serve them**. Otherwise every canonical link, sitemap line and search result would be a 404. So the build checks it: a content type whose URL no page route serves stops `dev` and `build` with `content-url-without-page`. Blog serves `/blog/article/:slug` with its own page, which is also why `'/blog/article/:slug'` is a valid `routePaths` key.
The web build can't read your API: `config.api.ts` is server code, and a plugin factory may need options only your app knows. So a plugin states its public content types **once**, in a browser-safe module exposed as `./content`, and both sides load that same module:
```ts title="plugins/blog/src/content.ts"
import { blogCategoryContentType } from '@/content/category'
import { blogPostContentType } from '@/content/post'
export const contentTypes = [blogPostContentType, blogCategoryContentType]
```
Any output layout works, as long as the package's `exports` resolve `@vitnode//content` (the `./*` wildcard in VitNode's own plugins covers it).
- **The web build** imports every configured plugin's `./content` module, checks each URL in it against your page routes (`content-url-without-page`), and writes the modules it loaded to `src/content-modules.gen.ts`.
- **The API**, when it boots, loads the same module and compares it with what the plugin actually registers, through admin and public modules alike. A plugin that publishes URLs without a loadable `./content` module stops the API with `content-module-missing`. One whose module leaves a published type out, or declares it with a different URL, stops it with `incomplete-content-types`.
Where the API looks depends on how the app is built:
| Setup | The API checks against | Wiring |
| :------------------------------------------ | :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Single app (web and API in one) | `src/content-modules.gen.ts`: exactly the modules this web build loaded and checked | `buildApiConfig({ contentModules })`, already in `create-vitnode-app` |
| Separate API app (`apiMonorepo`, `onlyApi`) | `/content` resolved from the API app's own `node_modules`, the same exports lookup | Nothing. Needs Node.js 22.12+ (synchronous `require` of an ES module) |
```ts title="src/vitnode.api.config.ts"
// [!code ++]
import { contentModules } from './content-modules.gen'
export const vitNodeApiConfig = buildApiConfig({
plugins: [blogApiPlugin()],
// [!code ++]
contentModules,
// ...
})
```
A separately built API proves that each plugin's `./content` module exists and
matches what it publishes, which is what any web build would load. It can't
prove that your web app configures that plugin, or was built from the same
version. A plugin installed only in the API (a headless setup) has its URLs
checked against no pages.
A plugin whose content publishes no URLs (no delivery, no search) needs none of this.
Details live in [Content Delivery and SEO](/docs/content-engine/public-pages) and [Search](/docs/dev/search).
Search stores each result's URL when it indexes it. After you change
`routePaths`, `domains` or `localePrefix`, rebuild the index in **Debug
Panel → Search** (`/admin/core/debug/search`) so old results pick up the
new URLs.
## Validation errors [#validation-errors]
A bad configuration fails loudly, when `dev` or `build` starts, not quietly in production. Every message starts with `[VitNode i18n]` and names the exact entry. The error is a `LocaleRoutingConfigError` with a `code`.
**Checked from the config alone** (web app and API):
| Code | Cause | Fix |
| :----------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------- |
| `unknown-route-locale` | `routePaths` has a locale that isn't enabled | Add it to `i18n.locales` or remove its block |
| `invalid-route-path` | Not a valid path: uppercase, `[id]` or `$id` syntax, whitespace, not a string | Use lowercase and VitNode syntax (`:id`, `*`) |
| `root-route-path` | `/` is translated | Remove it. `localePrefix` spells the home page |
| `reserved-route-path` | Source or translation is under `/admin` or `/api` | Remove it. Those URLs are never localized |
| `locale-segment` | Translation starts with a locale code, e.g. `/pl/...` | Pick another first segment |
| `parameter-mismatch` | A parameter is missing, added or renamed, or `*` was dropped or added | Keep the English path's parameters exactly |
| `duplicate-source-path` | Two keys are the same pattern | Keep one |
| `duplicate-route-path` | Two translations match the same URLs | Spell one of them differently |
| `invalid-domain` | `origin` has a path, query, credentials or isn't http(s) | Use `https://host` only |
| `duplicate-domain` | Two domains use the same host | Merge their `locales` |
| `unknown-domain-locale` | A domain's `defaultLocale` isn't in its `locales`, or a locale isn't enabled | Fix the list |
| `domain-locale-conflict` | A locale is on two domains | Give each locale one home |
| `unassigned-locale` | Domains are configured, but a locale has none | Add it to a domain |
| `ambiguous-never-prefix` | `never` with several locales on one host | Add `domains` (one locale each) or use `as-needed` |
**Checked at build time**, once the route list is known:
| Code | Cause | Fix |
| :------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| `unknown-source-path` | The key isn't a route in this app | Use one of the suggested paths |
| `parameter-mismatch` | The key names a parameter differently from the route (`:id` vs `:slug`) | Write the key with the route's own names |
| `inconsistent-layout-path` | A translated layout has an untranslated child, or a child isn't under the layout's translation | Translate the child under the layout's prefix |
| `route-collision` | A translation spells the same URL as another route | Spell one of them differently |
| `route-shadowed` | A translation overlaps a more specific untranslated route | Translate that route too, or add an identity entry |
**Content URLs**, also at build time. These start with `[VitNode content URLs]` and are a `ContentUrlError`:
| Code | Cause | Fix |
| :----------------------------- | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `content-url-without-page` | A content type's `delivery.path` or `search.pathTemplate` has no page route serving it | Add a page at that path, point the setting at an existing page, or turn it off |
| `invalid-content-types-module` | A plugin's `content` module doesn't export a `contentTypes` array | Export the plugin's `defineContentType` definitions, or delete the module |
**Content declarations**, when the API boots (`VitNodeAPI`), also a `ContentUrlError`:
| Code | Cause | Fix |
| :----------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| `content-module-missing` | The plugin publishes content URLs, but its `./content` module wasn't found where the API looked | Export the content types from a browser-safe module and expose it as `./content` |
| `incomplete-content-types` | The loaded module leaves a published content type out, or declares it with a different URL | Add it to that module's `contentTypes`, and register those same definitions in the API |
| `invalid-content-types-module` | The module doesn't export a `contentTypes` array, or (separate API) Node.js can't `require` it | Export the array; run Node.js 22.12+ and keep top-level `await` out of the module |
## Migration notes [#migration-notes]
If you ran `never` with several languages on one host and let a cookie pick
the language, the app now stops with `ambiguous-never-prefix`. Either add
`domains` with one locale each, or switch to `localePrefix: 'as-needed'` so
Polish lives at `/pl/...`. Old unprefixed links keep serving the default
language.
- **`search.pathTemplate` no longer needs `{locale}`.** Write `/blog/article/{slug}`. A legacy leading `/{locale}/` is still accepted and stripped. `{locale}` anywhere else is an error. Then rebuild the search index.
- **Content URLs in the default locale are unprefixed** under `as-needed`. Canonical URLs, hreflang and sitemaps used to emit `/en/...` for every record, and now emit `/...`. Old `/en/...` links redirect with a 308.
- **Every content URL needs a page, and every plugin with public content ships a `./content` module.** A plugin that registers content types with delivery or search must export them as `contentTypes` from a browser-safe module exposed as `./content`. Until it does, the API refuses to boot with `content-module-missing`, which names each content type and URL. That's deliberate: the alternative is a site publishing links nobody checked. Every URL in that module then needs a page route (`content-url-without-page`). Blog now ships its `/blog/article/:slug` page. Plugins without public content are unaffected.
- **Single apps pass `contentModules`.** Add `import { contentModules } from './content-modules.gen'` and `contentModules` to `buildApiConfig` in `src/vitnode.api.config.ts`. The file is generated by `dev` and `build`. Without it the API falls back to resolving packages at runtime, which a bundled production server can't do.
- **A split API needs the same routing config.** In a single app, `vitnode.api.config.ts` reuses `vitNodeConfig.i18n`, so nothing to do. In a separate API app (`apiMonorepo` or `onlyApi` in `create-vitnode-app`), its own `i18n` must mirror `localePrefix`, `domains` and `routePaths`. Otherwise canonical URLs, sitemaps and search links built by the API won't match the site.
```ts title="apps/api/src/i18n.ts"
export const i18n = {
defaultLocale: 'en',
locales: [
{ code: 'en', name: 'English' },
{ code: 'pl', name: 'Polski' },
],
// [!code ++:6]
localePrefix: 'as-needed',
routePaths: {
pl: {
'/discover': '/odkrywaj',
},
},
timeZone: 'UTC',
messages: {},
} satisfies VitNodeI18nConfig
```
## Learn More [#learn-more]
# Messages & ICU Syntax (/docs/dev/i18n/messages)
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
# Namespaces (/docs/dev/i18n/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.
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).
## 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.
The symptom of a namespace that was never asked for. Check that the route
declares it in the plugin's `routes.ts`.
`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.
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.
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 `
## Next [#next]
# Translating Pages (/docs/dev/i18n/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 {t('title')}
}
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"
}
}
}
```
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.
## 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 (
{t('greeting', { name: 'Alex' })}
{t('items', { count: 3 })}
)
```
`core.global` is provided by the root shell to every route, supplying shared
strings for dialogs, toasts, and buttons.
## Learn More [#learn-more]
# API i18n (/docs/dev/i18n/server)
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') })
```
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.
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`:
### 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.
### The signed-in user's language [#the-signed-in-users-language]
`core_users.language`, already loaded on `c.get("user")`.
### 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`.
### `defaultLocale` [#defaultlocale]
`en` unless your `i18n` config says otherwise.
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]
Promise',
},
getMessages: {
description: 'The merged message tree, if you need the raw object.',
type: '(locale?: string) => Promise',
},
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 => {t('welcome.email.body')}
}
```
## 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. That one is registered twice, and the two halves are not interchangeable:
```ts title="plugins/{your_plugin}/src/config.tsx"
import messages from './locales'
export const yourPlugin = () =>
buildPlugin({
manifest,
localeFiles: {
// [!code ++:2]
en: '@acme/your-plugin/locales/en.json',
},
messages,
})
```
`messages` is your own barrel, whose `import('./en.json')` is relative to your build output - right for anything running inside your package, and a specifier no host bundler can follow. `localeFiles` is the same list written as the subpaths your `package.json` exports, and it is what an app's translations are actually loaded from: the app's build turns it into literal imports in `src/package-messages.gen.ts`. Ship both, and keep them in step.
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({
manifest,
messages, // [!code ++]
modules: [postsModule],
})
```
Adding a language later is a new file plus one line in each list that names it - 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)"
///
Everything a plugin ships belongs under its own namespace, or it will collide
with core. See [Namespaces](/docs/dev/i18n/namespaces).
## 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 (/docs/dev)
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. */}
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.
## Start with a running app [#start-with-a-running-app]
## Create an app [#create-an-app]
```bash tab="bun"
bun create vitnode-app@canary
```
```bash tab="pnpm"
pnpm create vitnode-app@canary
```
```bash tab="npm"
npm create vitnode-app@canary
```
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]
# Mobile Navigation (/docs/dev/mobile-navigation)
On a phone, the desktop header's navigation has nowhere to go. So below the
`sm` breakpoint (640px) VitNode splits it in two: your most-used links move to a
**floating bottom bar** pinned to the bottom of the screen - the kind your thumb
already knows from native apps - and everything else lives in a **side drawer**
behind the user button at the top.
Both menus come from the `navigation` option in `src/vitnode.config.ts`. See
[Main Navigation](/docs/dev/navigation) for the item options.
{/* Image prompt: A phone-sized light-mode screenshot of a community site. At the bottom floats a white, fully rounded bar with a soft shadow and four equal tabs - "Home", "Discover", "Search" and a hamburger "Menu" tab, with icons above small labels, the active "Search" tab tinted blue on a light gray pill. Top right in the header sits a small round user avatar. Neutral grays, blue accent, 390x844. */}
## Two menus, one config [#two-menus-one-config]
| Key | Where visitors see it | Holds |
| :---------------- | :---------------------------------------------------------------------- | :------------------------------------------------- |
| `header` | In the header on tablets and desktops, and in the side drawer on phones | Any number of items, with dropdowns one level deep |
| `mobileBottomBar` | Pinned to the bottom of the screen, on phones only | Up to three links, no dropdowns, plus a Menu tab |
A page can sit in both menus at once - Search in the header _and_ in the bottom
bar is a perfectly normal choice.
```ts title="src/vitnode.config.ts"
import { CompassIcon, MessagesSquareIcon, SearchIcon } from 'lucide-react'
export const vitNodeConfig = buildConfig({
// ...
navigation: {
header: [
// ...
],
// [!code ++:5]
mobileBottomBar: [
{ href: '/forum', icon: MessagesSquareIcon, title: 'app.menu.forum' },
{ href: '/discover', icon: CompassIcon, title: 'app.menu.discover' },
{ href: '/search', icon: SearchIcon, title: 'app.menu.search' },
],
},
})
```
A fourth link stops the app at startup with a `[VitNode navigation]` error, so
the bar never silently drops one.
## The bottom bar [#the-bottom-bar]
Each link is an icon above a short label. The current page is tinted and sits
on a highlight that slides between tabs. A tab counts as current when the URL is
its address or anything below it, so `/blog/article/my-first-post` keeps a Blog tab lit
(`/` only matches the home page itself).
The last tab is always **Menu**. It opens a drawer from the bottom with the
rest of the Header menu - everything the bar does not already show, dropdowns
included. On a page that lives in there, the Menu tab is the one lit. If the bar
already covers every header link, the Menu tab steps aside.
An empty bottom bar is not drawn at all. That is the default when
`navigation.mobileBottomBar` is missing, so phones start with just the header and its
side drawer until you add a link.
At 320px each of the four tabs gets about 72px, which fits one word like
"Discover" or "Settings" - longer labels are cut off with an ellipsis. A link
without an icon shows the first letter of its label instead. The two menus
are separate lists, so a bottom bar link can point at a shorter message key
than the same page in the header.
## The side drawer [#the-side-drawer]
The user button stays at the top of the header, where it always was. On a phone
it shows the member's avatar (or a person icon for guests), and a tap slides a
drawer in from the side with:
- the member's name and email, linking to their profile - or **Login** and
**Register** buttons for guests,
- the **full Header menu**, dropdowns included - only while the bottom bar is
empty, since otherwise its Menu tab already has it,
- the account links from the desktop user menu (profile, files, settings,
AdminCP for admins),
- theme and language switches,
- **Log out**.
Swipe it away, tap outside it, press Esc or hit the close button.
Desktop is untouched: the same button still opens the usual dropdown there.
{/* Image prompt: A phone-sized dark-mode screenshot of a side drawer covering the right five-sixths of the screen over a blurred page. At the top "Menu" with a close X, then a rounded card with a round avatar, the name "Ada" and an email, a "Navigation" list with icons and the current item highlighted, an "Account" list (My Profile, My Files, Settings), and a Light / Dark / System segmented control. Neutral grays, blue accent, 390x844. */}
## For developers [#for-developers]
- **No API involved.** The header reads both menus from the config in the
browser and on the server, so they render with the page, prerendered pages
included.
- **Room at the bottom.** While the bar is on screen, the page gets extra
bottom padding so it never covers your footer.
- **Notches and home indicators.** The bar sits above the iPhone home indicator
via `env(safe-area-inset-bottom)`, which needs `viewport-fit=cover` in your
viewport meta tag. New apps have it; in an older app, update the viewport
entry in `src/routes/__root.tsx`:
```ts title="src/routes/__root.tsx"
{ content: 'width=device-width, initial-scale=1, viewport-fit=cover', name: 'viewport' },
```
- **Translations.** The drawer's own words - "Menu", "Navigation", "Account" -
live under `core.global.mobile_nav`. See [Languages & Localization](/docs/dev/i18n)
to translate them. Link titles are message keys from your own locale files.
# Configure moderators (/docs/dev/moderation/configure-moderators)
You set up moderators on the same AdminCP screen as every other staff permission. This guide makes a user a moderator who handles blog reports everywhere and example article reports only in some categories.
## Before you begin [#before-you-begin]
You need the `staff_moderators` admin permissions **Create moderators** and **Edit moderator permissions**, or a root role. The content types you want moderated must have [reports enabled](/docs/dev/moderation/enable-reports).
### Add the moderator [#add-the-moderator]
Open **AdminCP → Staff → Moderators** and choose **Add Moderator**. Pick a role or a single user and save. The new entry grants nothing yet, and the AdminCP opens its permissions.
### Grant report permissions [#grant-report-permissions]
Keep **Restricted** selected. Pick a plugin on the left, open a module, and tick the permissions. For the blog, open **Articles** and tick **View article reports**, **Claim, assign and resolve article reports**, **Open hidden articles** and **Hide and unhide articles**.
A permission that depends on another one stays locked until its dependency is ticked. **Hide and unhide articles** needs **Open hidden articles**, so a moderator can always see what they hid.
### Choose where a scoped permission applies [#choose-where-a-scoped-permission-applies]
A scoped permission shows its scope under the checkbox: **All resources**, or the number of selected resources. Here the example plugin's **View reports** covers two categories and the management permission covers one:
### Save [#save]
Choose **Save changes**. The moderator's permissions apply on their next request. If a resource no longer exists, the picker marks it **Removed**. Take it out before saving.
## Check the result [#check-the-result]
Sign in as the moderator. The user menu now has a **Moderator CP** link to `/modcp/reports`, and the reports board shows blog reports plus example article reports from the two selected categories only. See [Process reports](/docs/dev/moderation/process-reports).
## When saving is refused [#when-saving-is-refused]
The form checks scopes before it sends them, and the API checks them again. Each problem is shown under the permission it belongs to:
| Message | What to change |
| ---------------------------------------------------------- | -------------------------------------------------------------- |
| Choose where *permission* applies | Open **Change** and pick **All resources** or some resources |
| Pick at least one resource for *permission* | A selection cannot be empty |
| *Permission* reaches further than *dependency* | Narrow the permission, or widen its dependency first |
| *Permission* names resources that no longer exist | Remove the resources marked **Removed** |
You can only grant what you hold yourself. An administrator whose own moderator permissions cover two categories cannot give a third one, or **All resources**, to somebody else. Only a root administrator can grant **Unrestricted**. Changing a role's permissions or a user's roles takes effect immediately. VitNode clears the cached permissions of every affected user.
# Enable reports (/docs/dev/moderation/enable-reports)
Readers report content with a **Report** button, and every report lands in the moderators' queue. How you turn it on depends on what is being reported:
| What readers report | Guide |
| ------------------------------------------- | --------------------------------------------------------------------------------------- |
| Records of a Content Engine content type | [Report content](/docs/content-engine/reports): the `reports` option and `ReportButton` |
| Anything else your plugin stores | [Custom report targets](/docs/dev/moderation/reference#custom-report-targets) with `defineReportTarget` |
Then set up the people who handle the reports:
1. [Manage report reasons](/docs/dev/moderation/manage-report-reasons) to choose what readers can pick.
2. [Configure moderators](/docs/dev/moderation/configure-moderators) to give someone `can_view_reports` and `can_manage_reports`.
3. [Process reports](/docs/dev/moderation/process-reports) to work the queue in the ModCP.
# Moderation (/docs/dev/moderation)
VitNode moderation lets signed-in users report content, and lets moderators review those reports and act on the content from the public site. It is built from three parts that core provides and any plugin can use: reports, the **Moderator CP** (ModCP) and scoped moderator permissions.
| Part | What it does |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| Reports | A report stores the reason, the reporter's details and a server-side snapshot of what the reporter saw |
| Moderator CP | `/modcp/reports` on the public site: a reports board, the snapshot, assignment, notes, resolution and content actions. `/modcp/approvals` holds content waiting for approval |
| Scoped permissions | A moderator permission can cover every resource of a family, such as every forum section, or only some of them |
A moderator signs in with their normal user session. The ModCP never asks for an AdminCP session, and the server authorizes every ModCP request.
## Choose a guide [#choose-a-guide]
| You want to | Read |
| --------------------------------------------------------------- | ------------------------------------------------------------------- |
| Let readers report a Content Engine content type, like the blog | [Enable reports](/docs/dev/moderation/enable-reports) |
| Choose the reasons members pick from when they report | [Report reasons](/docs/dev/moderation/manage-report-reasons) |
| Limit moderators to some categories or sections | [Scoped permissions](/docs/dev/moderation/scoped-permissions) |
| Give a user or role moderator permissions in the AdminCP | [Configure moderators](/docs/dev/moderation/configure-moderators) |
| Review, assign, resolve and act on reports | [Process reports](/docs/dev/moderation/process-reports) |
| Approve or reject new content and edits before they go live | [Review approvals](/docs/dev/moderation/review-approvals) |
| Look up routes, options, events and limits | [Moderation reference](/docs/dev/moderation/reference) |
## How the parts fit together [#how-the-parts-fit-together]
1. A content type opts in with `reports: true`. This registers a **report target** and adds report permissions to the moderator catalog. Nobody holds them until an administrator grants them.
2. A reader clicks **Report** on the article page. The browser sends only the article id, the language, the reason and the details. The server checks that the reader can read the article, then stores a snapshot of it.
3. A moderator opens the ModCP. The reports board shows only reports the moderator may view, filtered before anything is counted.
4. The moderator takes the report, writes internal notes, hides the article if needed and closes the report with an outcome. Every step lands in the report's timeline.
Reports belong to core, not to the plugin. They keep their snapshot after the article is edited, after its revisions are pruned, after it is deleted and even after its plugin is uninstalled.
## What is not included yet [#what-is-not-included-yet]
This version covers reports, hiding and restoring content, and [reviewing approvals](/docs/dev/moderation/review-approvals). It has no warnings, bans, automatic moderation, anonymous reports, report notifications or permanent deletion from the ModCP. Moderators still have to read things themselves, sorry.
# Report reasons (/docs/dev/moderation/manage-report-reasons)
Report reasons are the choices a member sees first in the report dialog, like **Spam** or **Abusive content**. You manage them in the AdminCP, with a title and a description in every language your site serves, so the list fits your community instead of a fixed one.
A new installation starts with four reasons: **Spam**, **Abusive content**, **Rule violation** and **Other**. **Other** asks the member to explain. Sites upgraded from the fixed list get the same four on their next `pnpm db:migrate`, and existing reports keep their reason.
## Before you begin [#before-you-begin]
You need the **Report reasons** admin permissions, or a root role. Each permission covers one action: **View report reasons**, **Create report reasons**, **Edit and reorder report reasons** and **Delete report reasons**. Grant them in **AdminCP → Staff → Administrators**.
### Open the list [#open-the-list]
Open **AdminCP → Moderation → Report reasons**. The list is in the order members see it, and the **Details** column shows which reasons make the member explain.
### Add a reason [#add-a-reason]
Choose **Add reason**. Write a short **Title** and a one-line **Description**, then pick another language from the menu next to each field to translate it. A language you leave empty falls back to the site's default language.
Turn on **Require details** when moderators cannot act on the reason without an explanation, as with **Other**. The member then has to write at least 10 characters before the report is sent.
### Put the most common reason first [#put-the-most-common-reason-first]
Drag a row by its handle to move it. With a keyboard, focus the handle, press Space, move with the arrow keys and press Space again to drop. The order saves on drop.
## Edit or delete a reason [#edit-or-delete-a-reason]
Choose the pencil to edit a reason. Reports already filed with it show the new title, because a report stores which reason was picked, not its text.
Choose the trash can to delete a reason. Members can no longer pick it, and reports filed with it stay, labeled **Removed reason** in the [Moderator CP](/docs/dev/moderation/process-reports).
## Limits [#limits]
- At most 10 reasons. **Add reason** is disabled at 10 and the API refuses an 11th with `409 limit_reached`.
- At least one reason. The last one cannot be deleted (`409 last_reason`), so the dialog always has something to offer.
- Titles are up to 100 characters, descriptions up to 255.
## Check the result [#check-the-result]
Open a published article as a signed-in member and choose **Report**. The dialog lists your reasons in your order, in the member's language, and a reason with **Require details** asks **What should moderators know?** before **Send report**.
The routes and events behind this page are in the [moderation reference](/docs/dev/moderation/reference#report-reasons).
# Process reports (/docs/dev/moderation/process-reports)
The **Moderator CP** at `/modcp/reports` is where moderators work through reports, signed in with their normal account. This guide takes a spam report about a blog article from new to closed.
## Before you begin [#before-you-begin]
You need a moderator entry with `can_view_reports` for the content type, and `can_manage_reports` to change anything. Hiding needs `can_hide`. See [Configure moderators](/docs/dev/moderation/configure-moderators).
### Open the board [#open-the-board]
Choose **Moderator CP** in the user menu. **Reports** is a board with three columns, **New**, **In progress** and **Done**. It holds the reports you may view, newest first in each column:
### Read the report [#read-the-report]
Open a report. The heading names the content type and its author. The main card starts with the **Description**, the reporter's own words, followed by the **Snapshot**, which is what the reporter saw at the moment they filed it. Choose **View full snapshot** to read it in a side panel. It never changes, even if the article was edited, its revisions were pruned or it was deleted.
On the right, **Details** opens with the reported content: its type, its title linked to the live page and the plugin it belongs to. Below are the assignee, the reporter and the author with their role colors, the reason and the **Visibility** of the content right now. **Linked reports** lists other reports about the same content, each with its reporter and the start of their text.
### Take the report [#take-the-report]
Drag the card from **New** to **In progress**, or open the report and choose **Start progress** in the status button (**New**), or **Assign to me** under the assignee. The report is assigned to you and moves to **In progress**. To hand it over, open the assignee and pick another moderator; the list shows only moderators who may manage this report. **Stop progress** unassigns you and moves it back to **New**.
When two moderators take the same report at once, one wins and the other sees **Another moderator took this report first**. Every change carries the version you loaded, so acting on a stale page refreshes it instead of overwriting someone else's work.
### Note and act [#note-and-act]
Under **Activity**, choose **Add an internal note** or press `M`. Notes use the rich-text editor, and `Cmd+Enter` (`Ctrl+Enter` on Windows) saves them. They are visible to moderators only, never to the reporter or the author. **Notes** is the tab that opens first; **All** and **History** show the rest of the activity.
To change a note, open its **…** menu and choose **Edit** or **Delete**. You can always edit and delete your own notes. Editing or deleting another moderator's notes needs `can_edit_notes` or `can_delete_notes`. An edited note shows **(edited)**, and **History** records every edit with the text before and after, and every deletion with the removed text.
Open **Actions** next to the status button, choose **Hide content** and confirm. The article leaves the public site, search and the sitemap at once, exactly like [hiding it from the AdminCP](/docs/content-engine/content-visibility). It gets a revision, the `hidden` event fires and VitNode revalidates the caches. The activity records the action only when it succeeds. **Restore content** brings it back.
### Close the report [#close-the-report]
Drag the card to **Done**, or open the status button on the report and choose **Close report**. Pick an outcome, **No violation**, **Action taken** or **Duplicate**, and add an explanation for the other moderators if you like. When you already hid the content, **Action taken** is picked for you. **Close report** moves it to **Done**. Other reports about the same content stay open, because each reporter's report closes on its own.
On a closed report, the status button offers **Reopen**, which needs a reason that goes into the activity. Dragging the card out of **Done** asks for the same reason.
## Check the result [#check-the-result]
The report sits in the **Done** column, and its activity lists the report, the assignment, your note, the hide and the resolution with names and times. Open the article signed out: it answers `404` while hidden. Open it as the moderator: it loads with the hidden notice, because `can_view_hidden` lets moderators inspect hidden content without any AdminCP edit permission.
## Who sees what [#who-sees-what]
- **Reporters** see only their own toast. Nothing about the report is public.
- **Moderators** with `can_view_reports` see the report, the reporter's name, the snapshot and the activity, for content in their scopes. Without it, a direct URL answers like a report that does not exist.
- **Moderators** with `can_manage_reports` can also take, reassign, note, resolve and reopen, and edit or delete their own notes.
- **Moderators** with `can_edit_notes` or `can_delete_notes` can edit or delete any moderator's notes.
- **Authors** of the reported content never learn who reported it.
When content moves to a resource outside a moderator's scope, the report moves with it. The moderator loses access, and if the report was assigned to them, VitNode unassigns it and logs that in the activity. When the content is deleted, the report keeps its last known scope.
# Moderation reference (/docs/dev/moderation/reference)
Exact names, types and behavior of the moderation APIs. For step-by-step guides, start at [Moderation](/docs/dev/moderation).
## `reports` on a content type [#reports-on-a-content-type]
`defineContentType({ reports })` from `@vitnode/core/content`. Omitted or `false` registers nothing.
| Name | Type | Required | Default | Description |
| ---------------- | ------------- | -------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `titleField` | field name | No | `admin.titleField` when it is in `publicApi.fields`, else none | A `text`, `textarea` or `slug` field |
| `snapshotFields` | field names | No | Public `text`, `textarea`, `richText`, `enum` and `file` fields, without the title | Fields of kind `text`, `textarea`, `richText`, `slug`, `number`, `boolean`, `enum`, `dateTime` or `file` |
`reports: true` uses both defaults. It throws without `publicApi`, for an unknown option, for `reports.enabled`, and for a field that does not exist or cannot be snapshotted.
The server-side model can scope reports with `createContentModel(definition, { moderationScope: { column, family } })`, where `column` is a base-table column holding the resource id. A content type that reaches its container through a relation, such as a forum comment through its topic, has no such column, so its report permissions stay unscoped.
## Generated moderator permissions [#generated-moderator-permissions]
Added to the content type's `permissionModule` in the **moderator** catalog, unless the plugin declares that moderator module itself. All of them carry the target's scope family when it has one.
| Permission | Depends on | Added when | Allows |
| -------------------- | ------------------ | ---------------------------- | --------------------------------------------------- |
| `can_view_reports` | | Always | The reports board, report details and related reports |
| `can_manage_reports` | `can_view_reports` | Always | Take, reassign, notes, resolve, reopen; edit and delete your own notes |
| `can_edit_notes` | `can_manage_reports` | Always | Edit any moderator's notes |
| `can_delete_notes` | `can_manage_reports` | Always | Delete any moderator's notes |
| `can_view_hidden` | | The target can be hidden | Opening hidden content on the public site |
| `can_hide` | `can_view_hidden` | The target can be hidden | **Hide content** and **Restore content** in the ModCP |
Content actions also need `can_manage_reports`, because they are recorded in the report.
[Public write](/docs/content-engine/public-write-api#moderator-permission) adds `can_edit` to the same module. In a container collection with [publishing policies](/docs/content-engine/container-policies), `can_edit` and `can_approve` are scoped by the collection's family, whose id is the container definition id and whose resources are container ids and `"{id}:tree"` subtrees. See [Container-scoped permissions](/docs/dev/moderation/scoped-permissions#container-scoped-permissions). Generated entries merge with the report permissions; only a module the plugin declares itself in `permissionStaff.moderator` is left as declared.
## Scoped grants [#scoped-grants]
A stored grant is `{ plugin, module, permission, scope? }`. `scope` is one of:
```ts
{ family: "example.category", mode: "all" }
{ family: "example.category", mode: "selected", ids: ["1", "2"] }
```
Declare a scoped permission with `{ permission, dependsOn?, scope: "family.id" }` in `permissionStaff.moderator`. Admin permissions cannot be scoped. Resource ids match `/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/`.
`PATCH /api/@vitnode/core/admin/staff/entry/moderator/{id}` answers `400` with `{ error: "invalid_permissions", issues }`. Each issue has a `key` and a `type`: `missing_scope`, `empty_selection`, `invalid_resource`, `unknown_resource`, `unexpected_scope`, `wrong_family` or `dependency_scope`. A grant wider than the caller's own permissions is `403`.
`GET /api/@vitnode/core/users/permissions` returns the signed-in user's moderator grants, each with its `scope`.
## `defineModerationScope` [#definemoderationscope]
From `@vitnode/core/api/moderation`. Register with `buildApiPlugin({ moderation: { scopes } })`.
| Name | Type | Required | Description |
| ------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
| `id` | `string` | Yes | Lowercase and dot separated, unique across plugins |
| `label` | `string` | Yes | i18n key |
| `description` | `string` | No | i18n key shown in the picker |
| `list` | `(c, { cursor, limit, search }) => Promise<{ items, nextCursor }>` | Yes | One page of resources for the AdminCP picker |
| `find` | `(c, ids) => Promise` | Yes | The resources with these ids that exist |
An item is `{ id: string; label: string; context?: string[] }`. The AdminCP reads them through `GET /api/@vitnode/core/admin/staff/scope-resources/{family}?search=&cursor=`, or `?ids=1,2` to label a saved selection, which also returns `missing` ids.
## Custom report targets [#custom-report-targets]
Content Engine types register their target automatically. Anything else registers one with `defineReportTarget` and `buildApiPlugin({ moderation: { reportTargets } })`.
| Name | Type | Required | Description |
| ------------------ | ------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `type` | `string` | Yes | Stable id stored in reports, such as `forum.topic` |
| `label` | `string` | Yes | i18n key for the kind of thing, an ICU plural called with `count: 1` |
| `permissionModule` | `string` | Yes | Moderator module the report permissions are added to |
| `parseId` | `(value) => string \| null` | Yes | Validates a client id before anything reads it |
| `capture` | `(c, { targetId, locale }) => Promise` | Yes | The snapshot body, or `null` when the reporter cannot read the target |
| `current` | `(c, { targetId, locale }) => Promise<{ hidden, url } \| null>` | Yes | The target now, or `null` once deleted |
| `scope` | `string` | No | Scope family id |
| `resolveScope` | `(c, targetId) => Promise` | With `scope` | The resource id now, `""` for none, `undefined` once deleted |
| `actions` | `{ hide?, unhide? }` | No | `{ permission, available(state), run(c, { actorUserId, targetId, tx }) }` |
`run` executes inside the report's transaction and returns `{ changed, effects }`. `effects` runs after the commit. When `run` throws, the transaction rolls back and no timeline entry is written.
## Report UI [#report-ui]
Public pages report a target with the components from `@vitnode/core/tanstack/moderation`. Both load their own messages (`REPORT_NAMESPACES`) and lazy-load the form, and both show a **Sign in** link instead of the form to guests. For a walkthrough, see [Enable reports](/docs/dev/moderation/enable-reports).
### `contentTarget` [#contenttarget]
`contentTarget(pluginId, definition, id)` from `@vitnode/core/content` returns the `ContentTarget` of one record: `{ pluginId, type, id }`, where `type` is `definition.id` and `id` is the record id as a string. A custom report target uses the same shape with its own `type`.
### `ReportButton` [#reportbutton]
A ghost button labelled **Report** that opens the dialog. Its accessible name is "Report `typeLabel`".
| Name | Type | Required | Default | Description |
| ----------------- | ---------------- | -------- | ------- | --------------------------------------------------------------------------- |
| `target` | `ContentTarget` | Yes | | The reported record |
| `typeLabel` | `string` | Yes | | What the item is called, already translated, for "Report `typeLabel`" |
| `describedBy` | `string` | No | | Id of the element naming the item, read after the label so list buttons differ |
| `locale` | `string \| null` | No | `null` | The locale the reader was served, for moderators |
| `requestedLocale` | `string \| null` | No | `null` | The locale the reader asked for, when the content fell back to another |
| `preview` | `ReportPreview` | No | | What the reader is reporting, shown at the top of the dialog: `{ title, imageUrl?, meta? }`, already translated |
| `className` | `string` | No | | Classes for the button |
### `ReportDialog` [#reportdialog]
The same dialog, controlled by you. Use it for your own trigger, such as a menu item, or to share one dialog across a long list. It takes `target`, `typeLabel`, `locale`, `requestedLocale` and `preview` like `ReportButton`, plus `open: boolean` and `onOpenChange(open: boolean)`.
```tsx
import type { ContentTarget } from "@vitnode/core/content";
import { ReportDialog } from "@vitnode/core/tanstack/moderation";
const [reporting, setReporting] = useState(null);
{reporting ? (
{
if (!open) setReporting(null);
}}
open
target={reporting}
typeLabel={t("report_type")}
/>
) : null}
```
The dialog has three screens: pick a reason, add details, and **Report sent**. Picking a reason with a click, tap, Space or Enter moves on; arrow keys only move the selection. A failure shows a toast with a description: already reported (`409 duplicate`), no longer available (`404`), too many reports (`429`), session ended (`401`), reason just removed (`400 reason_not_found`, back to the reasons), missing details (`400 details_required`) and anything else.
## Report lifecycle [#report-lifecycle]
| Status | Reached by |
| ------------- | -------------------------------------------------- |
| `new` | Filing a report, unassigning, or reopening an unassigned report |
| `in_progress` | Taking or assigning a report, or reopening an assigned one |
| `done` | Resolving with `no_violation`, `action_taken` or `duplicate` |
A report stores its reason's `code`. Admins manage the reasons in [Report reasons](/docs/dev/moderation/manage-report-reasons); the four starter codes are `spam`, `abusive`, `rule_violation` and `other`, and only a reason with `requiresDetails` needs details. Every change except a note needs `expectedVersion`. A stale version answers `409` with `{ error: "conflict", current }`, and taking a report someone else holds answers `409 already_claimed`.
## ModCP API routes [#modcp-api-routes]
All under `/api/@vitnode/core/moderation`, using the user session. A guest gets `401`, a user without a moderator entry `403`, and a report outside the moderator's scopes `404`.
| Method and path | Permission | Body |
| ------------------------------------ | -------------------- | -------------------------------------------- |
| `GET /reasons` | Anyone | Returns `{ reasons }` in display order, each `{ id, code, requiresDetails, title, description }` with every translation as `{ languageCode, value }[]` |
| `POST /reports` | Signed in | `{ pluginId, targetType, targetId, locale?, requestedLocale?, reason, description? }`, where `reason` is a reason `code` |
| `GET /reports` | `can_view_reports` | Query `status`, `assigned`, `search`, `page`, `pageSize` |
| `GET /reports/{id}` | `can_view_reports` | |
| `POST /reports/{id}/claim` | `can_manage_reports` | `{ expectedVersion }` |
| `POST /reports/{id}/assign` | `can_manage_reports` | `{ expectedVersion, assigneeId }` |
| `POST /reports/{id}/notes` | `can_manage_reports` | `{ body }`: plain text or a rich-text document |
| `POST /reports/{id}/notes/{noteId}/edit` | `can_manage_reports` and the note's author, or `can_edit_notes` | `{ body }` |
| `POST /reports/{id}/notes/{noteId}/delete` | `can_manage_reports` and the note's author, or `can_delete_notes` | |
| `POST /reports/{id}/resolve` | `can_manage_reports` | `{ expectedVersion, resolution, explanation? }` |
| `POST /reports/{id}/reopen` | `can_manage_reports` | `{ expectedVersion, reason }` |
| `POST /reports/{id}/actions/{action}` | `can_manage_reports` and the action's permission | `{ expectedVersion }` |
| `GET /reports/{id}/assignees` | `can_manage_reports` | |
## Report reasons [#report-reasons]
The AdminCP routes behind [Report reasons](/docs/dev/moderation/manage-report-reasons), under `/api/@vitnode/core/admin/report-reasons`, using the AdminCP session. Each needs the matching `report_reasons` admin permission.
| Method and path | Permission | Body | Success |
| ---------------- | ------------ | ------------------------------------------------- | ------------------ |
| `GET /` | `can_view` | | `{ reasons }` with `position` |
| `POST /create` | `can_create` | `{ title, description, requiresDetails }` | `201 { id }`, added last |
| `PATCH /{id}` | `can_edit` | Any of `{ title, description, requiresDetails }` | `{ id }` |
| `PUT /reorder` | `can_edit` | `{ ids }`: every reason id once, in the new order | `200` |
| `DELETE /{id}` | `can_delete` | | `200` |
`title` and `description` are `{ languageCode, value }[]`. `title` needs at least one value. Empty values are dropped, and a missing language falls back to the default language in the dialog. A new reason gets a generated `code`.
| `error` | Status | When |
| --------------- | ------ | ------------------------------------------- |
| `limit_reached` | `409` | Creating an 11th reason |
| `last_reason` | `409` | Deleting the only reason left |
| `mismatch` | `400` | `ids` misses, repeats or invents a reason |
| `not_found` | `404` | No reason with that id |
## Approval routes [#approval-routes]
Also under `/api/@vitnode/core/moderation`, for [approvals](/docs/content-engine/approvals). The queue routes need a moderator entry and show only submissions in containers where the moderator holds `can_approve`; anything else answers `404`, so its existence is not revealed. Every response is `Cache-Control: private, no-store`.
| Method and path | Permission | Input | Success |
| -------------------------------- | ------------- | ------------------------------------------------------------------------- | ---------------------------------- |
| `GET /approvals` | `can_approve` | Query `status` (default `pending`), `contentTypeId`, `containerId`, `page`, `pageSize` | `{ items, page, pageSize, total }` |
| `GET /approvals/filters` | `can_approve` | | `{ contentTypes, containers }` the moderator may review |
| `GET /approvals/mine` | Signed in | Query `page`, `pageSize`, `pluginId` (optional, one plugin's submissions only) | The member's own pending, approved and rejected submissions, newest first |
| `GET /approvals/{id}` | `can_approve` | | The submission with `values`, `baseValues`, `current`, `fields`, `record` and `history` |
| `POST /approvals/{id}/approve` | `can_approve` | | `{ id, status }` |
| `POST /approvals/{id}/reject` | `can_approve` | `{ reason? }`, up to 2000 characters | `{ id, status }` |
The pending queue is oldest first; decided statuses are newest decision first. A list item has `id`, `kind`, `status`, `contentTypeId`, `pluginId`, `itemId`, `title`, `author`, `reviewer`, `container` (`{ id, name, slug, path }`), `reason`, `createdAt` and `decidedAt`.
A refused decision answers `{ error, message }`:
| `error` | Status | When |
| ----------- | ------ | ----------------------------------------------------------------------- |
| `notFound` | `404` | No such submission in the moderator's scope |
| `forbidden` | `403` | The record now lives in a container where the moderator cannot approve |
| `decided` | `409` | The submission is no longer `pending` |
| `gone` | `409` | The record was deleted. The submission becomes `cancelled` |
| `stale` | `409` | The record changed since the proposal, or the proposal no longer validates |
Statuses are `pending`, `approved`, `rejected`, `superseded` (replaced by the author's newer proposal) and `cancelled` (the record was deleted first). The constants are `CONTENT_SUBMISSION_STATUSES`, `CONTENT_SUBMISSION_KINDS` and `CONTENT_SUBMISSION_DECISION_CODES` from `@vitnode/core/content`. Server code can decide one with `decideContentSubmission(c, { decision, id, reason?, reviewerId })` from `@vitnode/core/content/server`, which throws `ContentSubmissionDecisionError` with the same `code` and `status`.
## Events [#events]
| Event | Payload |
| ----------------------------- | ------------------------------------------------------------- |
| `moderation.report.created` | `{ reportId, pluginId, targetType, targetId, reason }` |
| `moderation.report.assigned` | `{ reportId, assigneeId, previousAssigneeId }` |
| `moderation.report.action` | `{ reportId, action, pluginId, targetType, targetId }` |
| `moderation.report.resolved` | `{ reportId, resolution }` |
| `moderation.report.reopened` | `{ reportId }` |
| `moderation.report.note_updated` | `{ reportId, noteId }` |
| `moderation.report.note_deleted` | `{ reportId, noteId }` |
| `moderation.report_reason.created` | `{ reasonId, code }` |
| `moderation.report_reason.updated` | `{ reasonId, code }` |
| `moderation.report_reason.deleted` | `{ reasonId, code }` |
| `moderation.report_reason.reordered` | `{ reasonIds }` in the new order |
| `content.approval.submitted` | `{ submissionId, replacedSubmissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId }` |
| `content.approval.approved` | `{ submissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId, reviewerId }` |
| `content.approval.rejected` | `{ submissionId, pluginId, contentTypeId, contentId, containerId, kind, authorId, reviewerId, reason }` |
Adding a note emits no event. Hiding through a report also emits the content type's own `hidden` or `unhidden` event. See [Built-in events](/docs/dev/events/built-in-events#moderation-events).
## Snapshot format [#snapshot-format]
Stored in `core_moderation_reports.snapshot` as JSON, `version: 1`:
| Field | Description |
| ----------- | ---------------------------------------------------------------------- |
| `capturedAt` | When the server captured it |
| `target` | `{ pluginId, type, id }` |
| `title` | The display title |
| `fields` | `{ name, label, kind, value }` with `kind` `text`, `richText`, `file` or `value` |
| `locale` | `{ requested, served, fallback }` |
| `source` | `{ version, updatedAt, publishedAt }` of the captured state |
| `authors` | `{ id, name }` of the record's authors |
| `scope` | The scope resource at capture time, as evidence |
| `url` | The public address at capture time |
| `truncated` | `true` when text was cut to fit |
The snapshot is read in one read-only transaction, so its fields and `source` describe the same state. The ModCP renders every snapshot with a generic viewer that needs no plugin code, and rich text goes through the same element allowlist as the public site.
## Limits [#limits]
| Limit | Value |
| -------------------------------- | ---------- |
| Report details | 2000 characters, at least 10 when the reason requires details |
| Report reasons | 1 to 10; titles up to 100 characters, descriptions up to 255 |
| Plain-text notes, reopen reasons | 3 to 2000 characters |
| Resolution explanations | Optional, up to 2000 characters |
| Rich-text notes | 64 KB, not empty |
| One text value in a snapshot | 20,000 characters |
| Whole snapshot | 256 KB; rich text falls back to plain text, then fields are dropped |
| Reports per user | 20 per hour |
| Open reports per reporter and target | 1 |
| Queue page size | 25 by default, up to 100 |
| Approval queue page size | 25 by default, up to 100 |
| Rejection reason | Optional, up to 2000 characters |
| Pending submissions per record | 1 |
File fields keep `{ id, name, mimeType, size, url }` only. The file's bytes are never copied, so a file deleted later cannot be opened from the report.
## Database [#database]
The migration `20261011193321_add_moderation_reports` adds `core_moderation_reports` and `core_moderation_report_events`. Neither references the reported content, so deleting content keeps its reports. Reporter, assignee and resolver are `ON DELETE SET NULL`, so deleting an account keeps the evidence. The unique `openKey` column enforces one open report per reporter and target, even under concurrent submissions.
The migration `20261019161102_add_moderation_report_reasons` adds `core_moderation_report_reasons` with a unique `code`, `requiresDetails` and `position`. Titles and descriptions live in `core_languages_words`. `core_moderation_reports.reason` holds the reason's `code` without a foreign key, so deleting a reason keeps its reports. `db:prepare` and `db:migrate` add the four starter reasons only while the table is empty.
Approvals live in `core_content_submissions`, one row per submission. Rows are never deleted with the content, author and reviewer are `ON DELETE SET NULL`, and a partial unique index allows one `pending` submission per record. Container policy overrides are stored in `core_content_containers.policies`.
# Review approvals (/docs/dev/moderation/review-approvals)
When a container's [publishing policy](/docs/content-engine/container-policies) asks for approval, new content and edits from members do not go live straight away. They wait in the **Approvals** queue of the Moderator CP at `/modcp/approvals` until a moderator says yes or no. [Approvals](/docs/content-engine/approvals) explains what is stored meanwhile and what authors see.
## Before you begin [#before-you-begin]
You need a moderator entry with `can_approve` for the content type, in a scope that covers the container the content lives in: the container itself, its subtree, or **All resources**. The queue only shows submissions you may decide, so two moderators can see two different queues. See [Container-scoped permissions](/docs/dev/moderation/scoped-permissions#container-scoped-permissions) and [Configure moderators](/docs/dev/moderation/configure-moderators).
### Open the queue [#open-the-queue]
Choose **Moderator CP** in the user menu, then **Approvals**. The number next to it counts what is still pending.
{/* Image prompt: Moderator CP approvals queue with status tabs (Pending, Approved, Rejected, Replaced, Cancelled), Type and Location filters, and a list of submissions showing the author avatar, a New or Edit badge, the content type, the title, the location and the date */}
Each row shows who sent it, whether it is **New** content or an **Edit** of something already live, the content type (a topic or a comment, for example), where it lives and when it arrived.
- The tabs switch between **Pending** and the decided ones: **Approved**, **Rejected**, **Replaced** (the author sent a newer version) and **Cancelled** (the content was deleted first).
- **Type** and **Location** narrow the list to one content type or one container.
Tabs, filters and the page number live in the address, so a filtered queue is a link you can share.
### Read the submission [#read-the-submission]
Open a row. For **New** content you see every proposed field. For an **Edit** you see **Changes**: each changed field shows **Live now** next to **Proposed**, and the untouched fields are folded away below.
**History** lists earlier submissions for the same content, with their outcomes and reasons. **View live** opens published content in a new tab when its content type has a page address (`search.pathTemplate`).
### Decide [#decide]
- **Approve** publishes new content, or applies the edit to the live version. On a content type with [revisions](/docs/content-engine/editorial#revisions), the edit is one new revision.
- **Reject** opens a dialog with an optional **Reason**. Nothing on the site changes, and the author can read your reason and try again.
Either way you land back in the queue with a short confirmation.
## When a decision fails [#when-a-decision-fails]
| Message | What happened |
| --- | --- |
| **Already decided** | Another moderator got there first. |
| **The record changed** | Someone edited the content after the proposal was made. Reject it and ask the author to resubmit. |
| **The content is gone** | It was deleted, so the submission was cancelled. |
| **Out of your reach** | The content moved to a container where you cannot approve. |
| **Submission not found** | It no longer exists, or it is outside what you moderate. |
The detail page warns you when the content is gone or has changed before you click, so surprises should be rare. Rare, not extinct.
# Scoped moderator permissions (/docs/dev/moderation/scoped-permissions)
A scoped moderator permission applies to every resource of a **scope family**, or only to the resources an administrator picks. "View reports in every section" and "hide topics only in section B" are two grants of scoped permissions. This guide uses the example plugin, whose article reports are scoped by category.
## Before you begin [#before-you-begin]
Scopes build on [staff permissions](/docs/dev/working-with-users/staff-permissions) and on reports. If your content type does not report yet, start with [Enable reports](/docs/dev/moderation/enable-reports).
### Register a scope family [#register-a-scope-family]
A scope family tells the AdminCP which resources exist. Create it on the server with `defineModerationScope`:
```ts title="plugins/example/src/api/lib/moderation.ts"
import { defineModerationScope } from "@vitnode/core/api/moderation";
import { and, asc, gt, ilike, inArray } from "drizzle-orm";
import { example_categories } from "@/database/categories";
export const exampleCategoryScope = defineModerationScope({
id: "example.category",
label: "@vitnode/example.moderation.category.label",
description: "@vitnode/example.moderation.category.desc",
list: async (c, { cursor, limit, search }) => {
const rows = await c
.get("db")
.select({ id: example_categories.id, name: example_categories.name })
.from(example_categories)
.where(
and(
cursor ? gt(example_categories.id, Number(cursor)) : undefined,
search ? ilike(example_categories.name, `%${search}%`) : undefined,
),
)
.orderBy(asc(example_categories.id))
.limit(limit + 1);
const page = rows.slice(0, limit);
return {
items: page.map(row => ({ id: String(row.id), label: row.name })),
nextCursor: rows.length > limit ? String(page.at(-1)?.id) : null,
};
},
find: async (c, ids) => {
const numeric = ids.map(Number).filter(id => Number.isSafeInteger(id));
if (numeric.length === 0) return [];
const rows = await c
.get("db")
.select({ id: example_categories.id, name: example_categories.name })
.from(example_categories)
.where(inArray(example_categories.id, numeric));
return rows.map(row => ({ id: String(row.id), label: row.name }));
},
});
```
`list` feeds the picker one page at a time. `find` labels a saved selection and lets the API refuse an id that does not exist. Return `context`, such as `["Games"]`, on each resource to show where a nested resource sits. Both callbacks read the database, so the family never reaches the browser.
### Add it to the plugin [#add-it-to-the-plugin]
Pass the family to `buildApiPlugin`, and translate its label:
```ts title="plugins/example/src/config.api.ts"
buildApiPlugin({
manifest,
moderation: { scopes: [exampleCategoryScope] }, // [!code ++]
modules: [/* ... */],
});
```
```json title="plugins/example/src/locales/en.json"
{
"@vitnode/example": {
"moderation": {
"category": {
"label": "Categories",
"desc": "Limit this permission to articles in some categories."
}
}
}
}
```
Family ids are global. Two plugins registering the same id, or a permission naming a family nobody registers, stops the API at boot with a `ModerationRegistryError`.
### Tell the content model where a record sits [#tell-the-content-model-where-a-record-sits]
On the server-side model, name the base-table column that holds the resource id:
```ts title="plugins/example/src/database/articles.ts"
export const articleContent = createContentModel(articleContentType, {
references: { category: () => example_categories.id },
moderationScope: { column: "category", family: "example.category" }, // [!code ++]
});
```
The report permissions of `example.article` are now scoped by `example.category`. The server reads the column itself, so a client can never claim a record is in another category. The definition in `content/article.ts` stays browser-safe, without callbacks.
## Check the result [#check-the-result]
Save the file while `pnpm dev` runs. Open **AdminCP → Staff → Moderators**, edit a moderator and select the example plugin. **View reports** and **Claim, assign, annotate and resolve reports** now show a scope under the checkbox, and **Change** opens the category picker. See [Configure moderators](/docs/dev/moderation/configure-moderators).
## Container-scoped permissions [#container-scoped-permissions]
A [container collection](/docs/content-engine/containers) with [publishing policies](/docs/content-engine/container-policies) brings its own scope family, so there is nothing to define. The family id is the collection's id, such as `forum.forums`, and its label is the collection's title.
Every content type filed in that collection with [public write](/docs/content-engine/public-write), through `field.container()` or `field.relation({ container: true })`, gets two moderator permissions scoped by it:
| Permission | Added when | Allows |
| ------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `can_edit` | `publicWrite.update` is on | Edit any record in the container from the public site, at any age; create where `create: "moderators"` |
| `can_approve` | `publicWrite` is on | See and decide [approvals](/docs/dev/moderation/review-approvals) there, and skip approval for your own posts |
They merge with the report permissions when the content type also has `reports: true`. Label them in the plugin's locale file. `can_edit` shares its key with the admin permission, and a missing label shows the raw name:
```json title="plugins/forum/src/locales/en.json"
{
"@vitnode/forum:topic:can_edit": "Edit topics",
"@vitnode/forum:topic:can_approve": "Approve topics",
"@vitnode/forum:comment:can_edit": "Edit comments",
"@vitnode/forum:comment:can_approve": "Approve comments"
}
```
### Pick forums or whole subtrees [#pick-forums-or-whole-subtrees]
A resource is either one container or one container with everything below it:
| Resource | Picker label | Covers |
| ----------- | ------------ | ------------------------------------------------------------------------- |
| `"12"` | Help | Container 12 only, never its children |
| `"12:tree"` | Help › * | Container 12 and every container below it, including ones created later |
The `:tree` entry is listed only for a container that has children. A record in container `C` is covered by a grant that names `C`, `C:tree` or the `:tree` of any ancestor, by **All resources**, by an unscoped grant, or by a root role. The server resolves the record's container on every check, and again when a decision is made, so a topic moved to another forum follows its new scope.
A moderator entry on its own grants nothing. Someone flagged as staff, with no `can_edit` or `can_approve` for a forum, edits and approves exactly as much there as any member: nothing beyond their own posts.
## How grants combine [#how-grants-combine]
A user's effective moderator permissions come from their own staff entry and the entries of every role they hold:
- **Grants of one permission merge.** "View reports in A" from a role and "view reports in B" from the user give "view reports in A and B". "All resources" wins over a selection.
- **Permissions never combine across each other.** A role with "hide in A" and a user entry with "view in B" never allow hiding in B. Each permission keeps its own scope.
- **Dependencies are checked per resource.** Managing reports depends on viewing reports, so "manage in A" needs "view in A". Saving "manage in B" with only "view in A" is refused, and if broken data ever gets through, the effective scope of "manage" is cut down to where "view" is held.
- **Root roles and unrestricted entries** still allow everything, in every scope.
`isModerator` in the session means "has a moderator entry". It grants no permission by itself, and the ModCP shows only what the grants allow.
## Compatibility with unscoped grants [#compatibility-with-unscoped-grants]
Unscoped permissions work as before. A grant without a `scope` allows the permission everywhere.
When a plugin later makes an existing permission scoped, grants saved before that change have no scope. They keep meaning **all resources**, and the editor shows them as **All resources**. A new save always needs an explicit scope. The API answers `400` with `missing_scope` instead of guessing that a missing scope means "everything".
## Check a scope in your own code [#check-a-scope-in-your-own-code]
Pass the resource when you check a scoped permission:
```ts
const allowed = await checkStaffPermission(c, {
type: "moderator",
plugin: "@vitnode/example",
module: "article",
permission: "can_view_reports",
resource: { family: "example.category", id: "2" },
});
```
A check without `resource` only passes for an unscoped or an **All resources** grant, so older code can never be widened by a selection. When a record moves to another resource, call `syncModerationReportScope(c, { pluginId, targetType, targetId })` from `@vitnode/core/api/moderation` after the move, so its reports follow it. The ModCP also re-reads the scope every time it opens a report.
# Main Navigation (/docs/dev/navigation)
The links in the site header and in the phone bottom bar come from one place:
the `navigation` option in `src/vitnode.config.ts`. There is no database
table, no API call and no AdminCP screen behind them, so the menu renders with
the page, even on a [prerendered](/docs/dev/deployments/prerendering) one. To
change it, edit the file and deploy.
### Add the labels to your messages [#add-the-labels-to-your-messages]
Menu labels are message keys, so they follow the visitor's language like the
rest of the UI. Put them in your app's locale file, under one namespace such as
`app.menu`.
```json title="src/locales/app/en.json"
{
"app": {
// [!code ++:6]
"menu": {
"community": "Community",
"discover": "Discover",
"discover_description": "Fresh posts from every corner of the site.",
"search": "Search"
}
}
}
```
Add the same keys to every other language's file. For Polish, that is
`src/locales/app/pl.json` registered under `pl` in `src/locales/app.ts`.
### Add header links [#add-header-links]
Add a `navigation.header` array to the config. Each item needs an `href` and a
`title`, which is the full message key.
```ts title="src/vitnode.config.ts"
import { buildConfig } from '@vitnode/core/vitnode.config'
import { CompassIcon, SearchIcon } from 'lucide-react' // [!code ++]
export const vitNodeConfig = buildConfig({
// ...
// [!code ++:6]
navigation: {
header: [
{ href: '/discover', icon: CompassIcon, title: 'app.menu.discover' },
{ href: '/search', icon: SearchIcon, title: 'app.menu.search' },
],
},
})
```
Items show up in the order you list them. When the header runs out of room,
the ones that do not fit move into a **More** dropdown at the end.
### Group links in a dropdown [#group-links-in-a-dropdown]
Give a header item an `items` array to turn it into a dropdown. The parent
opens the dropdown on hover and still follows its own `href` when clicked. Each
child can carry a `description` key, shown under its label.
```ts title="src/vitnode.config.ts"
import { CompassIcon, MessagesSquareIcon, SearchIcon } from 'lucide-react'
navigation: {
header: [
{
href: '/forum',
icon: MessagesSquareIcon,
title: 'app.menu.community',
items: [
{
description: 'app.menu.discover_description',
href: '/discover',
icon: CompassIcon,
title: 'app.menu.discover',
},
{ href: '/search', icon: SearchIcon, title: 'app.menu.search' },
],
},
],
},
```
## Item options [#item-options]
| Name | Type | Required | Default | Description |
| :--------------- | :------------------------------ | :------- | :------ | :------------------------------------------------------------ |
| `href` | `string` | Yes | - | A path on this site (`/forum`) or an `https://` address |
| `title` | `string` | Yes | - | Message key of the link label, such as `app.menu.discover` |
| `description` | `string` | No | - | Message key of the text under the label inside a dropdown |
| `icon` | `ComponentType<{ className? }>` | No | - | Drawn before the label, for example a `lucide-react` icon |
| `isOpenInNewTab` | `boolean` | No | `false` | Opens the link in a new tab, with `rel="noopener noreferrer"` |
| `items` | item array | No | - | Header items only: the links of the dropdown |
Pass the icon component itself (`CompassIcon`), not an element
(`
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
## Moving from the AdminCP menu [#moving-from-the-admincp-menu]
Earlier versions stored the menu in the `core_navigation` table and edited it
in **AdminCP → System → Navigation**. That screen, its API routes, the
`navigation` staff permission and the `navigation.*` events are gone, and a
migration drops the table. Copy your items into `vitnode.config.ts` before you
run `vitnode migrate`.
Plugins no longer declare menu presets: remove the `navigation` array from
`buildApiPlugin()` and the `navigation` keys from the plugin's locale files.
To suggest a link, show the config snippet in your plugin's README.
# Limit who sees a notification (/docs/dev/notifications/access)
Add an `access` check to a notification type when the content behind it is private, such as a topic in a members-only forum. Core asks your check who may see the notification before delivering it, before emailing it and every time the inbox loads. A member who loses access stops seeing the item, even after it was delivered.
This guide continues the `forum.topic_reply` type from [Publish notifications](/docs/dev/notifications/publishing).
### Add the access check [#add-the-access-check]
Add `access` to the type. It receives a batch of candidate user ids and returns the ones that may see the notification:
```ts title="plugins/forum/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { and, eq, inArray } from 'drizzle-orm'
import { z } from 'zod'
import { forum_topic_members } from '@/database/topic-members'
export const topicReplyNotification = buildNotificationType({
id: 'forum.topic_reply',
// other options unchanged
// [!code ++:14]
access: async ({ c, data, userIds }) => {
const members = await c
.get('db')
.select({ userId: forum_topic_members.userId })
.from(forum_topic_members)
.where(
and(
eq(forum_topic_members.topicId, data.topicId),
inArray(forum_topic_members.userId, userIds),
),
)
return members.map((member) => member.userId)
},
})
```
Answer the whole batch with one query. A batch holds up to 500 ids by default, so a query per user would run 500 times. When every candidate shares one answer, such as "is the topic still public?", check once and return `userIds` or `[]`.
### Remove notifications when content goes away [#remove-notifications-when-content-goes-away]
When a topic is deleted, take its notifications out of every inbox. Call `remove()` in the route that deletes the topic:
```ts title="plugins/forum/src/api/modules/topics/routes/delete.route.ts"
await c.get('notifications').remove({
subject: { type: 'forum.topic', id: topic.id },
})
```
`remove()` matches the `subject` you passed to `publish()`, lowers the unread counts in the same transaction and returns how many items it deleted. To remove only some members, for example after kicking them from a private topic, add `type` and `userIds`:
```ts title="plugins/forum/src/api/modules/topics/routes/kick.route.ts"
await c.get('notifications').remove({
subject: { type: 'forum.topic', id: topic.id },
type: 'forum.topic_reply',
userIds: removedMemberIds,
})
```
`remove()` keeps inboxes tidy, but it is not required for privacy. An item whose `access` check now says no already shows "This notification is no longer available." instead of its text.
If `access` throws while notifications are delivered, the whole batch fails
and the queue retries it later. When the inbox loads, a throw turns that one
item into the "no longer available" placeholder. Let real database errors
throw, but do not throw for "no access": return fewer ids instead.
## Check the result [#check-the-result]
1. Publish a reply in a private topic with two members and one non-member listed in `recipients`. Only the two members get an inbox item.
2. Remove one member from the topic and reload their notifications. The item shows "This notification is no longer available." and no longer links to the topic.
3. Delete the topic. The item disappears from the remaining member's inbox, and their unread count drops at the same moment.
For the full `remove()` signature, see the [Notifications API reference](/docs/dev/notifications/reference#remove).
# Notifications in the AdminCP (/docs/dev/notifications/admincp)
Open **AdminCP → System → Notifications** (`/admin/core/system/notifications`) to see how notifications are doing, decide what members get by default and stop everything when you need to.
## Permissions [#permissions]
The screen uses the core `notifications` staff permission module. Grant it in **AdminCP → Staff → Administrators**, see [Staff permissions](/docs/dev/working-with-users/staff-permissions).
| Permission | Allows |
| -------------------------- | ------------------------------------------------------------ |
| `notifications.can_view` | Open the screen and see activity and types |
| `notifications.can_edit` | Change what each type does by default |
| `notifications.can_manage` | The **Settings** sheet and **Reset all members to defaults** |
## Check activity [#check-activity]
**Activity** shows four numbers for the last 24 hours, 7 days or 30 days, each compared with the period before:
- **Emails delivered**: notification emails that went out. Test emails do not count.
- **Failure rate**: failed emails out of every email attempted.
- **Events published**: notifications that plugins and core published.
- **Emails skipped**: emails that were due but not sent, for example because the member turned email off or already read the notification.
Hover or tap a trend line to see the count for one day, or one hour in the 24-hour view. Days follow the site's time zone, so "today" means the same to every administrator. When notifications are paused, a **Notifications are paused** banner shows above the numbers.
## Set what members get by default [#set-what-members-get-by-default]
**Notification types** lists every registered type, grouped by plugin. Each row shows what members get today, and opening it lets you change that. Changes save as you click.
### Turn on email for the type [#turn-on-email-for-the-type]
Add `email: true` and pick the default mode for members who never change it:
```ts title="plugins/forum/src/api/lib/notifications.ts"
export const topicReplyNotification = buildNotificationType({
id: 'forum.topic_reply',
// other options unchanged
defaults: { inApp: true, email: 'daily' }, // [!code ++]
email: true, // [!code ++]
})
```
`email: true` reuses the `title`, `body` and `target` from `present`. Each email links to the item and to **Manage notification preferences** on `/settings/notifications`. A default other than `'none'` without `email` throws when the module loads.
### Word the email separately (optional) [#word-the-email-separately-optional]
Pass a function instead of `true` when the email needs its own subject or button label:
```ts title="plugins/forum/src/api/lib/notifications.ts"
email: ({ data, t }) => ({
subject: t('@acme/forum.notifications.topic_reply.email_subject', {
title: data.topicTitle,
}),
title: t('@acme/forum.notifications.topic_reply.title', {
title: data.topicTitle,
}),
actionLabel: t('@acme/forum.notifications.topic_reply.email_action'),
}),
```
It receives the same arguments as `present`, in the recipient's language. Add the new keys to `src/locales/api/en.json`.
## How digests are scheduled [#how-digests-are-scheduled]
Daily digests go out at 08:00 and weekly digests on Monday at 08:00, in each member's time zone. The hour and day are the same for everyone, and members cannot change them.
- A daily digest covers the 24 hours before 08:00. A weekly one covers the seven days before Monday 08:00. A notification that arrives after 08:00 waits for the next digest.
- The time zone comes from the member's **Region** setting on `/settings`, then from their language, then UTC.
- Periods follow local time, so on the night clocks change a day lasts 23 or 25 hours. No day is skipped or sent twice.
- Each notification joins exactly one digest, and an empty digest is never sent.
- A digest lists up to 25 notifications, newest first, and says how many more are waiting.
The `notifications-schedule` cron plans digests every 5 minutes, so a digest can arrive up to 5 minutes after 08:00.
## What is checked at send time [#what-is-checked-at-send-time]
Right before an email or digest goes out, core checks each notification again: the member's current email mode, the type's policy in the AdminCP, the type's `access` check, and whether the member already read it.
Digests and delayed emails include only notifications that are still unread. A member who read or archived an item in the inbox does not get it by email too. A member who switched modes since the notification arrived gets it in the new mode, or not at all for `none`. A member who takes a type by email only has no inbox item to read, so their email always goes out.
## Delivery records and retries [#delivery-records-and-retries]
Every send, including test emails, is a row in `core_notification_deliveries`. List them with `GET /deliveries` in the [AdminCP API](/docs/dev/notifications/reference#admincp-endpoints).
| Status | Meaning |
| --------- | ------------------------------------------------------------------------------------------- |
| `pending` | Waiting for its send time |
| `sending` | Claimed by a worker |
| `sent` | The provider accepted it. `providerMessageId` holds the provider's id |
| `failed` | All 5 attempts failed. `lastError` holds the error with addresses and tokens redacted |
| `skipped` | Nothing to send. `skipReason` says why, such as `empty`, `email_disabled` or `user_missing` |
A failed attempt is retried after 10 seconds, then 20, 40 and 80. Every attempt passes the same `idempotencyKey` to your adapter, so a provider that deduplicates, such as Resend, never delivers a retry twice. SMTP through Nodemailer cannot deduplicate, so a crash between "accepted" and "recorded" can send one email twice. To forward the key from your own adapter, see [Custom email adapter](/docs/dev/email/custom-adapter#idempotency-and-the-return-value).
## Check the result [#check-the-result]
1. Open **AdminCP → System → Notifications**, select **Settings**, and run **Send a test email to me**. The email arrives at your own address.
2. Set **Replies to your topics** to **Right away** on `/settings/notifications`, then trigger a reply as another member. The email arrives within about a minute, as long as your [cron adapter](/docs/dev/cron) runs the queue worker.
3. If it does not, see [Emails are not sending](/docs/dev/notifications/troubleshooting#emails-are-not-sending).
# Inbox and realtime (/docs/dev/notifications/inbox-and-realtime)
Every recipient gets their own inbox items, and every member has one stored unread count. Each change to an inbox updates that count in the same database transaction and then pushes the new value to the member's open tabs. This page explains how read state, grouping and the live count behave, so you can predict what members see.
## Read and unread [#read-and-unread]
An inbox item is unread while it is not archived and the member has not read its latest activity. Each item has two counters:
- `activitySeq` starts at 1 and increases each time a grouped notification joins the item.
- `readSeq` records how far the member has read.
Opening `/notifications` or the bell never marks anything read. Opening an item, marking it read or **Mark all as read** does.
When the browser marks an item read, it sends the `activitySeq` it displayed as `throughSeq`. If a fourth reply joined the item after the bell rendered it, the item stays unread, because the member has not seen that reply yet.
**Mark all as read** marks everything that exists when the request takes the member's lock. A notification delivered a moment later stays unread, so nothing that arrives during the click is lost.
## Grouping [#grouping]
Types with [`grouping`](/docs/dev/notifications/notification-types#grouping) merge related notifications into one item per member, type, group key and time window:
- Windows are fixed UTC slots, not sliding ones. With a 60-minute window, 14:00 to 14:59 UTC share an item, and 15:00 starts a new one.
- A new notification in a read item makes it unread again, and one in an archived item brings it back to the inbox.
- Items sort by their latest activity, so a grouped item moves to the top when it grows.
- The unread count counts items, not notifications. Ten replies in one grouped item add 1.
## Items that are no longer available [#items-that-are-no-longer-available]
Before returning a page of the inbox, core checks every item again: the type is still registered, its stored data still parses, `access` still allows the member and `present` still renders. If any check fails, the item comes back as a placeholder with the title "This notification is no longer available." and no link.
The placeholder keeps its read state, so members can still read or archive it, and the unread count never includes an item they cannot clear. This covers deleted content, revoked access and uninstalled plugins.
## The live unread count [#the-live-unread-count]
The browser receives the same `{ unread, revision }` pair from three places:
1. The session payload, `user.notifications` in `GET /api/@vitnode/core/users/session`, read fresh on every request.
2. The WebSocket message `notificationsStateChannel`, sent after every committed inbox change and once each time a signed-in socket opens.
3. `GET /api/@vitnode/core/notifications/state`, only used when there is no socket.
`unread` is always the absolute count. `revision` increases with every change, and the browser keeps the state with the highest revision, so a slow response never undoes a newer realtime update. Messages are sent only after commit, so a rolled-back change never reaches the browser.
WebSocket messages missed while a tab was offline are not replayed. Instead, the server sends the current count as the first message on every new connection, so a reconnect catches up without an extra request. While the socket is open, the browser never calls `/state`. Without a socket, for example when the API runs inside the web app on the same origin or the connection is down, it reads `/state` every 60 seconds while the tab is visible, and right away when a tab returns after more than 30 seconds in the background.
When the count changes, open notification lists refresh once per burst: 1 second after the last change and at most 5 seconds after the first.
With `REDIS_URL` set, realtime messages travel between API instances over
Redis, so delivery on instance A reaches a tab connected to instance B.
Without Redis, only tabs connected to the same instance update live. Others
catch up on their next reconnect or page load. See
[Redis](/docs/dev/advanced/redis).
## What core ships in the UI [#what-core-ships-in-the-ui]
| Piece | Where |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| Bell with unread badge | Site header on every screen size. Loads the recent list only when opened |
| Notifications page | `/notifications`, with **All** and **Unread** tabs, a category filter and infinite scroll |
| Preferences | `/settings/notifications`, see [Preferences](/docs/dev/notifications/preferences) |
A default theme needs no wiring. To build your own bell, call the [member endpoints](/docs/dev/notifications/reference#member-endpoints) and listen to the [realtime channel](/docs/dev/notifications/reference#realtime-channel).
# Notifications (/docs/dev/notifications)
VitNode notifications give every member an inbox under the bell in the site header. A plugin calls `c.get("notifications").publish()` from an API route. Core then stores the notification, delivers it to each recipient, updates their unread count live and sends email to members who asked for it.
### Apply the database migration [#apply-the-database-migration]
Stored notifications add six `core_notification*` tables. Run the migrations once after upgrading `@vitnode/core`:
```bash tab="bun"
bun run db:migrate
```
```bash tab="pnpm"
pnpm db:migrate
```
```bash tab="npm"
npm run db:migrate
```
In development, `pnpm dev` runs `vitnode db:prepare`, which applies them for you.
### Pick the toasts to keep [#pick-the-toasts-to-keep]
A reply, a mention, an approval or a finished export belongs in the inbox, because a member may look for it later. Feedback about something happening right now, such as "Import started", can stay a toast.
### Declare a type for each [#declare-a-type-for-each]
Declare and register one type per kept toast, as in [Publish notifications](/docs/dev/notifications/publishing):
```ts title="plugins/shop/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { z } from 'zod'
export const exportReadyNotification = buildNotificationType({
id: 'shop.export_ready',
version: 1,
schema: z.object({ exportId: z.number() }),
category: 'system',
label: '@acme/shop.notifications.export_ready.label',
defaults: { inApp: true, email: 'none' },
present: ({ data, t }) => ({
title: t('@acme/shop.notifications.export_ready.title'),
target: `/shop/exports/${data.exportId}`,
}),
})
```
### Replace the toast with `publish()` [#replace-the-toast-with-publish]
```ts title="plugins/shop/src/api/modules/exports/routes/finish.route.ts"
// [!code --:4]
c.get('realtime').sendToUser(user.id, notificationsChannel, {
title: 'Your export is ready',
type: 'success',
})
// [!code ++:7]
await c.get('notifications').publish({
type: exportReadyNotification,
recipients: [user.id],
allowSelf: true,
data: { exportId: job.id },
idempotencyKey: `export:${job.id}`,
})
```
The bell updates over the same WebSocket, so members still see it right away. `allowSelf: true` matters here: the member who started the export is also the request's actor, and the actor is skipped by default.
## Check the result [#check-the-result]
1. Run the export as a member, then reload the page. The notification is still under the bell, with an unread count.
2. Sign out and back in on another browser. The same notification is there.
3. On `/settings/notifications`, the new type is listed and can be turned off.
The AdminCP dashboard's **Send a notification** widget already works this way: it shows a toast and stores the message as a `core.admin_message` notification. Toasts sent with `sendToUser()` and `notificationsChannel` keep working unchanged, see [WebSocket](/docs/dev/websocket).
# Notification types (/docs/dev/notifications/notification-types)
A notification type describes one kind of notification: the data it stores, how it reads in the inbox, who may see it and what members get by default. You build it with `buildNotificationType()` and register it on your API plugin. For a guided first type, see [Publish notifications](/docs/dev/notifications/publishing).
## Signature [#signature]
```ts
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
buildNotificationType(
definition: NotificationTypeDefinition,
): NotificationTypeDefinition
```
It returns the definition unchanged after checking it. Pass that same object to `notificationTypes` and to `publish({ type })`, so TypeScript checks `data` against `schema` at every call site.
Register types on `buildApiPlugin({ notificationTypes })`, or on any module with `buildModule({ notificationTypes })`. Core collects them from every installed plugin when the API starts.
## Options [#options]
',
required: true,
},
category: {
description:
'Groups types on the preferences page and in inbox filters. 1 to 50 characters of a-z, 0-9, "_" or "-". Core translates account, content, social and system.',
type: 'string',
required: true,
},
label: {
description: 'API message key for the type name on the preferences page.',
type: 'string',
required: true,
},
description: {
description:
'API message key for a one-line explanation under the label.',
type: 'string',
},
defaults: {
description:
'What a member gets before changing anything. Administrators can override it in the AdminCP.',
type: '{ inApp: boolean; email: "none" | "immediate" | "daily" | "weekly" }',
required: true,
},
present: {
description:
"Renders one inbox item as plain text in the recipient's language.",
type: '(args: NotificationPresentArgs) => { title: string; body?: string; target?: string | null }',
required: true,
},
email: {
description:
'Turns on email for this type. true reuses present. A function writes the email separately. Required when defaults.email is not "none".',
type: 'boolean | (args: NotificationPresentArgs) => { subject: string; title: string; body?: string; actionLabel?: string }',
},
access: {
description:
'Returns which of userIds may see the notification. Without it, every recipient may.',
type: '(args: { c, data, subject, userIds }) => number[] | Promise',
},
grouping: {
description:
'Merges related notifications that arrive in the same time window into one inbox item.',
type: '{ windowMinutes: number; key?: (args: { data, subject }) => string | null }',
},
subjectType: {
description:
'The only subject type publish() accepts for this type, such as "forum.topic".',
type: 'string',
},
mandatory: {
description: 'Always delivered to the inbox. Members cannot change it.',
type: 'boolean',
default: 'false',
},
migrate: {
description:
'Upgrades data stored by an older version before it is parsed.',
type: '(data: unknown, fromVersion: number) => unknown',
},
}}
/>
`buildNotificationType()` throws a `NotificationRegistryError` when the module loads if the id, category or subject type is invalid, `version` is below 1, `grouping.windowMinutes` is outside 1 to 10,080 (one week), or `defaults.email` is not `"none"` while `email` is missing. Two registered types with the same `id` stop the API from starting.
## `present` arguments [#present-arguments]
`present` runs on the API each time an item is listed or emailed. It receives:
`, then `.notifications.categories.`.
## How core cleans `present` output [#how-core-cleans-present-output]
Core cleans what `present` returns before anyone sees it:
- `title` and `body` are plain text. Markup is never rendered, whitespace is collapsed and each string is cut at 500 characters.
- `target` must be a path on the same site, such as `/forum/topics/42`. Absolute URLs, `//host`, `javascript:` and backslashes are dropped, and the item renders without a link.
- If `present` throws or returns an empty title, the item shows "This notification is no longer available." and the error is logged.
## `access` [#access]
Core calls `access` once per delivery batch, again before each email or digest, and each time a member's inbox loads. It receives a bounded batch of user ids, never the whole audience. A worked example is in [Limit who sees a notification](/docs/dev/notifications/access).
## `grouping` [#grouping]
```ts title="plugins/forum/src/api/lib/notifications.ts"
grouping: {
windowMinutes: 60,
key: ({ data }) => `topic:${data.topicId}`,
},
```
Notifications with the same type and key, for the same member, in the same window join one inbox item, such as "Alex and 4 others replied to Shipping day". Windows are fixed UTC slots: with 60 minutes, 14:00 to 14:59 is one window. The key defaults to the subject. A notification without a subject, or a `key` that returns `null`, is never grouped. Use `actors`, `actorCount` and `eventCount` in `present` to word a grouped item:
```json title="plugins/forum/src/locales/api/en.json"
"title": "{others, plural, =0 {{name} replied} one {{name} and # other replied} other {{name} and # others replied}} to {title}"
```
## `version` and `migrate` [#version-and-migrate]
Stored notifications outlive your code. When `schema` changes shape, increase `version` and make `migrate` upgrade the old data. Here version 1 stored `title`, and version 2 renames it to `topicTitle`:
```ts title="plugins/forum/src/api/lib/notifications.ts"
export const topicReplyNotification = buildNotificationType({
id: 'forum.topic_reply',
version: 2,
schema: z.object({ topicId: z.number(), topicTitle: z.string() }),
migrate: (data, fromVersion) => {
if (fromVersion !== 1) return data
const old = data as { title: string; topicId: number }
return { topicId: old.topicId, topicTitle: old.title }
},
// other options unchanged
})
```
Data that cannot be upgraded is never shown. That covers a missing `migrate`, a stored version newer than the code, a thrown error or a failed parse. A notification not yet delivered is marked failed, and inbox items show the "no longer available" placeholder.
## `mandatory` [#mandatory]
Set `mandatory: true` for account notices members must not miss, such as "Your role changed". The type always reaches the inbox, ignores AdminCP policies that would disable it, and shows as locked on the preferences page. Its email follows the installation default.
Password resets, email verification and sign-in codes are not notifications. Keep sending them with `c.get("email").send()`, so they arrive even for members who turned every notification off.
# Preferences (/docs/dev/notifications/preferences)
Members choose, per notification type, whether it shows in their notification list, whether it comes as push and how it reaches them by email. Core builds the page at `/settings/notifications` from the registered types, so a new plugin's types appear there with no UI code.
## The settings page [#the-settings-page]
`/settings/notifications` has two parts:
- **Where notifications reach you** turns push and email on or off for the whole account. The **Email** switch turns notification email off for every type the member can change, after a confirmation.
- **What you get notified about** lists one row per type. The bell, phone and mail icons show what is on. Opening a row shows a switch per channel and, when email is on, a choice between **Right away**, **Daily digest** and **Weekly digest**.
Members can turn push on, and core stores and respects those choices, but
VitNode does not send push notifications yet. Nothing changes for members when
delivery arrives.
## How core decides what a member receives [#how-core-decides-what-a-member-receives]
Core resolves the notification list, push and email separately, so a member can take a type by email only, in the list only, both or neither. For each type it checks, in this order:
1. **Disabled by the installation.** The member gets nothing. Mandatory types skip this check.
2. **Mandatory type.** Always in the notification list. Email follows the installation default.
3. **The member's own choice**, unless an administrator turned off **Member can edit** for the type in the [AdminCP](/docs/dev/notifications/admincp#set-what-members-get-by-default).
4. **The installation default** set in the AdminCP.
5. **The type's own `defaults`.**
A channel the AdminCP set to **Disabled** is off for everyone and disappears from members' settings. Locked types show "Set by the admin", and the API refuses changes to them with `400`. Push is on by default wherever the installation allows it.
A type offers email only when it declares `email`, an [email adapter](/docs/dev/email) is configured, and the AdminCP has not set its email to **Disabled**. There is no installation-wide email switch: to stop one kind of email, disable email on that type.
### Example [#example]
`forum.topic_reply` defaults to `{ inApp: true, email: 'daily' }`. An administrator changed its email default to weekly.
| Member | Notification list | Email |
| -------------------------------------- | ----------------- | -------------------------------- |
| Never opened preferences | yes | weekly, the installation default |
| Chose **Right away** | yes | immediate, their choice |
| Turned the notification list off | no | weekly, email is independent |
| Anyone, after email is set to Disabled | yes | none |
## Time zone [#time-zone]
Digests go out at 08:00 in the member's time zone. The time zone belongs to the account, not to notifications: members set it under **Region** on `/settings`, and **Use this device's time zone** fills it in from the browser. Without one, core uses the time zone of the member's language, then UTC. See [How digests are scheduled](/docs/dev/notifications/email-and-digests#how-digests-are-scheduled).
## Account email is not a notification [#account-email-is-not-a-notification]
Password resets, email verification and sign-in codes are sent with `c.get("email").send()`. They never pass through notification preferences, AdminCP policies or digests, so a member who turned every notification off still receives them. Use a [mandatory type](/docs/dev/notifications/notification-types#mandatory) for account notices that also belong in the inbox.
# Publish notifications (/docs/dev/notifications/publishing)
This guide notifies a topic's author when someone replies to their topic. You declare a notification type once, register it on your API plugin, and publish it from the route that saves the reply. The examples use a forum plugin with the id `@acme/forum`.
## Before you begin [#before-you-begin]
You need a plugin with an API part (`src/config.api.ts`) and a route that writes to the database. See [Create a plugin](/docs/dev/plugins/create) if you do not have one yet.
### Declare the notification type [#declare-the-notification-type]
Create a file for your plugin's notification types:
```ts title="plugins/forum/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { z } from 'zod'
export const topicReplyNotification = buildNotificationType({
id: 'forum.topic_reply',
version: 1,
schema: z.object({ topicId: z.number(), topicTitle: z.string() }),
category: 'social',
label: '@acme/forum.notifications.topic_reply.label',
defaults: { inApp: true, email: 'none' },
present: ({ data, t }) => ({
title: t('@acme/forum.notifications.topic_reply.title', {
title: data.topicTitle,
}),
target: `/forum/topics/${data.topicId}`,
}),
})
```
`id` is permanent, because stored notifications refer to it. `schema` checks the `data` you publish. `present` turns that data into the inbox text, in the recipient's language, every time the inbox loads. Every option is listed in [Notification types](/docs/dev/notifications/notification-types).
### Add the messages [#add-the-messages]
The API renders notification text, so the strings belong in your plugin's API messages:
```json title="plugins/forum/src/locales/api/en.json"
{
"@acme/forum": {
"notifications": {
"topic_reply": {
"label": "Replies to your topics",
"title": "New reply in {title}"
}
}
}
}
```
`label` names the type on the member's preferences page. If your plugin has no `src/locales/api/` folder yet, create it as shown in [Shipping translations with a plugin](/docs/dev/i18n/server#shipping-translations-with-a-plugin).
### Register the type [#register-the-type]
Pass the type and the API messages to `buildApiPlugin()`:
```ts title="plugins/forum/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
import { topicReplyNotification } from '@/api/lib/notifications' // [!code ++]
import { topicsModule } from '@/api/modules/topics/topics.module'
import messages from '@/locales/api'
import { manifest } from '@/manifest.gen'
export const forumApiPlugin = () =>
buildApiPlugin({
manifest,
messages,
notificationTypes: [topicReplyNotification], // [!code ++]
modules: [topicsModule],
})
```
Core collects the types of every installed plugin when the API starts, so restart the API after adding one. Two types with the same `id` stop the API from starting, with an error that names both plugins.
### Publish in the reply route [#publish-in-the-reply-route]
In the handler that saves the reply, publish inside the same transaction:
```ts title="plugins/forum/src/api/modules/topics/routes/reply.route.ts"
await c.get('db').transaction(async (tx) => {
const [reply] = await tx
.insert(forum_replies)
.values({ topicId: topic.id, authorId: user.id, content })
.returning()
// [!code ++:8]
await c.get('notifications').publish({
type: topicReplyNotification,
tx,
recipients: [topic.authorId],
subject: { type: 'forum.topic', id: topic.id },
data: { topicId: topic.id, topicTitle: topic.title },
idempotencyKey: `reply:${reply.id}`,
})
})
```
`topic`, `user` and `content` come from your existing route. Because of `tx`, the notification is saved together with the reply: a rolled-back reply notifies nobody, and a saved reply always notifies, even if the server stops right after the commit. `subject` names what the notification is about. Core uses it to group notifications and to [remove them later](/docs/dev/notifications/access#remove-notifications-when-content-goes-away).
`publish()` returns `{ eventId, duplicate }` and does not wait for delivery. Delivery starts after your route sends its response, so a large audience never slows the request down.
`publish()` throws a `NotificationPublishError` when `data` does not match the
schema or the type is not registered. Inside a transaction, that error rolls
back the reply too. Catch it if the notification is optional for the write.
See [Errors](/docs/dev/notifications/reference#errors).
## Choose an idempotency key [#choose-an-idempotency-key]
The `idempotencyKey` names the real-world event, not the attempt to publish it. Publishing the same type with the same key again does nothing and returns the first event with `duplicate: true`. Retries, double clicks and replayed event listeners never notify twice.
| Event | Good key | Bad key |
| ------------------------------ | --------------------------- | ------------------------ |
| A reply was posted | `reply:${reply.id}` | `reply:${Date.now()}` |
| An article was first published | `post-published:${post.id}` | `post-${post.updatedAt}` |
| An export finished | `export:${job.id}` | `crypto.randomUUID()` |
Use a random key only when every call really is a new message, such as an administrator sending the same announcement twice on purpose.
## Choose the recipients [#choose-the-recipients]
`recipients` holds the user ids your plugin picked, up to 100,000 per publish. Core removes duplicates and the actor, which is the signed-in admin or user of the request. When the notification is delivered, core also skips deleted users, members who turned the type off and anyone your type's [`access` check](/docs/dev/notifications/access) rejects.
To notify the actor about their own work, set `allowSelf: true`:
```ts title="plugins/forum/src/api/modules/exports/routes/finish.route.ts"
await c.get('notifications').publish({
type: exportReadyNotification,
recipients: [user.id],
allowSelf: true,
data: { exportId: job.id },
idempotencyKey: `export:${job.id}`,
})
```
A queue task or cron job has no signed-in user. Pass the real actor as `actorId`, or `actorId: null` for a system notification.
## Check the result [#check-the-result]
1. Sign in as a second user and reply to a topic started by someone else. Replying to your own topic notifies nobody, because the actor is skipped.
2. Sign in as the topic author. Within a few seconds the bell shows an unread count, and the new item links to `/forum/topics/{id}`.
3. Open `/settings/notifications`. **Replies to your topics** is listed under **What you get notified about**, in the **Social** group once more than one category exists.
If nothing arrives, see [Troubleshooting](/docs/dev/notifications/troubleshooting#notifications-arrive-late-or-never).
# Queue and scale (/docs/dev/notifications/queue-and-scale)
Notifications run on VitNode's database-backed [queue](/docs/dev/advanced/queue) and [cron](/docs/dev/cron). No extra service is needed, but the queue worker must run: without a working cron adapter, nothing is delivered in the background.
## Queue tasks and cron jobs [#queue-tasks-and-cron-jobs]
All of these belong to `@vitnode/core`. Tasks appear in **Debug Panel → Queue** (`/admin/core/debug/queue`) and cron jobs in **Debug Panel → Cron & queue** (`/admin/core/debug/cron`).
| Name | Kind | Does |
| ------------------------ | --------------------- | ----------------------------------------------------------------------- |
| `notifications-fanout` | Task, 10 attempts | Delivers one notification to its recipients, batch by batch |
| `notifications-email` | Task, 5 attempts | Sends due emails and digests |
| `notifications-cleanup` | Task, 3 attempts | Removes notifications older than the retention period |
| `notifications-schedule` | Cron, every 5 minutes | Plans digests, recovers stalled work and queues the email task when due |
| `notifications-cleanup` | Cron, daily at 02:00 | Queues the cleanup task |
A request that publishes starts delivery right after its response is sent. Anything that misses that, such as a publish from a queue task, waits for the queue worker, which runs every minute.
## Batched delivery [#batched-delivery]
The fan-out task walks the recipients in batches of `fanoutBatchSize`, 500 by default. Each batch is one short transaction that filters out deleted users, opted-out members and anyone `access` rejects, then writes inbox items, unread counts and immediate email deliveries, and saves its progress on the event. Realtime updates go out after the batch commits.
- **A crash loses at most one batch.** The retry continues after the last saved batch.
- **A batch that runs twice changes nothing.** Core keeps one receipt per notification and member, and only members without a receipt get an item.
- **Large audiences do not block the queue.** One task stops after 20 seconds and queues a new task for the rest.
- **No deadlocks between writers.** Every inbox write locks the affected members in user id order, so concurrent writers wait for each other instead.
The integration test `fanout.load.integration.test.ts` delivers one notification to 1,000 members with batches of 200, with two workers racing on the same event. It checks that every member gets exactly one item, that `access` runs about once per batch and that the number of queries stays below the number of recipients.
## Recovery [#recovery]
| Stuck work | Recovered by |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| Queue task left processing by a stopped worker | The queue worker, after 15 minutes |
| Notification unfinished with no task left | `notifications-schedule`, after 10 minutes, by queuing a new task |
| Email left in `sending` | `notifications-schedule`, after 15 minutes, by setting it back to `pending` |
| Two workers on one notification | A row lock. The second waits, then continues from the saved progress |
## Retention [#retention]
The nightly cleanup removes, in batches:
- inbox items with no activity for `retentionDays`, lowering unread counts for unread ones;
- older notifications that no inbox item points to;
- finished email delivery records older than `retentionDays`;
- pending digest email for notifications no digest picked up within 14 days. The inbox items stay.
## Configure the workers [#configure-the-workers]
How much work each run does and how long notifications are kept are deployment settings, so they live in your API config, not in the AdminCP. Add a `notifications` block to `buildApiConfig`:
```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
export const vitNodeApiConfig = buildApiConfig({
// other options unchanged
// [!code ++:6]
notifications: {
retentionDays: 30,
fanoutBatchSize: 1000,
emailBatchSize: 100,
emailConcurrency: 8,
},
})
```
| Name | Type | Required | Default | Description |
| ------------------ | -------- | -------- | ------- | ------------------------------------------------------- |
| `retentionDays` | `number` | No | `90` | Days to keep notifications, from 1 to 3,650 |
| `fanoutBatchSize` | `number` | No | `500` | Recipients per delivery transaction, from 10 to 5,000 |
| `emailBatchSize` | `number` | No | `50` | Emails one worker run picks up, from 1 to 500 |
| `emailConcurrency` | `number` | No | `4` | Emails sent at the same time during a run, from 1 to 20 |
A value outside its range is clamped to the nearest limit, and a value that is not a whole number falls back to the default. Restart the API to apply a change.
The defaults suit most sites. Raise `fanoutBatchSize` when one announcement to a huge audience needs too many runs, and `emailConcurrency` when your email provider allows more parallel sends. Lower `emailBatchSize` when a slow provider makes runs time out.
# Notifications API reference (/docs/dev/notifications/reference)
`c.get("notifications")` is available in every Hono route, event listener and queue task. This page lists its methods, the REST endpoints behind the bell and the AdminCP screen, and the WebSocket channel that carries the unread count. For the type definition, see [Notification types](/docs/dev/notifications/notification-types).
## Methods [#methods]
| Method | Returns | Behavior |
| --------------- | -------------------------------------------------- | ------------------------------------------------------------------------ |
| `publish(args)` | `Promise<{ eventId: number; duplicate: boolean }>` | Stores one event and queues its delivery. Does not wait for delivery |
| `remove(args)` | `Promise` | Deletes matching inbox items and lowers unread counts. Returns the count |
| `state(userId)` | `Promise<{ unread: number; revision: number }>` | Reads one member's stored unread count |
### `publish` [#publish]
| string',
required: true,
},
data: {
description: "Checked against the type's schema.",
type: 'TData',
required: true,
},
idempotencyKey: {
description:
'Names the real-world event, 1 to 255 characters. Unique per plugin and type.',
type: 'string',
required: true,
},
recipients: {
description:
'Candidate user ids, at most 100,000 after duplicates are removed. Without it, the event is stored and delivers nothing.',
type: 'readonly number[]',
},
subject: {
description:
"What the notification is about. Used by grouping and remove(). Must match the type's subjectType.",
type: '{ type: string; id: number | string }',
},
tx: {
description:
'Your transaction. The event and its delivery task commit or roll back with your write.',
type: 'Transaction',
},
actorId: {
description:
'Who caused it. Defaults to the signed-in admin, then the signed-in user. Pass null for a system notification.',
type: 'number | null',
},
allowSelf: {
description: 'Deliver to the actor too.',
type: 'boolean',
default: 'false',
},
}}
/>
Publishing the same type and `idempotencyKey` again returns the first event with `duplicate: true`.
### `remove` [#remove]
### Add a passkey (once) [#add-a-passkey-once]
1. Sign in to the AdminCP at `/admin` with your **email and password**.
2. In the **same browser**, go to the community site, sign in, and open **Settings → Security**.
3. Select **Add a passkey** and confirm with your fingerprint, face or PIN.
### Sign in with it [#sign-in-with-it]
1. Go to `/admin`.
2. Select **Sign in with a passkey**.
3. Pick your passkey and confirm with your fingerprint, face or PIN.
You'll land wherever you were heading in the AdminCP.
Why the password first? Your account has AdminCP access, so VitNode only lets
it add a passkey while an AdminCP session for **you** is open in that browser.
That way a hijacked social login can't quietly add a passkey and walk into the
AdminCP.
## Enrollment [#enrollment]
Passkeys are enrolled in one place - **Settings → Security** - and one passkey works for both the site and the AdminCP. Nothing is stored per area, so there's no second passkey to manage.
For accounts that **currently have AdminCP access**, both enrollment steps (`/register/options` and `/register`) also require the browser to hold a valid AdminCP session for the same user. Without one, the API answers `403 admin_session_required` and the settings page explains what to do. Members without staff access enroll exactly as before.
The check runs at both steps, so an AdminCP session that expires or is signed out mid-ceremony stops the passkey from being saved.
## Sign-in [#sign-in]
1. `POST /api/@vitnode/core/users/passkeys/admin-sign-in/options` issues request options with `userVerification: "required"` and no `allowCredentials`, so the browser offers any passkey saved for your RP ID. It stores a new challenge with the ceremony `admin_sign_in` and sets it in the HttpOnly cookie `_passkey_admin_sign_in`.
2. The browser asks the authenticator for an assertion.
3. `POST /api/@vitnode/core/users/passkeys/admin-sign-in` then:
- **consumes** the challenge atomically, scoped to the cookie's token hash, the `admin_sign_in` ceremony and "not expired". A public sign-in or registration challenge never matches, and a replay always fails.
- **verifies** the assertion with SimpleWebAuthn against your configured `origins` and `rpId`, with `requireUserVerification: true`, the same user-handle and signature-counter checks as public sign-in.
- **resolves the user from the stored credential** - never from anything else the browser sends, and never from the public session cookie.
- **checks staff access right now**, skipping the cache, and counting the user's primary role, every secondary role and any root role. Someone whose access was removed gets `403 not_staff`, even though their passkey is still valid.
- only then calls `SessionAdminModel.createSessionByUserId()` - the same call the password form makes - which sets the `vitnode_auth_admin` cookie.
The routes live under `users/passkeys` rather than `admin/` on purpose: every `/admin/*` API path demands an AdminCP session, which nobody has yet while signing in.
## Sessions stay separate [#sessions-stay-separate]
| | Public passkey sign-in (`/login`) | AdminCP passkey sign-in (`/admin`) |
| ------------------------------ | --------------------------------- | -------------------------------------- |
| Challenge ceremony | `authentication` | `admin_sign_in` |
| Challenge lifetime | 5 minutes | 2 minutes |
| User verification | Required | Required |
| Staff access checked | No | Yes, at sign-in time |
| Creates | Public session (`vitnode_auth`) | AdminCP session (`vitnode_auth_admin`) |
| Reads the other area's session | No | No |
A public session never turns into an AdminCP session - not after a passkey sign-in, not after SSO, not after a password sign-in. Signing out of one area leaves the other alone, exactly as described in [Authentication](/docs/dev/advanced/auth).
Social SSO never issues an AdminCP session either. SSO providers only sign people in to the public site, and the staff enrollment rule above means an SSO-only session can't be turned into an AdminCP passkey.
Once signed in, an AdminCP session behaves like one started with a password: staff access is re-checked on every request, so revoking it ends the session on the next request.
## Recovery [#recovery]
- **Password stays.** The AdminCP password form is untouched. It's the way in for staff who haven't added a passkey yet, and the fallback when a passkey is lost.
- **Lost the passkey?** Sign in to the AdminCP with your password, then add a new passkey in **Settings → Security** and remove the old one there.
- **Forgot the password too?** Use **Forgot password?** on the public `/login` page, then sign in to the AdminCP with the new password.
- The [last-recovery-method rule](/docs/dev/passkeys#keeping-members-locked-in-the-good-way) still applies, so you can't remove the last way into your account.
## What people see [#what-people-see]
| Message | Why |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Passkey sign-in cancelled | The browser prompt was closed or timed out. Try again. |
| That took a little too long | The two-minute challenge expired, was already used, or the cookie was blocked. Start again. |
| Passkey not recognized | The passkey was removed, belongs to another RP ID, or failed verification (including no user verification). |
| No AdminCP access | The passkey is valid, but the account doesn't have AdminCP access right now. |
| Passkeys aren't supported here | The browser or device can't use passkeys. The button is disabled and the password form still works. |
| Open the AdminCP first | (Settings → Security) A staff account tried to add a passkey without an AdminCP session in that browser. |
## For developers [#for-developers]
Error codes (JSON body `{ error }`):
| Status | Code | Route |
| ------ | ------------------------ | -------------------------------- |
| `400` | `invalid_challenge` | `/admin-sign-in` |
| `403` | `verification_failed` | `/admin-sign-in` |
| `403` | `not_staff` | `/admin-sign-in` |
| `403` | `admin_session_required` | `/register/options`, `/register` |
| `404` | `passkeys_disabled` | all |
On the frontend, `useAdminPasskeySignInAction` from `@vitnode/core/tanstack/admin` runs the ceremony, drops the AdminCP identity caches and navigates to the sanitized `returnTo` - the same things the AdminCP password form does. It leaves the public session cache alone, because nothing about the public session changed.
If you registered your own auth transport with `setAuthTransport`, implement `startAdminPasskeySignIn` and `finishAdminPasskeySignIn` as well, and relay cookies on both. The challenge cookie is set by the first call and read by the second, and the second sets the AdminCP cookie. The server-side versions are exported as `startAdminPasskeySignInOnApi` and `finishAdminPasskeySignInOnApi` from `@vitnode/core/tanstack/auth/server`.
# Passkeys (WebAuthn) (/docs/dev/passkeys)
Passkeys let members sign in with their fingerprint, face or screen lock instead of a password. They are built on WebAuthn, can't be phished, and there is nothing to leak - the server only ever stores a **public** key.
VitNode ships passkeys in core. Members add them under **Settings → Security** and use them with **Sign in with a passkey** on `/login`. Staff can use the same passkey on the AdminCP login at `/admin` - see [AdminCP passkey sign-in](/docs/dev/passkeys/admincp). Under the hood it uses [SimpleWebAuthn](https://simplewebauthn.dev) (`@simplewebauthn/server` and `@simplewebauthn/browser`) - the same libraries Better Auth uses - while sessions, users and permissions stay 100% VitNode.
Looking for the member-facing walkthrough? See [Using
passkeys](/docs/dev/passkeys/using-passkeys) - it's written so you can link
your community straight to it.
## Quick start [#quick-start]
Passkeys are **opt-in**: they stay off until you set `authorization.passkeys`. `true` turns them on, with everything derived from `VITNODE_WEB_URL`:
- **origin** - `VITNODE_WEB_URL` itself, e.g. `https://community.example.com`
- **RP ID** - its hostname, e.g. `community.example.com`
- **RP name** - `metadata.shortTitle`, falling back to `metadata.title`
```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
export const vitNodeApiConfig = buildApiConfig({
// [!code ++:3]
authorization: {
passkeys: true,
},
})
```
Need something the defaults can't give you - several origins, or one RP ID shared across subdomains? Pass an object instead, and set only what differs:
```ts title="apps/api/src/vitnode.api.config.ts"
authorization: {
passkeys: {
rpId: "example.com",
origins: ["https://example.com", "https://forum.example.com"],
},
},
```
Then run the migration (below) and you're done. The login page shows the passkey button as soon as the API reports passkeys as enabled.
## Database migration [#database-migration]
Passkeys add two tables to core:
| Table | What's in it |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core_users_passkeys` | One row per credential: unique credential ID, COSE public key, signature counter, WebAuthn user handle, transports, device type, backup state, AAGUID, name, timestamps |
| `core_users_passkey_challenges` | Short-lived challenges: a SHA-256 hash of the browser token, the ceremony, the challenge, the user (for registration) and `expiresAt` |
Both reference `core_users` with `ON DELETE CASCADE`. Apply them like any other core migration:
```bash tab="bun"
bun run db:migrate
```
```bash tab="pnpm"
pnpm db:migrate
```
```bash tab="npm"
npm run db:migrate
```
In development `pnpm dev` runs `vitnode db:prepare`, which applies it for you.
## RP ID, origins and HTTPS [#rp-id-origins-and-https]
A passkey belongs to one **RP ID** (a domain). The browser only offers it on pages whose hostname is that domain or a subdomain of it, and VitNode only accepts responses from the **origins** you list.
- **HTTPS is required**, with one exception: `localhost` (and `*.localhost`) works over plain HTTP, so local development needs no certificates.
- **IP addresses can't be RP IDs.** Open `http://localhost:3000`, not `http://127.0.0.1:3000` - the browser will refuse.
- **Origins are bare**: `https://example.com`, not `https://example.com/` or `https://example.com/login`.
- **Sharing across subdomains**: set `rpId: "example.com"` and list every origin, e.g. `https://example.com` and `https://forum.example.com`.
Choose the RP ID before members create passkeys. **Changing it later makes
every existing passkey unusable** - they are cryptographically bound to the
old domain. Members would have to sign in another way and add new ones.
VitNode checks the configuration when the API boots:
- A `passkeys` setting that can't work (plain HTTP on a real domain, an RP ID that isn't a parent of an origin, an IP address - including a derived one like `VITNODE_WEB_URL=http://192.168.1.10:3000`) **fails the boot** with a message naming the problem.
Turn passkeys off by removing `passkeys`, or with `passkeys: false`. The **Sign in with a passkey** button disappears from `/login`, the **Security** item disappears from settings (`/settings/security` answers "not found"), and every passkey route answers `404 passkeys_disabled`. Saved passkeys stay in the database, so switching passkeys back on brings them straight back.
_passkey_registration`, `_passkey_authentication` or `_passkey_admin_sign_in` (so `vitnode_auth_passkey_...` by default).
- Challenges expire after **five minutes** - AdminCP sign-in challenges after **two**. Expired rows are swept every time a new ceremony starts.
- Verification consumes the challenge with a single `DELETE ... RETURNING` scoped to the token hash, the ceremony, "not expired" and - for registration - the signed-in user. It's atomic: two concurrent requests with the same cookie can never both win, and a replayed response always fails.
- Because the lookup is by the cookie's token, a challenge can't be used from another browser, by another account, or for another ceremony - a public sign-in challenge never opens the AdminCP, and the other way round.
### Verification [#verification]
The server calls SimpleWebAuthn's `verifyRegistrationResponse` / `verifyAuthenticationResponse` with the stored challenge, your configured `origins` and `rpId`, and `requireUserVerification: true` (options also ask for `userVerification: "required"` and a discoverable credential with `residentKey: "required"`).
On sign-in, the user comes **only** from the stored credential - anything the browser sends besides the WebAuthn response is ignored. If the authenticator returns a user handle, it must match the one saved with that credential.
### Signature counters [#signature-counters]
- Authenticators that always report `0` (most synced passkeys - iCloud Keychain, Google Password Manager) are accepted every time.
- Authenticators with a real counter must go **up**. A counter that stays the same or goes backwards - including dropping back to `0` - is rejected as a possible cloned key.
- The new counter is written with a compare-and-set (`WHERE counter = `), so two sign-ins racing on one credential can't both succeed.
### Sessions [#sessions]
A successful passkey sign-in calls `SessionModel.createSessionByUserId()` - exactly what password sign-in does - so it sets the usual `vitnode_auth` cookie on the current device. It **never** creates an AdminCP session, even for staff. The AdminCP has its own passkey flow at `/admin` with a separate challenge, a live staff check and its own session - see [AdminCP passkey sign-in](/docs/dev/passkeys/admincp).
Accounts with AdminCP access can only **add** a passkey while an AdminCP session for the same user is open in that browser (`403 admin_session_required` otherwise). Everyone else enrolls as usual.
On the client, `usePasskeySignInAction` clears identity-specific caches (the AdminCP entries, files, devices and passkeys) before navigating, and keeps the `returnTo` destination, just like the password form.
### Keeping members locked in (the good way) [#keeping-members-locked-in-the-good-way]
A member can't remove their **last** passkey unless the account still has a password or a linked SSO provider. A password only counts while [password sign-in](/docs/dev/advanced/auth#turning-off-password-sign-in) is switched on. The check runs in a transaction that locks the user row, so two tabs deleting "one of two" passkeys at once can't leave the account with nothing.
## Events [#events]
| Event | Payload | Fires when |
| ---------------------- | ----------------------------- | -------------------------- |
| `user.passkey.created` | `{ passkeyId, userId }` | A member adds a passkey |
| `user.passkey.updated` | `{ passkeyId, userId, name }` | A member renames a passkey |
| `user.passkey.deleted` | `{ passkeyId, userId }` | A member removes a passkey |
See [Built-in events](/docs/dev/events/built-in-events) for how to listen to them.
## Deployment checklist [#deployment-checklist]
- **Serve the site over HTTPS** on the exact origins you configured. A reverse proxy is fine - what matters is the URL in the member's address bar.
- **Set `VITNODE_WEB_URL`** in every environment, and set `rpId` in the config if you share passkeys across subdomains.
- **Preview deployments** on generated hostnames (e.g. `my-app-git-branch.vercel.app`) are different origins - passkeys created on production won't work there, and a preview needs its own origin in `origins` to register new ones.
- **Separate API server?** Nothing changes: the API checks the _web_ origin the ceremony ran on, not its own URL. Make sure `cookieDomain`/CORS already let the browser send credentialed requests to it.
- **Custom auth transport?** If you registered one with `setAuthTransport`, implement `startPasskeySignIn`, `finishPasskeySignIn`, `startAdminPasskeySignIn` and `finishAdminPasskeySignIn`, and relay cookies on all four - the challenge cookie is set by the first call and read by the second.
- **Rate limiting** - the options routes create a database row per call. Keep the [rate limiter](/docs/dev/advanced/rate-limiter) on in production.
## Troubleshooting [#troubleshooting]
In development, VitNode logs why a ceremony failed (wrong origin, RP ID mismatch, counter error...) to the API console. The browser only ever receives a generic error code.
| You see | Likely cause |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| No passkey button on `/login` | Passkeys disabled, or the derived config was invalid - check the boot log |
| "The RP ID is neither ... nor a parent domain" | `rpId` doesn't match the hostname of an origin |
| Browser error "invalid domain" / `SecurityError` | The page's hostname isn't the RP ID or a subdomain of it, or the page isn't HTTPS/localhost |
| "That took a little too long" | The five-minute challenge expired, or the cookie was blocked - start again |
| "Passkey not recognized" | The passkey was removed on the site, or it belongs to another RP ID |
# Using passkeys (/docs/dev/passkeys/using-passkeys)
A passkey lets you sign in with your fingerprint, your face or your device's screen lock - no password to remember, and nothing a phishing site can steal. It's the same thing your phone already uses to unlock itself, just pointed at this site.
Your passkey is stored on your device or in your password manager (iCloud Keychain, Google Password Manager, 1Password, Bitwarden and friends). The site only ever keeps a public key, which is useless to anyone who gets hold of it.
## Before you start [#before-you-start]
- Use a recent browser: Chrome, Safari, Edge or Firefox.
- Your device needs a screen lock - a PIN, pattern, password, fingerprint or face unlock. A hardware security key with a PIN works too.
- You need to be signed in the usual way to add your first passkey.
## Create a passkey [#create-a-passkey]
1. Sign in with your email and password (or your social login).
2. Open your avatar menu, go to **Settings**, then **Security**.
3. Select **Add a passkey**.
4. Your browser asks you to confirm - use your fingerprint, face, PIN or security key.
5. Done! You'll see "Passkey added", and the new passkey shows up in the list.
The passkey gets a name automatically, like "iCloud Keychain" or "Chrome (Mac OS)". Want something clearer, like "Work laptop"? Select the pencil icon next to it, type a new name and select **Save**.
If you see "Already set up", this device or password manager already has a
passkey for your account - you're good to go.
You can add as many passkeys as you like - for example one on your phone and one on your laptop. If your password manager syncs passkeys, one passkey follows you to all your devices; these show a **Synced** badge. Passkeys marked **This device only** live on one device or security key.
## Sign in with a passkey [#sign-in-with-a-passkey]
1. Go to the login page.
2. Select **Sign in with a passkey**. You don't need to type your email.
3. Pick your passkey in the browser prompt and confirm with your fingerprint, face or PIN.
That's it - you'll land wherever you were heading. Signing in on a computer with a passkey that lives on your phone? Most browsers offer a QR code to scan with your phone.
**On the staff team?** The same passkey signs you in to the AdminCP too. To
add one, sign in to the AdminCP with your password first, then add the
passkey from **Settings → Security** in the same browser. See [AdminCP
passkey sign-in](/docs/dev/passkeys/admincp).
## Remove a passkey [#remove-a-passkey]
1. Go to **Settings → Security**.
2. Select the red bin icon next to the passkey.
3. Confirm with **Remove**.
The site forgets the passkey straight away, so it can't be used to sign in anymore. It may still appear in your password manager - delete it there too to keep things tidy.
You can't remove your **last** passkey if it's the only way into your account.
Add another passkey, or set a password with "Forgot password?" on the login
page first. This keeps you from accidentally locking yourself out.
## Something went wrong? [#something-went-wrong]
| Message | What to do |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| Passkey sign-in cancelled | The prompt was closed or timed out. Just try again. |
| That took a little too long | The request expired after five minutes. Start again. |
| Passkey not recognized | That passkey was removed or belongs to another site. Try another one or use your password. |
| Passkeys aren't supported here | Your browser or device can't use passkeys. Update your browser or sign in another way. |
| Passkeys are turned off | This site has switched passkeys off for now. Use your password or social login. |
# Performance (/docs/dev/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:
| Route Option | Read When | In Initial Bundle? | Optimization |
| :----------------- | :-------------------- | :------------------ | :---------------------------------------------------------------------- |
| `path`, `id` | Route tree generation | **Yes** | Keep route paths concise |
| `head` | Page navigation | **Yes** | Isolate metadata strings in leaf files |
| `loader` | Pre-render | **Yes (fn only)** | `await import()` large dependencies inside fn |
| `pendingComponent` | Route loading | **Yes** | Plain skeleton markup only - never a layout component from a UI library |
| `component` | Render | **No (Lazy Chunk)** | Automatically code-split |
---
## 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 { Spinner } from '@vitnode/core/components/ui/spinner'
// [!code ++:6]
const RichEditor = React.lazy(async () =>
import('@vitnode/core/components/form/fields/editor').then((mod) => ({
default: mod.AutoFormEditor,
})),
)
export const ArticleEditor = (props) => (
```bash tab="bun"
bun run build
```
```bash tab="pnpm"
pnpm build
```
```bash tab="npm"
npm run build
```
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 (/docs/dev/plugins/admin/dashboard-widgets)
Dashboard widgets are **AdminCP plugin extensions**. Define the component and
list it on the plugin's `adminNav` export, next to its sidebar entries; the
AdminCP dashboard then discovers it automatically.
{/* Image prompt: VitNode AdminCP dashboard with a “Site notes” statistics widget in a draggable grid. Show the widget panel, the corner resize bracket on each card, and the settings gear. Dark theme, 1600x900. */}
### 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) => (
Published notes
{String(settings.total ?? 42)}
)
```
### Register it on the plugin's `adminNav` [#register-it-on-the-plugins-adminnav]
Add it to the `adminNav` your plugin exports from its `admin/nav` module (the
same object that holds its [sidebar entries](/docs/dev/plugins/admin)). VitNode
collects every plugin's `adminNav` into the app's generated `admin-nav.gen.ts`,
and the AdminCP shell hands the widgets to the dashboard.
```tsx title="plugins/site-notes/src/admin/nav.tsx"
import type { AdminNavPluginSource } from '@vitnode/core/lib/plugin'
import { BarChart3Icon } from 'lucide-react'
import { manifest } from '@/manifest.gen'
import { StatsWidget } from '@/views/admin/widgets/stats-widget'
export const adminNav = {
pluginId: manifest.id,
admin: {
dashboard: {
widgets: [
// [!code ++:8]
{
component: StatsWidget,
defaultEnabled: true,
defaultRows: 1,
defaultSpan: 1,
icon:
### Name it [#name-it]
The widget's title comes from your plugin's frontend messages, under
`admin.dashboard.widgets.{id}`. A `desc` is optional and shows in the widget panel.
```json title="plugins/site-notes/src/locales/en.json"
{
"@acme/site-notes": {
"admin": {
"dashboard": {
"widgets": {
"stats": { "title": "Note stats", "desc": "How many notes are live." }
}
}
}
}
}
```
### 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/admin/nav.tsx"
{
component: StatsWidget,
// [!code ++:4]
permission: { module: 'site_notes', permission: 'can_view_stats' },
settingsComponent: StatsSettings,
id: 'stats',
}
```
## 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 in the widget's panel while the dashboard is being edited. |
## How admins arrange them [#how-admins-arrange-them]
Your widget does not need any code for this - it is what the dashboard does with every widget. Press **Edit layout** and the **Widgets** panel slides in beside the grid.
| To… | Do this |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **Add a widget** | Click it in the panel to put it at the end, or drag it onto the grid. While you drag, the grid opens a gap the widget's real size, right where it will land. |
| **Change your mind** | Drag it back over the panel and let go. Nothing is added, and the card glides back to where it came from. |
| **Move a widget** | Drag the card from anywhere on it, or Tab to it and use Space and the arrow keys. The spot it came from turns into a dashed slot. |
| **Resize a widget** | Grab the little bracket in the card's bottom corner and pull. Sideways snaps the width between 1 and 3 columns, down and up snap the height between 1 and 3 rows, and the other widgets glide out of the way. A dashed outline follows your pointer so you can see where you are pulling. From the keyboard, Tab to the corner and use the arrow keys. |
| **Edit a widget** | Click the card (or Tab to it and press Enter ). The panel switches to that widget: a width switch, its own settings form if it has one, and a bin in the header. **Save settings** stores the settings straight away and leaves the rest of your unsaved arrangement alone. The arrow at the top goes back to the list. |
| **Remove a widget** | The bin on the card's toolbar, or in its panel. |
| **Finish** | The panel footer says whether anything changed. **Save** keeps the arrangement; **Cancel** throws it away and leaves edit mode. |
New widgets fade in and scroll into view, and screen readers hear where a widget was picked up and dropped in the admin's own language. With _reduce motion_ turned on in the operating system, all of it happens instantly.
The drop gap uses `defaultSpan` and `defaultRows`, so pick them to match what the widget looks like the moment it is added.
# AdminCP Pages (/docs/dev/plugins/admin)
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.
### 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')),
}),
])
```
### Render the plugin page [#render-the-plugin-page]
```tsx title="plugins/site-notes/src/pages/admin-settings-page.tsx"
const AdminSettingsPage = () => (
Site notes settings
Manage the notes plugin.
)
export default AdminSettingsPage
```
### 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:
### Verify the screen [#verify-the-screen]
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
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. */}
## Extend the panel [#extend-the-panel]
# API Modules (/docs/dev/plugins/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.
`create-vitnode-app --plugin` writes a `hello` module, its `config.api.ts` and
a page that calls it. Read on for what each piece does—then rename them, or add
a second module beside 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. */}
### Define one plugin endpoint [#define-one-plugin-endpoint]
Route and module files import their builders from the plugin's own
`src/api/builders.ts`, which binds them to the generated `manifest`. That is
where the plugin id comes from, so no route or module spells it:
```ts title="plugins/site-notes/src/api/builders.ts"
import { bindApiPlugin } from '@vitnode/core/api/lib/bind-api-plugin'
import { manifest } from '@/manifest.gen'
export const { buildModule, buildRoute } = bindApiPlugin(manifest)
```
```ts title="plugins/site-notes/src/api/modules/notes/list.route.ts"
import { z } from '@hono/zod-openapi'
import { buildRoute } from '@/api/builders'
export const listNotesRoute = buildRoute({
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'] }),
})
```
### 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 '@/api/builders'
import { listNotesRoute } from './list.route'
export const notesModule = buildModule({
name: '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'
import { manifest } from './manifest.gen'
export const siteNotesApiPlugin = () =>
buildApiPlugin({
manifest,
modules: [notesModule], // [!code ++]
})
```
This file, and not `config.tsx`: the API config reaches your handlers, database
and secrets, while `config.tsx` is read by the browser build. A module
registered in the wrong one is shipped to every visitor.
`buildApiPlugin` keeps everything it was given as a literal type - the plugin
id, the tuple of modules, and every module nested inside them. That type is
what the [fetcher](/docs/dev/fetcher) infers routes from, so a route you add
here is callable, and checked, the moment you save.
### Export the type an application registers [#export-the-type-an-application-registers]
Your pages call the endpoint through the universal fetcher, and the fetcher
looks the plugin up in the API plugin registry. Export one reduced type beside
your factory - `create-vitnode-app --plugin` writes this for you:
```ts title="plugins/site-notes/src/config.api.ts"
import type { ApiPluginContract } from '@vitnode/core/api/lib/plugin'
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
export const siteNotesApiPlugin = () =>
buildApiPlugin({ manifest, modules: [notesModule] })
// [!code ++:3]
export type VitNodeApiPlugin = ApiPluginContract<
ReturnType
>
```
`ApiPluginContract` keeps the four things a call needs - the literal plugin id,
every module path you serve, your module tree and your route definitions - and
drops everything else. Your Hono application, content models, event listeners,
queue tasks, WebSockets, search indexers and messages are runtime concerns, so
an app that installs your plugin never resolves them to type-check a call.
`import type` is the whole point: the factory is never executed here, so none of
the Hono, database or secret code behind it is ever reached by a browser build.
Your package augments nothing. The app that installs you writes the entry into
its own generated `src/api-registry.gen.ts`, from the plugins it configured. A
package that registered itself would put its routes into the registry of every
project that merely installed it.
To type-check your own pages before any app has installed the plugin, the
scaffold writes `test-fixtures/api-registry.d.ts` - the same entry an app
generates, kept outside `src` and out of the published package.
### 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. This is the one place `siteNotesApiPlugin()`
is ever called - everywhere else it is a type.
### Call it [#call-it]
```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'
const response = await fetcher({
plugin: '@acme/site-notes', // [!code ++]
method: 'get',
module: 'notes',
path: '/',
})
const { notes } = await response.json()
```
Nothing but the plugin id crosses into the browser bundle. `module`, `path`,
`method` and the response are inferred from the module tree registered above,
and a typo in any of them is a compile error.
# API Routes (/docs/dev/plugins/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.
### 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 '@/api/builders'
export const getNoteRoute = buildRoute({
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' })
},
})
```
### 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 '@/api/builders'
export const publishNoteRoute = buildRoute({
// [!code ++:4]
adminStaffPermission: {
module: 'site_notes',
permission: 'can_publish',
},
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 }),
})
```
{/* 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. */}
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.
# Build and watch a plugin (/docs/dev/plugins/build)
`vitnode build` turns a plugin's `src` folder into `dist/src`: one JavaScript file, one declaration file (`.d.ts`) and one declaration map per module. `vitnode dev` does the same in watch mode, so an app using the plugin reloads as you save. There is no build config to write. VitNode owns it, and every plugin and adapter package is built the same way.
## What tsdown does [#what-tsdown-does]
[tsdown](https://tsdown.dev) is the compiler behind both commands. It runs in **unbundle mode**: every module is compiled on its own instead of being merged into one bundle, so `src/pages/home-page.tsx` becomes `dist/src/pages/home-page.js`.
Every `.ts` and `.tsx` file under `src` is compiled, not only what an `index.ts` imports, because the plugin's `"./*"` export makes each module public. Test files (`*.test.ts`, `*.test.tsx`, `*.test-d.ts`), `src/tests/`, `__tests__/` and `__fixtures__/` folders stay out of `dist`.
The output is ES modules that Node and Vite load as they are:
- **Imports of packages stay imports.** React, Hono, Drizzle, `@vitnode/core` and every other package are left for the app to install, exactly as written.
- **Relative imports get their `.js` extension**, and dynamic imports such as `lazy(() => import("./pages/home-page"))` keep working.
- **`@/` aliases become relative paths**, in the JavaScript and in the declarations. The aliases come from `paths` in `tsconfig.build.json`.
- **JSX** uses React's automatic runtime (`react/jsx-runtime`).
- **File names are kept**, so `auth.server.ts` stays `auth.server.js`. Modules keep their side effects; nothing is tree-shaken away.
A production build is minified and ships declaration maps, but no JavaScript source maps. `vitnode dev` writes readable JavaScript with source maps instead.
## Assets and aliases [#assets-and-aliases]
Every file under `src` that is not code (locale JSON, CSS, images for emails) is copied to the same place under `dist/src`. Imports of those files stay imports, with their import attributes:
```ts title="src/locales/index.ts"
export default {
en: async () => await import("./en.json", { with: { type: "json" } }),
};
```
`dist/src/locales/index.js` imports `./en.json` next to it, so the compiled module finds its JSON the way the source did. An app loads your translations through the `"./locales/*.json"` export instead, which points at `src/locales`.
## Types and declarations [#types-and-declarations]
Two TypeScript jobs run side by side, and both must pass:
| Job | What it does |
| -------------- | ------------------------------------------------------------------------------ |
| tsdown | Writes the `.d.ts` files and their maps with the TypeScript compiler |
| `tsc --noEmit` | Type checks the whole package with `tsconfig.build.json` and fails on an error |
Declarations are written from every file `tsconfig.build.json` includes. That matters for files nothing imports, such as `global.d.ts` and the generated `types/api-registry.gen.d.ts`: they are what lets `fetcher({ plugin: "@acme/site-notes", ... })` infer its response, and that inferred type lands in your `.d.ts` files.
You don't need `isolatedDeclarations` or explicit return types. Inferred types come out the same as `tsc` would write them.
## Generated manifest [#generated-manifest]
Before compiling, `vitnode build` also writes `src/manifest.gen.ts`. It exports `manifest`, which holds the plugin's `name` (as `id`), `version`, `description`, `author` and `license` from `package.json`, and imports the title, Lucide icon and update source from the plugin's own `src/plugin-info.ts`. `vitnode dev` writes it on start and again whenever `package.json` changes. It is the single source of the plugin id, passed to `buildPlugin()`, `buildApiPlugin()` and `bindApiPlugin()`, and it is what the [AdminCP plugin catalog](/docs/dev/plugins/catalog) shows, so commit it with the rest of `src`.
## What a plugin package needs [#what-a-plugin-package-needs]
| File | Why |
| --------------------- | --------------------------------------------------------------------------------------- |
| `package.json` | `"type": "module"`, `exports` pointing into `./dist/src/`, and `tsdown` and `typescript` in `devDependencies` |
| `tsconfig.json` | Compiler options for your editor, with `"paths": { "@/*": ["./src/*"] }` |
| `tsconfig.build.json` | The same, without tests: what `vitnode build` compiles and type checks |
The CLI treats a folder as a plugin package when it has `tsconfig.build.json` and its `exports` point into `./dist/src/`. `create-vitnode-app` generates all three files. A `tsdown.config.ts` in a plugin is not read.
## How `vitnode dev` watches a plugin [#how-vitnode-dev-watches-a-plugin]
`vitnode dev` runs three watchers:
- **tsdown js** rebuilds the JavaScript and copies changed assets, usually within 100 ms for a plugin.
- **tsdown types** rebuilds the declarations once TypeScript has caught up, a few seconds later.
- **`tsc --watch --noEmit`** prints type errors.
The two tsdown watchers run as separate processes, so the TypeScript compiler never holds back the JavaScript your app reloads.
Adding, deleting or renaming a file restarts both tsdown watchers with the new list of modules, after a short pause so a branch switch counts as one change. Output for a deleted module is removed from `dist/src`. A file that fails to compile is reported, the last good output stays in place, and the next save rebuilds.
Ctrl +C stops every watcher. If one of them exits on its own, the CLI stops the rest and exits with an error.
## How dist stays consistent [#how-dist-stays-consistent]
A build only writes to `dist/src`, and only files whose content changed. An app watching the plugin reloads for the module you edited, not for every file in the package. After a successful build, files under `dist/src` that no source produces anymore are deleted. Nothing outside `dist/src` is touched, so don't keep hand-written files in `dist/src`.
Writes are not atomic. A changed file is overwritten in place, so for a moment an app's dev server can see the old or a partly written file, and may reload once more when the write finishes. Since only changed files are written, this window covers the files you edited.
## Plugin, CLI and app builds [#plugin-cli-and-app-builds]
VitNode uses different builds for different things. This page is about the first one.
| Build | Who runs it | Tool |
| -------------- | ---------------------------------- | ----------------------------------------------------------- |
| Plugin package | `vitnode build` in a plugin | tsdown in unbundle mode, plus `tsc --noEmit` |
| VitNode CLI | `pnpm build:scripts` in `@vitnode/core` | tsdown with `packages/vitnode/tsdown.config.ts`, into `dist/scripts` |
| App | `vitnode build` in an app | Vite and TanStack Start, unchanged |
`@vitnode/core` itself is built as a plugin package into `dist/src`. Its CLI build writes `dist/scripts` and only cleans that folder, so the two never delete each other's output.
## Limitations [#limitations]
- tsdown needs Node.js `^22.18.0`, `^24.11.0` or `26` and later, which is also the range VitNode supports. Node.js 23 and 25 are not on the list.
- Declarations are generated by the TypeScript compiler, which is the slow part of a build. In watch mode they arrive a few seconds after the JavaScript. For a package as large as `@vitnode/core`, adding or deleting a file rebuilds all of its declarations.
- Each JavaScript rebuild renders every module of the package again and writes only the changed ones. That takes under 100 ms for a typical plugin and about 2 seconds for the roughly 1,600 modules of `@vitnode/core`.
- A re-export-only `index.ts` may get no `.d.ts.map`, so "Go to definition" stops at its `.d.ts` first.
## Next steps [#next-steps]
# Show a plugin in the AdminCP catalog (/docs/dev/plugins/catalog)
**AdminCP → System → Plugins** lists every plugin the running application is configured with: its icon, title, package ID, description and installed version, with the VitNode core version shown separately above the list. The version and description come from each plugin's own `package.json` at build time, so nobody types a version number by hand. The title and icon come from a small file in the plugin.
### Describe the plugin in package.json [#describe-the-plugin-in-packagejson]
Make sure your `package.json` has a `description` next to its `name` and `version`:
```json title="plugins/site-notes/package.json"
{
"name": "@acme/site-notes",
"version": "1.2.0",
"description": "Pin short notes to any page of your community."
}
```
### Set the title and icon [#set-the-title-and-icon]
Create `src/plugin-info.ts` with the title and a [Lucide icon](https://lucide.dev/icons) name:
```ts title="src/plugin-info.ts"
import type { PluginInfo } from '@vitnode/core/lib/plugin-manifest'
export const pluginInfo: PluginInfo = {
title: 'Site Notes',
icon: 'sticky-note',
}
```
Plugins created with the generator already have this file, with the `puzzle` icon.
### Register the generated manifest [#register-the-generated-manifest]
`vitnode build` writes `src/manifest.gen.ts`. It holds the `name`, `version`, `description`, `author` and `license` from `package.json` and imports the title and icon from `src/plugin-info.ts`. It is also the single source of the plugin id (`manifest.id`), so nothing else spells the id by hand. Pass it to both registrations:
```tsx title="src/config.tsx"
import { buildPlugin } from '@vitnode/core/lib/plugin'
import { manifest } from './manifest.gen'
import { routes } from './routes'
export const siteNotesPlugin = () =>
buildPlugin({
manifest,
routes,
})
```
```ts title="src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
import { manifest } from '@/manifest.gen'
export const siteNotesApiPlugin = () =>
buildApiPlugin({
manifest,
modules: [],
})
```
### Build the plugin [#build-the-plugin]
Run the build in the plugin's folder, or keep `vitnode dev` running:
```bash
vitnode build
```
Both commands generate the file before TypeScript and tsdown run. Commit it, like `types/api-registry.gen.d.ts`.
### Check the result [#check-the-result]
Restart your app, sign in to the AdminCP and open **System → Plugins**. Your plugin shows its icon, title, `@acme/site-notes`, the description and `1.2.0`. Search matches the title, the package ID and the description.
## Where each value comes from [#where-each-value-comes-from]
| Value | Source | Required | Default |
| ----------- | ------------------------------- | -------- | -------------- |
| ID | `name` in `package.json` | Yes | - |
| Version | `version` in `package.json` | No | Unknown |
| Description | `description` in `package.json` | No | No description |
| Title | `title` in `src/plugin-info.ts` | No | The ID |
| Icon | `icon` in `src/plugin-info.ts` | No | Puzzle icon |
The ID is the plugin id: `buildPlugin()` and `buildApiPlugin()` read it from `manifest.id`. Title and description are plain text, shown as written in every language. The icon is a Lucide icon name in kebab-case, such as `newspaper` or `messages-square`. `buildPlugin()` and `buildApiPlugin()` throw at startup for anything else, and an unknown name falls back to the puzzle icon. Because an icon is just a name, the API returns it too, so plugins registered only in the API show their own icon as well.
## When the manifest is regenerated [#when-the-manifest-is-regenerated]
- `vitnode build` regenerates the file before every build, so a published package always carries its real version.
- `vitnode dev` regenerates it whenever `package.json` changes, or `src/plugin-info.ts` is created or deleted. Edits inside `src/plugin-info.ts` need no regeneration: the generated file imports it. The file is only rewritten when its content changes, so adding a dependency rebuilds nothing.
- A broken `package.json` edit is reported in the terminal and the last good file stays in place.
The app picks up a new plugin, a removed one or a new version after it is rebuilt and restarted. Nothing is stored in the database.
## Frontend and API inventory [#frontend-and-api-inventory]
A plugin can be registered in `vitnode.config.ts` (frontend), in `vitnode.api.config.ts` (API), or both. The catalog lists each plugin ID once. The API cannot see the frontend config, so the web build hands it over: the Vite plugin writes `src/plugin-inventory.gen.ts`, a plain list of `{ id, manifest }` entries with no plugin code, and you pass it to the API config:
```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { frontendPlugins } from './plugin-inventory.gen'
export const vitNodeApiConfig = buildApiConfig({
plugins: [siteNotesApiPlugin()],
frontendPlugins,
// ...the rest of your API config
})
```
New apps that serve their API from the web app already do this. If your API runs as a separate deployment without that web build, leave `frontendPlugins` out. The catalog then lists the API's plugins only and says so with a notice, instead of guessing what the browser runs.
## Version mismatch warnings [#version-mismatch-warnings]
When the web build and the API both report a version for the same plugin and the versions differ, the row shows a warning such as _"Version mismatch: the web app runs 1.1.0, the API runs 1.2.0."_ It usually means one side was redeployed without the other. Rebuild and redeploy both.
A side that reports no version is unknown, not a mismatch.
## Older plugins [#older-plugins]
`buildPlugin()` and `buildApiPlugin()` take the plugin id from `manifest`, so an older plugin that still passes `pluginId` needs `src/manifest.gen.ts` first: run `vitnode build` or `vitnode dev` once, then pass `manifest` instead. A plugin without `src/plugin-info.ts` gets its ID as the title and the default icon. Add it when convenient.
A frontend inventory entry carrying the manifest of another package throws at startup: the API checks that `manifest.id` equals the entry's `id`.
## Update and security information [#update-and-security-information]
Add `updates.url` to your plugin's `src/plugin-info.ts` and the catalog row also shows new releases and security updates. Setup is covered in [Publish updates for your plugin](/docs/dev/updates/plugin-authors); what administrators see is in [Check for updates in the AdminCP](/docs/dev/updates/admin).
## Who can see the catalog [#who-can-see-the-catalog]
The page and its endpoint, `GET /api/@vitnode/core/admin/plugins`, require the **Plugins → View installed plugins and their versions** permission (`plugins.can_view` in the `@vitnode/core` module). Staff without it don't see the link, get a not-found page on a direct visit, and a `403` from the API. Root administrators have it automatically. The **Check for updates** button additionally needs `plugins.can_check_updates`.
# Create a Plugin (/docs/dev/plugins/create)
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.
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/*`.
### Generate the package [#generate-the-package]
Run this at the workspace root and enter a package name such as
`@acme/site-notes` when prompted:
```bash tab="bun"
bun create vitnode-app@canary --plugin
```
```bash tab="pnpm"
pnpm create vitnode-app@canary --plugin
```
```bash tab="npm"
npm create vitnode-app@canary -- --plugin
```
### Run/Restart it and visit the route [#runrestart-it-and-visit-the-route]
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
### Check the generated page [#check-the-generated-page]
Visit the route printed in the console, such as `http://localhost:3000/site-notes`. You should see a page with a title and a link to the plugin's README.
## What gets generated [#what-gets-generated]
One page at `/site-notes` whose loader calls the plugin's own `hello` endpoint, its strings, and a Vitest test for the endpoint (`pnpm test` in the plugin). `src/plugin-info.ts` sets the plugin's title and Lucide icon for [the AdminCP plugin catalog](/docs/dev/plugins/catalog), and `src/api/builders.ts` binds `buildModule` and `buildRoute` to the plugin's generated `manifest`, so API files never spell the plugin id. The generator also registers the plugin in your apps' `vitnode.config.ts` and `vitnode.api.config.ts`, installs it and builds it.
The plugin name must be a valid npm name and must not be one of core's routes: `admin`, `api`, `core`, `discover`, `files`, `login`, `notifications`, `register`, `search`, `users` or `vitnode`.
Check the result the way your app will load it:
```bash
vitnode plugin validate site-notes
```
See [Plugin CLI](/docs/dev/cli/plugins) for what validation checks.
## Add the next capability [#add-the-next-capability]
# Migrate a plugin from SWC to tsdown (/docs/dev/plugins/migrate-to-tsdown)
Plugins generated before the switch to tsdown compiled with `tsc`, SWC and `tsc-alias`. `vitnode build` and `vitnode dev` no longer run those tools, so an older plugin needs `tsdown` instead. Your sources, exports and import paths stay the same, and the migration takes about five minutes.
### Swap the build dependencies [#swap-the-build-dependencies]
In the plugin's folder, remove SWC and `tsc-alias`, then add tsdown:
```bash tab="bun"
bun remove @swc/cli @swc/core tsc-alias
bun add -D tsdown
```
```bash tab="pnpm"
pnpm remove @swc/cli @swc/core tsc-alias
pnpm add -D tsdown
```
```bash tab="npm"
npm uninstall @swc/cli @swc/core tsc-alias
npm i -D tsdown
```
Keep `typescript`: the build still uses it for declarations and type checking. If a standalone API app in your workspace builds with `tsc-alias`, keep it there. Only plugin packages switched.
### Delete `.swcrc` [#delete-swcrc]
Delete `.swcrc` from the plugin, and the `/.swcrc` line from its `.npmignore`. VitNode owns the build configuration, so there is nothing to replace it with.
### Check `package.json` [#check-packagejson]
The scripts should call the CLI, and `exports` should point into `./dist/src/`, which is how the CLI recognizes a plugin package now that `.swcrc` is gone:
```json title="package.json"
{
"type": "module",
"scripts": {
"build:plugins": "vitnode build",
"dev": "vitnode dev"
},
"exports": {
"./locales/*.json": "./src/locales/*.json",
"./*": {
"import": "./dist/src/*.js",
"types": "./dist/src/*.d.ts",
"default": "./dist/src/*.js"
}
}
}
```
If your scripts still run `tsc`, `swc` and `tsc-alias` directly, replace them with these two.
### Build the plugin [#build-the-plugin]
```bash tab="bun"
bun run build:plugins
```
```bash tab="pnpm"
pnpm build:plugins
```
```bash tab="npm"
npm run build:plugins
```
The first build removes leftovers from the old build that no source produces anymore, such as a stray `dist/vitest.config.d.ts`. Files outside `dist/src` are not touched.
## Check the result [#check-the-result]
Validate the plugin from the app that uses it, through the same loaders the app runs:
```bash
vitnode plugin validate
```
`dist/src` holds one `.js`, `.d.ts` and `.d.ts.map` per module, plus copies of your JSON and CSS. Then start `vitnode dev` in the plugin and save a file: the app reloads with the change.
## Troubleshooting [#troubleshooting]
| Message | Fix |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `... is not a VitNode app, API or plugin package.` | Add `tsconfig.build.json`, or point `exports` into `./dist/src/` |
| `Could not find "tsdown" from ...` | Install `tsdown` in the plugin as shown in the first step |
| `Build failed: tsc exited with code 2` | A type error. The build prints it; the old build failed on it too |
| A file you put in `dist/src` by hand disappears | Move it to `src`. Non-code files there are copied to `dist/src` on every build |
[Build and watch a plugin](/docs/dev/plugins/build) explains what the new build does with each file.
# Breadcrumbs (/docs/dev/routing/breadcrumbs)
VitNode renders breadcrumb trails automatically in both the public site header and the AdminCP shell. **A route joins the trail by declaring a crumb**, and the trail reads parent to child:
```text
Home / Notes / Getting Started
```
A route declares only what its own crumb should display. VitNode manages the rest: accessible `` markup, separators, locale-aware links, and `aria-current="page"` semantics. No manual link construction, no duplicated trails, and zero drama.
## Static crumb [#static-crumb]
Declare a breadcrumb function directly inside `definePluginRoute`. Because it renders within the route's declared namespaces, `useTranslations` works out of the box:
```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'
// [!code ++:7]
export const route = definePluginRoute({
breadcrumb: () => {
const t = useTranslations('@acme/site-notes.home')
return t('title')
},
})
const NotesLayout = ({ children }: { children: React.ReactNode }) => {
return (
{children}
)
}
export default NotesLayout
```
{/* Image prompt: Modern web header showing breadcrumb trail Home / Notes with Notes highlighted in dark theme, 1440x900. */}
## Dynamic crumb from loader [#dynamic-crumb-from-loader]
When a route is dynamic (such as `/notes/:slug`), its breadcrumb can read directly from the route's `loaderData`. This ensures the trail shows human-readable titles instead of raw IDs, without firing a second network request:
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
definePluginRoute,
type PluginRoutePageProps,
} from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'
interface Note {
content: string
title: string
}
export const route = definePluginRoute({
load: async ({ params }): Promise => {
return {
content: 'Loaded securely from your plugin loader.',
title: `Note: ${params.slug}`,
}
},
head: ({ loaderData, params }) => ({
title: loaderData?.title ?? params.slug,
}),
// [!code ++:5]
breadcrumb: ({ loaderData }) => {
const t = useTranslations('@acme/site-notes.home')
return `${t('note')}: ${loaderData.title}`
},
})
const NotePage = ({ loaderData }: PluginRoutePageProps) => {
return (
{loaderData.title}
{loaderData.content}
)
}
export default NotePage
```
The inline `breadcrumb` receives `{ loaderData, params, search }`—the exact same typed context passed to `head` and the page component.
{/* Image prompt: Header breadcrumb trail showing Home / Notes / Note: getting-started with the final crumb active, 1440x900. */}
## Omitting a route [#omitting-a-route]
Silence is the default: a route that declares no `breadcrumb` adds none, and the crumbs above it stay intact. Set `breadcrumb: false` when you want that silence to be deliberate—an `index()` page whose parent layout already names the screen, say:
```tsx title="plugins/site-notes/src/pages/notes-index-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
// [!code ++:3]
export const route = definePluginRoute({
breadcrumb: false,
})
const NotesIndexPage = () => {
return (
)
}
export default NotesIndexPage
```
Both spellings do the same thing. The trail simply ends at the deepest route that does declare a crumb, and that crumb is the one marked `aria-current="page"`.
## Trail behavior [#trail-behavior]
| Declaration | Behavior in breadcrumb trail |
| :---------------------- | :-------------------------------------------------------------------------- |
| `breadcrumb: Component` | Contributes one crumb with access to `loaderData`, `params`, and `search` |
| `breadcrumb: false` | Omitted from trail; parent crumbs remain visible |
| Omitted / `undefined` | The default: omitted from trail |
| Intermediate crumbs | Automatically rendered as locale-aware links to their respective route URLs |
| Leaf crumb (last item) | Rendered as text without a link and marked with `aria-current="page"` |
A breadcrumb component should return text or an inline element (like an icon with text). Never render ``, ``, links, or separators—the shell creates the landmark and manages links and separators for you.
In the AdminCP, breadcrumbs seamlessly coordinate with the admin navigation
declared in `admin/nav.tsx`. When a route matches a sidebar item, its
translated label is resolved automatically.
# Routing (/docs/dev/routing)
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.
## Simple route [#simple-route]
You can declare a single page with a path and a lazy component:
```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'
export const routes = definePluginRoutes([
page('/notes', {
component: lazy(() => import('./pages/note-page')),
messages: ['@acme/site-notes.home'],
}),
])
```
```tsx title="plugins/site-notes/src/pages/note-page.tsx"
import { useTranslations } from 'use-intl'
const NotePage = () => {
const t = useTranslations('@acme/site-notes.home')
return (
{t('title')}
)
}
export default NotePage
```
The `messages` array specifies which translation namespaces this page requires. A namespace must always be a **dotted path** into your plugin's message tree (such as `@acme/site-notes.home` rather than the bare plugin ID), allowing VitNode to only download the strings that this screen renders. For more details on message structure and limits, see the [Namespaces](/docs/dev/i18n/namespaces) and [Translating Pages](/docs/dev/i18n/pages) guides.
{params.slug}
)
}
export default NotePage
```
{/* Image prompt: Browser showing /notes/getting-started with a clean modern page heading 'getting-started' in dark theme, max-w-3xl container, 1440x900. */}
## Metadata (Head) [#metadata-head]
The `head` function returns the page's `` and `<meta>` tags. It runs
after the loader, so it can use the data to make a unique title, description, and other SEO tags.
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
// [!code ++:1]
definePluginRoute,
type PluginRoutePageProps,
} from '@vitnode/core/routing'
// [!code ++:6]
export const route = definePluginRoute({
head: ({ params }) => ({
description: 'A note delivered by the Site notes plugin.',
title: params.slug,
}),
})
const NotePage = ({ params }: PluginRoutePageProps) => {
return (
<article className="container mx-auto max-w-3xl p-4">
<h2 className="text-3xl font-semibold tracking-tight text-balance">
{params.slug}
</h2>
</article>
)
}
export default NotePage
```
### Localizing metadata [#localizing-metadata]
`head` runs outside the React component tree—during SSR and on every
navigation—so hooks like `useTranslations` cannot reach it. Instead, `head`
receives `t`, a translator over the namespaces the route declared in `messages`:
```ts title="plugins/site-notes/src/routes.ts"
page('/notes/:slug', {
component: lazy(() => import('./pages/note-page-slug')),
// [!code ++:1]
messages: ['@acme/site-notes.home'],
})
```
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
export const route = definePluginRoute({
// [!code ++:4]
head: ({ params, t }) => ({
description: t('@acme/site-notes.home.desc'),
title: `${t('@acme/site-notes.home.note')}: ${params.slug}`,
}),
})
```
Keys are **full dotted paths**, namespace included. A component scopes itself
once with `useTranslations('@acme/site-notes.home')` and then asks for
`t('title')`; in `head` there is no component to scope, so the whole key is
spelled out.
Values interpolate the same way they do in a component:
```tsx
head: ({ t }) => ({
title: t('@acme/site-notes.home.greeting', { name: 'Ada' }),
})
```
<Callout type="info" title="No extra request">
The route's namespaces are already fetched before `head` runs—the loader warms
them, and `head` runs after the loader—so translating metadata costs a cache
read, not a round trip.
</Callout>
`load` receives the same `t`, for a title that depends on data you are already
fetching:
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
export const route = definePluginRoute({
load: async ({ params, t }) => {
const note = await findNote(params.slug)
return { heading: `${t('@acme/site-notes.home.note')}: ${note.title}` }
},
head: ({ loaderData }) => ({ title: loaderData?.heading }),
})
```
<Callout type="warn" title="Declare the namespace first">
Calling `t` on a route that declares no `messages` throws, naming the
namespace to add. Echoing the key back instead would ship
`@acme/site-notes.home.title` into a `<title>`, where nothing would surface it
until it showed up in a search result.
</Callout>
## Loaders [#loaders]
Fetch data in `load`. It runs on the server during SSR and on the client for subsequent navigations. Data returned from `load` is automatically passed to both `head` (for dynamic metadata) and the page component as `loaderData`.
<Callout type="info" title="Declare load above head">
Always declare `load` **above** `head` in `definePluginRoute`. TypeScript
infers the type of `loaderData` in `head` directly from the return type of
`load`.
</Callout>
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
definePluginRoute,
type PluginRoutePageProps,
} from '@vitnode/core/routing'
interface Note {
content: string
title: string
}
export const route = definePluginRoute({
// [!code ++:6]
load: async ({ params }): Promise<Note> => {
return {
content: 'Loaded securely from your plugin loader.',
title: `Note: ${params.slug}`,
}
},
head: ({ loaderData, params }) => ({
description: loaderData?.content,
title: loaderData?.title ?? params.slug,
}),
})
const NotePage = ({ loaderData }: PluginRoutePageProps<Note>) => {
return (
<article className="container mx-auto flex max-w-3xl flex-col gap-4 p-4">
<h1 className="text-3xl font-semibold tracking-tight text-balance">
{loaderData.title}
</h1>
<p className="text-muted-foreground leading-relaxed text-pretty">
{loaderData.content}
</p>
</article>
)
}
export default NotePage
```
{/* Image prompt: Browser preview showing the rendered note page with title and content in container, 1440x900. */}
## Breadcrumbs [#breadcrumbs]
Declare a crumb directly in `definePluginRoute` to contribute to the public header or AdminCP breadcrumb trail.
Because `breadcrumb` renders as a React component within the route's declared namespaces, `useTranslations` from `use-intl` works out of the box:
```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'
// [!code ++:7]
export const route = definePluginRoute({
breadcrumb: () => {
const t = useTranslations('@acme/site-notes.home')
return t('title')
},
})
```
For dynamic routes, the crumb receives `{ loaderData }` and can combine dynamic records with localized copy:
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'
export const route = definePluginRoute({
load: async ({ params }): Promise<Note> => {
return {
content: 'Loaded securely from your plugin loader.',
title: params.slug,
}
},
head: ({ loaderData, params }) => ({
title: loaderData?.title ?? params.slug,
}),
// [!code ++:5]
breadcrumb: ({ loaderData }) => {
const t = useTranslations('@acme/site-notes.home')
return `${t('note')}: ${loaderData.title}`
},
})
```
For nested trails, deferred crumbs, and AdminCP trails, see the [Breadcrumbs guide](/docs/dev/routing/breadcrumbs).
## Loading states [#loading-states]
A route's `pendingComponent` is the skeleton shown while its page suspends, for example on a client-only route or a query the loader does not await. Client navigations keep the current page on screen with a top progress bar instead.
```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'
// [!code ++:1]
import { TablePendingSkeleton } from '@vitnode/core/tanstack/pending'
export const routes = definePluginRoutes([
page('/notes', {
component: lazy(() => import('./pages/notes-page')),
// [!code ++:1]
pendingComponent: TablePendingSkeleton,
}),
])
```
<Callout type="warn" title="A pending component is not code-split">
A router draws it *before* the page's own chunk has arrived, so there is
nothing to wait for it—TanStack Router never splits a `pendingComponent`, and
neither does VitNode. It is imported outright into the initial bundle. Keep it
to a skeleton.
</Callout>
VitNode ships pre-built skeleton shapes from `@vitnode/core/tanstack/pending`: `TablePendingSkeleton`, `FeedPendingSkeleton`, `FormPendingSkeleton`, `CardsPendingSkeleton`, `ProfilePendingSkeleton`, `AuthPendingSkeleton`, and `RoutePendingSpinner`.
To customize skeleton props (such as `rows` or `className`), rename the file to `routes.tsx` and return a JSX element:
```tsx title="plugins/site-notes/src/routes.tsx"
page('/notes', {
component: lazy(() => import('./pages/notes-page')),
// [!code ++:1]
pendingComponent: () => <FeedPendingSkeleton rows={4} />,
})
```
If `pendingComponent` is omitted, the route falls back to the application's global `defaultPendingComponent`. Learn more in the [Loading States guide](/docs/dev/routing/loading).
## Missing pages [#missing-pages]
When a loader cannot find what the URL requested, throw `notFound()` from `@tanstack/react-router` to activate the route's `notFound` component:
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { notFound } from '@tanstack/react-router'
import { definePluginRoute } from '@vitnode/core/routing'
export const route = definePluginRoute({
load: async ({ params }) => {
const note = await findNote(params.slug)
// [!code ++:3]
if (!note) {
throw notFound()
}
return note
},
// [!code ++:5]
notFound: () => (
<div className="container mx-auto p-4">
<p className="text-muted-foreground leading-relaxed">No such note.</p>
</div>
),
})
```
Unlike `pendingComponent`, `notFound` is part of the lazy page chunk and costs unvisited routes nothing. If omitted, the route falls through to the application's global `defaultNotFoundComponent`, preserving the application layout and navigation shell. Learn more in the [Errors & Not Found guide](/docs/dev/routing/not-found).
## Catch-all routes [#catch-all-routes]
A `*` segment matches every remaining segment of the URL, allowing a single route to own an entire subtree. It must be the final segment of a path and is only permitted on `page()` declarations (a layout ending in `*` would match before its child routes):
```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-catch-all')),
}),
])
```
The page reads the matched trailing path from `params._splat`:
```tsx title="plugins/site-notes/src/pages/notes-catch-all.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
const NotesCatchAll = ({ params }: PluginRoutePageProps) => {
const segments = (params._splat ?? '').split('/').filter(Boolean)
return (
<div className="container mx-auto max-w-3xl p-4">
<p className="text-muted-foreground leading-relaxed">
{segments.join(' / ')}
</p>
</div>
)
}
export default NotesCatchAll
```
## Route protection (requires) [#route-protection-requires]
Protect pages or entire layouts by declaring `requires`. VitNode checks the visitor's authentication state before the route chunk downloads:
```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'
export const routes = definePluginRoutes([
page('/notes/new', {
component: lazy(() => import('./pages/new-note-page')),
// [!code ++:1]
requires: 'authenticated',
}),
])
```
| `requires` | Behavior when not satisfied | Typical use cases |
| :---------------- | :------------------------------------------------------------------------- | :---------------------------------------- |
| `'authenticated'` | Redirects guests to `/login` with `returnTo` set to the target path | Dashboards, note editors, user settings |
| `'guest'` | Redirects authenticated users away (to `/` or their post-auth destination) | Sign-in, account creation, password reset |
| `'admin-guest'` | Redirects staff with active admin sessions into the AdminCP | AdminCP sign-in screen (`/admin`) |
<Callout type="info" title="AdminCP routes are pre-guarded">
Routes with `area: 'admin'` are automatically placed behind the AdminCP staff
session guard and cannot declare `requires`. To restrict access to specific
staff roles or permissions, gate content inside the route component or loader.
</Callout>
## Cache public pages [#cache-public-pages]
A page that looks the same for every visitor can declare `cache`, and VitNode reuses its server-rendered HTML for the given number of seconds:
```ts title="plugins/blog/src/routes.ts"
page('/blog/article/:slug', {
cache: { maxAge: 300, staleWhileRevalidate: 60 }, // [!code ++]
component: lazy(() => import('./pages/post-page')),
})
```
Routes are uncached by default, and a route with `requires` cannot be cached. [Cache server-rendered pages](/docs/dev/cache/pages) covers the setup and how the host app overrides a policy.
## Control preloading [#control-preloading]
Hovering a link runs the destination's loader early. Set `preload: false` on a page or layout whose loader is too costly to run on a hover:
```ts title="plugins/site-notes/src/routes.ts"
page('/notes/:slug/history', {
component: lazy(() => import('./pages/note-history-page')),
preload: false, // [!code ++]
})
```
Children of a `layout()` inherit its setting. [Preloading](/docs/dev/routing/preloading) explains what a preload runs and how to keep it to one request.
## Nested routes and layouts [#nested-routes-and-layouts]
A `layout()` wraps child routes in a shared UI frame without claiming a URL segment of its own. Use `index()` to render a page at the layout's root path.
Every path nested inside a layout is **relative** to its parent:
```ts title="plugins/site-notes/src/routes.ts"
import {
definePluginRoutes,
index,
layout,
lazy,
page,
} from '@vitnode/core/routing'
export const routes = definePluginRoutes([
layout('/notes', {
component: lazy(() => import('./pages/notes-layout')),
messages: ['@acme/site-notes.home'],
children: [
index({
component: lazy(() => import('./pages/notes-index-page')),
}),
page(':slug', {
component: lazy(() => import('./pages/note-page-slug')),
}),
],
}),
])
```
A layout component renders `{children}`:
```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { useTranslations } from 'use-intl'
const NotesLayout = ({ children }: { children: React.ReactNode }) => {
const t = useTranslations('@acme/site-notes.home')
return (
<div className="container mx-auto flex max-w-4xl flex-col gap-6 p-4">
<header className="border-b pb-4">
<h1 className="text-2xl font-bold tracking-tight text-balance">
{t('title')}
</h1>
</header>
<main>{children}</main>
</div>
)
}
export default NotesLayout
```
| Route helper | URL resolved | Purpose |
| :---------------------- | :------------- | :---------------------------------------------------- |
| `layout('/notes', ...)` | — | Wraps nested child routes with a persistent UI shell |
| `index(...)` | `/notes` | Renders at the exact URL of the parent layout |
| `page(':slug', ...)` | `/notes/:slug` | Relative leaf route rendered inside the parent layout |
## AdminCP routes [#admincp-routes]
Mount a screen in the staff-only Admin Control Panel by adding `area: 'admin'`. It automatically inherits the AdminCP shell, sidebar, and staff authentication guard:
```ts title="plugins/site-notes/src/routes.ts"
page('/admin/notes', {
// [!code ++:1]
area: 'admin',
component: lazy(() => import('./pages/admin-notes-page')),
messages: ['@acme/site-notes.admin'],
})
```
## Search parameters [#search-parameters]
Type and validate query strings (like pagination or filters). Declare `search` on the route for eager URL-level validation before code chunks load:
```ts title="plugins/site-notes/src/routes.ts"
page('/notes', {
component: lazy(() => import('./pages/notes-page')),
// [!code ++:3]
search: (input: Record<string, unknown>) => ({
page: Number(input.page) || 1,
}),
})
```
The component receives typed `search` values and a `navigate` helper:
```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
interface NotesSearch {
page: number
}
const NotesPage = ({
navigate,
search,
}: PluginRoutePageProps<undefined, NotesSearch>) => (
<div className="container mx-auto p-4">
<button
className="inline-flex items-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90"
onClick={() => void navigate({ search: { page: search.page + 1 } })}
type="button"
>
Next Page ({search.page})
</button>
</div>
)
export default NotesPage
```
<Cards>
<Card
icon={<DatabaseIcon />}
title="Data Fetching"
description="Learn universal fetchers, cache invalidation, and background mutations."
href="/docs/dev/fetcher"
/>
<Card
icon={<MilestoneIcon />}
title="Breadcrumbs"
description="Customize static and dynamic breadcrumbs across public and admin pages."
href="/docs/dev/routing/breadcrumbs"
/>
<Card
icon={<LoaderCircleIcon />}
title="Loading States"
description="Display debounced spinners and tailored skeleton fallbacks while pages stream."
href="/docs/dev/routing/loading"
/>
<Card
icon={<TriangleAlertIcon />}
title="Errors & Not Found"
description="Render localized 404 and 500 boundaries while keeping application layouts intact."
href="/docs/dev/routing/not-found"
/>
<Card
icon={<LanguagesIcon />}
title="Translations"
description="Stream localized message namespaces in parallel with route chunks using use-intl."
href="/docs/dev/i18n/pages"
/>
<Card
icon={<LayoutDashboardIcon />}
title="AdminCP Pages"
description="Mount plugin screens, navigation links, and permissions in the AdminCP."
href="/docs/dev/plugins/admin"
/>
</Cards>
# Loading States (/docs/dev/routing/loading)
VitNode gives every loading moment one indicator: a top progress bar for route navigation, a skeleton for a section that is still loading, and a spinner inside the button that started an action.
## Navigation progress bar [#navigation-progress-bar]
During a client-side navigation, a slim bar moves across the top of the viewport while the current page, header, and sidebar stay on screen and usable. `NavigationProgress` from `@vitnode/core/tanstack/pending` draws it, and `VitNodeRootProviders` already mounts it, so an app gets it without extra code.
The bar follows the router's own lifecycle:
- It appears only when a navigation lasts longer than 150 ms, so fast navigations never flash.
- It finishes when the router commits the destination, including an error page, a not-found page, or the target of a redirect.
- A newer navigation that replaces a pending one keeps the same bar moving instead of restarting it.
- Preloading on hover, `router.invalidate()`, and TanStack Query refetches never start it.
- With `prefers-reduced-motion`, it fades in and out at full width instead of moving.
To keep the current page visible, the router never swaps it for a pending component during a navigation:
```tsx title="apps/web/src/router.tsx"
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { RoutePendingSpinner } from '@vitnode/core/tanstack/pending'
export function getRouter() {
return createTanStackRouter({
routeTree,
defaultPendingComponent: RoutePendingSpinner,
// [!code ++]
defaultPendingMs: Infinity,
})
}
```
`defaultPendingComponent` still matters: it is the Suspense fallback of a route that has no `pendingComponent` of its own.
<Callout type="warn" title="Leave pendingMs alone">
Setting `pendingMs` on a route brings back the old behavior: the page you are leaving is replaced by a skeleton while the bar is also running. Use a section skeleton instead.
</Callout>
To show your own UI during a navigation, read the same state the bar uses with `useIsRouteNavigating()`.
## Component skeletons with Suspense [#component-skeletons-with-suspense]
For feature pages with multiple asynchronous queries, wrap content in React `<Suspense>` using VitNode's pre-built pending skeletons:
```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'
const NotesList = () => {
// Asynchronously fetched notes
return <div>Notes List</div>
}
const NotesPage = () => {
return (
<div className="container mx-auto max-w-3xl p-4">
{/* [!code ++:3] */}
<Suspense fallback={<FeedPendingSkeleton rows={4} />}>
<NotesList />
</Suspense>
</div>
)
}
export default NotesPage
```
{/* Image prompt: Skeletons of note cards with pulsing placeholders for title, text lines, and avatar in dark theme, 1440x900. */}
## Pre-built skeleton shapes [#pre-built-skeleton-shapes]
Import pre-built skeletons directly from `@vitnode/core/tanstack/pending`:
| Skeleton shape | Layout pattern | Typical use case |
| :--------------------- | :-------------------------------------------- | :-------------------------------------- |
| `FeedPendingSkeleton` | Card timeline with avatars and text rows | Activity feeds, note lists, blog posts |
| `TablePendingSkeleton` | Search toolbar, column headers, and rows | AdminCP data tables, member directories |
| `CardsPendingSkeleton` | Responsive 1/2/3 column card grid | Dashboard widgets, product catalogs |
| `FormPendingSkeleton` | Stacked input placeholders and action buttons | Settings forms, modal dialogs |
| `AuthPendingSkeleton` | Centered authentication card with form inputs | Sign-in, sign-up, password reset |
| `RoutePendingSpinner` | Centered accessible spinner | Suspense fallback with no known shape |
## Customizing skeleton props [#customizing-skeleton-props]
All skeleton shapes accept props from `RoutePendingSkeletonProps` to adapt to your layout:
```tsx title="plugins/site-notes/src/pages/notes-admin-page.tsx"
import { TablePendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'
const AdminNotesPage = () => {
return (
<Suspense
fallback={
// [!code ++:4]
<TablePendingSkeleton
className="p-6"
rows={8}
withDescription={false}
/>
}
>
<AdminNotesTable />
</Suspense>
)
}
export default AdminNotesPage
```
| Prop | Type | Default | Description |
| :---------------- | :-------- | :---------- | :------------------------------------------------------------ |
| `rows` | `number` | `3` to `6` | Number of skeleton items, rows, or cards to display |
| `withDescription` | `boolean` | `true` | Whether to display a skeleton subtitle under the heading |
| `className` | `string` | `undefined` | Additional Tailwind utility classes merged onto the container |
| `label` | `string` | `'Loading'` | Accessible screen-reader label (`aria-label`) |
## Keep data on screen during refetches [#keep-data-on-screen-during-refetches]
A background refetch should never blank content that is already loaded. Show a skeleton only for the first load, which is `isPending`, never `isFetching`. For a query keyed on a search term, a filter, or a page, keep the previous result while the next one loads and mark it as busy:
```tsx title="plugins/site-notes/src/views/notes-search.tsx"
import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import { cn } from 'cn'
const NotesSearch = ({ search }: { search: string }) => {
const query = useQuery({
...notesQueryOptions({ search }),
placeholderData: keepPreviousData,
})
if (query.isPending) return <FeedPendingSkeleton withDescription={false} />
return (
<ul
aria-busy={query.isFetching}
className={cn(query.isPlaceholderData && 'opacity-60')}
>
{query.data?.map(note => <li key={note.id}>{note.title}</li>)}
</ul>
)
}
```
## Show action progress on the button [#show-action-progress-on-the-button]
Submissions and mutations show their progress on the control that started them. Pass `isLoading` to `Button`: it disables the button, swaps the label for a spinner without changing the width, and sets `aria-busy`. `AutoForm` and `ConfirmAction` already do this for their submit buttons.
```tsx title="plugins/site-notes/src/views/delete-note-button.tsx"
import { Button } from '@vitnode/core/components/ui/button'
import { useMutation } from '@tanstack/react-query'
const DeleteNoteButton = ({ id }: { id: number }) => {
const mutation = useMutation({ mutationFn: deleteNote })
return (
<Button
isLoading={mutation.isPending}
onClick={() => mutation.mutate(id)}
variant="destructive"
>
Delete
</Button>
)
}
```
While the action runs, also disable any other control that would conflict with it, such as **Reject** next to a pending **Approve**.
<Cards>
<Card
icon={<DatabaseIcon />}
title="Data Fetching"
description="Learn universal fetchers, cache invalidation, and background mutations."
href="/docs/dev/fetcher"
/>
<Card
icon={<MapIcon />}
title="Plugin Routes"
description="Declare routes, lazy page components, metadata, and breadcrumbs."
href="/docs/dev/routing"
/>
<Card
icon={<TriangleAlertIcon />}
title="Errors & Not Found"
description="Handle 404, 500, and error boundaries in routes."
href="/docs/dev/routing/not-found"
/>
</Cards>
# Navigation (/docs/dev/routing/navigation)
Inside the app, use TanStack Router's `Link`. It builds the href, applies the
locale prefix, and preloads the destination once the pointer rests on it for
75 ms. You write the logical path; the router writes the language.
[Preloading](/docs/dev/routing/preloading) covers what a preload costs and how
to turn it off.
## 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 - or `/pl/odkrywaj`, once the app [translates the path](/docs/dev/i18n/localized-urls).
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 | With `routePaths` |
| --------------------------------------------- | ---------------- | ----------------- |
| The address bar | `/pl/discover` | `/pl/odkrywaj` |
| What the route tree matches (`rewrite.input`) | `/discover` | `/discover` |
| What you write | `to="/discover"` | `to="/discover"` |
| What React renders (`rewrite.output`) | `/pl/discover` | `/pl/odkrywaj` |
A translated path is spelled by the same rewrite, so route files, route IDs and
every `to` stay English. With `i18n.domains`, the domain already says the
language, so on `vitnode.pl` the same link renders `/odkrywaj`.
`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
```
## Link from a plugin page [#link-from-a-plugin-page]
A plugin page cannot use the router's typed `to`, because the host's route tree
does not know plugin URLs at compile time. Use `HrefLink` from
`@vitnode/core/tanstack/link` instead. It takes the same href string you would
put on an `<a>`, query and hash included, and renders a router link:
```tsx title="plugins/catalog/src/pages/catalog-list.tsx"
import { HrefLink } from '@vitnode/core/tanstack/link'
export const CatalogItemLink = ({ slug }: { slug: string }) => (
<HrefLink href={`/catalog/${encodeURIComponent(slug)}?tab=reviews`}>
Reviews
</HrefLink>
)
```
The link navigates without a full page load, [preloads](/docs/dev/routing/preloading)
after a 75 ms hover, and gets the visitor's locale prefix from the router.
Write the href without a locale prefix. An absolute URL such as
`https://example.com` renders a plain `<a>`. `aria-current="page"` is set only
when the href matches the current URL exactly, query and hash included.
To navigate from code after a form is saved, use `useHrefNavigate`:
```tsx title="plugins/catalog/src/pages/catalog-new-page.tsx"
import { useHrefNavigate } from '@vitnode/core/tanstack/link'
const navigate = useHrefNavigate()
// after a successful save:
await navigate(`/catalog/${encodeURIComponent(item.slug)}`)
```
Invalidate the queries the save changed before you navigate, so the next page's
loader reads fresh data. For filters, sorting and pagination on the page already
being viewed, use the page's own `navigate` prop shown above.
<Callout type="info" title="Keep plugins portable">
Plugin pages never import the host's route tree. `HrefLink` and `navigate`
work with any host, which saves future hosts from router spaghetti.
</Callout>
## Next [#next]
<Cards>
<Card
title="Routing"
description="How a URL gets claimed, by your app or by a plugin"
href="/docs/dev/routing"
/>
<Card
title="Translating a page"
description="Warm the right namespaces for the route you link to"
href="/docs/dev/i18n/pages"
/>
<Card
title="Breadcrumbs"
description="What the shell shows above your page"
href="/docs/dev/routing/breadcrumbs"
/>
</Cards>
# Errors & Not Found (/docs/dev/routing/not-found)
In TanStack Start, error handling and missing routes are configured through route boundaries rather than static files. VitNode provides built-in, localized error layouts (`NotFound`, `Error500Page`, and `ErrorActions`) mounted directly inside your application shell—keeping navigation, headers, and themes intact when errors occur.
## 404 Not Found [#404-not-found]
### Throwing 404 in loaders [#throwing-404-in-loaders]
When a requested resource (such as a note slug or user ID) is not found in the database, throw `notFound()` from `@tanstack/react-router` inside `load`:
```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { notFound } from '@tanstack/react-router'
import { definePluginRoute } from '@vitnode/core/routing'
export const route = definePluginRoute({
load: async ({ params }) => {
const note = await fetchNote(params.slug)
// [!code ++:3]
if (!note) {
throw notFound()
}
return note
},
})
```
When thrown, TanStack Router catches the signal and halts page execution, rendering the nearest `notFoundComponent`.
### Unmatched URLs keep the main shell [#unmatched-urls-keep-the-main-shell]
When a visitor navigates to a non-existent URL, the main shell (`_main.tsx`) is
still matched, so the route is caught **inside** it.
This ensures visitors never hit a blank, unstyled screen: they retain the main site header, navigation bar, and theme switcher, while search crawlers receive a real HTTP `404` status code:
```tsx title="apps/web/src/router.tsx"
const routeTree = withVitNodeRoutes(
fileRouteTree,
pluginRouteSpecs(pluginRouteSources),
{
mountUnder: {
admin: adminShellRoute,
blank: fileRouteTree,
main: mainShellRoute,
},
},
)
```
{/* Image prompt: VitNode 404 error page displayed inside the main site layout with header, 404 heading, localized description, and "Go back" / "Back to home" action buttons in dark theme, 1440x900. */}
## 500 Server & runtime errors [#500-server--runtime-errors]
When an unhandled exception or database failure occurs during SSR or client navigation, the router activates its `errorComponent`.
VitNode configures the global error boundary in `apps/web/src/router.tsx` using `Error500Page`:
```tsx title="apps/web/src/router.tsx"
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import {
Error500Page,
ErrorActions,
NotFound,
} from '@vitnode/core/tanstack/layout'
export function getRouter() {
return createTanStackRouter({
routeTree,
// [!code ++:2]
defaultNotFoundComponent: () => <NotFound actions={<ErrorActions />} />,
defaultErrorComponent: () => <Error500Page actions={<ErrorActions />} />,
})
}
```
`Error500Page` automatically renders localized strings from `core.global.errors.500`, keeping the error message friendly and clear while preserving layout structure.
{/* Image prompt: VitNode 500 internal server error page with large 500 status code, friendly error title, description, and recovery buttons in dark theme, 1440x900. */}
## Error action buttons [#error-action-buttons]
The `<ErrorActions />` component renders two primary recovery buttons:
1. **Go Back** (`router.history.back()`) — Takes the user to their previously viewed screen.
2. **Back to Home** (`/`) — Returns to the application homepage using locale-aware navigation.
You can also pass custom action elements into the `actions` prop of `NotFound` or `Error500Page`:
```tsx title="apps/web/src/routes/__root.tsx"
import { ErrorActions, NotFound } from '@vitnode/core/tanstack/layout'
export const Route = createRootRouteWithContext<RootRouterContext>()({
// [!code ++:1]
notFoundComponent: () => <NotFound actions={<ErrorActions />} />,
component: RootComponent,
})
```
## Standard error codes [#standard-error-codes]
VitNode provides `ErrorContent` to render standardized error presentations across public and administrative pages:
| Status code | Name | Common cause | Handled by |
| :---------- | :-------------------- | :------------------------------------------------------- | :---------------------- |
| `400` | Bad Request | Malformed request parameters or invalid form payloads | `ErrorContent` |
| `403` | Forbidden | Insufficient permissions or unauthorized staff action | Staff auth guards |
| `404` | Not Found | Route does not exist or loader threw `notFound()` | `NotFound` |
| `409` | Conflict | Resource already exists or version mismatch | API mutation handlers |
| `429` | Too Many Requests | Rate limits exceeded on public or API endpoints | Rate limiter middleware |
| `500` | Internal Server Error | Uncaught server exception or database connectivity issue | `Error500Page` |
<Callout type="info" title="Centralized error boundaries">
Keep root error fallbacks in your host application (`apps/web`). Individual
plugins should throw `notFound()` or errors from their loaders and let the
centralized, localized layouts handle presentation.
</Callout>
<Cards>
<Card
icon={<LoaderCircleIcon />}
title="Loading States"
description="Render instant skeletons and spinners during route transitions."
href="/docs/dev/routing/loading"
/>
<Card
icon={<MapIcon />}
title="Plugin Routes"
description="Declare URLs, lazy page components, metadata, and breadcrumbs."
href="/docs/dev/routing"
/>
<Card
icon={<DatabaseIcon />}
title="Data Fetching"
description="Server and client data loading with universal fetchers."
href="/docs/dev/fetcher"
/>
</Cards>
# Preloading (/docs/dev/routing/preloading)
VitNode starts loading a page when a visitor rests the pointer on a link to it, so the page is often ready by the time they click. This page explains what a preload costs, how to keep it to one API request, and how to turn it off for a route.
## What a preload does [#what-a-preload-does]
A preload runs the destination route the same way a navigation does, without showing it:
1. Downloads the route's JavaScript chunk.
2. Runs its guard, such as `requires: 'authenticated'`.
3. Runs its loader, including your module's `load` function.
Step 3 is what reaches your API. A forum list with 50 links can send many `GET` requests if a visitor sweeps across it, and each one counts against the [read budget](/docs/dev/advanced/rate-limiter#how-the-budgets-work) of the rate limiter.
## When a link preloads [#when-a-link-preloads]
The app's router sets the defaults in `src/router.tsx`:
```tsx title="apps/web/src/router.tsx"
const router = createTanStackRouter({
defaultPreload: 'intent',
defaultPreloadDelay: 75,
defaultPreloadStaleTime: 0,
// ...
})
```
| Visitor action | Result |
| ----------------------------------- | ---------------------------------------- |
| Hover or focus a link for 75 ms | The destination preloads once |
| Pass over a link in less than 75 ms | Nothing is loaded |
| Touch a link on a phone | The destination preloads at once |
| Click before 75 ms | The page loads normally, with no preload |
`defaultPreloadStaleTime: 0` hands freshness to TanStack Query instead of the router. The router reruns the loader for every preload and again on the click, and the loader answers from the query cache. That is why the next section matters.
## Make repeat preloads free [#make-repeat-preloads-free]
Read your API through `context.queryClient.query` in `load`, with a `staleTime`. The first preload fills the cache. Hovering again, or clicking after the hover, reads the same entry without a request, and two identical requests in flight at once share one fetch.
```tsx title="plugins/site-notes/src/pages/note-page.tsx"
import { queryOptions } from '@tanstack/react-query'
import { LOADER_DATA_QUERY_META } from '@vitnode/core/lib/query-client'
import { defineRoute } from '@vitnode/core/tanstack/plugin-routes'
import { fetchNote } from '../features/notes/fetch-note'
const noteQuery = (slug: string) =>
queryOptions({
queryKey: ['@acme/site-notes', 'note', { slug }],
queryFn: async () => await fetchNote(slug),
staleTime: 60_000, // [!code ++]
meta: LOADER_DATA_QUERY_META, // [!code ++]
})
export const route = defineRoute({
load: async ({ context, params }) =>
await context.queryClient.query(noteQuery(params.slug)), // [!code ++]
})
```
`LOADER_DATA_QUERY_META` is for a query whose data `load` returns, as here. The router already sends that data to the browser with the server-rendered HTML, so the meta keeps the query cache from sending it a second time. Leave it out when the page reads the query with `useSuspenseQuery` instead, as in [Cache app data](/docs/dev/cache/app).
A `load` that calls `fetcher` directly sends a new request on every hover and again on the click. Pick a `staleTime` per query: a minute is fine for a public article, a few seconds for a busy list, and data that changes after a write needs its key invalidated by that write. [Cache app data](/docs/dev/cache/app) covers keys, invalidation and per-user data.
## Turn off preloading for a route [#turn-off-preloading-for-a-route]
Set `preload: false` on a `page()`, `index()` or `layout()` when its loader is expensive or the visitor rarely opens it:
```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'
export const routes = definePluginRoutes([
page('/notes/:slug/history', {
component: lazy(() => import('./pages/note-history-page')),
preload: false, // [!code ++]
}),
])
```
A hover then skips the route's loader: its `load` and the loading of its `messages`. The click still runs everything.
| Value | Effect |
| -------- | ----------------------------------------------------------------------------- |
| left out | Uses the nearest parent `layout()` that sets it, otherwise the app's defaults |
| `false` | A preload skips this route's loader |
| `true` | Turns preloading back on under a `layout()` that set `false` |
<Callout type="info" title="The guard still runs">
`preload: false` skips only the loader. A preload still downloads the route's
chunk and still runs its `requires` guard, which reads the session from the
query cache. A real navigation always runs the guard and the loader, so
protected pages stay protected.
</Callout>
Any value other than `true` or `false` stops the build with an `invalid-preload` route error.
## Turn off preloading for one link [#turn-off-preloading-for-one-link]
To change a single link instead of a route, use the `Link` props from TanStack Router:
```tsx
import { Link } from '@tanstack/react-router'
const ExportLink = () => (
<Link preload={false} to="/settings/export">
Export data
</Link>
)
```
`preload={false}` stops this link from preloading. `preloadDelay={500}` waits longer for this link only. In a plugin page, [`HrefLink`](/docs/dev/routing/navigation#link-from-a-plugin-page) takes the same two props. A link cannot make a `preload: false` route run its loader early.
## When to turn it off [#when-to-turn-it-off]
- The loader is slow or expensive, such as a report, a search or an export.
- The page is rarely opened from the link, such as an edit or history page.
- The loader writes something or counts a view. A loader should only read, but a preload would count a visit nobody made.
Keep it on for ordinary reading pages. One cached preload makes the click feel instant and costs nothing on the second hover.
## Next [#next]
<Cards>
<Card
title="Cache app data"
description="Query keys, staleTime and invalidation after a write"
href="/docs/dev/cache/app"
/>
<Card
title="Rate Limiter"
description="How preloads use the read budget, not the write budget"
href="/docs/dev/advanced/rate-limiter"
/>
</Cards>
# Elasticsearch (/docs/dev/search-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" persist items={["bun", "pnpm", "npm"]} label="Install Elasticsearch support">
```bash tab="bun"
bun add @vitnode/elasticsearch@canary
```
```bash tab="pnpm"
pnpm add @vitnode/elasticsearch@canary
```
```bash tab="npm"
npm install @vitnode/elasticsearch@canary
```
</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 **Debug Panel → Search** in the AdminCP
(`/admin/core/debug/search`) and run **Rebuild index**. New changes are mirrored automatically; the rebuild fills
the historical records already in Postgres. Rebuilding (and clearing a
collection) needs the **Rebuild and clear the search index** permission
(`system:can_manage_search`) - viewing the section alone is not enough.
{/* Image prompt: VitNode AdminCP Debug Panel at /admin/core/debug/search showing the Search section with Elasticsearch as the engine, a “Rebuild index” button in the header, and collection counts. Dark theme, 1440x900. */}
</Step>
</Steps>
<Callout type="info" title="Upgrading an existing index">
Documents now carry `authorIds` (a list) instead of `authorId`, plus drafts as
private documents. If your index was created before that, delete it in
Elasticsearch and run **Rebuild index**. VitNode recreates it with the new
mapping.
</Callout>
<Callout type="info" title="Indexes created before uuid and bigint ids">
Documents now carry an `itemKey` keyword with the record id as text, so [uuid
and bigint](/docs/content-engine/id-strategy) records can be found. VitNode
adds the field to an existing index the first time it uses it. Older documents
get a value on the next **Rebuild index**; until then, results fall back to
the numeric `itemId`, which works for serial ids only.
</Callout>
<Callout type="info" title="Totals stop at 10,000">
Elasticsearch counts matches up to 10,000, the same depth you can page to.
Past that, `totalCount` reads 10,000 and means "at least this many" - nobody
scrolls that far anyway.
</Callout>
<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]
<Cards>
<Card
title="Search & Discovery"
description="Index plugin records and register rebuild indexers."
href="/docs/dev/search"
/>
<Card
title="Content Engine"
description="Make a content type searchable without hand-writing an indexer."
href="/docs/content-engine/public-pages"
/>
</Cards>
# External sources (/docs/dev/search-external)
The header search dialog reads the [site-wide search index](/docs/dev/search). Some content lives somewhere else: docs, a help center, a changelog. An external search source adds those results to the same dialog, in their own group below **Suggestions**, so people don't have to guess which search box to use.
VitNode's own site does this for its docs: type `hello` and you get community content first, then matching documentation pages.
<ImgDocs
src={searchDocsGroup}
alt="Header search dialog with the term hello: a Suggestions group with two Hello Content Engine articles and their dates, then a Documentation group listing docs pages such as Duplicate content and Create a Plugin, each with a book icon and its section path"
/>
## How sources behave [#how-sources-behave]
- A source runs only while someone types, from 2 characters, with the same short debounce as suggestions. The empty dialog still shows recent searches and popular content.
- Each source gets its own group, in the order you register them. A source with no matches stays hidden.
- Results are cached in the browser for 60 seconds and never retried. A failing source hides its group; the rest of the dialog keeps working.
- Only same-site paths (`/docs/...`) are shown, because rows open through the router. Hashes are fine, so a row can jump to a section.
- Results are not indexed, ranked against content or counted for [popularity](/docs/dev/search-suggestions#how-popularity-is-counted). The full `/search` page doesn't show them.
<Steps>
<Step>
### Write the source [#write-the-source]
A source is a plain object. `search` receives the term, the UI locale and an `AbortSignal`, and returns up to a handful of items. This one asks the Fumadocs search route and keeps one row per page:
```ts title="apps/web/src/docs/search-source.ts"
import type { SearchSource } from "@vitnode/core/tanstack/search";
import type { SortedResult } from "fumadocs-core/search";
import { BookOpenIcon } from "lucide-react";
export const docsSearchSource: SearchSource = {
icon: BookOpenIcon,
id: "docs",
labelKey: "site.search.docs",
namespace: "site.search",
search: async ({ signal, term }) => {
const response = await fetch(
`/docs/search?${new URLSearchParams({ query: term }).toString()}`,
{ signal },
);
if (!response.ok) {
throw new Error(`The docs search answered ${response.status}.`);
}
const results: SortedResult[] = await response.json();
return results
.filter(result => result.type === "page")
.slice(0, 5)
.map(page => ({
context: page.breadcrumbs?.slice(1).join(" / ") || null,
id: page.id,
title: page.content,
url: page.url,
}));
},
};
```
The real file also puts pages whose title matches first, links to the first matching section, and adds a plain-text excerpt for the highlighted row. It also gives each row its page's own icon in its category's color, so a UI page and a Development page look different at a glance.
An item's `icon` is a lucide icon name in kebab case (`mouse-pointer-click`), loaded on demand. `color` is any CSS color, such as `var(--ui-color)`; it tints the icon and its tile. Without an `icon`, the row uses the source's `icon` in neutral grey.
| Field | Type | Description |
| ----------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| `id` | `string` | Unique source id, used in cache keys and option ids |
| `icon` | `LucideIcon` | Shown in every row of the group |
| `labelKey` | `string` | Full translation key of the group heading |
| `namespace` | `string` | Translation namespace the dialog loads so `labelKey` resolves |
| `search` | `({ term, locale, signal }) => Promise<SearchSourceItem[]>` | Returns `{ id, title, url, context?, excerpt?, icon?, color? }` items |
</Step>
<Step>
### Translate the heading [#translate-the-heading]
Add the heading to your app's own messages, in every language you ship:
```json title="apps/web/src/locales/site/en.json"
{
"site": {
"search": {
"docs": "Documentation"
}
}
}
```
</Step>
<Step>
### Register the source [#register-the-source]
Call `configureSearchSources` once, at module scope in your router file, so it runs on the server and in the browser:
```tsx title="apps/web/src/router.tsx"
import { configureSearchSources } from "@vitnode/core/tanstack/search"; // [!code ++]
import { docsSearchSource } from "./docs/search-source"; // [!code ++]
configureSearchSources([docsSearchSource]); // [!code ++]
```
Calling it again replaces the list, so pass every source in one array.
</Step>
</Steps>
## Use the same search in your docs [#use-the-same-search-in-your-docs]
The easiest way is to not build a second search at all. VitNode's docs render the public header above the Fumadocs layout, so the same search box, menu and sign-in sit on every docs page. Pass `firstSearchSourceId` to show that source's group above **Suggestions**, and switch off Fumadocs' own search so <kbd>⌘</kbd> <kbd>K</kbd> opens one dialog, not two:
```tsx title="apps/web/src/docs/shell-content.tsx"
import { MainHeader } from "@vitnode/core/tanstack/layout";
import { DocsLayout } from "fumadocs-ui/layouts/spacious";
import { RootProvider } from "fumadocs-ui/provider/tanstack";
<RootProvider search={{ enabled: false }} theme={{ enabled: false }}>
<div className="[--fd-banner-height:--spacing(14)]">
<MainHeader firstSearchSourceId={docsSearchSource.id} variant="bar" />
<DocsLayout searchToggle={{ enabled: false }} themeSwitch={{ enabled: false }} tree={pageTree}>
{children}
</DocsLayout>
</div>
</RootProvider>;
```
`variant="bar"` turns the floating header card into a flat, full-width bar that sits flush on the docs layout, and `--fd-banner-height` tells Fumadocs how tall it is, so its sidebar and page fit underneath. Need a button before the logo, like a sidebar toggle? Pass it as `leading`. Load the header's data in the docs route too, with `loadMainShell(context)` in its `loader`.
Got a layout with its own search button? `SearchDialog` from `@vitnode/core/tanstack/search` is the header dialog without its trigger. Give it `open`, `onOpenChange` and the same `firstSourceId`.
## Check the result [#check-the-result]
Open any public page, press <kbd>⌘</kbd> <kbd>K</kbd> and type a word from a docs page title. A **Documentation** group appears below the suggestions. Do the same on a docs page and the group comes first. Arrow down into it and press <kbd>Enter</kbd>: you land on that docs page, scrolled to the matching section.
If the group never shows up, open the browser's network tab and check that the source's request answers `200` with results.
# Suggestions (/docs/dev/search-suggestions)
The search box in the public header opens a search bar that floats over the page. On larger screens it sits near the top. On phones it pins to the very top, so the keyboard doesn't swallow it.
Before you type, it shows what's popular. After two characters, it shows matching suggestions, each with its image or a type icon. Everything comes from the [site-wide search index](/docs/dev/search), so every indexed content type shows up here without extra code.
<ImgDocs
src={searchDialog}
alt="Search bar open over the page with an empty Search field and a Popular right now list: a forum topic with its forum name and excerpt, followed by articles and comments, each with a thumbnail or type icon and its date on the right, and keyboard hints at the bottom"
/>
## How the dialog works [#how-the-dialog-works]
Open it with the header search box, <kbd>⌘</kbd> <kbd>K</kbd> (<kbd>Ctrl</kbd> <kbd>K</kbd> on Windows and Linux), or <kbd>/</kbd> when you are not typing in a field.
| What you typed | What the dialog shows |
| ------------------- | ----------------------------------------------------------------------------- |
| Nothing or 1 letter | Your **recent searches** and **Popular right now**: up to 6 items this week |
| 2 or more letters | **Suggestions**: up to 6 items whose title words start with what you typed |
| 3 or more letters | A **See all results** row at the end that opens `/search` with the same term |
Move with <kbd>↑</kbd> <kbd>↓</kbd> and open with <kbd>Enter</kbd>; the bar at the bottom reminds you on larger screens. The highlighted row shows an excerpt, with your words marked. When a title starts with what you typed, the rest of it appears in grey. Press <kbd>Tab</kbd> (or <kbd>→</kbd> at the end of the field) to fill it in. Recent searches are remembered in your browser only, never on the server.
Suggestions match the start of every word in the title, so `hel wor` finds "Hello world". Words that only appear in the body are left to the full search page, which keeps suggestions fast on big sites. The best title match comes first; on a tie, the more popular item wins. Suggestions follow the same visibility rules as `/search`. Hidden content appears only for its authors and editors, and drafts never appear.
Suggestions and popular items always read the Postgres `core_search_index` table, so they also work when [Elasticsearch](/docs/dev/search-elasticsearch) answers `/search`.
Results that live outside the index, like your docs, can join the dialog as their own group. See [External sources](/docs/dev/search-external).
## How popularity is counted [#how-popularity-is-counted]
Each item gets one score, made of three signals:
| Signal | Counts when | Weight |
| ------- | ----------------------------------------------------------- | -----: |
| View | Someone opens the item's page | 1 |
| Click | Someone picks the item in the search dialog | 3 |
| Comment | A new public comment on the item is indexed for the first time | 5 |
Points fade with a 7-day half-life. A click from today is worth 3, and the same click from a week ago is worth 1.5. Last month's hit topic slowly makes room for this week's.
With [Redis](/docs/dev/cache) configured, VitNode ignores a repeat view or click from the same viewer within 30 minutes. It tells viewers apart by user id, or by a hash of the IP address for signed-out visitors. Without Redis every request counts, and one person mashing refresh can push their own post to the top. Set up Redis before you trust the ranking on a public site.
Scores live in `core_search_popularity`, one row per item. Deleting an item removes its row. Rebuilding the search index keeps every score and never counts comments again.
## Count views on your content page [#count-views-on-your-content-page]
Call `useRecordView` from `@vitnode/core/tanstack/search` in the page component that shows one item. Pass the item's content type id and record id:
```tsx title="plugins/forum/src/pages/topic-page.tsx"
import { useRecordView } from '@vitnode/core/tanstack/search' // [!code ++]
import { topicContentType } from '@/content/topic' // [!code ++]
const TopicPage = ({ loaderData }: PluginRoutePageProps<TopicPageData>) => {
const { topic } = loaderData
useRecordView({ itemId: topic.id, itemType: topicContentType.id }) // [!code ++]
// ...
}
```
The hook sends one request from the browser after the page renders. It runs in the browser on purpose. Public pages often come straight from the HTML cache, and the server never sees those visits. Pass `itemId: null` to skip counting, for example while the item is hidden. The blog's article page and the forum's topic page already call it.
Comments need no code. Take a Content Engine type that gets its search title from a relation to another searchable type, like a forum comment that points at its topic. The first time a public comment is indexed, its topic gets a comment signal. A document you index yourself works the same way when `containerType` is a searchable content type id and `containerId` is the parent's id.
## API routes [#api-routes]
All three routes are public and live under `/api/@vitnode/core/search`.
| Route | Query or body | Returns |
| ------------------ | --------------------------------------------------- | -------------------------- |
| `GET /suggest` | `search` (1-100 characters), `lang`, `first` (1-10, default 6) | `{ items: Suggestion[] }` |
| `GET /popular` | `lang`, `first` (1-10, default 6) | `{ items: Suggestion[] }` |
| `POST /popularity` | `{ itemType, itemId, signal: "view" \| "click" }` | `{ recorded: boolean }` |
A `Suggestion` is `{ id, itemType, itemId, title, url, context, createdAt, excerpt, image }`. `context` is the parent's title, such as the topic a comment belongs to, or `null`. `excerpt` is the first 500 characters of the indexed text. `image` is `{ url, width, height }` or `null`.
```bash
curl "http://localhost:3000/api/@vitnode/core/search/suggest?search=hel&lang=en"
```
```json
{
"items": [
{
"id": 105,
"itemType": "example.article",
"itemId": "3",
"title": "Hello Content Engine",
"url": "/articles/hello-content-engine",
"context": null,
"createdAt": "2026-10-10T10:55:34.335Z",
"excerpt": "Hello Content Engine A first article from the example plugin, served by the public API and rendered on its own page.",
"image": null
}
]
}
```
`POST /popularity` answers `{ "recorded": false }` when the item is not public in the index or the same viewer already counted it in the last 30 minutes. Comments can't be sent this way; only the index adds them.
# Search & Discovery (/docs/dev/search)
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}`,
authorIds: [article.authorId],
isPublic: article.status === 'published',
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, give your plugin a search indexer. It rebuilds one item type page by page: `load` returns the documents for up to `limit` source rows starting at `offset`, plus how many rows it read (`0` ends the rebuild). `count` is optional and powers the coverage report.
<Callout type="info" title="Content types index themselves">
A Content Engine type with `search` enabled gets its indexer automatically.
Write one only for data of your own.
</Callout>
```ts title="plugins/recipes/src/api/indexers/recipe.indexer.ts"
import type { SearchIndexer } from '@vitnode/core/api/models/search'
import { asc } from 'drizzle-orm'
import { recipes } from '@/database/recipes'
export const recipeSearchIndexer: SearchIndexer = {
itemType: 'recipe',
count: async (c) => await c.get('db').$count(recipes),
load: async (c, offset, limit) => {
const rows = await c
.get('db')
.select()
.from(recipes)
.orderBy(asc(recipes.id))
.limit(limit)
.offset(offset)
return {
documents: rows.map((recipe) => ({
itemType: 'recipe',
itemId: recipe.id,
title: recipe.title,
content: recipe.description,
url: `/recipes/${recipe.slug}`,
authorIds: [recipe.authorId],
createdAt: recipe.createdAt,
})),
itemsRead: rows.length,
}
},
}
```
Register it in `config.api.ts` (a module's `searchIndexers` works too):
```ts title="plugins/recipes/src/config.api.ts"
export const recipesApiPlugin = () =>
buildApiPlugin({
manifest,
searchIndexers: [recipeSearchIndexer], // [!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).
---
## Filter the search page [#filter-the-search-page]
`/search` has a filter sidebar next to the results (a **Filters** sheet on phones):
- **Content** - tick one or more types. Each row shows how many results it would have with the other filters applied.
- **Date created** - any time, the past 24 hours, week, month or year, or a **Custom range** picked on a calendar.
- **Authors** - add as many people as you like. A result matches when any of them wrote it, which counts co-authors too.
Results sit on a timeline grouped by month and day, so you can tell at a glance what happened yesterday and what is from last spring.
The same filters work in the public search API:
| Parameter | Example | What it does |
| ----------- | --------------------------- | ------------------------------------------ |
| `types` | `forum.topic,forum.comment` | Only these content types |
| `authorIds` | `1,7` | Written by any of these members (up to 20) |
| `from` | `2026-10-01T00:00:00.000Z` | Created at or after this moment |
| `to` | `2026-10-14T23:59:59.999Z` | Created at or before this moment |
```bash
curl "http://localhost:3000/api/@vitnode/core/search?authorIds=1,7&from=2026-10-01T00:00:00.000Z"
```
Two small routes feed the sidebar:
- `GET /api/@vitnode/core/search/authors?search=ax` finds members credited on public content. Without `search` it returns the most active ones.
- `GET /api/@vitnode/core/search/facets` takes the same filters as the search route (minus `types`) and returns `{ "types": { "forum.comment": 4, ... } }`.
A search engine plugin that can count implements `countByType` and sets `capabilities.facets` to `true`. One that can't returns `types: null`, and the sidebar quietly drops the numbers. Engines should also honour `authorIds`, or the author filter will be more of a suggestion.
Engines that can remove many documents at once can implement `deleteMany(c, itemType, itemIds)`. Deleting a container (say, a forum with all its topics) then costs one call instead of one per child. Skip it and VitNode politely calls `delete` for each item.
Browsing without a search term (a timeline, `/discover`, or the API without `search`) returns the first 1,000 characters of each hit's `content` - plenty for the snippet under the title. Search with a term and you get the whole text, so the snippet can jump to the match.
---
## Member timelines [#member-timelines]
Every member gets a timeline: everything credited to them, newest first. It lives on their profile (`/users/{nameCode}`) and on the **Timeline** tab of their AdminCP user page.
Who sees what depends on who's looking:
| Viewer | Published | Hidden | Drafts |
| ------------------------------------ | --------- | -------------------------------------------------- | --------------------- |
| Anyone, on `/search` and `/discover` | Yes | Only its authors and editors, with an eye-off icon | No |
| Anyone, on a member's profile | Yes | Only its authors and editors, with an eye-off icon | No |
| The member, on their own profile | Yes | Yes, with an eye-off icon | Yes, marked **Draft** |
| Staff, on the AdminCP user page | Yes | Yes, with an eye-off icon | Yes, marked **Draft** |
The **Hidden** column follows [Who can still see it](/docs/content-engine/content-visibility#who-can-still-see-it). An editor is staff with `can_edit` on the content type.
A draft has no public page yet, so its title isn't a link. Nobody gets sent to a 404.
Content Engine types opt in with `search.authorField`, which names the `field.user()` that holds the authors. With a multi-author field, every co-author gets the record on their timeline:
```ts title="plugins/blog/src/content/post.ts"
export const blogPostContentType = defineContentType({
fields: {
authorId: field.user({ min: 1, multiple: true, ordered: true }),
// ...
},
search: {
titleField: 'title',
contentFields: ['title', 'content'],
pathTemplate: '/blog/article/{slug}',
authorField: 'authorId', // [!code ++]
},
})
```
Every author is shown on the result, in the field's order, on `/search`, `/discover` and timelines alike. It shows overlapping avatars, then the names, such as **admin, devloop_tester and aXen**. Past three authors the list shortens to **admin, devloop_tester and 2 others**. Each hit in the API carries `authorIds` and `authors` (id, name, `nameCode`, avatar) in that order, and `author` stays the first one for code that only needs a single name. After turning `authorField` on for content that already exists, rebuild the index so older records get their authors.
The timelines come from two routes:
- `GET /api/@vitnode/core/search/timeline/{userId}` is public. It includes drafts only when the signed-in viewer is that member.
- `GET /api/@vitnode/core/admin/users/{id}/timeline` needs the `users` → `can_view` staff permission and returns every state.
---
## Result URLs for Content Engine types [#result-urls-for-content-engine-types]
`search.pathTemplate` is the English route of a result's page, with one `{slug}` placeholder. To turn search on for a content type, see [Content Engine search](/docs/content-engine/search). Leave the language out: VitNode adds the prefix, the domain and any translated segments from your app's [localized URL](/docs/dev/i18n/localized-urls) settings.
| `pathTemplate` | English result | Polish result (`as-needed`) | Polish result (with `domains`) |
| :------------- | :------------------ | :-------------------------- | :-------------------------------------- |
| `/blog/article/{slug}` | `/blog/article/hello-world` | `/pl/blog/article/witaj-swiecie` | `https://vitnode.pl/blog/article/witaj-swiecie` |
With `'/blog/article/:slug': '/wpisy/:slug'` in `routePaths.pl`, the Polish result becomes `/pl/wpisy/witaj-swiecie`.
Once `domains` is configured, every result URL is absolute, so a click always opens the right domain.
The rules:
- It starts with `/` and holds exactly one `{slug}`. No other placeholder, empty segment, `..` or whitespace.
- A page route has to serve it (`{slug}` read as `:slug`). If a plugin exports its content types from `src/content.ts` and none does, `dev` and `build` stop with `content-url-without-page`. See [Content URLs need a page](/docs/dev/i18n/localized-urls#content-urls-need-a-page).
- `{locale}` is no longer needed. A legacy leading `/{locale}/` (like `/{locale}/blog/article/{slug}`) is still accepted and stripped.
- `{locale}` anywhere else fails with: `search.pathTemplate "..." places "{locale}" somewhere other than the start of the path. The language is no longer part of the template: i18n.localePrefix, i18n.domains and i18n.routePaths now place it. Remove "{locale}" (recommended), or keep it only as the first segment ("/{locale}/...").`
- A content type that isn't localized can't use `{locale}` at all.
<Callout type="warn" title="Rebuild after changing URLs">
Result URLs are stored when a record is indexed. After you change
`pathTemplate`, `routePaths`, `domains` or `localePrefix`, rebuild the index
below so older results stop pointing at the old addresses.
</Callout>
A document you index yourself with `c.get('search').index()` keeps its `url` exactly as you pass it, so pass the public URL for that document's language.
---
## Manage the search index in the Debug Panel [#manage-the-search-index-in-the-debug-panel]
{/* Image prompt: VitNode AdminCP Debug Panel at /admin/core/debug/search with the "Search" section open in the side menu. Header with a "Rebuild index" button, a row of stat cards (status, engine PostgreSQL, indexed items, last indexed), and a collections table with a search box, indexed counts and a "Reindex" button per row. Dark theme, 1440x900. */}
Open **Debug Panel → Search** in the AdminCP (`/admin/core/debug/search`), or type "Search index" into the ⌘K admin search:
- The stat cards show the index status, the engine, how many items are indexed and when the last one was indexed. Recent sync errors appear below them.
- The collections table lists indexed counts per collection, with a search box to find one.
- **Reindex** rebuilds one collection, and **Rebuild index** in the header rebuilds all of them.
- **Remove documents** shows up instead of **Reindex** on a collection with no rebuild indexer. It clears that collection's documents, and live plugin writes may add them back.
Opening the section needs `system → can_view`. The rebuild, reindex and remove buttons need `system → can_manage_search`.
A rebuild is a queued job, so it only runs once [cron](/docs/dev/cron) is running. Until then it waits in the queue, patient but unproductive.
---
## Search Document Reference [#search-document-reference]
<TypeTable
type={{
itemType: {
description:
"Unique collection identifier (e.g. 'article', 'wiki_page').",
required: true,
type: 'string',
},
itemId: {
description:
'Primary key of the indexed record. A number for serial ids, a string for Content Engine types with a uuid or bigint idStrategy. Stored as text in core_search_index.',
required: true,
type: 'number | string',
},
title: {
description: 'Document title (indexed with highest search relevance).',
required: true,
type: 'string',
},
content: {
description: 'Body text (HTML is stripped to plain text automatically).',
required: true,
type: 'string',
},
url: {
description:
'Canonical destination URL for search result clicks. Leave it out for a private document that has no public page yet.',
type: 'string',
},
authorIds: {
description:
'User IDs credited with the record, lead author first. Powers member timelines.',
type: 'number[]',
},
isPublic: {
description:
'Whether the record shows up in public search. A private document is visible only on its authors’ own timelines and in the AdminCP.',
type: 'boolean',
default: 'true',
},
imageId: {
description:
'A `core_files` id shown as the result image. Results resolve it to `image: { url, width, height }`; a file that is not an image is skipped.',
type: 'number',
},
isHidden: {
description:
'A published record that was hidden. Set it together with `isPublic: false` and keep `url`. Its authors and editors still find it in search and on timelines, marked with an eye-off icon.',
type: 'boolean',
default: 'false',
},
}}
/>
## Learn More [#learn-more]
<Cards>
<Card
title="Table search"
description="Add search filtering to a single database table"
href="/docs/dev/database/search"
/>
<Card
title="Suggestions"
description="Header search dialog, popular content and popularity signals"
href="/docs/dev/search-suggestions"
/>
<Card
title="Elasticsearch"
description="Install, configure, and rebuild the external search adapter"
href="/docs/dev/search-elasticsearch"
/>
<Card
title="Content Engine search"
description="Automatic search indexing with Content Engine"
href="/docs/content-engine/search"
/>
</Cards>
# Server Functions & Isomorphic Fetching (/docs/dev/server-functions)
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 - naming the plugin, and letting the route infer:
```ts title="plugins/devices/src/lib/fetch-devices.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'
// [!code ++:10]
export const fetchDevices = async () => {
const response = await fetcher({
plugin: '@vitnode/core',
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.server.ts"
import { createServerFn } from '@tanstack/react-start'
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({
plugin: '@vitnode/core',
// [!code ++]
allowSaveCookies: true,
args: { body: data },
method: 'post',
module: 'users',
path: '/sign_in',
})
return { ok: response.ok }
})
```
The call is the same shape as the universal one - `plugin`, `module`, `path`,
`method`, `args` - and it is typed from the same registry. What the server
fetcher adds is exactly what a browser cannot do:
| Option | What it does |
| :------------------ | :----------------------------------------------------------- |
| `allowSaveCookies` | relays the API's `Set-Cookie` headers onto the host response |
| `additionalHeaders` | adds headers a browser may not forge, `Cookie` included |
| `origin` | calls a different API origin than the configured one |
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.
Keep code that imports `@vitnode/core/tanstack/fetcher/server` in a
`*.server.ts` file or inside a server function handler. The universal fetcher
rejects these three options at compile time, so a call that needs one cannot
end up in a shared module by accident.
## Learn More [#learn-more]
<Cards>
<Card
title="Fetcher"
description="The universal API client and server-only transport"
href="/docs/dev/fetcher"
/>
<Card
title="Plugin Routes"
description="Declare routes, lazy components, and loaders"
href="/docs/dev/routing"
/>
</Cards>
# Getting Started (/docs/dev/setup)
You need Node.js 22.18+ (or 24.11+, or 26+), 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" persist items={["bun", "pnpm", "npm"]} label="Create VitNode app">
```bash tab="bun"
bun create vitnode-app@canary
```
```bash tab="pnpm"
pnpm create vitnode-app@canary
```
```bash tab="npm"
npm create vitnode-app@canary
```
</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" persist items={["bun", "pnpm", "npm"]} label="Start local services">
```bash tab="bun"
bun run docker:dev
```
```bash tab="pnpm"
pnpm docker:dev
```
```bash tab="npm"
npm run docker:dev
```
</Tabs>
</Step>
<Step>
### Start VitNode [#start-vitnode]
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Start the development server">
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
</Tabs>
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>
# Connected Accounts (/docs/dev/sso/connected-accounts)
**Settings → Connected accounts** (`/settings/sso`) is where a signed-in member manages their SSO accounts. It shows up in the settings menu as soon as at least one [SSO adapter](/docs/dev/sso) is configured - no extra setup, no extra redirect URIs.
// Image prompt: A settings page titled "Connected accounts" with three grouped lists - "Sign-in accounts" (Google with an email and "Connected Mar 14", Discord, Facebook with a Connect button), "Profile" (Avatar, First name, Last name rows, each with its current value and a "From Google" / "Manual" dropdown) and "Sync" (Google · First name, an "On sign-in" switch and a "Sync now" button), light theme, blue accents.
The page uses the same grouped rows as the rest of Settings, in three groups:
- **Sign-in accounts** - every configured provider with the connected account and date. **Connect**, **Import avatar and name** (a one-time copy after a preview, labelled with what the provider shares) and **Disconnect** live here.
- **Profile** - shown once a connected account can supply something. One row per field it can supply: the value the member has now, and a dropdown choosing where it comes from (**Manual**, or a connected account that can supply it). Changes save immediately.
- **Sync** - shown once a field follows an account. One row per account with the fields it covers, an **On sign-in** switch and **Sync now**, which confirms it's the member at the provider and updates those fields right away. They stay signed in; no sign-out, no new session.
Only the avatar, first name and last name are ever imported. Email, username, display name, language, birthday, phone and headline are never touched. A provider's email is shown as connection info and nothing more.
## How connecting works [#how-connecting-works]
1. The member selects **Connect**. `POST /users/sso/connections/{providerId}/authorize` stores a short-lived, single-use **state** bound to that member, that provider and the `link` intent - only its SHA-256 hash is kept, in `core_users_sso_operations`.
2. The browser goes to the provider and comes back to the usual callback, `/login/sso/{providerId}`. That page recognises a settings state and calls the authenticated `POST /users/sso/connections/{providerId}/callback` instead of the public sign-in.
3. The state is spent the moment it is looked up - even a failed attempt burns it - and it must still be fresh (ten minutes), for the same provider, the same intent and the **currently signed-in member**. Anything else is a `400 invalid_state`.
4. The provider account is linked to the member. Accounts are never merged by email.
5. The member lands back on `/settings/sso` with a toast.
A provider account already linked to someone else answers `409 account_taken`. A member can have **one account per provider**; a second one answers `409 provider_already_connected`. Both rules are unique constraints on `core_users_sso`, so two racing requests can't sneak past them.
Connecting never creates a session - public or AdminCP - and never changes the profile.
<Callout type="info">
The public sign-in and the login-time "Connect *Provider* to your account"
password flow work exactly as before. See [How Accounts Link](/docs/dev/sso#how-accounts-link).
</Callout>
## Disconnecting [#disconnecting]
`DELETE /users/sso/connections/{providerId}` removes the connection and its sync settings (the profile sources cascade). Values already imported stay on the profile.
It refuses with `409 last_sign_in_method` when nothing else could sign the member in. What counts:
| Method | Counts when |
| ------------------ | ------------------------------------------------------------------ |
| Password | password sign-in is enabled **and** the member has a password |
| Passkeys | passkeys are enabled **and** the member has at least one |
| Other SSO accounts | the provider is still configured in `ssoAdapters` |
The check and the delete run in one transaction that locks the member's row - the same lock passkey removal takes - so two parallel requests can't remove the last two methods at once.
Disconnecting doesn't revoke anything at the provider. The page says so, and members remove the app in their provider account themselves.
## Import now [#import-now]
1. The member picks fields the adapter supports and selects **Continue**. The state now also carries the `import` intent and the chosen fields.
2. After the provider round trip, VitNode checks it's the **same provider account** that is connected (`409 account_mismatch` otherwise) and stores a ten-minute preview of just those fields.
3. `/settings/sso?import={providerId}` shows current values next to the new ones. The member confirms a subset, and `POST .../{providerId}/import` applies it. The preview works once.
A fresh round trip every time means no provider tokens are ever stored.
## Sync now [#sync-now]
Each field - `avatar`, `firstName`, `lastName` - has at most one source (`core_users_sso_profile_sources`, primary key `userId + field`). Different fields can use different providers. Picking a source in a field's dropdown moves the field to that account.
**Sync now** starts a round trip with the `sync` intent. The server - not the browser - decides which fields it covers: the ones sourced from that provider when the round trip starts (`400 nothing_to_sync` if there are none). On the way back it checks it's the same provider account (`409 account_mismatch`), re-reads the sources so a field made manual in the meantime is skipped, applies the values and answers with a per-field result. The member stays on `/settings/sso` with a toast, still signed in. No token is stored, and no session is created.
## Sync on sign-in [#sync-on-sign-in]
When the **On sign-in** switch is on, every sign-in through that provider refreshes the same fields automatically. It's optional - Sync now works without it. There's no polling and no background job.
The rules that keep this predictable:
- Connecting an account doesn't copy anything. Existing connections start as manual with sign-in updates off.
- A missing or empty value from the provider never erases a local one.
- Sync now and sign-in updates only ever touch fields sourced from that provider.
- Editing a field yourself - `PATCH /users/me`, an avatar upload or removal, or staff changing the avatar in the AdminCP - switches that field back to manual.
- Importing a field that syncs from a different provider switches it to manual too, and the response lists it in `manualFields`.
- Role limits still apply: personal information rules for names, avatar upload permission and size for the avatar. Importing names never turns on `showRealName`.
- Anything that goes wrong during a sign-in sync is swallowed - the member is still signed in.
## Avatars [#avatars]
Imported avatars go through the normal avatar pipeline (`setUserImage`), so storage, image processing, file ownership and cleanup of the previous avatar are the same as an upload. The download (`downloadRemoteImage`) only speaks HTTPS, resolves the host and refuses private, loopback, link-local and reserved addresses - again at connect time, and again after every redirect (three at most) - caps the size at the role's limit (5 MB hard cap), and trusts the bytes, not the `Content-Type`: only real JPEG, PNG or WebP files under 8192 × 8192 pass.
The URL and a SHA-256 of the last imported picture are kept on the connection, so the same avatar isn't downloaded again while it's still shown, or stored twice when a provider hands out a new URL for the same image. A failed download leaves the current avatar alone.
## API [#api]
All routes live under `users/sso/connections`, need a signed-in member, and use the public session only.
| Method | Path | Does |
| -------- | ------------------------- | ----------------------------------------- |
| `GET` | `/` | Providers, connections, sources, sign-in summary |
| `PUT` | `/preferences` | Field sources and sync toggles |
| `POST` | `/{providerId}/authorize` | Starts a `link`, `import` or `sync` round trip |
| `POST` | `/{providerId}/callback` | Finishes it (`sync` answers with `results`) |
| `GET` | `/{providerId}/import` | The pending import preview |
| `POST` | `/{providerId}/import` | Applies selected preview fields |
| `DELETE` | `/{providerId}/import` | Discards the preview |
| `DELETE` | `/{providerId}` | Disconnects |
```ts title="Calling it from your own UI"
import { fetcher } from "@vitnode/core/tanstack/fetcher"
const res = await fetcher({
plugin: "@vitnode/core",
method: "get",
module: "users/sso/connections",
path: "/",
})
```
Mutations take JSON bodies, which the browser can't send cross-site without a CORS preflight, on top of the API's CSRF middleware. Provider tokens never leave the server and never reach logs or events.
## Events [#events]
- [`user.sso.linked`](/docs/dev/events/built-in-events) - a provider was connected.
- [`user.sso.unlinked`](/docs/dev/events/built-in-events) - a provider was disconnected.
- [`user.sso.profile_synced`](/docs/dev/events/built-in-events) - profile fields changed because of a provider.
## Adapter support [#adapter-support]
Which fields a provider can supply comes from the adapter's `profileFields`. The page tells "this provider can't provide it" apart from "this provider didn't send it this time".
| Adapter | Avatar | First name | Last name |
| -------- | ------ | ---------- | --------- |
| Google | ✓ | ✓ | ✓ |
| Discord | ✓ | - | - |
| Facebook | ✓ | ✓ | ✓ |
Discord has no real-name fields, and VitNode never guesses a first and last name from a username or a full name. For your own provider, see [Custom SSO Adapter](/docs/dev/sso/custom-adapter#profile-data).
# Custom SSO Adapter (/docs/dev/sso/custom-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",
profileFields: ["avatar"],
// 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
if (!primaryEmail) throw new Error("GitHub account has no verified 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. It is a neutral, text-only button until you give the adapter an [icon and a brand color](/docs/dev/sso/icons).
---
## `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",
},
icon: {
description: "Brand mark for the login button: inline SVG markup or an image URL. See Provider Icons and Colors.",
required: false,
type: "string",
},
brandColor: {
description: "Hex color (#RGB or #RRGGBB) that fills the login button. The label turns white or near-black, whichever reads better. See Provider Icons and Colors.",
required: false,
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 the user profile: id, email, username, and optionally emailVerified, avatarUrl, firstName and lastName. VitNode keys accounts on the email, so set emailVerified: false (or throw) for an address the provider has not confirmed - VitNode then refuses the sign-in with a 400 instead of creating, linking or verifying an account with it. Set it to true when the provider confirms the address. The built-in adapters only ever return confirmed addresses.",
required: true,
type: "(token: TokenResponse) => Promise<SSOProviderUser>",
},
profileFields: {
description: "Which profile fields the provider can supply for Connected accounts: 'avatar', 'firstName', 'lastName'. Leave it out and nothing is ever imported from this adapter.",
required: false,
type: "readonly ('avatar' | 'firstName' | 'lastName')[]",
},
}}
/>
See [Provider Icons and Colors](/docs/dev/sso/icons) for the accepted `icon` and `brandColor` formats, and for registering a React component instead.
## Profile data [#profile-data]
[Connected accounts](/docs/dev/sso/connected-accounts) can import a member's avatar, first name and last name from your provider. Two steps:
1. Declare what the provider can supply in `profileFields`.
2. Return those values from `fetchUser` as `avatarUrl`, `firstName` and `lastName`.
```ts
fetchUser: async ({ access_token, token_type }) => {
// ...
return {
id: String(user.id),
email: primaryEmail,
username: user.login,
avatarUrl: user.avatar_url ?? null,
}
},
profileFields: ["avatar"],
```
All three are optional, so adapters written before this still work - they just have nothing to import. A few rules keep imports honest:
- Return `null` (or leave it out) when the provider has no value. VitNode never erases a member's value with an empty one.
- Only send separate first and last names the provider actually has. Don't split a full name - `"Mary Ann Smith"` has no safe answer.
- `avatarUrl` must be `https`. VitNode downloads and re-stores it itself, with SSRF protection and size and type checks, so you don't have to.
- Don't add scopes just for profile data. If a field needs extra permission, leave it out of `profileFields`.
## Built-in SSO Adapters [#built-in-sso-adapters]
<Cards>
<Card
title="Google SSO"
description="Configure Google OAuth credentials"
href="/docs/dev/sso/google"
/>
<Card
title="Discord SSO"
description="Configure Discord OAuth credentials"
href="/docs/dev/sso/discord"
/>
<Card
title="Facebook SSO"
description="Configure Facebook OAuth credentials"
href="/docs/dev/sso/facebook"
/>
</Cards>
# Discord (/docs/dev/sso/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 `VITNODE_WEB_URL`, so it has to match exactly -
no trailing slash, no locale prefix.
| Environment | Redirect URL |
| ------------------------------------- | ------------------------------------------- |
| Development (`VITNODE_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 leave them out of `clientEnv` - that list is what
publishes a value to 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:
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
</Tabs>
</Step>
<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 split in two columns - left a "Continue with" heading over a blurple "Discord" button with a "Last used" badge, right the email and password form, a vertical "or" divider between them, dark theme, 900x600. */}
</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`, `avatar` |
Both scopes are required: `identify` for the id and username, `email` for the
address the account is created with.
The `avatar` hash becomes
`https://cdn.discordapp.com/avatars/{id}/{avatar}.png?size=512`, which
[Connected accounts](/docs/dev/sso/connected-accounts) can import. A member
still on Discord's default avatar has none. Discord has no first or last name,
and VitNode doesn't guess one from `username` or `global_name`, so only the
avatar is offered.
## 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]
<Cards>
<Card
title="How SSO works"
description="The round trip, the state cookie and the security rules"
href="/docs/dev/sso"
/>
<Card
title="Google"
description="Add a second provider"
href="/docs/dev/sso/google"
/>
<Card
title="Custom adapter"
description="Any OAuth2 provider, in three functions"
href="/docs/dev/sso/custom-adapter"
/>
</Cards>
# Facebook (/docs/dev/sso/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**.
<ImgDocs
src={createAppDetails}
alt="Meta's Create an app wizard on the App details step, with App name set to VitNode Test and an App contact email filled in"
/>
</Step>
<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.
<ImgDocs
src={createAppUseCases}
alt="The Use cases step of Meta's app wizard with Authenticate and request data from users with Facebook Login selected"
/>
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 `VITNODE_WEB_URL`, so it has to match
character for character - no trailing slash, no locale prefix.
| Environment | Valid OAuth Redirect URI |
| ------------------------------------- | -------------------------------------------- |
| Development (`VITNODE_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.
<ImgDocs
src={appSettingsBasic}
alt="The Meta app dashboard sidebar for an app named VitNode Test, with a red arrow pointing at Basic under the expanded App settings section, and an Unpublished badge next to Publish above it"
/>
</Step>
<Step>
### Set the environment variables [#set-the-environment-variables]
Server-side variables, so leave them out of `clientEnv` - that list is what
publishes a value to 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:
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
</Tabs>
</Step>
<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 split in two columns - left a "Continue with" heading over a neutral "Google" button and a blue "Facebook" button side by side, right the email and password form, a vertical "or" divider between them, dark theme, 900x600. */}
</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/v26.0/dialog/oauth` |
| Token URL | `https://graph.facebook.com/v26.0/oauth/access_token` |
| Profile URL | `https://graph.facebook.com/v26.0/me` |
| Scopes | `public_profile,email` |
| Provider id | `facebook` |
| Fields read | `id`, `name`, `email`, `first_name`, `last_name`, `picture.width(512).height(512){url,is_silhouette}` |
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 `v26.0` in the adapter (`FACEBOOK_GRAPH_VERSION`), so a Meta version bump
never changes what this install sends.
`first_name`, `last_name` and `picture` are default public profile fields, so
[Connected accounts](/docs/dev/sso/connected-accounts) can import them without
asking for anything beyond `public_profile`. The default silhouette picture
counts as no avatar.
## 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]
<Cards>
<Card
title="How SSO works"
description="The round trip, the state cookie and the security rules"
href="/docs/dev/sso"
/>
<Card
title="Google"
description="Add a second provider"
href="/docs/dev/sso/google"
/>
<Card
title="Custom adapter"
description="Any OAuth2 provider, in three functions"
href="/docs/dev/sso/custom-adapter"
/>
</Cards>
# Google (/docs/dev/sso/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 `VITNODE_WEB_URL`, so it has to match
character for character - no trailing slash, no locale prefix.
| Environment | Authorized redirect URI |
| ------------------------------------- | ------------------------------------------ |
| Development (`VITNODE_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 leave them
out of `clientEnv`: that list is what publishes a value to 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:
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
</Tabs>
</Step>
<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`, `given_name`, `family_name`, `picture` |
The account name VitNode creates comes from Google's `name` field, stripped of
characters that cannot appear in a profile URL.
`given_name`, `family_name` and `picture` come with the `profile` scope Google
already asks for, so [Connected accounts](/docs/dev/sso/connected-accounts) can
import all three with no extra permission. Google never guarantees them - an
account without one simply has nothing to import for that field.
## 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>
<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]
<Cards>
<Card
title="How SSO works"
description="The round trip, the state cookie and the security rules"
href="/docs/dev/sso"
/>
<Card
title="Discord"
description="Add a second provider"
href="/docs/dev/sso/discord"
/>
<Card
title="Custom adapter"
description="Any OAuth2 provider, in three functions"
href="/docs/dev/sso/custom-adapter"
/>
</Cards>
# Provider Icons and Colors (/docs/dev/sso/icons)
Every SSO provider gets a button labelled with its name on `/login` and
`/register` ([where they go](/docs/dev/sso#on-the-login-page)). The built-in Google, Discord and Facebook adapters
already carry their brand marks and colors, so those buttons look right without
any configuration. A custom adapter starts out as a neutral button with
text only - a **GitHub** button with no octocat - and this page shows how to
give it a mark and a color.
<ImgDocs
alt="The VitNode login page with a Continue with heading over a blurple Discord button, a neutral Google button with the four-color G and a blue Facebook button, next to the email form"
src={loginSsoButtons}
/>
## From the adapter (SVG or image) [#from-the-adapter-svg-or-image]
Add an `icon` to whatever your adapter returns. It travels to the browser with
the rest of the provider list, so it has to be a string: inline SVG markup, or a
URL the browser can load as an image.
```ts title="apps/api/src/utils/sso/github.ts"
export const GitHubSSOApiPlugin = (): SSOApiPlugin => ({
id: 'github',
name: 'GitHub',
// [!code ++]
icon: '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12" /></svg>',
// ... getUrl, fetchToken, fetchUser
})
```
Use `fill="currentColor"` and leave the width and height off: the mark then
takes the button's text color in both light and dark mode - white on a
[brand-colored button](#brand-color) - and is sized to match the label. A
multicolor mark, such as Google's four-color G, keeps its own fills; give its
adapter no brand color so it sits on the neutral button it was designed for.
An image works the same way:
```ts
icon: 'https://cdn.example.com/brands/slack.svg' // remote file
icon: '/icons/slack.png' // something in your app's public folder
icon: 'data:image/png;base64,iVBORw0KGgo...' // inlined bytes
```
<Callout type="warn" title="What the login page will accept">
The markup is inserted into the page, so it is checked before it renders:
- inline markup must be a single `<svg>...</svg>` element - an XML prolog,
a `DOCTYPE` and comments around it are fine and get stripped,
- nothing executable - no `<script>`, no `onload`-style attributes, no
`javascript:` URLs, no `<foreignObject>`, and no `<style>` block (a `<style>`
inside inline SVG is not scoped, so it would restyle the whole page),
- image URLs must be `https:`, `http:`, a root-relative path (`/icons/x.png`),
or a `data:image/...` URI,
- at most 16 KB.
An icon that fails any of those is dropped. The button keeps its name and still
signs people in - you lose the mark, never the provider. In development the
console says which provider's icon was dropped, so a silent button is never a
mystery.
</Callout>
### Importing an .svg file [#importing-an-svg-file]
You do not have to paste the markup. Where the adapter is bundled by Vite -
`apps/web`, or any generated VitNode app - import the file itself:
```ts title="apps/web/src/vitnode.api.config.ts"
import githubIcon from './icons/github.svg?raw' // the file's markup
import slackIcon from './icons/slack.svg' // the file's URL
export const vitNodeApiConfig = buildApiConfig({
authorization: {
ssoAdapters: [
GitHubSSOApiPlugin({ icon: githubIcon }),
SlackSSOApiPlugin({ icon: slackIcon }),
],
},
// ...
})
```
Both work: `?raw` hands you the file's contents - prolog, `DOCTYPE`, generator
comment and all - and a plain import hands you a URL (`/assets/slack-a1b2c3.svg`
after a build, or an inlined `data:image/svg+xml,...` for a small file). Prefer
`?raw` when you want the mark to follow the button's text colour, since a file
loaded through `<img>` cannot see `currentColor`.
A standalone API app such as `apps/api` runs on Node with no bundler, so an
`import` of an `.svg` is not a module there. Read the file instead:
```ts title="apps/api/src/utils/sso/github.ts"
import { readFileSync } from 'node:fs'
const githubIcon = readFileSync(
new URL('./github.svg', import.meta.url),
'utf8',
)
```
Read it once at module scope, not inside `getUrl` - and remember `tsc` does not
copy `.svg` files into `dist`, so either copy it as part of your build or keep
the markup in a `.ts` constant, the way VitNode's own adapters do.
If you would rather have a component than a string, register it in the browser
instead - see [From the browser](#from-the-browser-react-component-or-jsx).
## Brand color [#brand-color]
Add a `brandColor` to fill the button with the provider's color, the way the
built-in Discord (`#5865F2`) and Facebook (`#0866FF`) adapters do:
```ts title="apps/api/src/utils/sso/github.ts"
export const GitHubSSOApiPlugin = (): SSOApiPlugin => ({
id: 'github',
name: 'GitHub',
icon: githubIcon,
// [!code ++]
brandColor: '#24292F',
// ... getUrl, fetchToken, fetchUser
})
```
The value has to be a hex color - `#RGB` or `#RRGGBB`. The button picks its
own text color: white when white text reaches a 4.5:1 contrast ratio on your
color, near-black otherwise, so a yellow brand still gets a readable label. A
`currentColor` icon follows that text color.
Leave `brandColor` out and the button stays neutral, with a border. That is the
right choice for providers whose guidelines ask for a neutral button, such as
Google and Microsoft. A value that is not a hex color is ignored the same way,
and in development the console names the provider.
## From the browser (React component or JSX) [#from-the-browser-react-component-or-jsx]
If you would rather ship an icon as a component - a `lucide-react` icon, a
component from your own design system, or plain JSX - register it by provider
id. A registered icon wins over whatever the adapter sent.
```tsx title="apps/web/src/router.tsx"
import { configureSSOIcons } from '@vitnode/core/tanstack/auth'
import { GitHubIcon } from './components/icons/github'
configureSSOIcons({
github: GitHubIcon, // a component: rendered with `className="size-4"`
slack: <img alt="" className="size-4" src="/icons/slack.png" />, // or JSX
})
```
Call it from a module your router entry imports, so it has run before the login
screen renders. `configureSSOIcons` merges, so you can call it more than once -
once per plugin, if that suits you.
This is also the escape hatch for a provider whose mark you cannot express as
one static SVG: an animated logo, a theme-aware pair of files, or an icon that
needs a wrapper element.
## Reference [#reference]
<TypeTable
type={{
'SSOApiPlugin.brandColor': {
description:
"Optional hex color (#RGB or #RRGGBB) that fills the provider's button. The label turns white or near-black, whichever reads better. Leave it out for a neutral button.",
required: false,
type: 'string',
},
'SSOApiPlugin.icon': {
description:
"Optional brand mark for the provider's button: inline SVG markup (an .svg file's contents included), an http(s) URL, a root-relative path, or a data:image URI.",
required: false,
type: 'string',
},
configureSSOIcons: {
description:
'Registers browser-side icons by provider id. A value is either a component taking `className` (a lucide icon counts), or a React element.',
required: false,
type: '(icons: Record<string, SSOIcon>) => void',
},
}}
/>
<Cards>
<Card
title="Custom SSO Adapter"
description="Build an adapter for any OAuth2 provider"
href="/docs/dev/sso/custom-adapter"
/>
<Card
title="Single Sign-On"
description="Register adapters and link accounts"
href="/docs/dev/sso"
/>
</Cards>
# Single Sign-On (SSO) (/docs/dev/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]
Register an SSO adapter in `apps/api/src/vitnode.api.config.ts`:
```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 **Google** button automatically renders on your login and registration forms,
four-color G included. The built-in adapters ship their own marks and colors -
Discord and Facebook buttons are filled with their brand color - and a custom
adapter can [add its own](/docs/dev/sso/icons).
## On the login page [#on-the-login-page]
The provider buttons sit in their own column next to the email form, under one
**Continue with** heading, so each button only needs the provider's name (screen
readers still hear "Continue with Google"). On small screens the columns stack:
providers first, then the form.
- `/login` packs the providers into a two-column grid, so six of them take three
rows instead of six. The passkey button goes right below.
- `/register` stacks them full width, because the sign-up form next to them is
taller anyway.
- The method someone signed in with last - a provider, a passkey or a password -
gets a **Last used** badge, and a last-used provider moves to the top of the
grid. It's remembered in that browser only after a successful sign-in, so a
visitor who gives up halfway through Discord's consent screen won't see it.
- Only one kind of method enabled? The card shrinks back to a single column.
---
## Supported Providers [#supported-providers]
<Cards>
<Card
title="Google"
description="Google Cloud Console setup with OpenID email verification"
href="/docs/dev/sso/google"
/>
<Card
title="Discord"
description="Discord Developer Portal with identify and email scopes"
href="/docs/dev/sso/discord"
/>
<Card
title="Facebook"
description="Meta Developers app with Facebook Login"
href="/docs/dev/sso/facebook"
/>
<Card
title="Custom OAuth2 Adapter"
description="Connect GitHub, Apple, or any OAuth2 provider"
href="/docs/dev/sso/custom-adapter"
/>
<Card
title="Provider Icons and Colors"
description="Put a brand mark and color on the login buttons"
href="/docs/dev/sso/icons"
/>
</Cards>
---
## 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. **Known Identity**: The provider account was linked before, so the user is signed straight into it.
2. **Existing Email Match**: An account already uses that address. The visitor is asked for that account's password; once it checks out, the provider identity is linked to the account and they are signed in. From then on that provider signs them straight in (case 1). A social login can never take over an account on its own - the password is what proves ownership.
3. **New Visitor**: A new user is created with their social display name and email. Avatar and real name stay empty until the member imports them from [Connected accounts](/docs/dev/sso/connected-accounts).
Signed-in members can also connect more providers, import their avatar and name, and disconnect accounts in **Settings → Connected accounts** - see [Connected Accounts](/docs/dev/sso/connected-accounts).
### SSO confirms the email [#sso-confirms-the-email]
A provider only hands VitNode an address it has verified itself (the built-in
adapters refuse anything else), so a social sign-in doubles as email
confirmation:
- a **new visitor** starts out with `emailVerified: true`, even when an email
adapter is configured and password sign-ups would have to confirm first;
- a **known identity** or a **freshly linked** account whose address is still
unconfirmed is marked confirmed - provided the address the provider returned
is the one on the account. An account whose email was changed since the link
was made is left alone.
### Linking an existing account [#linking-an-existing-account]
The callback answers `409` with a short-lived, signed **link offer** - the
account's email, whether it has a password, and a token good for ten minutes.
The login page turns that into a "Connect *Provider* to your account" form: the
email is shown read-only, the visitor types their password, and
`POST /users/sso/{providerId}/link` verifies both before it writes the
`core_users_sso` row and mints a session. The token carries the provider account
id, so nothing about *which* identity gets linked is taken from the browser.
An account created by another provider has no password to confirm with. When an
email adapter is configured the form offers **Set a password** (the ordinary
reset flow) and asks them to try the provider again afterwards; without one it
points back to the login page.
Every successful link emits [`user.sso.linked`](/docs/dev/events/built-in-events).
The address the provider returns is matched in its canonical form, so a Google account that reports `jan.kowalski@gmail.com` finds the member who registered as `jankowalski@gmail.com` instead of quietly becoming a second account. See [One Mailbox, One Account](/docs/dev/advanced/auth#one-mailbox-one-account).
## Learn More [#learn-more]
<Cards>
<Card
title="Users"
description="Session cookies and user model structure"
href="/docs/dev/working-with-users/users"
/>
<Card
title="Custom SSO Adapter"
description="Implement SSOApiPlugin for other providers"
href="/docs/dev/sso/custom-adapter"
/>
</Cards>
# Using connected accounts (/docs/dev/sso/using-connected-accounts)
Connected accounts let you sign in with an account you already have, like Google or Discord. They can also fill in your avatar and name so you don't have to - but only when you say so.
## Connect an account [#connect-an-account]
1. Open your avatar menu, go to **Settings**, then **Connected accounts**.
2. Find the provider under **Sign-in accounts** and select **Connect**.
3. Sign in at the provider and allow access.
4. You're back in settings with "Account connected". From now on you can use that button on the login page.
Your email here never changes, even if the provider account uses a different one. Each provider account can belong to one member only, and you can connect one account per provider.
## Import your avatar or name [#import-your-avatar-or-name]
1. Select **Import avatar and name** (or **Import avatar**, depending on what the provider shares) next to the account under **Sign-in accounts**.
2. Pick what to bring over - avatar, first name, last name - and select **Continue**.
3. Confirm it's you at the provider.
4. Review the values, untick anything you don't want, and select **Import selected**.
Nothing changes until that last step. If the provider didn't share something, your current value stays as it is. Importing your name doesn't switch on "Show my real name".
## Keep it up to date [#keep-it-up-to-date]
1. Under **Profile**, pick where each field comes from - for example "From Google" for your avatar. It saves right away.
2. Under **Sync**, select **Sync now** next to that account. You confirm it's you at the provider and land right back in settings with your profile updated. You stay signed in the whole time.
3. Want it automatic? Turn on **On sign-in** for that account.
Each field follows one account at a time, and different fields can follow different accounts.
Changed your mind and edited your name or avatar yourself? That field switches back to manual, so the next sync won't overwrite it.
## Disconnect an account [#disconnect-an-account]
Select **Disconnect** next to the account under **Sign-in accounts** and confirm. You can't sign in with that account anymore, and its sync settings are gone. Your avatar and name stay as they are.
The provider still lists this site as a connected app until you remove it in your provider account settings.
<Callout type="warn">
If that account is your only way in, you'll see "Keep a way to sign in".
Set a password with **Forgot password?** on the login page, add a passkey
under **Security**, or connect another account first.
</Callout>
# Custom adapter (/docs/dev/storage/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 `{year}/{month}/{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]
<Cards>
<Card
title="Storage overview"
description="upload(), keys, image optimization and deletes."
href="/docs/dev/storage"
/>
<Card
title="Local (disk) adapter"
description="The one adapter that uses the static descriptor."
href="/docs/dev/storage/local"
/>
<Card
title="AWS S3 / Cloudflare R2"
description="A production adapter worth copying."
href="/docs/dev/storage/s3-r2"
/>
</Cards>
# Storage (/docs/dev/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 "@/api/builders"
export const uploadCoverRoute = buildRoute({
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]
<Cards>
<Card
title="Local Disk"
description="Stores files in public/uploads for local development"
href="/docs/dev/storage/local"
/>
<Card
title="AWS S3 / Cloudflare R2"
description="Scalable object storage via @vitnode/s3"
href="/docs/dev/storage/s3-r2"
/>
<Card
title="Supabase Storage"
description="Native Supabase bucket storage"
href="/docs/dev/storage/supabase"
/>
<Card
title="Custom Storage Adapter"
description="Implement your own storage backend"
href="/docs/dev/storage/custom-adapter"
/>
</Cards>
---
## Image Optimization [#image-optimization]
Turn on `storage.image` and VitNode re-encodes JPEG, PNG, AVIF, TIFF and WebP uploads with [sharp](https://sharp.pixelplumbing.com/), converts them to WebP, and records their pixel dimensions:
```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
storage: {
adapter: LocalStorageAdapter(),
// [!code ++:5]
image: {
quality: 85, // 1-100, defaults to 85
webp: true, // set to false to keep the original format
maxPixels: 40_000_000, // width x height, defaults to 40 million
},
},
})
```
`maxPixels` is your guard against image bombs - a tiny PNG that claims to be 16383x16383 pixels and unpacks into gigabytes of memory. Anything over the limit is refused with a `400` before a single pixel is decoded. The default fits an 8K photo with room to spare, so most installs never need to touch it.
### What gets checked on every upload [#what-gets-checked-on-every-upload]
Whether or not `storage.image` is set, an upload declared as JPEG, PNG, WebP, GIF, AVIF or TIFF must actually _be_ that format. The type a client sends is just a claim (a browser guesses it from the file name), so VitNode reads the file's first bytes and refuses a mismatch - say, an HTML page named `cat.gif` - with a `400`. SVG and non-image files have no fixed signature and are not affected; limit them with `allowedMimeTypes`.
---
## 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]
<Cards>
<Card
title="Content Engine Fields"
description="Use field.file() in Content Engine models"
href="/docs/content-engine/fields"
/>
<Card
title="Self-Hosted Deployment"
description="Configure production storage mounts and S3 buckets"
href="/docs/dev/deployments/self-hosted"
/>
</Cards>
# Local (disk) (/docs/dev/storage/local)
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.
| Cloud | Self-hosted | Package |
| :------------- | :----------- | :--------------------------- |
| ⚠️ Not durable | ✅ Supported | Ships inside `@vitnode/core` |
## 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:
<Files>
<Folder name="public" defaultOpen>
<Folder name="uploads" defaultOpen>
<Folder name="2026" defaultOpen>
<Folder name="09" defaultOpen>
<Folder name="avatars" defaultOpen>
<File name="1b9d3f7c-0e4a-4c21-9a77-5d6f0b8e1c22.webp" />
</Folder>
</Folder>
</Folder>
</Folder>
</Folder>
</Files>
</Step>
<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' persist items={['Standalone API', 'TanStack Start app']}>
```ts tab="Standalone API" title="apps/api/src/index.ts"
import { serveStatic } from '@hono/node-server/serve-static'
import { storageStaticHeadersMiddleware } from '@vitnode/core/api/middlewares/storage-static.middleware'
import { mkdirSync } from 'node:fs'
// [!code ++:15]
const staticStorage = vitNodeApiConfig.storage?.adapter?.static
if (staticStorage) {
mkdirSync(staticStorage.root, { recursive: true })
app.get(
staticStorage.mountPath,
storageStaticHeadersMiddleware(),
serveStatic({
root: staticStorage.root,
rewriteRequestPath: (path) =>
path.startsWith(staticStorage.stripPrefix)
? path.slice(staticStorage.stripPrefix.length)
: path,
}),
)
}
VitNodeAPI({ app, vitNodeApiConfig })
```
```ts tab="TanStack Start app" title="src/server/vitnode-api.server.ts"
import { serveStatic } from '@hono/node-server/serve-static'
import { storageStaticHeadersMiddleware } from '@vitnode/core/api/middlewares/storage-static.middleware'
import { mkdirSync } from 'node:fs'
const createVitNodeApi = () => {
const app = new OpenAPIHono().basePath('/api')
// [!code ++:15]
const staticStorage = vitNodeApiConfig.storage?.adapter?.static
if (staticStorage) {
mkdirSync(staticStorage.root, { recursive: true })
app.get(
staticStorage.mountPath,
storageStaticHeadersMiddleware(),
serveStatic({
root: staticStorage.root,
rewriteRequestPath: (path) =>
path.startsWith(staticStorage.stripPrefix)
? path.slice(staticStorage.stripPrefix.length)
: path,
}),
)
}
VitNodeAPI({ app, vitNodeApiConfig })
return app
}
```
</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.
<Callout type="warn" title="Keep storageStaticHeadersMiddleware() in front of serveStatic">
Local uploads are served from your own origin - the one your session cookie
lives on. Without this middleware, an uploaded SVG or HTML file opened
directly in the browser runs its script **as your site**, signed in as
whoever clicked the link. The middleware adds `Content-Security-Policy:
sandbox` and `X-Content-Type-Options: nosniff`, so stored files can still be
shown in an `<img>` but never execute. It costs nothing - leave it in.
</Callout>
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' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun i @hono/node-server
```
```bash tab="pnpm"
pnpm i @hono/node-server
```
```bash tab="npm"
npm i @hono/node-server
```
</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 |
| :---------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VITNODE_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"
VITNODE_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/2026/09/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]
<TypeTable
type={{
publicPath: {
description:
'URL path prefix the files are served under. The `static` descriptor is derived from it.',
type: 'string',
default: '/api/uploads',
},
baseUrl: {
description:
'Origin used to build absolute URLs. Defaults to the configured API origin (`VITNODE_API_URL`).',
type: 'string',
},
}}
/>
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]
<Cards>
<Card
title="Storage overview"
description="upload(), keys, image optimization and deletes."
href="/docs/dev/storage"
/>
<Card
title="AWS S3 / Cloudflare R2"
description="The durable option, and still one adapter."
href="/docs/dev/storage/s3-r2"
/>
<Card
title="Self-hosted deployment"
description="Where the uploads directory lives in production."
href="/docs/dev/deployments/self-hosted"
/>
</Cards>
# AWS S3 / Cloudflare R2 (/docs/dev/storage/s3-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.
| Cloud | Self-hosted | Package |
| :----------- | :----------- | :--------------------------------------------------------- |
| ✅ Supported | ✅ Supported | [`@vitnode/s3`](https://www.npmjs.com/package/@vitnode/s3) |
## 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' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun i @vitnode/s3
```
```bash tab="pnpm"
pnpm i @vitnode/s3
```
```bash tab="npm"
npm i @vitnode/s3
```
</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' persist 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:
| Variable | Required | What it is for |
| :--------------------- | :------- | :------------------------------------------------------------------------------- |
| `S3_BUCKET` | Yes | Bucket name. Missing it fails the first upload with `Missing S3 configuration` |
| `S3_ACCESS_KEY_ID` | Yes | Access key ID |
| `S3_SECRET_ACCESS_KEY` | Yes | Secret access key |
| `S3_REGION` | AWS only | Bucket region, e.g. `us-east-1`. Defaults to `auto`, which is what R2 wants |
| `S3_ENDPOINT` | R2 only | The account's S3 API endpoint. Setting it also switches on path-style addressing |
| `S3_PUBLIC_URL` | No | Base URL public file URLs are built from - a CDN or custom domain |
```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 `{year}/{month}/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]
<TypeTable
type={{
bucket: { description: 'Bucket name.', type: 'string', required: true },
accessKeyId: {
description: 'Access key ID.',
type: 'string',
required: true,
},
secretAccessKey: {
description: 'Secret access key.',
type: 'string',
required: true,
},
region: {
description: 'Bucket region. Leave at `auto` for Cloudflare R2.',
type: 'string',
default: 'auto',
},
endpoint: {
description:
'Custom S3 endpoint. Required for Cloudflare R2 and any other S3-compatible provider.',
type: 'string',
},
publicUrl: {
description:
'Base URL public file URLs are built from, e.g. a CDN or custom domain.',
type: 'string',
},
forcePathStyle: {
description:
'Use path-style addressing (`endpoint/bucket/key`). Defaults to `true` whenever `endpoint` is set.',
type: 'boolean',
},
}}
/>
## 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]
<Cards>
<Card
title="Storage overview"
description="upload(), keys, image optimization and deletes."
href="/docs/dev/storage"
/>
<Card
title="Supabase Storage"
description="The other managed option, with a bucket per project."
href="/docs/dev/storage/supabase"
/>
<Card
title="Deploy to Vercel"
description="Where the env vars go on a serverless host."
href="/docs/dev/deployments/cloud/vercel"
/>
</Cards>
# Supabase Storage (/docs/dev/storage/supabase)
`@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.
| Cloud | Self-hosted | Package |
| :----------- | :----------- | :------------------------------------------------------------------------------------- |
| ✅ Supported | ✅ Supported | [`@vitnode/supabase-storage`](https://www.npmjs.com/package/@vitnode/supabase-storage) |
## 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' persist items={['bun', 'pnpm', 'npm']}>
```bash tab="bun"
bun i @vitnode/supabase-storage
```
```bash tab="pnpm"
pnpm i @vitnode/supabase-storage
```
```bash tab="npm"
npm i @vitnode/supabase-storage
```
</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:
| Variable | Required | What it is for |
| :------------------------ | :------- | :----------------------------------------------------------------------------------------- |
| `SUPABASE_URL` | Yes | Project URL, e.g. `https://abcdefgh.supabase.co`. The adapter appends `/storage/v1` itself |
| `SUPABASE_SECRET_KEY` | Yes | The `sb_secret_…` key. Server-side only |
| `SUPABASE_STORAGE_BUCKET` | Yes | Bucket name, exactly as you created it |
```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
`{year}/{month}/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]
<TypeTable
type={{
url: {
description:
'Your Supabase project URL. A trailing slash is trimmed and `/storage/v1` is appended.',
type: 'string',
required: true,
},
secretKey: {
description:
'Supabase secret key `sb_secret_…` (server-side only). Replaces the legacy service role key, and sent as both the `apikey` and `Authorization` header.',
type: 'string',
required: true,
},
bucket: {
description: 'Storage bucket name.',
type: 'string',
required: true,
},
}}
/>
## 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]
<Cards>
<Card
title="Storage overview"
description="upload(), keys, image optimization and deletes."
href="/docs/dev/storage"
/>
<Card
title="AWS S3 / Cloudflare R2"
description="The other managed option, and anything S3-compatible."
href="/docs/dev/storage/s3-r2"
/>
<Card
title="Custom adapter"
description="Implement StorageApiPlugin and store files anywhere."
href="/docs/dev/storage/custom-adapter"
/>
</Cards>
# Swagger (/docs/dev/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 '@/api/builders'
export const showOrderRoute = buildRoute({
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 '@/api/builders'
import { showOrderRoute } from './routes/show.route'
export const ordersModule = buildModule({
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 { manifest } from '@/manifest.gen'
export const shopApiPlugin = () =>
buildApiPlugin({
manifest,
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]
<Cards>
<Card
title="API routes"
description="Path params, query params, bodies and permissions"
href="/docs/dev/plugins/api/routes"
/>
<Card
title="API modules"
description="How routes are grouped, nested and mounted"
href="/docs/dev/plugins/api/modules"
/>
<Card
title="Fetcher"
description="Call these endpoints with full type inference"
href="/docs/dev/fetcher"
/>
<Card
title="Debugging"
description="When an endpoint answers, but not the way you expected"
href="/docs/dev/debugging"
/>
</Cards>
# Check for updates in the AdminCP (/docs/dev/updates/admin)
**AdminCP → System → Plugins** starts with a status card that sums up what needs your attention: security updates, failed checks or new versions. Below it, one list shows VitNode first and every plugin after it, each with its installed version and a status badge. Open a row to see the update details, the last check, and who made the package (author, website and license).
<ImgDocs
src={pluginUpdates}
alt="System → Plugins page: a status card says updates are available; the opened VitNode row shows Update to 2.0.0-canary.14 with a Canary tag and release notes link, then the author, website, license, channel, last good check and update source"
withoutBackground
/>
## Before you begin [#before-you-begin]
- A [cron adapter or external trigger](/docs/dev/cron) must be running. The daily check is a cron job; without a scheduler nothing is checked automatically.
- The API server needs outbound HTTPS (port 443) to the update manifests - for VitNode itself, `raw.githubusercontent.com`. Requests go out directly; HTTP proxy variables such as `HTTPS_PROXY` are not used.
- Run `vitnode db migrate` after upgrading. The check stores its results in three small tables: `core_update_sources`, `core_update_results` and `core_update_lock`.
## The daily check [#the-daily-check]
The cron job `@vitnode/core:cron:check_updates` runs at **03:17 every day in the API server's time zone** (the `TZ` environment variable - UTC on most hosts and containers). A newly registered job has never run, so the first scheduler tick after you deploy runs the first check. Until then the status card and every row say _Not checked yet_.
Each run fetches every distinct manifest once, even when several plugins share it, with a 10 second timeout, a 1 MB size limit and at most four sources at a time. Opening the catalog never contacts a publisher - it only reads stored results.
## Check now [#check-now]
Staff with **Plugins → Check for plugin and core updates now** (`plugins.can_check_updates`) see a **Check for updates** button. It runs the same check as the cron job and refreshes the page when it finishes.
- Only one check runs at a time across all API instances, and the daily check shares the same lease. A second click while one runs says _A check is already running_.
- A long check keeps its lease by renewing it every minute. If an API instance crashes mid-check, its lease runs out within five minutes and the next check takes over.
- If the server running a check can no longer confirm it holds the lease, the check stops and says _The check stopped before it finished_. Results stored before that are kept; press the button again a moment later.
- A manual check can run once every two minutes. A click inside that window says how many seconds to wait.
- The endpoint is `POST /api/@vitnode/core/admin/plugins/updates/check`. It answers `409` while a check runs (`"status": "running"`) or when the check was interrupted (`"status": "interrupted"`), and `429` during the cooldown.
Viewing the results only needs **Plugins → View installed plugins and their versions** (`plugins.can_view`). The same permission shows the [update count, security alert and System updates widget](/docs/dev/updates/alerts) everywhere else in the AdminCP. How the lease keeps checks exclusive is explained in [How update checks share one lease](/docs/dev/updates/lease).
## Read the results [#read-the-results]
Each row carries one badge. Open the row for the full story.
| Badge | What it means |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not checked yet | No check has covered this package yet. |
| Up to date | Every version you run is at or above the channel's newest release. |
| Update available | A newer release is on your channel. The row says _Update to 2.1.3_, with release notes when the publisher gave a link. |
| Check failed | The source could not be read. The last good result stays visible, with its date. |
| Security update | A version you run is inside a security update's affected range - see below. |
| No update source | The package declares no update source, so VitNode can't check it. |
| Status unknown | The publisher doesn't list this package or channel, or the installed version isn't valid SemVer. The row explains which. |
| Checks turned off | The install sets `updates: { enabled: false }`. |
Inside an opened row you may also see:
- **Requires a newer core** - the release declares a core range yours is outside. If an older release on the channel fits, it is named.
- **Compatibility unknown** - the publisher did not say which core the release needs. VitNode does not guess.
- **Not checked for this deployment yet** - you redeployed, changed channel or upgraded core since the last check. Results are recomputed from the stored manifest until the next check confirms them.
When the web app and the API run different versions of a plugin, the row shows a mismatch warning and both versions are checked. A vulnerable web app version is reported even if the API's version is fine.
Rows with a security update or a failed check open on their own, so the problem is the first thing you read.
## Unstable channels [#unstable-channels]
Any prerelease version gets an amber tag next to it named after its channel - **Canary**, **Alpha**, **Beta**, **RC** and so on. Hover it for a reminder: unstable builds can break between releases, so keep them off production. The tag also marks prerelease versions offered as updates.
## Security warnings [#security-warnings]
When a security update affects a version you run, the status card turns red and lists it, and the row gets a red **Security update** badge. Inside the row a red line with a shield icon names the security update, the affected version - with _(API)_ or _(web app)_ when they differ - and either _Fixed in 2.1.3_ or _No fixed version has been published yet_. **Details** opens the publisher's page.
Security updates are checked even when your channel has no newer release. A patch release on its own is never shown as a security fix; only a matching security update is.
## Choose a channel [#choose-a-channel]
By default each package follows the channel of the version you run: `2.1.0` is **stable**, `2.1.0-rc.1` is **rc** and `2.1.0-canary.4` is **canary**. VitNode never moves you between channels or suggests a downgrade. To follow another channel on purpose, set it in the API config:
```ts title="src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
updates: {
channel: 'stable',
},
// ...the rest of your API config
})
```
An install without outbound network access can switch checks off with `updates: { enabled: false }`. The status card then says so instead of showing results.
## Check the result [#check-the-result]
Open **System → Plugins** and press **Check for updates** in the status card. A toast reports how many updates and security updates were found, and the status card shows _Checked_ with the current time.
# Update alerts in the AdminCP (/docs/dev/updates/alerts)
You do not have to open **System → Plugins** to notice an update. VitNode shows the results of the [update checks](/docs/dev/updates/admin) in three more places across the AdminCP: a count in the navigation, a security alert in the header and a dashboard widget. All three read the results already stored by the last check. Opening them never contacts a publisher and never starts a check.
<ImgDocs
src={updateAlerts}
alt="AdminCP dashboard: a red 2 security updates pill sits next to search in the header and is open, listing VitNode and Forum under Security fixes and six packages under Other updates with an Open Plugins link, while the System item in the sidebar shows a count of 8"
withoutBackground
/>
The versions and the security update in the screenshot are illustrative demo data.
## Who sees the alerts [#who-sees-the-alerts]
Staff with **Plugins → View installed plugins and their versions** (`plugins.can_view`) see all three. Everyone else sees none of them, and their browser never asks for the data. Running a check still needs `plugins.can_check_updates` and stays a button on the Plugins page.
## The count next to System → Plugins [#the-count-next-to-system--plugins]
A number next to **System → Plugins** tells you how many packages have a newer release on their channel. Core counts as one package and every plugin counts once, even when its API and web app are registered separately. It is the same number of _Update available_ rows the Plugins page shows.
- The count only appears when it is above zero. While the data loads, or if it cannot be loaded, the menu looks exactly as before.
- Security updates do not add to the count. They have their own alert in the header.
- When the **System** group is folded, the count moves to the **System** item. In the collapsed icon sidebar a small dot marks the icon, and the count sits next to **Plugins** in the menu that opens.
## The security alert in the header [#the-security-alert-in-the-header]
When a security update affects something you run, a red pill appears in the AdminCP header, next to search, on every page:
> **2 security updates**
On a phone it shrinks to the shield and the number. Each component counts once, however many security updates match it. The pill has no close button on purpose: it disappears on its own once no evaluated finding applies to what you run - after you upgrade and redeploy, or after a check finds the publisher changed the affected range. It sits in the header, so it never pushes the page down.
Click it to see what is waiting, in two groups:
- **Security fixes** - every package a security update affects, with the version that fixes it.
- **Other updates** - packages with a newer release and no security finding.
Each group lists up to four packages and then says how many more there are. A row, or **Open Plugins** at the bottom, takes you to System → Plugins, where each affected row names the security update and its fix. The list itself is only fetched when you open the pill, so the header stays as light as before.
A publisher that cannot be reached never clears a warning. VitNode keeps the last known findings and adds _Based on the last known results_ under the list, so an outage at the publisher never looks like a fix.
## The System updates widget [#the-system-updates-widget]
The **System updates** widget is on the dashboard by default for staff who can view plugins. You can remove it or add it back from **Edit layout**, like any other widget. It reads like a small ledger, one row per fact:
| Row | Meaning |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| Status | The one-line verdict - see below. |
| VitNode | The core version you run and, after the arrow, the newer core release on your channel when one is known. |
| Plugin updates | Plugins with a newer release on their channel. Core is not included here. |
| Security | How many packages, core included, a security update affects - or _None_. |
| Last checked | How fresh the numbers are. |
Before anything was checked, the numbers show a dash and _Unknown_ instead of `0`.
### Status [#status]
| Status | What it means |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Security fix needed | At least one package you run is affected by a security update. |
| Updates available | A newer release exists for core or a plugin, and nothing is affected by a security update. |
| Up to date | Every installed package was checked and none has an update or a security warning. |
| 2 packages not confirmed | Nothing is outdated, but some packages could not be confirmed, for example they declare no update source. The Plugins page says why. |
| Checking... | A check is running. The widget, the count and the pill refresh every 15 seconds until it finishes. |
| Not checked yet | No check has run. The daily check runs overnight, or press **Check for updates** on the Plugins page. |
| No update sources | No installed package declares where its updates are published. |
| Checks turned off | The API config sets `updates.enabled` to `false`. |
### Last checked [#last-checked]
| Value | What it means |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 3 hours ago | The oldest stored result is that recent, so every package was checked at least that recently. |
| Failed 5 minutes ago | The latest check could not read a source. The numbers include the last known results for it. |
| Out of date | You redeployed, upgraded core or changed channel. Results are recomputed from the stored manifests until the next check. |
| Never | Nothing has been checked yet. |
The time is the **oldest** successful result, not the newest. One package checked a minute ago does not prove the others were.
## When update checks are turned off [#when-update-checks-are-turned-off]
With `updates: { enabled: false }` in the API config, nothing is checked. The navigation count and the security pill stay hidden, and the widget only says that checks are turned off. Nothing stored earlier is shown as current.
## How fresh the alerts are [#how-fresh-the-alerts-are]
The alerts share one request per browser tab. It is refreshed when it is older than a minute and you come back to the tab, after **Check for updates** finishes, and every 15 seconds while a check is running. There is no other polling.
## Check the result [#check-the-result]
Press **Check for updates** on **System → Plugins**. When it finishes, the count next to **Plugins**, the security pill and the widget update together without reloading the page.
# Update checks (/docs/dev/updates)
VitNode checks once a day whether a newer version of core or any installed plugin is published, and whether the version you run is affected by a published security update. The results appear in **AdminCP → System → Plugins**, as a count next to that menu item, as a security alert in the AdminCP header and in the **System updates** dashboard widget.
Each package says where its **update manifest** lives - a public JSON file on GitHub Raw or any other HTTPS host. VitNode reads those files from the server. It does not ask npm, and it does not install, download or change anything.
## Pick a guide [#pick-a-guide]
| You want to... | Read |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
| See updates and security warnings, run a check, choose a channel | [Check for updates in the AdminCP](/docs/dev/updates/admin) |
| Understand the update count, security alert and dashboard widget | [Update alerts in the AdminCP](/docs/dev/updates/alerts) |
| Learn how checks stay exclusive across API instances | [How update checks share one lease](/docs/dev/updates/lease) |
| Make your own plugin report updates | [Publish updates for your plugin](/docs/dev/updates/plugin-authors) |
| Look up every field of the JSON format | [Update manifest reference](/docs/dev/updates/manifest) |
| Warn installations about a vulnerability | [Publish a security update](/docs/dev/updates/security-updates) |
| Understand how VitNode's own release workflow updates the official feed | [Official release feed](/docs/dev/updates/official-releases) |
## What the checks can and cannot tell you [#what-the-checks-can-and-cannot-tell-you]
- **Informational only.** A check never installs an update or edits your dependencies. You upgrade the way you always do, then rebuild and redeploy.
- **Only what publishers declare.** A package without an update source shows a _No update source_ badge. Private and local plugins work exactly as before.
- **Not a vulnerability scanner.** A security warning means a publisher listed your installed version in a security update. No warning is not proof a version is secure, and dependencies of your plugins are not checked at all. Keep using `pnpm audit` or your usual scanner for those.
# How update checks share one lease (/docs/dev/updates/lease)
Every update check - the daily cron job and the **Check for updates** button - runs through one function, `runLockedUpdateCheck` in `@vitnode/core`. It takes a database lease first, so only one check runs at a time across all API instances. This page explains how that lease is kept, what happens when it is lost, and why an old owner can never write after a new one took over.
## The lease lifecycle [#the-lease-lifecycle]
The lease is the single row `check` in `core_update_lock`. A check always goes through these steps, in order:
1. **Acquire** the lease for 5 minutes. A manual check must also be past the two-minute cooldown, stamped in the same transaction.
2. **Start the heartbeat**, which renews the lease about once a minute.
3. **Run the check.**
4. **Stop the heartbeat** and wait for a renewal that is still on its way.
5. **Release** the lease, but only if it still belongs to this run.
The heartbeat never overlaps itself: the next renewal is scheduled only after the previous one answered. A renewal only succeeds for the current owner while its lease has not expired, so an owner that let its lease run out cannot bring it back.
All expiry decisions use the database clock (`clock_timestamp()` in UTC), never the API server's. Two instances with skewed clocks still agree on who holds the lease.
## Recovery after a crash [#recovery-after-a-crash]
An instance that dies mid-check stops renewing. Its lease runs out at most five minutes after its last renewal, and the next daily run or manual check takes it over. The crashed owner cannot release, renew or write after that, even if it comes back to life.
## Cancellation after the lease is lost [#cancellation-after-the-lease-is-lost]
The heartbeat aborts the check's `AbortSignal` with an `UpdateCheckLeaseLostError` when ownership cannot be confirmed:
- a renewal answers that the lease is gone,
- a renewal fails, for example because the database is unreachable,
- or no renewal confirmed the lease before it could have expired.
The signal reaches `fetchUpdateSource`. Requests in flight are aborted, queued sources never start, and nothing more is evaluated or stored. A cancelled request is not a publisher failure: the source keeps its last valid document and no error is recorded for it. Every started request is awaited before the check returns, and the heartbeat timers are cleared.
`runLockedUpdateCheck` then returns `{ status: "lease_lost" }`. The cron job logs a warning, and `POST /api/@vitnode/core/admin/plugins/updates/check` answers `409` with `"status": "interrupted"`.
## Fenced writes [#fenced-writes]
Renewing alone is not enough. A process paused by a long garbage collection or a slow network can wake up after its lease expired and another instance took over. Every write a check makes therefore goes through `withUpdateCheckLease`:
```ts title="packages/vitnode/src/api/lib/updates/check.ts"
await withUpdateCheckLease(db, lease.owner, async tx => {
// write the source document and the results computed from it
});
```
It opens a short transaction, takes `pg_advisory_xact_lock` on the lease name, locks the lease row with `SELECT ... FOR UPDATE`, and checks that the owner matches and the lease has not expired by the database clock. Only then does it run the writes, and it commits while still holding both locks. Otherwise it throws `UpdateCheckLeaseLostError` and writes nothing.
Acquire, renew and release take the same two locks. So a new owner cannot take the lease between an old owner's ownership check and its commit: the takeover waits for that transaction, and the old owner's next write sees the new owner and is refused. This covers the source documents and HTTP validators, the results, recorded failures and the clean-up of removed plugins.
The row lock also holds off an instance still running the previous release during a rolling deploy, since its lease statement locks the same row.
<Callout type="warn" title="Never hold the fence around a network request">
`withUpdateCheckLease` holds the lease lock until the callback returns. Fetch first, then write. A check writes one transaction per source - the source and its results commit together - and one more for the clean-up.
</Callout>
## The summary behind the AdminCP alerts [#the-summary-behind-the-admincp-alerts]
`GET /api/@vitnode/core/admin/plugins/updates/summary` feeds the [navigation count, security alert and dashboard widget](/docs/dev/updates/alerts). It needs `plugins.can_view` and reads stored results only - the same `loadUpdatesOverview` the catalog uses, condensed by `summarizeUpdates`. Core and each plugin count as one component. `oldestSuccessAt` is the oldest successful result among packages with an update source, and `null` while any of them has none. The web app reads it through one shared query, `useAdminUpdateSummary`.
# Update manifest reference (/docs/dev/updates/manifest)
An update manifest is one public JSON file per publisher. It can describe any number of packages. VitNode validates it completely before using any of it; an invalid or unsupported file is reported as a failed check, and the last valid copy keeps being used.
## Shape [#shape]
```json title="updates.json"
{
"schemaVersion": 1,
"packages": {
"@acme/site-notes": {
"channels": {
"stable": "2.1.3",
"canary": "2.2.0-canary.4"
},
"releases": {
"2.1.3": {
"publishedAt": "2026-10-15T12:00:00Z",
"requiresCore": ">=2.1.0 <3.0.0",
"url": "https://github.com/acme/site-notes/releases/tag/v2.1.3"
},
"2.2.0-canary.4": {}
},
"securityUpdates": [
{
"id": "NOTES-2026-001",
"affected": ">=2.0.0 <2.1.3",
"fixed": "2.1.3",
"url": "https://github.com/acme/site-notes/security/advisories/GHSA-xxxx-xxxx-xxxx"
}
]
}
}
}
```
The values above are illustrative, not a real release or vulnerability.
## Top level [#top-level]
| Name | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `schemaVersion` | `1` | Yes | Format version. Any other value fails with _uses a format this VitNode does not support_. |
| `packages` | object | Yes | Keyed by npm package name - the plugin's manifest ID. At most 500 packages. Unknown keys anywhere are rejected. |
## Package [#package]
| Name | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `channels` | object | No | `{}` | `stable`, `rc` and/or `canary`, each a version. Every one must have an entry in `releases`. `stable` cannot be a prerelease. A package does not have to publish every channel. |
| `releases` | object | No | `{}` | Keyed by exact SemVer version. At most 2000. |
| `securityUpdates` | array | No | `[]` | Independent of channels and releases. At most 500, with unique `id`s. |
## Release [#release]
| Name | Type | Required | Description |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------- |
| `publishedAt` | ISO 8601 date | No | Shown as _released ..._. Informational only. |
| `requiresCore` | SemVer range | No | The `@vitnode/core` versions this release supports. Missing means compatibility is unknown. |
| `url` | `https://` URL | No | Shown as **Release notes**. |
## Security update [#security-update]
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ------------------------------------------------------------ |
| `id` | string | Yes | Letters, digits, `.`, `_`, `:` or `-`, up to 100 characters. |
| `affected` | SemVer range | Yes | Installed versions inside this range get the red warning. |
| `fixed` | SemVer version | No | Leave it out when no fix exists yet. |
| `url` | `https://` URL | Yes | Shown as **Details**. |
Every security update is a security update - there are no severity levels. Explain the issue on the security update page; links are treated as untrusted, and only `https://` links become clickable.
## How versions are compared [#how-versions-are-compared]
- Comparisons use SemVer, not string order: `2.10.0` is newer than `2.9.0`, and `2.1.0-canary.4` is older than `2.1.0`.
- The selected channel is the installation's `updates.channel`, or else the channel of the installed version. An installed version newer than the channel's target is never offered a "downgrade".
- `requiresCore` is checked against the running core version. When the channel's newest release needs a newer core, VitNode names the newest release on the same channel that is newer than yours and explicitly declares support for your core, if one is listed.
- Security update ranges include prereleases: see [how ranges match prereleases](/docs/dev/updates/security-updates#how-affected-ranges-match-prereleases).
# Official release feed (/docs/dev/updates/official-releases)
VitNode core and the official plugins read the feed at `https://raw.githubusercontent.com/aXenDeveloper/vitnode/update-manifest/updates.json`. A GitHub Actions job writes it after every successful npm publish. Maintainers never edit it by hand.
## How a release updates the feed [#how-a-release-updates-the-feed]
The **Bump and Publish npm packages** workflow has a **Publish update manifest** job. It runs only in the `bump_and_publish` and `publish` modes, and only after the publish job succeeds - a `bump` run publishes nothing, so it advertises nothing.
1. It checks out the exact commit that was published.
2. From `PUBLISHED_PACKAGES` - the same list the publish steps use - it keeps the packages whose manifest points at this feed as `updates.url` - `src/plugin-info.ts` for a plugin, `src/manifest.ts` for core (today `@vitnode/core` and `@vitnode/blog`).
3. It reads each version from `package.json`. A plugin's `@vitnode/core` dependency becomes the release's `requiresCore`, resolving `workspace:*` the way pnpm does on publish.
4. It adds the releases and moves only the channel of this run: **canary**, **release-candidate** (`rc`) or **stable**. A channel never moves backwards.
5. It commits `updates.json` to the `update-manifest` branch. That branch exists only for the feed, so it outlives release branches.
## Where publishedAt comes from [#where-publishedat-comes-from]
`publishedAt` and the release `url` come from the GitHub Release tagged `v<version>` (`gh release view`). Nobody types a date. When the run skipped release notes (`skip_release_github_patch_notes`) or the release is still a draft, both fields are left out - the date is never invented, and the time of the workflow run is never used instead.
## Reruns and partial failures [#reruns-and-partial-failures]
- **Reruns are idempotent.** An existing release entry keeps its `publishedAt` and `url`; a rerun only fills in fields that were missing, for example after the GitHub Release was created later. A run that changes nothing pushes nothing.
- **Concurrent runs** share the `vitnode-update-manifest` concurrency group, and every push is fetched, merged and retried if another run got there first.
- **If npm publishing fails**, the job does not run. Fix the cause and re-run the workflow in `publish` mode.
- **If only the manifest job fails**, use **Re-run failed jobs**: it publishes the same commit again.
## Add a security update to the official feed [#add-a-security-update-to-the-official-feed]
Security updates are not part of releases. Edit `security/security-updates.json` in a pull request:
```json title="security/security-updates.json"
{
"schemaVersion": 1,
"securityUpdates": {
"@vitnode/blog": [
{
"id": "VITNODE-BLOG-2026-001",
"affected": ">=2.0.0 <2.1.3",
"fixed": "2.1.3",
"url": "https://github.com/aXenDeveloper/vitnode/security/advisories/GHSA-xxxx-xxxx-xxxx"
}
]
}
}
```
The **Publish security updates** workflow validates the file on the pull request. After it merges into `canary`, the workflow replaces the security updates in `updates.json` with exactly what the file lists; releases and channels stay untouched. The example above is illustrative - only real security updates belong in that file. Writing ranges is covered in [Publish a security update](/docs/dev/updates/security-updates).
## Check the result [#check-the-result]
After a release or a security update change, open the feed URL above. Within a few minutes of GitHub's cache, it shows the new version under `channels` and its entry under `releases`.
# Publish updates for your plugin (/docs/dev/updates/plugin-authors)
Add one field to your plugin's `src/plugin-info.ts` and publish a JSON file next to your code. Every installation of your plugin then shows your new releases and security updates in **AdminCP → System → Plugins**.
<Steps>
<Step>
### Declare the update source [#declare-the-update-source]
Add `updates.url` to the plugin's `src/plugin-info.ts`, next to its title and icon:
```ts title="plugins/site-notes/src/plugin-info.ts"
import type { PluginInfo } from "@vitnode/core/lib/plugin-manifest";
export const pluginInfo: PluginInfo = {
title: "Site Notes",
icon: "sticky-note",
updates: {
url: "https://raw.githubusercontent.com/acme/site-notes/main/updates.json",
},
};
```
The URL has to be `https://`, without a user name, password, query string or fragment. It ends up in browser-visible metadata, so it must never carry a token.
</Step>
<Step>
### Rebuild the plugin [#rebuild-the-plugin]
Run `vitnode build` (or keep `vitnode dev` running). `src/manifest.gen.ts` picks the URL up from `pluginInfo` as `updates`, next to the version, so both the API and the web app's plugin inventory know where to look.
</Step>
<Step>
### Publish the manifest [#publish-the-manifest]
Commit `updates.json` to the branch the URL points at. The smallest useful file names your package, a channel and that release:
```json title="updates.json"
{
"schemaVersion": 1,
"packages": {
"@acme/site-notes": {
"channels": { "stable": "1.2.0" },
"releases": {
"1.2.0": {
"publishedAt": "2026-10-01T12:00:00Z",
"requiresCore": ">=2.0.0 <3.0.0",
"url": "https://github.com/acme/site-notes/releases/tag/v1.2.0"
}
}
}
}
}
```
The package key must equal the `name` in `package.json`. `publishedAt`, `requiresCore` and `url` are optional; without `requiresCore` installations see _Compatibility unknown_. Every field is described in the [manifest reference](/docs/dev/updates/manifest).
</Step>
</Steps>
## Check the result [#check-the-result]
Install the plugin in an app, open **System → Plugins** and press **Check for updates**. With the plugin at `1.1.0` the row says _Update available: 1.2.0_; at `1.2.0` it says _Up to date_.
## Several packages, one manifest [#several-packages-one-manifest]
A publisher with several plugins can keep one file. Point every plugin at the same URL and list each package under `packages`. VitNode downloads a shared file once per check.
```json title="updates.json"
{
"schemaVersion": 1,
"packages": {
"@acme/site-notes": {
"channels": { "stable": "1.2.0" },
"releases": { "1.2.0": {} }
},
"@acme/polls": {
"channels": { "stable": "0.4.1", "canary": "0.5.0-canary.2" },
"releases": { "0.4.1": {}, "0.5.0-canary.2": {} }
}
}
}
```
## Hosting on GitHub Raw [#hosting-on-github-raw]
`https://raw.githubusercontent.com/<owner>/<repo>/<branch>/updates.json` works well: it is public, served over HTTPS and supports `ETag`, so an unchanged file costs a `304 Not Modified`. Raw files are cached for a few minutes, so a fresh release can take that long to appear. Keep the file on a branch that is never deleted. VitNode's own feed lives on a dedicated branch for that reason.
Any other HTTPS host works too, as long as it is publicly reachable on port 443. Redirects are followed up to three times, only to other public HTTPS addresses.
## Private and local plugins [#private-and-local-plugins]
Leave `updates` out of `src/plugin-info.ts`. The plugin works as before, and the plugins page shows a _No update source_ badge for it. Nothing is sent anywhere for a plugin without an update source.
# Publish a security update (/docs/dev/updates/security-updates)
A security update in your update manifest turns every affected installation's catalog row red within a day - or right away when an administrator presses **Check for updates**. VitNode compares each installed version, API and web app separately, with the security update's `affected` range.
## Add a security update [#add-a-security-update]
Add an entry to the package's `securityUpdates` array:
```json title="updates.json"
{
"id": "NOTES-2026-001",
"affected": ">=2.0.0 <2.1.3",
"fixed": "2.1.3",
"url": "https://github.com/acme/site-notes/security/advisories/GHSA-xxxx-xxxx-xxxx"
}
```
Write `id`, `affected` and `url` every time. There are no severity levels or summaries: a security update is a security update, and the details live on the page `url` points to. Add `fixed` once a release contains the fix; installations then read _Fixed in 2.1.3_. The example is illustrative, not a real vulnerability.
Security updates do not depend on channels or releases. An installation is warned even when its channel has no newer release, and even when you no longer publish that channel at all.
## Announce a vulnerability without a fix [#announce-a-vulnerability-without-a-fix]
Publish the security update without `fixed`. Affected installations see _No fixed version has been published yet_. Put mitigation steps on the security update page, such as disabling a feature. When the fix ships, add `fixed` - and widen or narrow `affected` if the release that fixes it changes the picture.
## How affected ranges match prereleases [#how-affected-ranges-match-prereleases]
Ranges are matched with prereleases included, by SemVer order:
| Installed | `affected: ">=2.0.0 <2.1.3"` | Why |
| ---------------- | ---------------------------- | --------------------------------------------------- |
| `2.1.0` | affected | Inside the range. |
| `2.1.0-canary.4` | affected | `2.1.0-canary.4` sorts between `2.0.0` and `2.1.3`. |
| `2.1.3-canary.1` | affected | A prerelease of `2.1.3` sorts before `2.1.3`. |
| `2.1.3` | not affected | The upper bound is exclusive. |
| `2.0.0-rc.1` | not affected | Prereleases of `2.0.0` sort before `2.0.0`. |
If the fix already landed in `2.1.3-canary.2`, say so in the range: `">=2.0.0 <2.1.3-canary.2"`. When in doubt, keep a prerelease inside the range - a false warning is cheaper than a missed one.
## What a warning does not mean [#what-a-warning-does-not-mean]
A warning means the publisher listed that version. No warning is not proof that a version is secure, and VitNode does not scan your plugins' own dependencies. A patch release without a security update is not shown as a security release.
For VitNode's own packages, security updates are maintained in `security/security-updates.json` in the VitNode repository; see [Official release feed](/docs/dev/updates/official-releases#add-an-security update-to-the-official-feed).
# WebSocket (/docs/dev/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. A single app serves it from the same deployment as the site and the API, Vercel included - see [Set up the endpoint](/docs/dev/websocket/setup).
## Quick start [#quick-start]
### 1. Send a Toast to a User [#1-send-a-toast-to-a-user]
Push a transient toast 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.
<Callout type="info" title="Need it to stick around? Use the Notifications Center">
`notificationsChannel` is for transient toasts: they reach open tabs only and
are gone on reload. For anything users should find later - with an inbox,
unread count, email and preferences - publish a persistent notification with
`c.get("notifications").publish()`. See
[Notifications](/docs/dev/notifications). The bell's unread count travels over
this same connection on `notificationsStateChannel`.
</Callout>
---
### 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 { createWebSocketChannel } from "@vitnode/core/ws/types"
export interface MessagePayload {
roomId: string
message: string
senderId: number
}
// [!code ++:5]
export const chatChannel = createWebSocketChannel<never, MessagePayload>({
pluginId: "@acme/chat",
module: "rooms",
id: "messages",
})
```
The first type parameter is what the client sends, the second what it receives.
The channel id becomes `{pluginId}_{module}_{id}`.
---
## Client-Side Consumption [#client-side-consumption]
Listen for incoming channel messages with `useVitNodeWebSocket`:
```tsx title="plugins/chat/src/views/chat-room.tsx"
import { useVitNodeWebSocket } from "@vitnode/core/ws/use-websocket"
import { chatChannel } from "../ws/chat.channel"
export const ChatRoom = ({ roomId }: { roomId: string }) => {
const [messages, setMessages] = React.useState<string[]>([])
// [!code ++:7]
useVitNodeWebSocket(chatChannel, {
onMessage: (payload) => {
if (payload.roomId === roomId) {
setMessages((prev) => [...prev, payload.message])
}
},
})
return (
<div>
{messages.map((msg, i) => (
<p key={i}>{msg}</p>
))}
</div>
)
}
```
---
## Rooms [#rooms]
A room is a named group of browser tabs, such as everyone looking at one chat thread or editing one record. Send a message to a room and only its members get it, on every API instance. A room is any string your feature picks, for example `chat:42`.
### Join and leave per tab [#join-and-leave-per-tab]
All tabs of a browser share one socket, so a socket joins a room on behalf of a tab. Let each tab send its own random `clientId` with every message, and join or leave with it:
```ts title="plugins/chat/src/api/modules/rooms/rooms.socket.ts"
import { buildWebSocket } from "@vitnode/core/api/lib/websocket"
import { wsRegistry } from "@vitnode/core/ws/registry"
interface RoomMessage {
clientId: string
roomId: string
type: "join" | "leave"
}
export const roomsSocket = buildWebSocket<RoomMessage>({
id: "presence",
onMessage: ({ data, ws }) => {
const room = `chat:${data.roomId}`
// [!code ++:5]
if (data.type === "join") {
wsRegistry.join(ws, room, data.clientId)
} else {
wsRegistry.leave(ws, room, data.clientId)
}
},
})
```
Register the socket on its module with `webSockets: [roomsSocket]`. The socket stays in the room until its last tab leaves, so a closed tab never cuts off the others. Check who may join (the session on `c`, a permission) before calling `join`: a room is only as private as that check.
`join` and `leave` return `true` when they changed something. `wsRegistry.membersOf(room)` lists the members on this instance and `wsRegistry.roomsOf(ws)` lists the rooms of one socket.
### Send to a room [#send-to-a-room]
```ts
// [!code ++:4]
c.get("realtime").toRoom(`chat:${roomId}`, chatChannel, {
roomId,
message: "Hello!",
senderId: user.id,
})
```
Each socket in the room receives the payload once, however many of its tabs joined. Put the room or record in the payload so every tab can ignore what is not its own.
### Join again after a reconnect [#join-again-after-a-reconnect]
A new connection starts with no rooms on the server. `useVitNodeWebSocket` returns a `connectionId` that changes every time the shared connection opens, in every tab, so join from an effect that depends on it. `roomsChannel` is `createWebSocketChannel<RoomMessage>({ pluginId: "@acme/chat", module: "rooms", id: "presence" })`, the channel of `roomsSocket` above:
```tsx title="plugins/chat/src/views/chat-room.tsx"
const [clientId] = React.useState(() => crypto.randomUUID())
const { connectionId, send } = useVitNodeWebSocket(roomsChannel)
// [!code ++:4]
React.useEffect(() => {
if (!connectionId) return
send({ clientId, roomId, type: "join" })
}, [clientId, connectionId, roomId, send])
```
[Reconnects and missed messages](/docs/dev/websocket/reconnects) covers reloading what the tab missed while it was away.
### Clean up when a socket closes [#clean-up-when-a-socket-closes]
A socket that closes leaves all of its rooms. Use `onConnectionClose` to update your own state, such as an "online now" list:
```ts title="plugins/chat/src/api/modules/rooms/presence.ts"
import { wsRegistry } from "@vitnode/core/ws/registry"
// [!code ++:5]
wsRegistry.onConnectionClose((ws, left) => {
for (const { memberId, room } of left) {
markOffline(room, memberId)
}
})
```
`left` holds every `{ memberId, room }` the socket was in. Register the listener once, at module load.
### Rooms on several instances [#rooms-on-several-instances]
With `REDIS_URL` set, `toRoom` also publishes the message over Redis, and every other instance delivers it to its own members. Room membership itself stays local to each instance.
When an instance keeps per-room state in memory, it can follow the other instances:
- `onRemoteRoomMessage((room, id, data) => ...)` sees room messages from other instances before they reach local sockets. A collaborative document uses it to apply the same edit to its own copy.
- `publishToInstances(topic, data)` and `onInstanceMessage(({ topic, data, origin }) => ...)` exchange data between instances that never reaches a socket, such as each instance's list of members. Republish it periodically and let entries from a silent instance expire, so a crashed instance leaves no ghosts.
Without Redis, all of this works on a single instance with no extra setup: `toRoom` delivers locally and instance messages go nowhere.
---
## 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**: A dropped connection retries after about a second, then backs off (with a little jitter) up to 30 seconds, so a restarted server is not stampeded by every open tab.
- **Offline aware**: When the browser goes offline, the socket closes and stops retrying. It reconnects the moment the network comes back, or when a tab becomes visible again after sleep, without waiting for the backoff.
- **Heartbeat, both ways**: The server pings every socket every 30 seconds and closes the ones that stopped answering, so vanished clients do not linger (the standalone API's `ws` server and Nitro's crossws both do). The browser sends its own ping every 25 seconds and reconnects when no reply arrives within 10 seconds, so a half-dead connection after a Wi-Fi drop never pretends to be online.
- **No replay**: Messages sent while a socket is down are not queued. A feature that must not miss updates reloads its state when the socket opens again - see [Reconnects and missed messages](/docs/dev/websocket/reconnects).
- **Closed on revoke**: A socket is tied to the session and device that opened it. Revoking sessions (signing out a device, changing or resetting a password, an admin revoke) closes those sockets on every instance through `closeUserConnections`, so a revoked device stops receiving the user's pushes.
- **Multiple Instances**: With `REDIS_URL` set, `sendToUser`, `broadcast` and `toRoom` are relayed to every API instance over Redis pub/sub. Without Redis they only reach clients connected to the same instance.
## Learn More [#learn-more]
<Cards>
<Card
title="Set up the endpoint"
description="Serve /api/ws from a single app, Vercel included, or a standalone API"
href="/docs/dev/websocket/setup"
/>
<Card
title="Reconnects and missed messages"
description="Restore rooms and reload state after the socket comes back"
href="/docs/dev/websocket/reconnects"
/>
<Card
title="Notifications"
description="Persistent inbox, unread count, email and digests"
href="/docs/dev/notifications"
/>
<Card
title="Events"
description="In-process domain events across plugins"
href="/docs/dev/events"
/>
<Card
title="Queue Tasks"
description="Background jobs and asynchronous processing"
href="/docs/dev/advanced/queue"
/>
</Cards>
# Reconnects and missed messages (/docs/dev/websocket/reconnects)
A VitNode socket will close: a Wi-Fi drop, a deploy, a laptop lid, or a serverless host reaching its function's time limit. The client reconnects on its own, but the new connection starts empty, and nothing sent in between is replayed. This page shows how a feature gets back to the right state.
## What a reconnect keeps and loses [#what-a-reconnect-keeps-and-loses]
| After a reconnect | State |
| ------------------------------- | --------------------------------------------------------------------------- |
| The connection itself | Reopened by the leader tab, with backoff and jitter (about 1 s, up to 30 s) |
| The user | Read again from the session cookie on the new handshake |
| Rooms | Gone. Each tab joins again. |
| Messages sent while disconnected | Gone. Pub/sub has no replay. |
| Durable data in the database | Untouched. Reload it. |
Treat every realtime message as a hint that something changed, and the database as the truth. A toast is transient and may be missed; an unread count is durable and is reloaded.
## Restore state when the connection opens [#restore-state-when-the-connection-opens]
`useVitNodeWebSocket` returns `connectionId`, which changes every time the shared connection opens and is `null` while it is down. All tabs share one socket, held by a leader tab, and every tab - leader or follower - gets the new `connectionId`. Depend on it to rejoin and reload:
```tsx title="plugins/chat/src/views/chat-room.tsx"
const { connectionId, send } = useVitNodeWebSocket(roomsChannel, {
onMessage: (message) => appendMessage(message),
})
React.useEffect(() => {
if (!connectionId) return
send({ clientId, roomId, type: "join" }) // the server forgot the room
void queryClient.invalidateQueries({ queryKey: ["chat", roomId] }) // reload what was missed
}, [clientId, connectionId, queryClient, roomId, send])
```
Messages sent before the socket is open are queued and sent once it opens, so the join is never lost. Do not resend writes from that effect: a mutation that went over HTTP already happened, and sending it again would do it twice.
VitNode's own features follow the same rule:
- **Notifications**: the server sends the user's unread count and revision as soon as a socket opens. Every tab compares it with what it has and refetches the inbox when it changed. While no socket is open, the bell polls every 60 seconds.
- **Live editing**: each tab joins its record's room on every new connection, then reloads the field locks and the shared draft, and reopens its rich text documents so the server sends the edits it missed. Without a socket the form polls over HTTP.
## Delivery across instances [#delivery-across-instances]
`c.get("realtime")` delivers to the sockets on the instance that called it, then publishes the message to Redis. Every other instance delivers it to its own matching sockets and ignores its own echo, so nobody gets a message twice. An instance accepts sockets only once it is subscribed.
| Setup | Who receives a message |
| ------------------------- | -------------------------------------------------------------- |
| No `REDIS_URL` | Sockets on the same instance only. Fine for one server. |
| `REDIS_URL`, one instance | Same as above, plus a ready check before sockets are accepted. |
| `REDIS_URL`, many | Matching sockets on every instance. |
On serverless hosts such as Vercel the HTTP request that sends a message and the socket that should receive it often run on different instances, even within one deployment, so set `REDIS_URL` there. A publish started during a request is kept alive with the request's `waitUntil`, so the instance is not frozen before Redis has it.
When the Redis subscription drops and comes back, the instance closes its sockets with code `1012`. The clients reconnect and run the restore above, which picks up whatever was published while the instance could not hear it. While Redis is down, new handshakes on that instance answer `503` and the client keeps retrying.
## Related [#related]
<Cards>
<Card
title="Set up the endpoint"
description="Serve /api/ws from a single app or a standalone API"
href="/docs/dev/websocket/setup"
/>
<Card
title="Redis"
description="Shared cache, rate limits and realtime pub/sub"
href="/docs/dev/advanced/redis"
/>
</Cards>
# Set up the WebSocket endpoint (/docs/dev/websocket/setup)
VitNode's WebSocket lives at `/api/ws`. A single app serves it from the same deployment as the site and the HTTP API, through Nitro. A standalone API serves it from its own Node server. Both run the same handshake, protocol and handlers, so plugins and `useVitNodeWebSocket` work the same either way.
New single apps from `create-vitnode-app` already include everything on this page. Follow it to add WebSockets to an older single app.
## Single app [#single-app]
The browser upgrades `/api/ws`. Nitro owns that route, so the upgrade never reaches the TanStack Start catch-all, while every other `/api/*` request still does. Nitro then sends the handshake through the embedded Hono API as an ordinary `GET /api/ws`, so the Origin check, the rate limiter and the session cookie apply before the socket opens.
<Steps>
<Step>
### Enable WebSockets in the Vite config [#enable-websockets-in-the-vite-config]
Tell VitNode this app serves its own socket:
```ts title="vite.config.ts"
plugins: [
vitnode({ appRoot: import.meta.dirname, webSocket: true }), // [!code highlight]
devtools(),
tailwindcss(),
tanstackStart(),
viteReact(),
],
```
That one flag turns on Nitro's WebSocket support, mounts VitNode's Nitro route at `/api/ws` and lets the browser open the socket. Without it the browser never connects in an app that embeds the API.
The route ships with `@vitnode/core`, so there is no file to copy. It runs in Nitro's bundle, loads your server bundle on the first upgrade a fresh instance gets, and hands every handshake to the API your server bundle registered with `configureInProcessApi`. If that bundle cannot load, the handshake gets `503` and the client retries.
<Callout type="warn">
Older single apps mounted their own `src/server/websocket.ts` through `nitro({ handlers })`. Delete that file and the `nitro()` call when you switch to `webSocket: true`, or two handlers fight over `/api/ws`.
</Callout>
</Step>
<Step>
### Mount the handshake on the embedded API [#mount-the-handshake-on-the-embedded-api]
Add the `/ws` route after `VitNodeAPI`, so the API's middleware runs first:
```ts title="src/server/vitnode-api.server.ts"
import { websocketOriginMiddleware } from "@vitnode/core/api/middlewares/websocket-origin.middleware" // [!code ++]
import { upgradeWebSocket } from "@vitnode/core/ws/crossws.server" // [!code ++]
import { handleVitNodeWebSocket } from "@vitnode/core/ws/handle" // [!code ++]
const createVitNodeApi = () => {
const app = new OpenAPIHono().basePath("/api")
VitNodeAPI({ app, vitNodeApiConfig })
// [!code ++:5]
app.get(
"/ws",
websocketOriginMiddleware(),
upgradeWebSocket(handleVitNodeWebSocket()),
)
return app
}
```
`upgradeWebSocket` from `@vitnode/core/ws/crossws.server` does not upgrade anything itself. It hands the connection's handlers back to the Nitro route, which opens the socket. A plain `GET /api/ws` gets `426 Upgrade Required`.
</Step>
</Steps>
## Standalone API [#standalone-api]
A separate API server runs on `@hono/node-server` and upgrades with its own helper and a `ws` server. Mount the route after `VitNodeAPI`, and pass the web app's origin when it is not `VITNODE_WEB_URL`:
```ts title="apps/api/src/index.ts"
import { serve, upgradeWebSocket } from "@hono/node-server"
import { websocketOriginMiddleware } from "@vitnode/core/api/middlewares/websocket-origin.middleware"
import { handleVitNodeWebSocket } from "@vitnode/core/ws/handle"
import { WebSocketServer } from "ws"
app.get(
"/ws",
websocketOriginMiddleware({ origin: [webOrigin] }),
upgradeWebSocket(handleVitNodeWebSocket()),
)
serve({
fetch: app.fetch,
port: Number(process.env.PORT ?? 8000),
websocket: { server: new WebSocketServer({ noServer: true }) },
})
```
A web app pointed at that API with `VITNODE_API_URL` connects to it on its own; it needs no `webSocket` option and no Nitro route.
## Who may connect [#who-may-connect]
Both setups apply the same rules before a socket opens:
- **Origin**: the configured web and API origins, any extra `origin` you pass, and the handshake's own origin (a page on the same host, such as a preview deployment). A handshake without an `Origin` header is not a browser and is allowed. Anything else gets `403`.
- **Session**: the session cookie decides the user. Guests connect too, as `null`; a handler that needs a user checks `c.get("user")` itself, and live editing checks the AdminCP session on every message.
- **Redis**: with `REDIS_URL` set, the instance answers `503` until it is subscribed to the realtime channel, so it never accepts a socket that other instances cannot reach. The client retries.
A rejected handshake registers nothing. Identity is fixed for the life of a socket: after sign-in or sign-out the client reconnects on its own, but a session revoked from another device keeps its open socket until that socket closes.
## Check the result [#check-the-result]
Run the app, open the site, and look at the browser's network panel: `/api/ws` shows `101 Switching Protocols`, followed by `vitnode_ping` and `vitnode_pong` frames every 25 seconds. **AdminCP → Core → System → Integrations** shows WebSocket as active.
## Related [#related]
<Cards>
<Card
title="Reconnects and missed messages"
description="Restore rooms and reload state after the socket comes back"
href="/docs/dev/websocket/reconnects"
/>
<Card
title="Vercel"
description="Function duration limits and what they mean for sockets"
href="/docs/dev/deployments/cloud/vercel"
/>
</Cards>
# Widget Variants (/docs/dev/widgets/block-variants)
Sooner or later somebody asks for "the same callout, but smaller". You have three options: a second widget type, a `size` field in the middle of the copy, or a **variant**.
Variants are the third one, and they exist because the first two both lie about what changed. The words did not change. The shape did.
```text
data what the widget says "Ships on Friday"
variant how this instance says it "grid" | "list" | "compact"
layout how widgets sit together an Area's job, not a widget's
```
Keep those three apart and every screen that touches a widget stays honest. Mix them and a widget definition slowly turns into a settings page.
{/* Image prompt: Three side-by-side cards showing the same three feature items rendered three ways - as a 3-column grid of cards, as a stacked list with one item per row, and as a dense two-line summary. Above them a single shared data panel with the words "Data (one copy)" connected by three arrows to the three renderings, each labelled grid, list and compact. Clean dark UI, blue accents, 1600x900. */}
## Declaring them [#declaring-them]
Two optional keys on `defineWidget`:
```tsx title="plugins/example/src/widgets/features.tsx"
export const featuresWidget = defineWidget({
component: Features,
defaultVariant: 'grid',
fields: featuresFields,
id: 'features',
name: 'Features',
variants: [
{ id: 'grid', label: 'Grid', description: 'Cards side by side.' },
{ id: 'list', label: 'List', description: 'One per row.' },
{ id: 'compact', label: 'Compact', description: 'A dense summary.' },
],
})
```
| Key | Rule |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variants` | A list of `{ id, label?, description? }`. Leave it off entirely if the widget has one look - `variants: []` is refused, because a picker of nothing is worse than no picker. |
| `defaultVariant` | Must name one of them. Setting it without `variants` is refused too. |
| `id` | Lowercase letters, digits and single hyphens, up to 32 characters. It is written into every instance that picks it, so it has to survive the round trip unchanged. |
| `label` | What the editor shows. Falls back to the id, so a one-word variant needs no label at all. |
Two variants sharing an id is refused: a stored instance names its variant by id alone, so the two could never be told apart.
## Reading it in the component [#reading-it-in-the-component]
The variant arrives as a prop, next to the data rather than inside it:
```tsx
const Features = ({ data, variant }: WidgetComponentProps<FeaturesData>) => (
<section className={variant === 'compact' ? 'gap-2' : 'gap-4'}>
<h2>{data.heading}</h2>
{/* same data, three arrangements */}
</section>
)
```
`variant` is `string | undefined`. Undefined means "nobody picked one", which is exactly when `defaultVariant` applies - so a component that wants a single answer can start with `const shape = variant ?? "grid"`.
## The stored shape [#the-stored-shape]
A variant is one more key on the instance, beside `data` and never in it:
```json
{
"id": "01JC4Z8N9WQKX7R2M5T6V3B8HD",
"type": "example:features",
"variant": "list",
"data": {
"heading": "One block, three shapes",
"primary": { "title": "Data" }
}
}
```
That placement is the whole feature. Because `variant` is a sibling of `data`:
- switching it never touches, re-validates or re-saves the content,
- the block's schema stays the schema of its **content**, so a search indexer reading `data` never trips over a styling token,
- and a block that drops a variant later does not need a data migration to get rid of it.
## How a variant resolves [#how-a-variant-resolves]
```ts
import { resolveWidgetVariant } from '@vitnode/core/widgets'
resolveWidgetVariant(featuresWidget, undefined) // { kind: "resolved", variant: "grid" }
resolveWidgetVariant(featuresWidget, 'list') // { kind: "resolved", variant: "list" }
resolveWidgetVariant(featuresWidget, 'carousel') // { kind: "unknown", variant: "carousel" }
```
| Stored | Declared | Result |
| :----------- | :----------------------- | :--------------------------------------------------------- |
| nothing | `defaultVariant: "grid"` | The component is given `"grid"`. |
| nothing | no default | The component is given `undefined` and decides for itself. |
| `"list"` | `"list"` is declared | The component is given `"list"`. |
| `"carousel"` | not declared | **Unknown.** The block is not rendered with a guess. |
An unknown variant is treated the way unreadable data is: the page shows a fallback rather than inventing a look, and the properties panel says which variant is stored and offers the ones the block does declare, so somebody can fix it in one click. Nothing is deleted on your behalf.
<Callout title="Why not just fall back to the default?">
Because "carousel" meant something to whoever chose it. Silently rendering a
grid would ship a page that looks fine to everybody except the person who
asked for a carousel, and nothing anywhere would say it had been overruled. A
visible fallback is a worse-looking page for an hour; a silent one is a wrong
page forever.
</Callout>
## In the editor [#in-the-editor]
Select a block that declares more than one variant and a **Variant** picker sits above its fields in the properties panel.
Picking one is a single action - it updates the page immediately, marks the zone unsaved, keeps the instance's id, and leaves `data` byte for byte as it was. It is not an edit of the block's content, and the fields do not reset while you try the options.
A block with one variant, or none, shows no picker at all. There is nothing to decide.
## Backward compatibility [#backward-compatibility]
Nothing was migrated when variants landed, and nothing needs to be.
- An instance stored **before** variants existed has no `variant` key. It resolves to the block's `defaultVariant`, or to `undefined` if the block declares none - which is exactly how it rendered yesterday.
- A block that **adds** `variants` later keeps rendering every instance already stored. They simply all take the default until somebody picks something else.
- A block that **removes** a variant does not break its zone: the instances holding it are flagged as unknown and fixable, not dropped.
`variant` is optional in the stored shape, in the API's validation and in the type. A zone full of `{ id, type, data }` is a perfectly valid zone.
## When a variant is the wrong answer [#when-a-variant-is-the-wrong-answer]
| You want | Use |
| :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| The same content in a different arrangement | A **variant**. |
| Different content, or a field the other look does not have | Two **block types**. A variant that needs its own fields is two blocks wearing one coat. |
| Blocks side by side in columns | An [**Area**](/docs/dev/widgets/layout-areas). Arranging _several_ blocks is never one block's job. |
| Something an editor should type | A **field**. If the answer is prose, a URL or a number, it is content. |
The smell test: if changing the option would make you want to re-word the copy, it is data. If the copy reads the same either way, it is a variant.
# The blocks() Field (/docs/dev/widgets/blocks-field)
## Adding a zone to a content type [#adding-a-zone-to-a-content-type]
```ts title="plugins/example/src/content/page.ts"
import { defineContentType, field } from '@vitnode/core/content'
export const pageContentType = defineContentType({
id: 'example.page',
tableName: 'example_pages',
fields: {
title: field.text({ required: true, minLength: 3, maxLength: 200 }),
slug: field.slug({ source: 'title' }),
// [!code ++:4]
content: field.blocks({
allowed: ['core:*', 'example:callout'],
max: 50,
}),
},
publication: true,
})
```
| Option | Default | What it does |
| :---------- | :------ | :-------------------------------------------- |
| `allowed` | `"*"` | Which blocks may be placed here. |
| `max` | `200` | Most block instances one record may hold. |
| `min` | none | Fewest block instances. |
| `localized` | `false` | Give every language its own blocks and order. |
`min` and `max` count **block instances**, wherever they sit. A block inside a
[layout area](/docs/dev/widgets/layout-areas) counts towards the limit; the area
holding it does not, so an empty area counts as nothing. Two blocks are two
blocks whether they sit side by side in an area or one under the other.
A `blocks()` field is never `required` and never `nullable` - the empty list is what "no blocks" is, so a create that says nothing about the zone gets `[]`. That empty list is still checked against `min`, so a zone that declares `min: 1` refuses a create that leaves it out.
## Restricting what may go in [#restricting-what-may-go-in]
`allowed` takes three shapes, and they mix freely:
```ts
field.blocks({ allowed: '*' }) // every registered block
field.blocks({ allowed: ['core:*', 'blog:*'] }) // two whole plugins
field.blocks({ allowed: ['core:hero', 'core:text'] }) // exactly these two
```
A namespace wildcard is the useful middle: installing another plugin does not silently widen what a page may contain, while adding a block to a plugin you already trust does.
The shape is a string union on purpose, so a later `{ categories: [...] }` or `{ excluding: [...] }` object can join the array without any existing definition changing.
## The stored shape [#the-stored-shape]
One JSONB column, `NOT NULL DEFAULT '[]'`:
```sql
"content" jsonb DEFAULT '[]' NOT NULL
```
holding an ordered list of instances:
```json
[
{
"id": "01JC4Z8N9WQKX7R2M5T6V3B8HD",
"type": "core:hero",
"data": { "title": "Build your community", "align": "start" }
},
{
"id": "01JC4Z8N9X3R7T2M5Q6K8V4B9F",
"type": "example:callout",
"data": { "title": "Heads up", "body": "...", "tone": "info" }
}
]
```
| Key | Rule |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Stable and unique **within the zone**. Never the array index - a reorder must not change what a block is. |
| `type` | The globally unique block id. |
| `data` | Validated against that block's own field schema. |
| `variant` | Optional. The look this instance picked, from the ones its block [declares](/docs/dev/widgets/block-variants). Absent means "the block's default". |
Array order **is** the rendered order. Nothing sorts it.
### Areas in the same list [#areas-in-the-same-list]
A zone holds **content nodes**, and a node is either a block instance or an [Area](/docs/dev/widgets/layout-areas) - a small layout container with its own id, a `layout` of four tokens, and `children` that are blocks:
```json
{
"id": "01JC4Z8N9X3R7T2M5Q6K8V4B9F",
"kind": "area",
"layout": { "columns": 2, "gap": "md" },
"children": [
{ "id": "01JC…", "type": "core:text", "data": { "heading": "Left" } }
]
}
```
An Area is told apart by `kind: "area"`, needs no entry in `allowed` - its children are checked against the same list the zone's own blocks are - and cannot contain another Area. A zone stored before Areas existed is a list of blocks, which is a list of nodes that never nests, so nothing was migrated.
### Why one column [#why-one-column]
A block instance is a document: an id, a type, and whatever that type declares. Splitting it across tables would buy a join per zone, a migration per new block, and an ordering Postgres would have to rebuild on every read. One `UPDATE` re-orders a whole page, and a revision snapshot of it is a value rather than a graph - which is what makes drafts, revisions and reusable blocks tractable later.
### Instance ids [#instance-ids]
`createBlockInstanceId()` produces a 26-character Crockford base32 identifier - 10 characters of millisecond timestamp, then 16 of randomness. It sorts by creation time, which is what lets a later merge of two edits order instances it has never seen.
```ts
import { createBlockInstance } from '@vitnode/core/widgets'
const hero = createBlockInstance('core:hero', { title: 'Build your community' })
// { id: "01JC4Z8N9W…", type: "core:hero", data: { title: "…" } }
```
Storage accepts any stable id of 1-64 URL-safe characters, so an imported document or a reusable block can keep the identity it arrived with.
## What the API checks on a write [#what-the-api-checks-on-a-write]
Every create and update runs the zone through the registry, once, before anything is stored - so a row that exists has already been validated. Nothing re-checks it on read, and [the renderer never repeats that schema parse](/docs/dev/widgets/rendering#validation) - it only compares the stored shape against the block's current fields, so a definition that moved on since the write cannot reach a component.
The whole request is refused if any instance fails:
| Refused | Message |
| :------------------------------- | :------------------------------------------------------------------------------------ |
| A block the field does not allow | `Block "core:cta" is not allowed in this field.` |
| A block no plugin registers | `Block "shop:cart" is not registered. Install or enable the plugin that provides it.` |
| Data the block's fields reject | `Block "core:hero" data is invalid - title: Too big…` |
| Two instances sharing an id | `Block instance id "01…" appears more than once.` |
Errors are keyed by the instance's index, so a client can point at the block that is wrong.
## Localization [#localization]
```ts
content: field.blocks({ localized: true })
```
The column moves to the generated translation table, exactly as a localized `text` field does, and keeps the translation lifecycle, revisions and preview it already had - no new concepts.
What this localizes is the **whole block document**, not the text inside each block. Each language owns its own list: which blocks are in it, what is in them, and what order they come in. The two need not correspond at all.
```text
en: core:hero → core:text → core:cta
pl: core:hero → core:cta → blog:gallery
```
That is deliberate. A translated landing page is rarely the same page with different words - a market may need a different call to action, or no gallery - and treating a zone as one translatable document is what makes that expressible. It is also the only model that reuses VitNode's existing localization: a per-field locale map inside JSON would be a second localization system that the translation table, the revision history and the public locale resolution all know nothing about.
The cost is the other side of the same coin: adding a block to one language does not add it to the others, and there is no "this paragraph is the translation of that paragraph" link between two locales. A field inside a block is therefore never `localized: true`; see [Defining a block](/docs/dev/widgets/defining-a-block#localization).
## Editing one [#editing-one]
A `blocks()` field is the storage half, and the [Visual Editor](/docs/dev/widgets/visual-editor) is how somebody arranges what goes in it. The two are joined by whatever your page hands the editor and whatever your API does with the payload that comes back - the field's own `allowed`, `min` and `max` are re-checked on the way in either way.
For a zone that is not a column on a record at all - a settings screen, a forum index, anything a page simply _has_ - the storage half is core's, and you declare the zone rather than a field. See [Editable Pages](/docs/dev/widgets/editable-pages).
## Exposing the zone publicly [#exposing-the-zone-publicly]
`blocks` is publicly exposable, and crosses whole:
```ts
publicApi: {
path: "pages",
fields: ["title", "slug", "content", "publishedAt"],
}
```
The public read returns the instances in stored order, each one's `data` already validated on the way in.
## What a zone is not [#what-a-zone-is-not]
| | |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Not indexable** | A btree index over a JSONB document orders pages by their serialised bytes. `indexes` refuses it. |
| **Not filterable or orderable** | For the same reason. |
| **Not searchable** | Indexing block prose into search is its own stage. |
| **Not an AdminCP form field** | The generated form and the DataTable both leave it out - a zone is arranged on the page by the [Visual Editor](/docs/dev/widgets/visual-editor), not typed into a control. |
# Content Zones (/docs/dev/widgets/content-zones)
A **Content Zone** is a place on a page where widgets may appear, named by the developer who put it there.
```tsx title="src/routes/_main/pages.$slug.tsx"
import { ContentZone } from '@vitnode/core/widgets/zone'
import { blocksRegistry } from '@/blocks.gen'
;<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```
That is the whole idea. A zone takes a list of block instances and renders them through [`ContentRenderer`](/docs/dev/widgets/rendering). What it adds on top is a **name** - and a name is what the [Visual Editor](/docs/dev/widgets/visual-editor) and [Editable Pages](/docs/dev/widgets/editable-pages) use to place, rearrange, and save widgets on the page.
```text
Public page
↓
ContentZone
↓
ContentRenderer
↓
Blocks
```
## A zone id is not a block id [#a-zone-id-is-not-a-block-id]
These two identifiers are easy to confuse and never interchangeable.
| | Says | Looks like | Written by |
| :-------------------- | :--------------------------- | :-------------------------------- | :------------------------------ |
| **Zone id** | _where_ content is rendered | `main`, `settings:before-profile` | you, in the page's source |
| **Block instance id** | _which block_ sits inside it | `01JC4Z8N9WQKX7R2M5T6V3B8HD` | `createBlockInstanceId()`, once |
A page has a handful of zones and they do not change when content does. A zone holds any number of block instances, and which ones it holds changes every time somebody edits the page.
### Rules for a zone id [#rules-for-a-zone-id]
One or more `:`-separated segments of lowercase letters, digits and single hyphens, up to 64 characters.
```tsx
<ContentZone id="main" />
<ContentZone id="sidebar" />
<ContentZone id="before-profile" />
<ContentZone id="homepage:hero" />
<ContentZone id="settings:before-profile" />
```
The optional prefix is yours to use however you like - a screen, a plugin, a section. `settings:before-profile` and `profile:before-profile` are two different zones, which is the point.
A zone id is never generated and never an array index. Saved editor state will address zones by these strings, so an id that changes is a zone that loses its content. `ContentZone` refuses anything it could not address later:
```tsx
<ContentZone id="Before Profile" blocks={content} />
// BlockError: Content zone id "Before Profile" is not usable. …
```
That throws the first time the page renders, in development or in a test, because a zone id is a literal you wrote - never something a visitor can influence.
### One id, one place on the page [#one-id-one-place-on-the-page]
A zone id names a **location**, so two zones on one page may not share one. Render the same id twice and view mode simply renders both lists, but edit mode refuses:
```tsx
<ContentZone id="main" />
<ProfileForm />
<ContentZone id="main" />
// BlockError: Two `<ContentZone id="main" />` outlets are on the page at the same time…
```
The editor stores, moves and saves blocks by zone id. With two of them it cannot tell which place a block belongs to, and a save would write one over the other - so it says so the moment both are on the page, rather than picking one and being wrong quietly. Moving a zone to a different element, re-rendering it under another branch of the page, and React's double-invoked effects in development are all fine: the refusal is only for two elements that are genuinely on the page at once.
Need the same content in two places? Two ids - `main` and `main-aside` - and the page decides what goes in each.
## Zones around locked application UI [#zones-around-locked-application-ui]
This is the case Content Zones exist for. Not every page is a CMS page: most of an application is code, and the useful thing is to be able to put content _around_ it.
```tsx title="src/routes/_main/settings.tsx"
<UserSettingsLayout>
<ContentZone
id="settings:before-profile"
blocks={layoutContent.beforeProfile}
/>
<ProfileForm />
<ContentZone
id="settings:after-profile"
blocks={layoutContent.afterProfile}
/>
</UserSettingsLayout>
```
`ProfileForm` is application code. It has validation, permissions and tests, and nobody is going to drag a block into the middle of it. The two zones around it are content widgets - an authorized moderator clicks **Edit widgets** in the user menu to rearrange them without touching the form.
```text
editable zone
↓
locked system UI
↓
editable zone
```
<Callout title="See it running">
`/example/zones` in the example plugin is exactly this page: four zones around
a profile form that stays application code.
</Callout>
## Several zones on one page [#several-zones-on-one-page]
Nothing assumes one zone per page. Each one has its own id, its own list and its own rules.
```tsx
<>
<ContentZone id="hero" blocks={page.hero} />
<ArticleContent />
<ContentZone id="after-content" blocks={page.afterContent} />
</>
```
## What a zone renders [#what-a-zone-renders]
By default: **nothing but the blocks**. No wrapper, no element, no class.
That is deliberate. A zone often lives inside a flex or grid container, and an uninvited `<div>` there is a broken `gap` and a column that stopped being a column.
Ask for a wrapper when you want one:
```tsx
<ContentZone
as="aside"
className="flex w-full flex-col gap-4 md:w-64"
id="settings:sidebar"
blocks={content}
/>
```
| Props | Renders |
| :--------------------------------- | :---------------------------------- |
| neither `as` nor `className` | the blocks, and nothing around them |
| `className` only | a `<div>` with that class |
| `as` (with or without `className`) | that element |
`as` takes an **HTML element name** - `"section"`, `"aside"`, `"header"`, `"ul"` - and not a component. The wrapper's job is to carry the zone's identity into the DOM, and a component is free to drop the `data-*` props it is handed, which would lose that identity silently and only in the case nobody tests. If you want the zone inside a component of yours, compose instead of substituting:
```tsx
<Card>
<ContentZone id="settings:sidebar" blocks={content} />
</Card>
```
That reads better anyway, and the zone stays exactly as heavy as it was.
## Empty zones [#empty-zones]
An empty zone renders **nothing at all** - wrapper included.
```tsx
<ContentZone id="sidebar" blocks={[]} />
```
There is no empty container, no stray border and no gap in a flex column. `null`, `undefined` and `[]` behave identically, so a page whose zones are all empty is byte-for-byte a page without zones. The registry is not even consulted.
This is a deliberate performance and layout decision, not an oversight. Most zones in an application are empty most of the time - a page with eight placement points and two filled ones should cost exactly two. Emitting a marker element for the other six would put six nodes in every visitor's document, participate in every flex and grid calculation, and exist for the benefit of a person who is not there.
An editor will need to _see_ an empty zone in order to drop something into it. That is edit mode's job, and edit mode can render whatever placeholder it likes, because by then somebody has asked for it.
## Restricting what may go in a zone [#restricting-what-may-go-in-a-zone]
`allowedBlocks` takes the same shape - and means the same thing - as `allowed` on a [`blocks()` field](/docs/dev/widgets/blocks-field#restricting-what-may-go-in):
```tsx
<ContentZone
id="main"
blocks={page.content}
allowedBlocks={['core:*', 'blog:*']}
/>
```
There is one allowlist format in VitNode, one function that evaluates it, and this is it.
### Two allowlists, two jobs [#two-allowlists-two-jobs]
The same value means two different things in two places, and the difference matters.
| | `field.blocks({ allowed })` | `<ContentZone allowedBlocks>` |
| :------------- | :-------------------------- | :------------------------------------------ |
| **Is** | a write boundary | a description of the location |
| **Runs** | on every create and update | not at all in production |
| **On refusal** | the whole request is a 422 | the block is skipped in development |
| **Answers** | "may this be stored?" | "what belongs here?" |
| **For** | the API | the future editor, and you reading the page |
The field is the thing that _enforces_. A stored instance has already crossed it, so a page re-checking the same list on every render would be paying twice for one answer. The zone's copy exists to say what a location is for - which is what a block picker will need, and what a reader of the JSX needs.
Public rendering is therefore **not** a second _schema_ validation boundary - it re-parses nothing, though it does always check that a stored block still structurally matches its block's fields. What the zone does with its allowlist follows the same `validate` modes the [renderer](/docs/dev/widgets/rendering#validation) already uses, and it _skips_, never rejects:
| `validate` | A block the zone does not allow |
| :-------------------------- | :----------------------------------------------- |
| `"never"` | renders |
| `"development"` _(default)_ | is skipped in development, renders in production |
| `"always"` | is skipped everywhere |
In development the block is skipped, a dashed notice names it, and one `console.warn` is logged per block type - a development aid for content that drifted, not a gate. In production the write boundary is trusted and nothing is checked at all.
`validate="always"` is the exception, for a page rendering blocks the API never saw - a live import, a third-party feed. Even then it costs one `Map` lookup and a list scan per block, not a schema parse.
### Declaring the allowlist once [#declaring-the-allowlist-once]
The zone's allowlist and the field's `allowed` are usually the same value, and writing it twice is a typo waiting to happen.
If the page is an [editable page](/docs/dev/widgets/editable-pages), do not write it on the page at all. `defineEditablePage` declares each zone's allowlist once, and `<EditablePage>` hands every zone under it both the allowlist and the blocks:
```tsx title="plugins/example/src/pages/zones-page.tsx"
<EditablePage layout={layout} page={settingsPage}>
<ContentZone id="before-profile" registry={blocksRegistry} />
</EditablePage>
```
An `id` is the whole zone. There is no second copy to drift, and asking for a zone the page does not declare throws rather than rendering one no save will ever reach.
You may still pass props on a declared zone, with one rule: the page declaration is the ceiling.
| | |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blocks` | Overrides where the content comes from - the array you pass is what renders. |
| `allowedBlocks` | **Narrows only.** It is intersected with the page's allowlist, so `"*"` here cannot re-open a zone the page restricted, and an intersection of nothing is a developer error rather than a zone nobody can fill. |
| `min` / `max` | **Tighten only.** The higher `min` and the lower `max` win, and a `min` that ends up above the `max` throws where you wrote it. |
That is only true for a zone an [editable page](/docs/dev/widgets/editable-pages#what-a-call-site-may-still-say) declares, because that declaration is what the save route checks against. A standalone `<ContentZone>` has nothing to be intersected with, so its own props are simply its own.
For a zone outside an editable page, put the array in a module of its own and import it from both ends:
```ts title="plugins/example/src/content/page-blocks.ts"
export const PAGE_BLOCKS_ALLOWED = ['core:*', 'example:callout'] as const
```
```ts title="plugins/example/src/content/page.ts"
content: field.blocks({ allowed: PAGE_BLOCKS_ALLOWED, max: 50 })
```
```tsx
<ContentZone
id="settings:before-profile"
allowedBlocks={PAGE_BLOCKS_ALLOWED}
blocks={content}
/>
```
One declaration, two readers, and the page imports an array rather than a content type.
<Callout title="Why the zone does not take the field itself" type="warn">
An earlier draft of this API accepted `field={pageContentType.fields.content}` so the allowlist could be read straight off the descriptor. It was measured and removed.
A content type is authored by _calling_ `defineContentType` at module scope, so importing one retains everything that call reaches - the field factories, the schema builders, Zod, the admin labels. On `/example/zones` the difference was **8 chunks and 23.5 kB** against **15 chunks and 181.8 kB**, to read one array of strings.
A boundary test keeps that honest: `blocks/zone.tsx` reaches `react` and nothing else, `content/define.ts` reaches Zod, and `content/fields.ts` reaches nothing - the descriptors are cheap, the content _type_ is not.
</Callout>
### Where the registry comes in [#where-the-registry-comes-in]
Pass it, from the route that renders blocks:
```tsx
import { blocksRegistry } from '@/blocks.gen'
```
`blocks.gen.ts` statically imports every configured plugin's block components, so importing it from a root module - `router.tsx`, a root layout - would put every block in the application on every page, including the ones that render none. Import it in the route that needs it and it stays in that route's chunk. A test asserts the application's root router cannot reach it.
A plugin cannot see the host's generated file at all, so a plugin-owned page builds the registry it needs from the blocks it knows about:
```tsx title="plugins/example/src/pages/zones-page.tsx"
import { createBlockRegistry } from '@vitnode/core/widgets'
import { blocks as coreBlocks } from '@vitnode/core/widgets/built-in'
import { blocks as exampleBlocks } from '@/blocks'
const blocksRegistry = createBlockRegistry([coreBlocks, exampleBlocks])
```
Either way the registry is a value the page owns, and nothing global had to be set up first.
## A zone never fetches [#a-zone-never-fetches]
`ContentZone` is rendering infrastructure. It takes block data as a prop and never goes looking for it.
```text
route loader
↓
one request for the page
↓
zones render what it returned
```
The alternative writes itself, and it is the thing to avoid:
```text
page
├ zone A → request
├ zone B → request
└ zone C → request
```
Five zones on a settings page would be five round trips for data that came from one row. A block that genuinely needs its own data - "the six newest articles" - fetches it inside its own component, where it can be cached and suspended on its own terms.
## Performance [#performance]
A zone costs a function call.
- **No request.** It renders the list it was given.
- **No hydration.** It holds no state, subscribes to nothing, and server-renders like any other component. A page full of zones ships the same JavaScript as a page without them.
- **No editor.** `@vitnode/core/widgets/zone` reaches React and `ContentRenderer`, and that is the entire list. A boundary test asserts the reachable module graph, so drag-and-drop, forms, query and AdminCP code cannot drift into it later.
- **No DOM.** Unless you ask for a wrapper, a zone is not in the markup at all.
## What the editor will find [#what-the-editor-will-find]
When a zone renders a wrapper, the wrapper carries its identity:
```html
<aside
class="…"
data-vitnode-zone="settings:sidebar"
data-vitnode-zone-allowed="core:*,example:callout"
></aside>
```
Two attributes, both short strings. That is the whole metadata story for now, and it is free: they ride on an element you asked for anyway. There is no zone registry, no context and no module-level state holding a list of zones - a public page has nobody to tell.
The format stays small and predictable on purpose. An id, and a comma-separated allowlist. Nothing here will ever grow into a serialised JSON blob in an attribute: anything bigger than a couple of identifiers belongs in edit mode, where it can be a JavaScript value instead of a string somebody has to parse back out of the document.
<Callout title="A zone without a wrapper has no marker - by design" type="warn">
Most zones render no element, so most zones leave no trace in view-mode HTML. That is the [empty-zone and no-wrapper behaviour](#what-a-zone-renders) working as intended, and it means **the set of zones on a page is not discoverable by scanning public DOM**.
Edit mode does not try. It knows its zones because it rendered them - each `ContentZone` registers itself while edit mode is on - rather than walking the document looking for attributes that were never promised to be there. That registration is also what notices [two zones claiming one id](#one-id-one-place-on-the-page): the list the editor keeps is the truth, not the DOM.
</Callout>
If you need those values yourself, `@vitnode/core/widgets` exports the pieces without any React:
```ts
import {
assertContentZoneId,
contentZoneAttributes,
isContentZoneId,
parseContentZoneId,
} from '@vitnode/core/widgets'
parseContentZoneId('settings:before-profile')
// { name: "before-profile", scope: "settings" }
```
## Props [#props]
| Prop | Default | |
| :-------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | — | The zone's stable name. Required. |
| `blocks` | — | The instances to render. `null`, `undefined` and `[]` all render nothing. |
| `registry` | the process default | The registry to resolve blocks against. |
| `allowedBlocks` | none | What may be placed here. Same shape as a `blocks()` field's `allowed`. Under an editable page it may only narrow what the page allows. |
| `min` / `max` | `0` / `200` | How many blocks belong here. Under an editable page they may only tighten the page's own bounds, and with no `max` written anywhere storage still applies its usual ceiling of `200`. |
| `as` | none | An HTML element name to wrap in. Components are not accepted. |
| `className` | none | A class for that wrapper. Implies `as="div"`. |
| `validate` | `"development"` | Passed through to the renderer, and gates the allowlist check. |
| `fallback` | a development-only notice | What to render for a block that is skipped. |
Everything but `id` and `blocks` is optional and named, so later additions - a label, a maximum, a permission - are additions rather than a new signature.
## Verifying it yourself [#verifying-it-yourself]
`/example/zones` in the example plugin is the manual test page for everything above. It renders four zones around a locked profile form, and its own copy lists what each one should look like.
### In development [#in-development]
<Steps>
<Step>
Start the development environment from the repository root:
```bash
pnpm dev
```
</Step>
<Step>
Open [http://localhost:3000/example/zones](http://localhost:3000/example/zones) and check the page itself:
| | Expected |
| :----------- | :--------------------------------------------------------------------- |
| Order | Blocks appear in the order the loader lists them - callout, then text. |
| Locked UI | The profile form renders untouched between the two zones. |
| Empty zone | `settings:before-footer` leaves no gap below the layout. |
| Independence | Each zone renders its own blocks; none affects another. |
</Step>
<Step>
Open DevTools → Elements and check the DOM:
| Zone | Expected |
| :------------------------ | :----------------------------------------------------------------------------------- |
| `settings:sidebar` | `<aside data-vitnode-zone="settings:sidebar" data-vitnode-zone-allowed="core:text">` |
| `settings:before-profile` | its two blocks, with **no** element wrapping them |
| `settings:after-profile` | its block, with **no** element wrapping it |
| `settings:before-footer` | nothing - no element, no comment, no whitespace node |
</Step>
<Step>
Open DevTools → Network, filter to Fetch/XHR, and reload. `ContentZone` issues **no request of its own**: the blocks arrived with the route's loader data.
</Step>
<Step>
Break a zone id on purpose, to confirm it fails loudly rather than silently:
```tsx
<ContentZone id="Settings Sidebar" blocks={loaderData.sidebar} />
```
The page should throw a `BlockError` naming the id and the rule. Put it back.
</Step>
<Step>
Open an unrelated route - `/`, or `/docs` - with the Network panel open, and confirm **no block module loads**. A page that renders no blocks should never request one. This is the property the root router must not break; the [import-graph test](#performance) is the standing guard, and this is how you see it.
</Step>
</Steps>
### A block whose plugin is gone [#a-block-whose-plugin-is-gone]
Content outlives plugins, so the interesting case is a page referencing a block nothing registers. Simulate it **temporarily** - do not commit the change.
<Steps>
<Step>
In `plugins/example/src/blocks.tsx`, comment the callout out of the registered list:
```ts
export const blocks = {
pluginId: manifest.id,
blocks: [], // was [calloutBlock]
} satisfies BlockPluginSource
```
The loader in `zones-page.tsx` still places an `example:callout`, which is exactly the situation: stored content naming a block that is no longer installed.
</Step>
<Step>
**In development**, reload `/example/zones`. Expect a dashed notice reading _Block "example:callout" is not registered_, one `console.warn` in the terminal and browser console, and **every other block still rendering** - the text block, the profile form, the CTA, the sidebar.
</Step>
<Step>
**In production**, run the production flow below with the same edit in place. Expect the callout to be silently absent, no notice, no error, and a 200 response. A visitor sees a page with one section missing, not a stack trace.
</Step>
<Step>
Revert `blocks.tsx`.
</Step>
</Steps>
### Against a production build [#against-a-production-build]
Dev-mode checks miss bundling, minification and real SSR, so repeat the important ones against a build:
<Steps>
<Step>
Build and start:
```bash
pnpm build
pnpm start
```
`pnpm build` runs `vite build` for the web app; `pnpm start` serves `.output/server/index.mjs`. To do just the web app, use `pnpm --filter web build` and `pnpm --filter web start`.
</Step>
<Step>
Read the **server-rendered markup**, not the hydrated DOM - `view-source:`, or:
```bash
curl -s http://localhost:3000/example/zones | grep -o 'data-vitnode-zone[^>]*'
```
Exactly one match, for the sidebar. The unwrapped zones contribute no attribute, and the empty one contributes nothing.
</Step>
<Step>
Confirm the block content is in the HTML the server sent, not painted in afterwards - search the source for a block's text. If it is there, the zone server-rendered and needs no hydration to be readable.
</Step>
<Step>
Confirm no editor code reached the page:
```bash
curl -s http://localhost:3000/example/zones | grep -cE 'dnd-kit|tiptap|cmdk'
```
`0`. The [import-graph tests](#performance) are the standing guarantee; this is the spot check that the guarantee survived bundling.
</Step>
<Step>
Load an unrelated route and confirm its chunks hold no block components - search the modules it preloads for a block id such as `core:hero`:
```bash
curl -s http://localhost:3000/ | grep -o '/assets/[^"]*\.js' | sort -u
```
Fetch those and grep for `core:hero`. Nothing should match: a page that renders no blocks must not carry any.
</Step>
</Steps>
## The same zone, in edit mode [#the-same-zone-in-edit-mode]
A zone renders blocks. It is also the surface an authorized editor arranges them on - see [Visual Edit Mode](/docs/dev/widgets/visual-editor).
```text
ContentZone in view mode:
render blocks
ContentZone in edit mode:
render blocks + the editing surface
```
The part worth saying is what did **not** change. Zones are still addressed by the ids you wrote, block instances by the ids already stored, and the allowlist by the format both the field and the zone already speak. Edit mode is a change inside `ContentZone`, not a change to the pages that use it - so there is no `EditableContentZone` to migrate to, and nothing stored before it existed needed rewriting.
The editor is not in the bundle of a page nobody is editing. It arrives on the first click of **Edit widgets**, through a dynamic import that a [boundary test](/docs/dev/widgets/visual-editor#the-lazy-loading-guarantee) keeps honest.
# Defining a Widget (/docs/dev/widgets/defining-a-block)
## One call [#one-call]
```tsx title="plugins/example/src/widgets/callout.tsx"
import type { WidgetComponentProps, WidgetData } from '@vitnode/core/widgets'
import { defineWidget } from '@vitnode/core/widgets'
import { field } from '@vitnode/core/content'
import { InfoIcon } from 'lucide-react'
const calloutFields = {
body: field.textarea({ required: true, minLength: 1, maxLength: 600 }),
title: field.text({ required: true, minLength: 1, maxLength: 120 }),
tone: field.enum({
defaultValue: 'info',
values: ['info', 'success', 'warning'],
}),
}
type CalloutData = WidgetData<typeof calloutFields>
const Callout = ({ data }: WidgetComponentProps<CalloutData>) => (
<aside>
<h2>{data.title}</h2>
<p>{data.body}</p>
</aside>
)
export const calloutWidget = defineWidget({
component: Callout,
description: 'A short highlighted note in one of three tones.',
fields: calloutFields,
icon: InfoIcon,
id: 'callout',
name: 'Callout',
})
```
`WidgetData<typeof calloutFields>` is the inferred data type: `title` and `body` are `string`, `tone` is `"info" | "success" | "warning" | undefined` because it has a default. Nothing is written twice.
## Give it an icon [#give-it-an-icon]
`icon` is the picture people see next to the widget's name in the [Visual Editor](/docs/dev/widgets/visual-editor): on its card in the catalogue, on the card that follows the pointer while it is dragged, and at the top of its properties panel. Pass the icon **component**, not an element - `icon: InfoIcon`, not `icon: <InfoIcon />` - so the editor can size and colour it to match everything around it.
```tsx
import { MegaphoneIcon } from 'lucide-react'
export const promoWidget = defineWidget({
component: Promo,
fields: promoFields,
icon: MegaphoneIcon,
id: 'promo',
})
```
Any component that accepts a `className` works, so an icon from another set or your own inline SVG is fine too. Pick one that says what the widget **is** at a glance: a megaphone for a call to action, a "T" for text. Leave `icon` off and the widget gets the generic widget icon, which is fine but makes every such card look alike. Core's own widgets use `PanelTopIcon` (Hero), `MegaphoneIcon` (Call to action) and `TypeIcon` (Text).
The icon only shows up in the editor. Your widget's component on the public page never renders it.
## Component props [#component-props]
```ts
interface WidgetComponentProps<TData> {
/** The instance's own stable id - not the widget's. */
blockId: string
data: TData
index: number
type: string
variant?: string
}
```
`data` is checked against the widget's schema when the page is saved, and its shape is checked again before render, so a component never checks for missing fields. Defaults are filled in when it is saved, not at render. `variant` is the look this instance picked, and is `undefined` for a widget that offers none.
<Callout type="warn" title="A text field is not a safe link">
The schema checks that a `field.text()` is a string, not that it is a URL you want people clicking. If your widget turns one into an `href`, check it with `isValidNavigationHref` from `@vitnode/core/lib/navigation` first - it allows a site path (`/discover`) or an `https://` URL and refuses `javascript:` and friends. Core's Hero and Call to action widgets simply leave the link out when it fails.
</Callout>
## Two looks, one widget [#two-looks-one-widget]
A widget that should render the same content in more than one shape declares its shapes instead of growing a `style` field:
```tsx
export const featuresWidget = defineWidget({
component: Features,
defaultVariant: 'grid',
fields: featuresFields,
id: 'features',
variants: [{ id: 'grid' }, { id: 'list' }, { id: 'compact' }],
})
```
The chosen variant is stored **beside** the instance's data, never inside it, and the editor grows a picker for it with no further work. See [Block Variants](/docs/dev/widgets/block-variants) for the resolution rules and what happens to a stored variant a block stops offering.
## Ids are namespaced for you [#ids-are-namespaced-for-you]
Write `id: "callout"`. The registry prefixes the namespace of the plugin that registered it, derived from the **last segment** of the package name:
| Plugin | Block id | Stored as |
| :------------------- | :------------- | :--------------------- |
| `@vitnode/core` | `hero` | `core:hero` |
| `@vitnode/blog` | `latest-posts` | `blog:latest-posts` |
| `@acme/page-builder` | `pricing` | `page-builder:pricing` |
Writing the namespace yourself is an error - a block would otherwise be addressable under two names, and content written under the wrong one would be unrenderable.
Two packages whose names end in the same segment (`@vitnode/blog` and `@acme/blog`) collide. The registry refuses to build and names both; set `namespace` on one of their `blocks` modules to settle it.
## Which fields a block may hold [#which-fields-a-block-may-hold]
| Kind | Supported | Why |
| :------------------------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field.text()`, `field.textarea()` | ✅ | Plain strings, edited in the properties panel. |
| `field.number()`, `field.boolean()` | ✅ | |
| `field.enum()`, `field.dateTime()` | ✅ | |
| `field.group()` | ✅ | Nested objects are ordinary JSON. |
| `field.file()`, `field.relation()`, `field.user()` | Not yet | A reference is a row identifier the owning record has to pin against deletion, and a value inside a JSON document has nowhere to put a foreign key. |
| `field.repeatable()` | Not yet | Its rows are rows on a generated child table, identified by a database id a JSON document does not have. |
| `field.slug()` | No | A slug is a record's address, and a block is not addressable on its own. |
| `field.blocks()` | Not yet | Nested blocks need depth limits, their own allowlist and cycle detection first. |
Every one of those rules lives in one table, `blockFieldKindRefusal`, and the error a refused field produces quotes the reason from it.
<Callout title="Media and relations are a limitation of today, not of the model">
The serialized shape - `{ id, type, data }`, with `data` holding this field map's values - does not change when these land: a `file` field would store a `core_files.id` exactly as a file *column* does. What is missing is the lifecycle around it. A content column pins its file with `ON DELETE RESTRICT`, which is what makes the Files screen answer 409 instead of leaving a published page pointing at bytes that are gone; a value inside JSONB has no foreign key to carry that.
The intended solution is to extract a widget's references out of its data on write - the field map already says which leaves are references - and pin them in a reference table the same way, so deletion, cleanup and `onDelete` keep working. Until that exists, storing a bare id in JSON would be a foreign key with none of the guarantees of one, which is worse than not supporting it. Put the image on the record for now and let the widget choose how to present it.
</Callout>
## Localization [#localization]
A widget's **fields** are never `localized: true`. There is no translation row for them to live in, and per-field locale maps inside JSON would be a second localization system that revisions, preview and the public locale resolution know nothing about.
The **zone** is what translates:
```ts
content: field.widgets({ localized: true })
```
This is document-level localization, not translated field values: each language gets its own widgets, in its own order, and the two need not correspond at all.
```text
en: Hero → Text → CTA
pl: Hero → CTA → Gallery
```
See [The blocks() field](/docs/dev/widgets/blocks-field#localization).
Editing a widget's text in the [properties panel](/docs/dev/widgets/visual-editor#the-properties-panel) changes nothing about this. What somebody types goes into the `data` of the snapshot the page mounted for the locale it is showing, and it is saved by whoever already owned that locale's zone.
## Validating data by hand [#validating-data-by-hand]
A definition is metadata: an id, the field map and the component. It carries no schema of its own, which is what keeps `defineWidget` - and therefore every public page that renders a widget - free of a validation library. The schema is derived from the fields on demand:
```ts
import { parseWidgetData, widgetDataSchema } from '@vitnode/core/widgets'
const data = parseWidgetData(calloutWidget, { title: 'Heads up', body: '...' })
// { title: "Heads up", body: "...", tone: "info" }
widgetDataSchema(calloutWidget).safeParse(input)
```
`parseWidgetData` applies defaults and throws a `BlockError` naming the field when the value does not fit; its return type is inferred from the definition's field map. `widgetDataSchema` is the underlying Zod object, built once per definition and cached.
A variant is not part of that schema, and neither is the arrangement of the widgets around this one - those are the instance's `variant` and its [Area's layout](/docs/dev/widgets/layout-areas). The rule of thumb: **`data` is what the widget says, `variant` is how this instance says it, `Area.layout` is how widgets sit together.**
The Content Engine calls these for you on every write. You need them only when you are producing widget data outside the API - a seed, a migration, an importer.
# Editable Pages (/docs/dev/widgets/editable-pages)
A settings page is edited on the settings page. A forum index is edited on the forum index. Nobody opens an admin screen to arrange a page they cannot see.
```text
the real page
↓ Edit widgets ← in the user menu, only if you hold the page's permission
the same page, editable
↓ Save
↓ Finish editing
the real page again
```
That is the whole feature. What you write to get it is one page declaration, one line of registration, and `<EditablePage>` around the zones you already had. **The button is not yours to draw** - it lives in the user menu in the site header, on every page, and appears there by itself the moment an editable page somebody may edit is on screen.
{/* Image prompt: A clean left-to-right technical diagram on a dark background. Three labelled boxes joined by arrows. First: "defineEditablePage" showing a small list of zone names (before-profile, sidebar, after-profile) each with a tiny allowlist pill beside it. Second: a miniature browser window titled "/example/zones" with two dashed zone outlines around a solid form, and a small outlined button in the corner reading "Edit widgets". Third: a database icon labelled "core_page_layouts" with one row shape beside it, split into a "pageId" cell and a wider "zones JSONB" cell holding two small zone chips. A thin annotation under the middle box reads "one declaration, three readers". Blue accent on the arrows, neutral grey boxes, 1600x600. */}
## The whole thing, in three files [#the-whole-thing-in-three-files]
### 1. Declare the page [#1-declare-the-page]
```ts title="plugins/example/src/content/settings-page.ts"
import { defineEditablePage } from '@vitnode/core/content/editor'
import { PAGE_BLOCKS_ALLOWED, PAGE_SIDEBAR_BLOCKS_ALLOWED } from './page-blocks'
export const settingsPage = defineEditablePage({
id: 'example:settings',
permission: { module: 'widgets', permission: 'can_edit' },
zones: {
'before-profile': {
allowed: PAGE_BLOCKS_ALLOWED,
max: 20,
default: [
{
id: '01JEXAMPLEZONESBEFORE00001',
type: 'example:callout',
data: {/* … */},
},
],
},
'after-profile': { allowed: PAGE_BLOCKS_ALLOWED, max: 20 },
sidebar: { allowed: PAGE_SIDEBAR_BLOCKS_ALLOWED, max: 20 },
'before-footer': { allowed: PAGE_BLOCKS_ALLOWED, max: 20 },
},
})
```
| | | |
| :----------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `id` | required | The page's stable identity, `plugin:page`. The stored layout is keyed by it, so it is written once by hand and never generated. |
| `permission` | required | The **moderator** permission somebody needs before the editor will offer to open. `plugin` defaults to whoever registered the page. |
| `zones` | required | One entry per place on the page blocks may go. At least one. |
And per zone:
| | |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed` | The block allowlist, or `"*"`. Declared **here**, so the page never repeats it. |
| `max` / `min` | How many **blocks** the zone accepts. An area counts nothing itself; the blocks inside it each count one. Leaving `max` out is not "unlimited" - see below. |
| `default` | The layout the zone ships with, as real stored nodes. |
#### Three limits, and they count different things [#three-limits-and-they-count-different-things]
Leave `max` out and the zone still has one: **200**, the `CONTENT_BLOCKS_DEFAULT_MAX` a [`blocks()` field](/docs/dev/widgets/blocks-field) already defaults to, because a zone and a field are stored and validated by the same code. Omitted means "the usual ceiling", never "as many as you like".
| Limit | Value | Counts |
| :---------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A zone's `max` / `min` | `200` when `max` is omitted, `0` when `min` is | **Block instances.** A block inside an [area](/docs/dev/widgets/layout-areas) counts one; the area holding it counts nothing, so an empty area counts as nothing at all. |
| `CONTENT_BLOCKS_ABSOLUTE_MAX` | `1000` | **Nodes in the zone's root list** - blocks and areas alike, children not included. It is the ceiling the stored column can be read back through, so a zone's own `max` may lower it and nothing may raise it. |
| `AREA_CHILDREN_DEFAULT_MAX` | `50` | **One area's children.** A third limit, checked per area, unrelated to the two above. |
All three are exported from `@vitnode/core/widgets`, and a zone that declares a `min` above its effective `max` is refused where it is declared rather than the first time somebody saves.
Zone ids are **page-local**: `"sidebar"`, not `"settings:sidebar"`. The page id already namespaces them - it is what the stored layout is keyed by, and the zone ids are the keys inside it.
<Callout title="The defaults are content, not a placeholder">
A zone nobody has customised renders its `default`, and the read that serves
it says so with `updatedAt: null`. That is the layout you shipped - it is what
a visitor sees before anybody has touched the page, and what a future *reset*
will restore to. So it lives in code rather than being seeded into the
database, and the first **Save** is entitled to write over it.
</Callout>
The definition module is a plain value with **no third-party import anywhere in its graph**, which is what lets the API and a public page import the same file. Ask for a zone it does not declare - on the page, in a save, anywhere - and it throws with the zone ids it does declare.
### 2. Register it [#2-register-it]
```ts title="plugins/example/src/config.api.ts"
buildApiPlugin({
manifest,
// [!code ++:4]
editablePages: [settingsPage],
permissionStaff: {
moderator: { widgets: ['can_edit'] },
},
modules: [adminModule /* … */],
})
```
Two lines, and both are needed for different reasons. `editablePages` is what makes the page id resolvable on the server: without it, a read is a `404` and a save is a `400`. `permissionStaff.moderator` is what puts **Widgets → can edit** in front of somebody granting it - a permission nobody can grant is a permission nobody holds.
Registering one page id twice, or two plugins claiming the same id, is a startup error rather than a race about which loaded last. So is declaring a page whose permission is missing from that plugin's `permissionStaff.moderator` catalogue: the server would boot, the page would read fine, and nobody outside a root role could ever edit it - which is a thing you want to hear at boot rather than from somebody who cannot find the button.
### 3. Render it [#3-render-it]
```tsx title="plugins/example/src/pages/zones-page.tsx"
// [!code ++:4]
<EditablePage
adapter={adapter}
canEdit={canEdit}
layout={layout}
openEditing={search.edit === true}
page={settingsPage}
>
<ContentZone id="before-profile" registry={blocksRegistry} />
<ProfileForm />
<ContentZone
as="aside"
className="w-full lg:w-64"
id="sidebar"
registry={blocksRegistry}
/>
</EditablePage>
```
`<ContentZone id="sidebar" />`. That is the entire zone. No `blocks`, because the provider holds the layout. No `allowedBlocks`, because the provider holds the allowlist. On a page that declared its zones there is nothing left to pass.
#### What a call site may still say [#what-a-call-site-may-still-say]
You can pass those props anyway, and they still do something - just not _anything_. The page declaration is what the server checks a save against, so a zone on that page can be narrowed at the call site and never widened.
| At the call site | |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `blocks` | **Overrides the source.** For a zone whose content genuinely comes from somewhere else, the array you pass is what renders. |
| `allowedBlocks` | **Only narrows.** It is intersected with the page's allowlist, so `"*"` here cannot open a zone the page restricted, and asking for blocks the page does not allow is a developer error rather than a quietly wider zone. |
| `min` / `max` | **Only tighten.** The higher `min` and the lower `max` win. Ask for a combination no list of blocks could satisfy - a `min` above the `max` - and it throws where you wrote it. |
The page stays the ceiling and the floor. That is what makes "the zone as declared" the one thing both the editor and the save route have to agree on, and it is why an intersection is refused rather than silently emptied: a zone allowing nothing at all is a page nobody could edit.
A **standalone** `<ContentZone>` - one no editable page declares - is unaffected. There is nothing to intersect with, so its own `allowedBlocks`, `min` and `max` are simply its own.
| Prop | | |
| :------------ | :------- | :--------------------------------------------------------------------------------------------------- |
| `page` | required | The definition. It is what resolves each zone's blocks and allowlist. |
| `layout` | optional | What the loader read. `null` renders every zone's shipped default. |
| `canEdit` | optional | `true` mounts the editor runtime and offers **Edit widgets** in the user menu. `false` does neither. |
| `openEditing` | optional | Open in edit mode on arrival - what `?edit=true` asks for. Ignored unless `canEdit`. |
| `adapter` | optional | Where **Save** goes. `createContentEditorAdapter` builds one. |
| `onExit` | optional | Called by **Finish editing**, after the unsaved-changes prompt. Edit mode ends either way. |
Edit mode itself is **not a prop**. The page that is editable and the action that opens it are in two different parts of the document - one in `<main>`, the other in the header - so neither may own the state between them. `<EditablePage>` publishes what it is and whether this visitor may edit it; the site shell holds "is somebody editing", answers the user menu with it, and reserves the sidebar's room from the whole page while it is true. Walk away from the page and the offer leaves with it, so the entry is never there for a page that has no zones.
`EditablePage` also adopts the canonical **zones** a save comes back with, so the editor rebases onto what the server actually stored. View mode shows the stored result the moment you press **Finish editing**, with no reload and no second request. The metadata around those zones - `updatedAt` and friends - belongs to the page that owns the layout, not to the editor: hold the payload the save answered with in your own state, and a "Last rearranged 2 minutes ago" line moves with it instead of sitting on the timestamp the loader happened to read. Hand `EditablePage` a layout belonging to a different page id and it throws, because rendering one page's blocks under another page's zones is how a save writes them onto the wrong page.
## Loading it [#loading-it]
```ts title="plugins/example/src/pages/zones-page.tsx"
const [stored, staff] = await Promise.all([
fetcher({
plugin: '@vitnode/core',
method: 'get',
module: 'pages',
path: '/layout',
args: { query: { pageId: settingsPage.id } },
}),
fetcher({
plugin: '@vitnode/core',
method: 'get',
module: 'users',
path: '/permissions',
}),
])
if (!stored.ok) {
throw new Error(`Reading this page's layout answered ${stored.status}…`)
}
```
Two public reads, one round trip. The first is the layout; the second is who is looking.
The `if` is the important line. "Nothing is stored" and "I could not read what is stored" are two different answers and must never look alike: the first is a `200` full of shipped defaults, the second is a throw. Render something plausible in place of a failed read and the next **Save** writes it over whatever the page really held.
## Saving it [#saving-it]
```tsx
const adapter = useMemo(
() =>
createContentEditorAdapter({
page: settingsPage,
save: async (payload) => {
const response = await fetcher({
plugin: '@vitnode/core',
method: 'put',
module: 'pages',
path: '/layout',
args: { body: payload },
})
if (!response.ok) throw new Error(`Saving answered ${response.status}.`)
return zodLayout.parse(await response.json())
},
}),
[],
)
```
The adapter turns the editor's snapshot into a payload carrying **only the zones that changed**, refuses up front to send a zone the page does not declare, and hands the server's canonical answer back so the editor rebases onto what was _stored_ rather than onto what it sent.
```ts
interface EditablePageSavePayload {
pageId: string
zones: Record<string, ContentNode[]> // what you want stored
expectedZones: Record<string, ContentNode[]> // what you were editing
}
```
`expectedZones` is the second half of every save: for each zone being written, the value the editor started from. The server compares it with what is actually stored before touching anything, which is what turns "last save wins" into "the save that knew what it was replacing wins". The adapter fills it in from the editor's own baseline - you do not assemble it.
<Callout title="Two files, and neither of them the editor">
`createContentEditorAdapter` produces a `VisualEditorAdapter`, but it needs
nothing from the editor to do it. So it ships beside the page definition, its
whole graph is two modules with no third-party package in it, and a plain
`import` keeps the example plugin's boundary test green: nothing under core's
`src/editor/` is in the page's eager graph. The `@vitnode/core/editor/adapter`
barrel, by contrast, is thirty-three modules and Zod.
</Callout>
## The two routes [#the-two-routes]
They are core's, not your plugin's, and they are addressed by page id.
```http
GET /api/vitnode/core/pages/layout?pageId=example:settings public
PUT /api/vitnode/core/pages/layout that page's permission
```
```ts
interface EditablePageLayoutPayload {
pageId: string
updatedAt: string | null // null: nothing stored, these are the defaults
zones: Record<string, ContentNode[]>
}
```
`GET` is public, because a visitor renders the page from it. It answers with the **effective** layout - the shipped defaults with whatever has been customised laid over them - so the page renders what it is handed and resolves nothing itself. The defaults it sends have been through the same block schemas a saved zone goes through, so a zone still on its default arrives in the same shape as one somebody has edited, fields the block fills in and all. Hand `EditablePage` the layout from this route and it never has to guess: the `default` you declared is a fallback for a zone the server did not send, and it has not been through those schemas. A page id nobody registered is a `404`; a registered page nobody has rearranged is a `200` holding the declared defaults and `updatedAt: null`.
`PUT` takes `{ pageId, zones, expectedZones }` with only the zones that changed, and answers with the canonical stored value of **those zones only** - the same `EditablePageLayoutPayload`, `updatedAt` and all, which is what the page adopts so its own layout metadata stays current. The mapping from a zone id to somewhere to store it comes from the registered page, never from the body, so there is no shape of request that reaches a zone the page did not declare. A body that writes a zone without a baseline for it is a `400`: without one the server cannot tell an edit from an overwrite.
After validation the write is one read, one comparison, one merge and one upsert, whatever number of zones the save named. The block validator is the engine's own; the event - `core.page-layout.updated`, carrying the page id and the zones that changed - is emitted after the commit rather than inside it; and a save that changed nothing stores nothing, bumps no `updatedAt` and emits nothing, while still answering canonically.
### Two moderators, one page [#two-moderators-one-page]
The comparison is **per zone**, inside the same transaction that writes, which is what lets an ordinary afternoon work out:
| | |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Two people, **different zones** | Both saves land. One writes the sidebar, the other the footer, and each leaves the other's zone exactly as it found it. Zones merge because a save only ever writes what it names. |
| Two people, **the same zone** | The second one gets a `409` and **nothing is written**. The zone moved after their editor read it, so storing their copy would delete a change they never saw. |
A `409` is not a lost afternoon: the refusal says which zones moved, nothing that was arranged is thrown away, and reloading the page picks up what is really there to redo the change on top of it. Nothing polls and nothing locks - the baseline travels with the save, so the only thing that can ever be overwritten is a zone whose stored value is still the one being edited.
## "Can I edit this?" [#can-i-edit-this]
The page asks the existing public route:
```http
GET /api/vitnode/core/users/permissions → { root, permissions[] }
```
`root` is a role that holds everything and lists nothing, so it counts as yes on its own. Otherwise the page looks for its own `{ plugin, module, permission }` in the list.
<Callout title="Why a moderator permission and not an admin one" type="warn">
An admin-type check reads `c.get("admin")`, and only `globalAdminMiddleware`
populates it. On a public page that middleware never ran, so
`checkStaffPermission(c, { type: "admin", … })` does not merely answer *no* - it
answers no **structurally**, for everybody, including the person who genuinely
administers the site. A moderator permission reads `c.get("user")`, which a public
request does have. That is why `permission` on a page definition is a
`permissionStaff.moderator` entry, and why `PUT /pages/layout` asserts it as one.
</Callout>
`?edit=true` may **request** edit mode - it is what a link hands you, and what `openEditing` passes on - and it never authorizes it. The page only opens in edit mode when the permission agrees, the **Edit widgets** entry is absent from the user menu otherwise, and the save asserts the permission again server-side whatever the URL said.
## Where a layout is stored [#where-a-layout-is-stored]
In core, in one ordinary table:
```ts
core_page_layouts
pageId varchar primary key
zones jsonb not null default '{}'
createdAt timestamp
updatedAt timestamp
```
**One row per page, holding overrides only.** `zones` is a `Record<zoneId, ContentNode[]>` carrying just the zones somebody has actually rearranged. What the page renders is the two halves put together:
```ts
effective[zoneId] = Object.hasOwn(stored.zones, zoneId)
? stored.zones[zoneId]
: zone.default
```
Defaults live in code; the database stores the custom ones. A page nobody has touched has **no row at all** - which is exactly what `updatedAt: null` means. Save a zone back to precisely what it ships with and its key is dropped again; empty the object and the row goes with it. A reset is therefore a delete rather than a re-seed, and the shipped layout is written down in exactly one place.
A stored zone the page no longer declares is **ignored for rendering but not deleted**. Only declared zones are read, so nothing renders it, and no ordinary save touches it: take a zone off a page for one release, put it back in the next, and what was stored for it is still there.
None of this is a Content Engine content type. No publication, no search indexing, no generated CRUD, no AdminCP screens. Layout persistence is **internal infrastructure** - you do not browse it, any more than you browse the sessions table.
<Callout title="There is no AdminCP → Layouts screen in V1, on purpose">
Central layout administration - listing the pages somebody has customised,
resetting one to its shipped defaults, exporting a layout as JSON, copying one
page's layout onto another - is deliberately left to a possible **V2**. Each
of them is a query on one table keyed by `pageId`: list is `select "pageId"`,
reset is a `delete`, export is a single row. The shape makes them easy later;
none of them is built now, and none of them is needed to arrange a page.
</Callout>
Every submitted zone is re-validated against that zone's own `allowed`, `min` and `max`, read off the **registered page** rather than off the request, before anything is stored.
## When a save is refused [#when-a-save-is-refused]
Every refusal is named, and none of them falls back to a default or silently drops content.
| | |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| A page id nobody registered | `400`, saying there is nothing this save could be writing. |
| A zone the page does not declare | `400`, listing the zones it does. |
| No zones at all | `400`. A save names what it changed, and this one named none. |
| A zone written without a baseline | `400`. Every zone in `zones` needs its counterpart in `expectedZones`. |
| A zone somebody else changed first | `409`, naming the zones that moved. Nothing is written - not even the zones that would have been fine. |
| A block the zone does not allow | `400`, from the zone's own `allowed` - nested inside an area too. |
| Too many or too few blocks | `400`, from the zone's own `max` and `min`, counting an area's children. |
| The permission is not held | `403`. |
| The stored layout cannot be read | `500`. A read that fails is never answered with defaults: the next **Save** would write them over whatever is really there. |
The client has its own guard before any of this: a zone holding a value the editor cannot read keeps **Save** disabled until somebody removes it deliberately. See [unreadable content](/docs/dev/widgets/visual-editor#content-the-editor-cannot-read).
## What this costs a public page [#what-this-costs-a-public-page]
The page definition is a module a public page imports, so it was measured rather than asserted. Every number is the import graph of a real file in this repository.
| Entry | Source files | Third-party |
| :-------------------------------------------- | -----------: | :---------- |
| `@vitnode/core/content/editor` | 12 | none |
| `createContentEditorAdapter` alone | 2 | none |
| `EditablePage` (`blocks/page.tsx`), eagerly | 15 | `react` |
| `ContentZone` (`blocks/zone.tsx`) | 19 | `react` |
| **The example's page definition, end to end** | **15** | **none** |
| `@vitnode/core/content/define` | 34 | `zod` |
| `@vitnode/core/content` (the barrel) | 54 | `zod` |
| `@vitnode/core/editor/adapter` (the barrel) | 33 | `zod` |
A module whose whole graph has no external specifier cannot add a package to anything that imports it. That is the entire argument for keeping the declaration off the content type: a page gets its zone ids, allowlists and defaults without the schema builder that turns field descriptors into Zod.
The same rule applies to blocks. `plugins/example/src/blocks/callout.tsx` used to import `field` from `@vitnode/core/content`; switching two import paths to `@vitnode/core/content/fields` took the playground's eager graph from **132 modules to 107**, and the Content Engine modules it reaches from **41 to 16**. The rendered page was byte-for-byte identical.
```ts
import { field } from '@vitnode/core/content' // [!code --]
import { field } from '@vitnode/core/content/fields' // [!code ++]
```
Two boundary tests keep it that way. Core's own names every module `@vitnode/core/content/editor` reaches and asserts it reaches no third-party one; the example plugin's walks the **real page** and asserts nothing under core's `src/editor/` - and no drag-and-drop, command palette or database package - is in its eager graph, while following its dynamic imports does reach `@dnd-kit/core`, so the guarantee is not vacuous.
## `<PageWidgets>`: the loading, the saving and the permission, once [#pagewidgets-the-loading-the-saving-and-the-permission-once]
Everything above is the contract. You rarely write it, because core owns the two routes a layout is read and written through - so core also owns talking to them.
```tsx title="Any page that declares its zones"
import { loadPageWidgets, PageWidgets, PageWidgetsZone } from '@vitnode/core/tanstack/widgets'
export const route = defineRoute({
load: async ({ context }) => await loadPageWidgets(context.queryClient, settingsPage),
})
const Page = () => (
<PageWidgets page={settingsPage}>
<PageWidgetsZone id="header" />
<ProfileForm />
<PageWidgetsZone id="footer" />
</PageWidgets>
)
```
That is the whole integration. No `fetcher` call, no `createContentEditorAdapter`, no permission comparison and no registry plumbing: `PageWidgets` reads the layout and the viewer's moderator permissions, builds the adapter, folds each save's canonical answer back into the cache, and hands every `PageWidgetsZone` the right blocks and the application's block registry. It takes the page definition and nothing else - which is why the definition names its permission's `plugin` rather than leaning on the server-side default, so the browser can answer "may I edit this?" without knowing who registered the page.
`loadPageWidgets` is the one line a **route** writes. A zone never fetches and a loader is where this framework reads, so the warm belongs there - and neither query rejects, so a widget area that cannot be read costs the page it decorates nothing.
<Callout title="When to reach past it">
Write the loader and adapter by hand when the page is not read from core's own
layout route - zones stored on your own record, a different API, a preview of
something unsaved. The sections above are that contract, and `<EditablePage>`
is still what you wrap them in.
</Callout>
## Core ships one: the account settings page [#core-ships-one-the-account-settings-page]
`/settings` - the account settings screen every member of every VitNode install visits - declares two zones of its own, and is the reference for the three lines above:
| Zone | Where it sits |
| :------- | :-------------------------------------------------- |
| `header` | Under the "Settings" heading, above the two panels. |
| `footer` | Below the panels, above the site footer. |
Both take **every installed block**, so a plugin's own block can go there too, and both cap at ten. They ship empty: an install nobody has touched renders no extra markup at all, and the zones are invisible until somebody puts something in them.
```text
Settings ← the page heading
header zone ← "Two-factor sign-in becomes required on 1 October."
nav | panel ← application UI, not editable
footer zone ← "Need a hand? Contact support"
```
Rearranging them is gated on the moderator permission `@vitnode/core` → **Widgets** → `can_edit`, grantable from **Staff → Moderators** in the AdminCP. Hold it (or a root role) and **Edit widgets** appears in the user menu while you are on `/settings`, exactly as it does on a page your own plugin declared.
<Callout>
A zone renders from the block registry your application generated, so every plugin you configured is offered. In an install that has never rendered a block anywhere else, core's own `core:text`, `core:cta` and `core:hero` are offered instead of nothing.
</Callout>
A read failure is not fatal. If the layout route cannot be reached, the page still renders in full - just without its widget areas, and with **Edit widgets** withheld, because an editor that opened on empty zones would offer to save over whatever is really stored.
## The playground [#the-playground]
`/example/zones` is the reference integration and the manual test page: four zones around a locked profile form, blocks from two plugins, a block stored with a variant, an area holding two blocks, and a second area left empty. The page itself draws no button at all: **Edit widgets** appears in the user menu for somebody holding `example.widgets/can_edit`, and nowhere else.
Visit it signed out and it is an ordinary page - shipped defaults, no entry in any menu, no editor chunk. Two checklists on the page say exactly what to look for in DevTools, including the two that matter here: that a save carries one zone rather than the whole page, and that nothing under `src/editor/` is requested until somebody clicks **Edit widgets**.
# End-to-end Example (/docs/dev/widgets/end-to-end)
Everything below is the `@vitnode/example` plugin as it ships, so you can read the finished version in the repository.
```text
define block → register in plugin → blocks() field → create content → ContentRenderer
```
<Steps>
<Step>
## Define the block [#define-the-block]
```tsx title="plugins/example/src/blocks/callout.tsx"
import type { BlockComponentProps, BlockData } from '@vitnode/core/widgets'
import { defineBlock } from '@vitnode/core/widgets'
import { field } from '@vitnode/core/content'
const calloutFields = {
body: field.textarea({ required: true, minLength: 1, maxLength: 600 }),
title: field.text({ required: true, minLength: 1, maxLength: 120 }),
tone: field.enum({
defaultValue: 'info',
values: ['info', 'success', 'warning'],
}),
}
type CalloutData = BlockData<typeof calloutFields>
const tones: Record<string, string> = {
info: 'border-primary/40 bg-primary/5',
success: 'border-success/40 bg-success/5',
warning: 'border-destructive/40 bg-destructive/5',
}
const Callout = ({ data }: BlockComponentProps<CalloutData>) => (
<aside
className={`flex flex-col gap-2 rounded-lg border p-4 md:p-6 ${tones[data.tone ?? 'info']}`}
>
<h2 className="text-base font-semibold text-balance md:text-lg">
{data.title}
</h2>
<p className="text-sm leading-relaxed text-pretty md:text-base">
{data.body}
</p>
</aside>
)
export const calloutBlock = defineBlock({
component: Callout,
description: 'A short highlighted note in one of three tones.',
fields: calloutFields,
id: 'callout',
name: 'Callout',
})
```
</Step>
<Step>
## Export the plugin's `blocks` module [#export-the-plugins-blocks-module]
The subpath is the registration. Name the file `src/blocks.tsx` so it resolves as `@vitnode/example/blocks`.
```tsx title="plugins/example/src/blocks.tsx"
import type { BlockPluginSource } from '@vitnode/core/widgets'
import { manifest } from '@/manifest.gen'
import { calloutBlock } from './blocks/callout'
export const blocks = {
pluginId: manifest.id,
blocks: [calloutBlock],
} satisfies BlockPluginSource
```
That is the whole registration for the browser. VitNode's Vite plugin finds the module, writes `src/blocks.gen.ts` in every application that configures the plugin, and the block is available as `example:callout`.
Add `namespace: "acme"` here if the derived one - the last segment of the package name - is not the id you want.
</Step>
<Step>
## Give the API the same list [#give-the-api-the-same-list]
The API validates writes, so it needs the definitions too. Pass the **same object**:
```ts title="plugins/example/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'
import { manifest } from '@/manifest.gen'
// [!code ++:2]
import { blocks } from './blocks'
export const exampleApiPlugin = () =>
buildApiPlugin({
manifest,
// [!code ++:2]
blocks,
modules: [adminModule],
})
```
Passing a different plugin's module is an error - the API and the browser must namespace a block identically or a stored `type` would resolve to two different things.
</Step>
<Step>
## Add a `blocks()` field to a content type [#add-a-blocks-field-to-a-content-type]
```ts title="plugins/example/src/content/page.ts"
import { defineContentType, field } from '@vitnode/core/content'
export const pageContentType = defineContentType({
id: 'example.page',
tableName: 'example_pages',
fields: {
title: field.text({ required: true, minLength: 3, maxLength: 200 }),
slug: field.slug({ source: 'title' }),
content: field.blocks({
allowed: ['core:*', 'example:callout'],
max: 50,
}),
},
publication: true,
publicApi: {
path: 'pages',
fields: ['title', 'slug', 'content', 'publishedAt'],
},
})
```
```ts title="plugins/example/src/database/pages.ts"
import { createContentModel } from '@vitnode/core/content/server'
import { pageContentType } from '@/content/page'
export const pageContent = createContentModel(pageContentType)
export const example_pages = pageContent.table
```
Register `pageContent` in the plugin's admin module and its public module, exactly like any other content type.
</Step>
<Step>
## Build and migrate [#build-and-migrate]
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Build and migrate">
```bash tab="bun"
bun run db:migrate
```
```bash tab="pnpm"
pnpm db:migrate
```
```bash tab="npm"
npm run db:migrate
```
</Tabs>
The generated migration is one table with one JSONB column for the zone:
```sql
CREATE TABLE "example_pages" (
"id" serial PRIMARY KEY,
"createdAt" timestamp DEFAULT now() NOT NULL,
"updatedAt" timestamp DEFAULT now() NOT NULL,
"publishedAt" timestamp,
"status" varchar(32) DEFAULT 'draft' NOT NULL,
"title" varchar(200) NOT NULL,
"slug" varchar(160) NOT NULL,
"content" jsonb DEFAULT '[]' NOT NULL
);
```
</Step>
<Step>
## Create a record with blocks [#create-a-record-with-blocks]
The generated admin route takes the zone as part of the payload. Give every instance its own stable id.
The generated admin module has no static type to infer from, so it is reached with `rawFetcher` - the same call the AdminCP itself makes.
```ts
import { createBlockInstance } from '@vitnode/core/widgets'
import { rawFetcher } from '@vitnode/core/tanstack/fetcher'
await rawFetcher({
method: 'post',
module: 'content/page',
path: '/',
pluginId: '@vitnode/example',
prefixPath: '/admin',
body: {
title: 'Build your community',
content: [
createBlockInstance('core:hero', {
title: 'Build your community',
description: 'Everything you need, in one place.',
}),
createBlockInstance('example:callout', {
title: 'Heads up',
body: 'Blocks are validated before they are stored.',
tone: 'info',
}),
],
},
})
```
`content/page` is the content type's `permissionModule`, derived from the entity half of its id.
Anything the registry refuses - an unregistered block, one the field does not allow, data that breaks a field, two instances sharing an id - is a 422 naming the index of the block at fault. Nothing half-valid is stored.
</Step>
<Step>
## Render it [#render-it]
```tsx title="src/site/pages/page-screen.tsx"
import { ContentRenderer } from '@vitnode/core/widgets/renderer'
import { blocksRegistry } from '@/blocks.gen'
export const PageScreen = ({ page }: { page: PageContent }) => (
<main className="mx-auto flex w-full max-w-3xl flex-col gap-8 px-4 py-10">
<h1 className="text-3xl font-semibold text-balance">{page.title}</h1>
<ContentRenderer blocks={page.content} registry={blocksRegistry} />
</main>
)
```
Read the record with the generated public route - the zone comes back whole, in stored order:
```ts
import { fetcher } from '@vitnode/core/tanstack/fetcher'
const page = await fetcher({
plugin: '@vitnode/example',
method: 'get',
module: 'content/pages',
path: '/{slug}',
args: { param: { slug } },
}).then(async (res) => await res.json())
```
That one is fully typed: `pages` is the content type's `publicApi.path`, and the response shape - `content` included - is inferred from the definition.
No extra request is made for the blocks themselves: the definitions came from the plugin configuration when the application started, and nothing re-validates data the write in step 6 already checked.
</Step>
</Steps>
## Where this goes next [#where-this-goes-next]
[Content Zones](/docs/dev/widgets/content-zones) put a name on the place those blocks are rendered, so the step above becomes:
```tsx
<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```
The [Visual Editor](/docs/dev/widgets/visual-editor) and [Editable Pages](/docs/dev/widgets/editable-pages) sit on top of exactly this. Clicking **Edit widgets** turns an interactive editing surface on for an authorized moderator: the block catalogue lists what the zone's allowlist resolves to, drag and drop re-orders widgets in place, and the properties panel edits each widget's fields.
# Widgets Overview (/docs/dev/widgets)
A **widget** is a page section somebody can place, in an order they choose: a hero, a paragraph of prose, a call to action, "the six newest articles". A plugin defines it once - the fields it holds and the React component that renders it - and every content type or editable page in the installation can offer it.
```text
Plugin
↓ defines widgets (defineWidget)
Widget Registry
↓ allowed by a blocks() field or defineEditablePage()
Content record / Page layout
↓
ContentZone
↓
ContentRenderer / Visual Editor (Edit widgets)
```
## What a widget is made of [#what-a-widget-is-made-of]
| Part | What it is |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| **Id** | `hero`, written without a namespace. The registry prefixes the plugin's own, so it is stored as `core:hero`. |
| **Fields** | Content Engine field descriptors - the same `field.text()`, `field.enum()` and friends a content type uses. There is no second schema system. |
| **Component** | One public React component. It receives the data the record stores for that instance. |
| **Schema** | Derived from `fields` at the write boundary. You never write it, and a public render never builds it. |
## What a widget is not [#what-a-widget-is-not]
A widget is **not** a content type. It has no table, no id of its own in the database, no permissions and no API routes. It is a value that lives inside a record or a page layout - which is exactly why re-ordering a page is one `UPDATE` and not a migration.
## Visual editing [#visual-editing]
Widgets power in-place visual editing. Wrap your page's content zones in `<EditablePage>`:
```tsx title="plugins/example/src/pages/settings-page.tsx"
// [!code ++:4]
<EditablePage
adapter={adapter}
canEdit={canEdit}
layout={layout}
page={settingsPage}
>
<ContentZone id="before-profile" />
<ProfileForm />
<ContentZone id="sidebar" />
</EditablePage>
```
There is no button to write. **Edit widgets** appears in the user menu in the site header whenever a page like this one is on screen and `canEdit` says yes. When an authorized moderator clicks it:
- **Drag and drop**: Rearrange widgets or drag new widgets into allowed zones.
- **Properties panel**: Configure widget settings, variants, and [Layout Areas](/docs/dev/widgets/layout-areas).
- **Zero visitor footprint**: The editor chunk is lazily loaded on click and never ships to ordinary visitors.
- **Layout persistence**: Overrides save directly to `core_page_layouts`—see [Editable Pages](/docs/dev/widgets/editable-pages).
- **Room, not overlap**: The whole site slides over for the sidebar, so nothing you are arranging ends up underneath it.
## How widgets reach an application [#how-widgets-reach-an-application]
Nothing is scanned and nothing is queried. A plugin exports a `widgets` module; VitNode's Vite plugin sees it and writes `src/widgets.gen.ts`, which builds the registry and registers it.
```ts title="src/widgets.gen.ts (generated)"
import {
createWidgetRegistry,
setDefaultWidgetRegistry,
} from '@vitnode/core/widgets'
import { widgets as widgets0 } from '@vitnode/core/widgets/built-in'
import { widgets as widgets1 } from '@vitnode/example/widgets'
export const pluginWidgets = [widgets0, widgets1]
export const widgetsRegistry = createWidgetRegistry(pluginWidgets)
setDefaultWidgetRegistry(widgetsRegistry)
```
Installing a plugin is the whole registration step. Removing it takes its widgets with it, and a page that still references one keeps rendering everything else - see [Rendering](/docs/dev/widgets/rendering).
A registry is a plain value, not a service: `createWidgetRegistry` returns an isolated one, and every consumer takes it as an argument. The last line installs it as the process default, which is a convenience for a renderer used without a `registry` prop. Two applications in one process each create their own and pass it explicitly.
Import `src/blocks.gen.ts` **only from a route that renders widgets** - it statically imports every plugin's widget components, so a root module that touches it makes every visitor pay for all of them. The API never needs it: it builds its own registry from the same plugins when it boots, which is what validates every write.
## Where validation happens [#where-validation-happens]
```text
write (untrusted) → full schema check, defaults applied → JSONB
read → nothing
render → structural check, every mode
```
Widget data is checked in full once, where it arrives: every create and update runs each instance through its widget's own schema before a row is written, and `ContentRenderer` never repeats that parse. What it does repeat, in every mode, is a cheap structural comparison of the stored object against the widget's current fields - because the write was validated against the definition the widget had _then_, and a plugin can rename a field afterwards. A widget whose stored shape no longer matches is skipped rather than handed to a component that would reach for a key that is gone. [Rendering](/docs/dev/widgets/rendering#validation) has the detail.
## Widgets that ship with core [#widgets-that-ship-with-core]
| Id | What it renders |
| :---------- | :--------------------------------------------------------------------------------------- |
| `core:hero` | A page heading with an optional eyebrow, lead paragraph and one link. |
| `core:text` | Plain paragraphs of prose. Blank lines separate paragraphs; nothing is parsed as markup. |
| `core:cta` | A short call to action with one link. |
## Guides [#guides]
<Cards>
<Card
title="Defining a Widget"
description="defineWidget, fields, namespacing and typed component props"
href="/docs/dev/widgets/defining-a-block"
/>
<Card
title="The blocks() Field"
description="Storing an ordered zone on a content type, and restricting what may go in it"
href="/docs/dev/widgets/blocks-field"
/>
<Card
title="Widget Variants"
description="One widget, several looks - stored beside the data instead of inside it"
href="/docs/dev/widgets/block-variants"
/>
<Card
title="Layout Areas"
description="Widgets side by side in up to four columns, without a columns container"
href="/docs/dev/widgets/layout-areas"
/>
<Card
title="Rendering"
description="ContentRenderer, missing widgets, and why a widget costs no extra request"
href="/docs/dev/widgets/rendering"
/>
<Card
title="Content Zones"
description="Naming a place on a page where widgets may appear, including around locked application UI"
href="/docs/dev/widgets/content-zones"
/>
<Card
title="Editable Pages"
description="Declaring a page's zones once, so the people who run the site rearrange them on the page itself"
href="/docs/dev/widgets/editable-pages"
/>
<Card
title="Visual Editor"
description="Turn a public page into an interactive editing surface with drag and drop and a widget sidebar"
href="/docs/dev/widgets/visual-editor"
/>
<Card
title="End-to-end Example"
description="From an empty plugin to a rendered page, in seven steps"
href="/docs/dev/widgets/end-to-end"
/>
</Cards>
# Layout Areas (/docs/dev/widgets/layout-areas)
A zone is a list. Lists go downwards. Pages, unfortunately, also go sideways.
An **Area** is the smallest thing that fixes that: a container stored in the zone, holding a few widgets and one small layout description. It is what you reach for when two widgets belong next to each other, and nothing more than that.
```text
zone
├─ block a full-width hero
├─ area 2 columns
│ ├─ block the explanation
│ └─ block the call to action
└─ block a closing note
```
{/* Image prompt: A wireframe of one content zone, top to bottom: a full-width block, then a rounded container labelled "Area · 2 columns" holding two blocks side by side, then another full-width block. A small sidebar on the right shows an "Area" panel with a 1-2-3-4 Columns switch, Alignment and Distribution selects under "LAYOUT", and Gap sliders under "SPACING". Dark UI, blue accents, 1600x900. */}
## The three-way split [#the-three-way-split]
This is the idea the whole feature is built on, and it is worth stating plainly:
| | Belongs to | Example |
| :------------------------------------------------ | :-------------------------------- | :----------------------------------- |
| **`data`** | One block | "Ships on Friday", a heading, a link |
| **[`variant`](/docs/dev/widgets/block-variants)** | One block instance | `grid`, `list`, `compact` |
| **`Area.layout`** | The relationship _between_ blocks | two columns, medium gap, top-aligned |
A block never describes the block next to it. That is why columns are not a field, and why `Area` exists at all.
## The stored shape [#the-stored-shape]
An Area sits in the zone's array, beside the blocks, and is told apart by its `kind`:
```json
[
{ "id": "01JC…HD", "type": "core:hero", "data": { "title": "Welcome" } },
{
"id": "01JC…KP",
"kind": "area",
"layout": { "columns": 2, "gap": "md", "align": "stretch" },
"children": [
{ "id": "01JC…R2", "type": "core:text", "data": { "heading": "Left" } },
{ "id": "01JC…T7", "type": "core:cta", "data": { "title": "Right" } }
]
}
]
```
| Key | Rule |
| :--------- | :------------------------------------------------------------------------------------------------------------------------ |
| `kind` | Always `"area"`. It is the only thing that distinguishes an Area from a block, which is why a block may never declare it. |
| `id` | The same kind of id a block instance has - stable, unique within the zone, and kept through every move and re-order. |
| `layout` | The tokens below. `columns` is required; the rest have defaults. |
| `children` | Blocks, in rendered order. **Blocks only.** |
Array order is rendered order, inside an Area exactly as outside one.
## The layout tokens [#the-layout-tokens]
Four closed sets. Not CSS, not class names - tokens VitNode renders, so a stored layout cannot turn into arbitrary styling smuggled through a content column.
| Token | Values | Default | What it does |
| :-------- | :------------------------- | :-------- | :--------------------------------------------------------------------------- |
| `columns` | `1` `2` `3` `4` | `2` | How many columns on a wide screen. Always one column on a phone - see below. |
| `gap` | `none` `sm` `md` `lg` | `md` | The space between children, in both directions. |
| `align` | `start` `center` `stretch` | `stretch` | How children line up across a row. `stretch` gives equal-height columns. |
| `justify` | `start` `center` `stretch` | `stretch` | How each child sits across its own column. `stretch` fills it. |
Areas are **mobile-first**: below the `md` breakpoint every Area is one column, whatever `columns` says. Two columns on a 360px screen is not a layout, it is a dare.
## An Area is not a block [#an-area-is-not-a-block]
This is the part worth reading twice, because it is what keeps Areas cheap:
- There is **no `core:area` block**. Nothing registers it, nothing can be installed to provide it, and `registry.get("core:area")` is `undefined` - on purpose.
- It needs **no entry in `allowedBlocks`**. A zone that allows `["core:text"]` still accepts an Area holding `core:text`. The allowlist governs blocks, and the children inside an Area are checked against the very same list as blocks at the zone's root.
- It has **no `data`, no fields and no component of its own**. There is nothing for a properties form to build, which is why the editor shows four selects instead.
In the editor's block catalogue it therefore lives in its own **Layout** section above the plugin groups, rather than pretending to be somebody's block.
```tsx
<ContentZone
id="settings:sidebar"
allowedBlocks={['core:text']}
blocks={content.sidebar}
/>
```
That zone accepts: `core:text` at the root, an Area, and `core:text` inside the Area. It still refuses `core:cta` in both places.
## Areas cannot contain Areas [#areas-cannot-contain-areas]
**In Stage 4, an Area's children are blocks. Never another Area.**
That is enforced everywhere it can be: the drag-and-drop resolver refuses the drop and says so out loud, the catalogue hides the Layout section while an Area is the insertion target, and the API refuses a nested Area on write. A stored document that somehow contains one is shown as unreadable rather than rendered.
<Callout title="Why one level, when the shape would obviously recurse?">
Because every extra level costs more than it looks. Nesting needs depth limits, cycle detection, an answer for what an allowlist means three levels down, a keyboard drag model that can climb out of a container, and a properties panel that can say *which* area you are editing. One level covers "put these two things side by side", which is what people actually ask for, at a fraction of the surface area.
The shape is ready for it - `children` is a list of nodes, and a nested area would be one more node kind in it - so the door is closed, not locked.
</Callout>
## In the editor [#in-the-editor]
| | |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Adding one** | The **Layout** section of the **Widgets** catalogue holds a single **Area** entry. It drops an empty Area into the targeted zone. |
| **Filling it** | Drag a block onto the Area, or use **Add widget** on the Area itself - the sidebar then says _Adding to an area in that zone_, and the Layout section disappears while it is targeted. |
| **Selecting it** | Click the Area's own shell (not a child) and the sidebar shows **Area properties**: Columns, Alignment and Distribution under **Layout**, then Gap and the space above/below and left/right under **Spacing**. Each control re-lays the page out as you pick it. |
| **Ungroup** | Removes the Area and leaves its children in the zone, at the position the Area held. Nothing is deleted. |
| **Delete area** | Removes the Area **and** its children. A non-empty Area asks first, and offers _Ungroup, keep widgets_ in the same breath. |
An **empty Area renders nothing at all in public** - no wrapper, no gap, exactly like an [empty zone](/docs/dev/widgets/content-zones#empty-zones). In edit mode it is a visible two-column drop target, because now somebody is looking for a place to put something.
## Reading a zone that may hold Areas [#reading-a-zone-that-may-hold-areas]
A zone is a list of **content nodes**, and a node is a block or an Area. Two helpers keep that from spreading through your code:
```ts
import { contentNodeBlocks, isBlockAreaInstance } from '@vitnode/core/widgets'
isBlockAreaInstance(node) // narrows a node to an Area
contentNodeBlocks(nodes) // every block in the zone, areas flattened away
```
`contentNodeBlocks` is what you want for anything that cares about blocks and not about arrangement: counting them, indexing their text, checking an allowlist. Rendering is already handled - `ContentRenderer` walks nodes and lays an Area out for you.
<Callout title="A migration you do not have to run">
A zone stored before Areas existed is a list of blocks, and a list of blocks
is a list of nodes that never nests. Nothing was rewritten, no column changed,
and a page that never uses an Area keeps exactly the markup it had - the Area
only exists in the DOM when one is stored.
</Callout>
## When an Area is the wrong answer [#when-an-area-is-the-wrong-answer]
| You want | Use |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| Two blocks side by side | An **Area**. This is the one. |
| One block that looks different | A [**variant**](/docs/dev/widgets/block-variants). |
| A different arrangement per breakpoint | Neither, yet. One arrangement, rendered responsively. |
| A page-wide template - sidebar, footer, header | Several [**zones**](/docs/dev/widgets/content-zones) in your own page markup. An Area arranges content inside a zone; it is not a page layout. |
| Columns inside columns | Nothing. See above, twice. |
# Rendering Widgets (/docs/dev/widgets/rendering)
## The renderer [#the-renderer]
```tsx title="src/routes/_main/pages.$slug.tsx"
import { ContentRenderer } from '@vitnode/core/widgets/renderer'
import { blocksRegistry } from '@/blocks.gen'
export const PageScreen = ({ page }: { page: PageContent }) => (
<main className="mx-auto flex w-full max-w-3xl flex-col gap-8 px-4 py-10">
<h1 className="text-3xl font-semibold text-balance">{page.title}</h1>
<ContentRenderer blocks={page.content} registry={blocksRegistry} />
</main>
)
```
For each stored instance it resolves the definition in the registry and renders the component with the instance's own id as the React key - so re-ordering a page moves DOM nodes instead of re-mounting them.
| Prop | Default | |
| :--------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blocks` | — | The stored list. `null`, `undefined` and `[]` all render nothing. |
| `registry` | the process default | The registry to resolve against. Passing it is the normal way. |
| `validate` | `"development"` | `"never"`, `"development"` or `"always"`. It governs the allowlist and the developer warnings, never the structural check - see below. |
| `fallback` | a development-only notice | What to render for a block that cannot be resolved or fails a check. |
| `allowed` | none | An allowlist to hold the instances to, under the same `validate` gate. [Content Zones](/docs/dev/widgets/content-zones#restricting-what-may-go-in-a-zone) pass theirs here. |
## Where the registry comes from [#where-the-registry-comes-from]
Pass it. `blocksRegistry` is exported from the generated `src/blocks.gen.ts`, and handing it to the renderer is explicit, testable, and works when one process serves more than one application.
<Callout title="Import blocks.gen only where you render blocks" type="warn">
That file statically imports every configured plugin's block components, so
anything that reaches it carries all of them. Import it from the route or page
that renders blocks - never from `router.tsx`, a root layout, or any other
module the whole application loads. A test asserts the application's root
router cannot reach it.
</Callout>
Evaluating `src/blocks.gen.ts` also installs that registry as the process default, so a renderer with no `registry` prop finds one. Treat that as a convenience for a renderer deep inside a tree that cannot be handed one, not as setup: it only works if something already imported the file on that route.
The API does not rely on it. It builds its own registry when it boots, from the same plugins' `blocks`, so write-time validation is never waiting on a front end to evaluate a module. With no registry at all, `ContentRenderer` throws a `BlockRegistryMissingError` naming both ways out.
`setDefaultBlockRegistry` returns the function that undoes it, so a test - or a second application - can install one without leaking it:
```ts
const restore = setDefaultBlockRegistry(registry)
try {
// ...
} finally {
restore()
}
```
## Validation [#validation]
Block data is validated **once, on write**. Every create and update runs each instance through its block's schema before the row is written, applying defaults and rejecting anything the fields refuse. What is in the column has therefore already crossed a trusted boundary.
So the renderer never repeats that parse. A full Zod parse per block per render is real work on the hot path, and re-running a check the write boundary already made buys nothing.
What it does run, on every render and in every mode, is far cheaper: before a block's component is called, the renderer compares the stored object against the block's fields. Stored data and a block definition drift apart - a field is renamed, a plugin ships a new version, a row is edited by hand - and a component written for today's fields is handed yesterday's object. `data.headline.toUpperCase()` on an object that has no `headline` is a crashed public page, so this one check is not something a mode can switch off.
The check is **structural, not a schema parse**: it reports a field the block no longer declares, a required field that is gone, a `null` in a field that is not nullable, a value of the wrong kind, and a group whose shape no longer matches. It deliberately does not police `minLength`, `max` or enum membership - those are the write boundary's job, and a too-long string is not a reason to blank a section of a live page.
That is what catches the cases where stored data and a block definition have drifted apart:
- a field renamed or made required after records were written
- a row edited by hand in the database
- content imported around the API
None of them can take a page down: the instance is skipped, its component is never called, and everything else renders.
`validate` decides what happens around that check - the allowlist a zone passes in, and what a developer is told:
| `validate` | What happens |
| :-------------------------- | :------------------------------------------------------------- |
| `"never"` | The structural check, and no allowlist. |
| `"development"` _(default)_ | The structural check, plus the allowlist in development. |
| `"always"` | The structural check, plus the allowlist in every environment. |
`validate="never"` is not a way to render data that no longer matches its block. There isn't one, and that is the point - it says "hold nothing to an allowlist", on a page that already trusts what it renders.
Set `validate="always"` on a page rendering block data the API never placed - a live import, a third-party feed - so a zone's allowlist is enforced there as well. It costs a `Map` lookup per block, not a schema parse.
Warnings follow a separate rule, and it is not this one: **nothing is ever logged in production**, whatever `validate` says, because a visitor's console is not a place to report a developer's problem. In development, a block that is not registered, one stored with a variant it does not declare, and an area stored somewhere an area cannot go each warn regardless of `validate` - they say a page is broken, not that a check was asked for. `validate` gates only the allowlist refusal and the drift warning, so `"never"` silences those two and nothing else.
<Callout title="The renderer never transforms">
Whatever is stored is what the component receives, in every mode. Validation
decides whether to render an instance; it never fills in defaults or coerces a
value, so a page cannot look different in development from how it looks in
production.
</Callout>
## When a block is unavailable [#when-a-block-is-unavailable]
Content outlives plugins. A page may reference `blog:latest-posts` long after the Blog plugin was disabled.
That never takes the page down, in any `validate` mode - resolving a block is a `Map` lookup, and a miss is handled the same way a failed check is.
| | Behaviour |
| :-------------- | :----------------------------------------------------------------------------------------------- |
| **Production** | Nothing is rendered in its place. A visitor sees a page with one section missing, not an error. |
| **Development** | A dashed notice naming the block and why it was skipped, plus one `console.warn` per block type. |
Pass `fallback` to decide for yourself:
```tsx
<ContentRenderer
blocks={page.content}
fallback={({ instance, reason }) =>
reason === 'unknown-type' ? (
<PluginMissingNotice type={instance.type} />
) : null
}
/>
```
## Performance [#performance]
A block is a normal React component and the renderer is a loop.
- **No request.** Definitions come from the configured plugins, not from the database. A page of hero + text + image + CTA is exactly as many requests as a page without blocks.
- **No client state.** `ContentRenderer` holds none, subscribes to nothing, and renders on the server like anything else.
- **No validation library.** `defineBlock` and `ContentRenderer` do not reach Zod; the schema machinery lives in the write path. Bundling core's three blocks plus a plugin's, the registry and the renderer comes to about 25 kB of JavaScript with no third-party dependency in it at all.
- **No editor.** `@vitnode/core/widgets` is free of React entirely - it is the metadata surface the API validates with - and `@vitnode/core/widgets/renderer` reaches no drag-and-drop, AdminCP, form or query code. Tests assert the reachable module graph of each entry point, so future editor code cannot drift into the public bundle.
Keep your own block components in that spirit: a block that needs a chart library should `lazy()` it inside its own module, so a page that never places it never pays for it.
## Content Zones [#content-zones]
`ContentRenderer` is the loop. A [Content Zone](/docs/dev/widgets/content-zones) is that loop with a name on it:
```tsx
<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```
The name is what lets an editor put something in a particular place later, and what lets blocks sit around application UI that stays locked. A zone renders through this renderer, so everything on this page applies to it unchanged.
# Visual Edit Mode (/docs/dev/widgets/visual-editor)
**Visual Edit Mode** is the part where somebody finally gets to move things around.
A page renders its [content zones](/docs/dev/widgets/content-zones) the way it always has. An authorized moderator opens the user menu in the header, clicks **Edit widgets**, and the _same page_ - same layout, same fonts, same widgets - grows an outline around each zone, makes every widget draggable where it stands, and slides a sidebar that slides in down the right-hand side while the whole site moves over to make room for it. They rearrange, edit in the sidebar, save, and leave. Nobody was sent to a separate admin screen to guess what the result would look like.
```text
public page
↓ Edit widgets ← the user menu, on whatever page you are on
the same page, editable
↓ Save
public page again
```
{/* Image prompt: A VitNode settings page in Visual Edit Mode. The left three quarters is a normal-looking settings screen with a profile form in the middle; above and below it, two content zones are outlined with dashed borders and small corner labels reading "Before profile" and "After profile". One block is selected with a blue ring and shows a small floating pill of icon buttons (edit, delete) in its top-right corner. The right quarter is a full-height sidebar headed "Widgets" with a search field and a grouped list of draggable block cards under "CORE" and "EXAMPLE", and a footer with a small amber dot beside "Unsaved changes" and a Discard link, above an eye-icon Preview button, a Finish editing button and a wide blue Save button. Dark theme, 1600x900. */}
## `ContentZone` did not change [#contentzone-did-not-change]
This is the promise the [Content Zones](/docs/dev/widgets/content-zones) page made, and it is worth being specific about how it was kept.
```tsx
<ContentZone
id="before-profile"
blocks={content.beforeProfile}
registry={blocksRegistry}
/>
```
That is the zone in view mode. It is also the zone in edit mode. There is no `EditableContentZone`, no `editable` prop, no second component to migrate to - and nothing stored today needs rewriting.
Internally `ContentZone` asks one question before it renders: _is an edit runtime present?_ In view mode the answer is `null` and the Stage 2 path runs untouched, including the `return null` for an empty zone. In edit mode the runtime answers, and the zone hands it everything it knows - id, blocks, registry, allowlist, wrapper - and lets it render the editing surface instead.
A visitor pays one `useContext` that answers `null`. That is the entire cost of a feature they will never see.
## Turning it on [#turning-it-on]
There are two ways to turn on visual editing, depending on how your page manages layouts.
### 1. High-level: `<EditablePage>` (Recommended) [#1-high-level-editablepage-recommended]
For pages that declare their zones with `defineEditablePage`, wrap your zones in `<EditablePage>` from `@vitnode/core/widgets/page`. It automatically resolves zone data, handles defaults, rebases canonical server responses, and mounts the editor runtime when edit mode is active.
```tsx title="plugins/example/src/pages/zones-page.tsx"
import { EditablePage } from '@vitnode/core/widgets/page'
import { ContentZone } from '@vitnode/core/widgets/zone'
import { createContentEditorAdapter } from '@vitnode/core/content/editor'
const SettingsPage = ({ canEdit, layout, search }: SettingsPageProps) => {
const adapter = useMemo(
() =>
createContentEditorAdapter({
page: settingsPage,
save: async (payload) => {
await savePageLayout(payload)
},
}),
[],
)
return (
// [!code ++:4]
<EditablePage
adapter={adapter}
canEdit={canEdit}
layout={layout}
openEditing={search.edit === true}
page={settingsPage}
>
<ContentZone id="before-profile" />
<ProfileForm />
<ContentZone id="after-profile" />
</EditablePage>
)
}
```
No button and no `editing` state: `<EditablePage>` tells the site shell that an editable page this visitor may edit is on screen, and the shell puts **Edit widgets** in the user menu. `openEditing` is only for arriving with edit mode already asked for, which is what a `?edit=true` link does.
See [Editable Pages](/docs/dev/widgets/editable-pages) for the full breakdown of `defineEditablePage`, defaults, and zone permissions.
### 2. Low-level: `<ContentEditorRuntime>` [#2-low-level-contenteditorruntime]
For custom hosts that manage their own raw zone persistence and do not declare an editable page, wrap your zones in `ContentEditorRuntime` from `@vitnode/core/widgets/edit`:
```tsx
import { ContentEditorRuntime } from '@vitnode/core/widgets/edit'
;<ContentEditorRuntime
adapter={adapter}
enabled={editing}
onExit={() => {
setEditing(false)
}}
>
<ContentZone id="before-profile" blocks={content.beforeProfile} />
<ProfileForm />
<ContentZone id="after-profile" blocks={content.afterProfile} />
</ContentEditorRuntime>
```
This one takes `enabled` from you, so a custom host that is not an editable page owns edit mode itself - and has to draw its own way in, because the user menu only offers one for a declared page.
| Prop | | |
| :--------- | :------- | :---------------------------------------------------------------------------- |
| `enabled` | required | `false` renders the children and nothing else. `true` loads the editor. |
| `children` | required | The page. Every `ContentZone` inside it becomes editable. |
| `adapter` | optional | Where **Save** sends its payload. Without one, Save says so and does nothing. |
| `onExit` | optional | Called by **Finish editing**, after the unsaved-changes prompt. |
### Who gets the button, and where it is [#who-gets-the-button-and-where-it-is]
The entry lives in **the user menu in the site header**, next to My Profile and Settings. That is one place for a site-wide action, it is on every page, and it means a page that happens to be editable does not have to find a corner of its own header to put a button in - which is how three pages end up with it in three different places.
It draws itself from what the page publishes, so there is nothing to render and nothing to wire:
```text
<EditablePage canEdit …> → "this page is editable, and this visitor may"
site shell → Edit widgets in the user menu
→ the room the sidebar needs, from the whole page
```
`canEdit` is still **yours**. VitNode does not decide who may edit a page, because VitNode does not know what your pages are - a plugin's settings screen, a marketing page and a user profile have three different answers. On editable pages it is usually checked against the moderator permission the page declares (e.g. `widgets: ["can_edit"]`); pass `false` and the entry is not in the menu, the runtime is not mounted, and the editor chunk is not requested.
<Callout title="A hidden button has never stopped anybody" type="warn">
`/example/zones` reads the visitor's effective moderator permissions in its
loader and only then says `canEdit`. That is a *signal*, not the boundary: the
save endpoint behind the adapter asserts the same permission again and answers
`403` without it. A URL like `?edit=true` is the same kind of thing - it may
*request* edit mode, and it must never grant it. See [Editable
Pages](/docs/dev/widgets/editable-pages#can-i-edit-this).
</Callout>
## The lazy-loading guarantee [#the-lazy-loading-guarantee]
The editor is not small. Drag and drop, a block catalogue, a form runtime and a properties panel add up, and every one of them is useless to a visitor reading the page.
So **none of it is in the public page's bundle**. `@vitnode/core/widgets/edit` reaches React and nothing else; the only path from it to the editor is a dynamic `import()` behind `React.lazy`:
```tsx title="packages/vitnode/src/blocks/edit.tsx"
const EditorRoot = lazy(async () => await import('../editor/root'))
```
The chunk is requested when `enabled` first flips to `true` - that is, on the first click of **Edit widgets** - and never before.
```text
view mode blocks/zone.tsx → react
edit seam blocks/edit.tsx → react
first click editor/root.tsx → @dnd-kit, @tanstack/react-form, sonner, …
```
This is enforced, not merely intended. `packages/vitnode/src/editor/boundaries.test.ts` walks the real module graph and fails the build if the arrow ever points the wrong way:
- `blocks/zone.tsx` and `blocks/edit.tsx` **eagerly** reach `react` and nothing else;
- neither reaches `@dnd-kit/*`, `@tanstack/react-form`, `sonner`, `@tanstack/react-query`, `@tanstack/react-router`, `cmdk` or `zod`;
- `blocks/edit.tsx` **does** reach `@dnd-kit/core` once dynamic imports are followed, which is the proof that the only path is a dynamic one;
- nothing under `src/editor/**` reaches `views/admin/**`, or any database or server package;
- the sidebar is the one panel `editor/root.tsx` mounts, `editor/toolbar/` and `editor/block-picker/dialog.tsx` do not exist, and the editor no longer reaches `cmdk` at all - a revert fails the test instead of quietly shipping a modal again.
Turning that static `import` back on would be a one-line change and a silently 200 kB heavier home page. The test is the thing that notices.
## Turning it on does not restart your page [#turning-it-on-does-not-restart-your-page]
Lazy loading is easy to get right in a way that quietly breaks the page underneath. The obvious shape is this one:
```tsx
if (!enabled) return <>{children}</>
return (
<Suspense fallback={children}>
<EditorRoot>{children}</EditorRoot>
</Suspense>
)
```
It looks like a toggle. It is a **remount**. React reconciles by position in the element tree, so the moment a wrapper appears above `children`, everything in them is torn down and built again: `useState` resets, uncontrolled inputs empty themselves, focus is lost, a playing video restarts. Reusing the identical `children` element object does not help - position is what counts, and `<Suspense>` alone is enough to do it.
That is not acceptable on a page somebody is already using. So the runtime is built the other way round:
```text
site shell <div> ← above the header, padding is the only thing on it
ContentEditorRuntime ← public, always mounted
ContentEditContext.Provider ← always mounted, value is null in view mode
{children} ← one fixed slot, never moves
{enabled && <Suspense><EditorRoot/></Suspense>} ← a SIBLING
```
The editor is never an ancestor of your page. Turning edit mode on changes one context value and mounts a sibling; nothing above `children` changes, so nothing in them remounts.
The site shell above it all is a plain block `<div>` at the document root, and it stays one whether or not anybody is editing. That is deliberate rather than incidental: **padding only transitions between two values of an element that already has a box**, so a wrapper that appeared when editing started - or went back to `display: contents` when it ended - would snap to its new width instead of gliding there, in whichever direction it was going. It carries the transition and the two custom properties and nothing else.
### Then how do zones become editable? [#then-how-do-zones-become-editable]
`@dnd-kit` needs its `DndContext` above every droppable, and the zones are inside your page. Since the editor may not wrap your page, the zones come **out** to it instead.
In edit mode `ContentZone` renders a bare host element - your `as`, your `className`, the usual `data-vitnode-zone` attributes - and registers that DOM node with the runtime. The editor, which owns the `DndContext`, renders the real `EditableZone` into each registered node with `createPortal`:
```text
page editor
──── ──────
<aside ref> ← createPortal(<EditableZone/>, node)
inside <DndContext>, inside the editor's own providers
```
The markup lands where you put the zone; the React tree it belongs to is the editor's. One consequence is worth knowing: a block rendered in a zone reads React context from the **editor**, not from inside your page subtree. Context from your app root reaches it as usual - the router, the theme, the intl provider - but a provider you render _between_ your page and a `ContentZone` will not. No built-in or plugin block relies on that today, and if yours does, pass the value through the block's own data instead.
## The interaction model [#the-interaction-model]
A block is a real component. It contains links, buttons, forms, embedded video - things that do something when you click them. In edit mode, clicking one has to mean _select this block_, not _follow this link_.
VitNode solves that with three layers on every block, and one escape hatch:
| | |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| **`inert` container** | The block's own component renders inside an `inert` element, so nothing in it can be clicked, focused or tabbed to. |
| **Transparent overlay** | A full-size `<button>` above it. Clicking anywhere on the block selects it; screen readers get _"Select the Hero block"_. |
| **Floating actions** | Edit and Delete appear on hover, on focus, and while selected. There is no move button: the widget itself is the handle. |
| **Preview toggle** | Removes all three. The block becomes the real thing again, exactly as a visitor sees it. |
The alternative - asking every block author to make their component "editor-aware" - was never on the table. A block's component is public rendering code, it is written by plugin authors who have never read the editor's source, and it must not grow a second mode. `inert` does the whole job in one attribute, from the outside.
Preview is there because the illusion has to break sometimes. Does the video play? Does the accordion open? Is the call-to-action button the right size once it is actually hoverable? Toggle Preview, use the page like a visitor, toggle back.
## Empty zones become visible [#empty-zones-become-visible]
An empty zone [renders nothing at all](/docs/dev/widgets/content-zones#empty-zones) in view mode - no wrapper, no placeholder, no gap. That is deliberate, and it stays true.
In edit mode the same zone renders a dashed drop target with its name and an **Add block** button, because now somebody _is_ looking for a place to put something.
That name is the zone's id made readable, so nobody has to decode your naming scheme: hyphens become spaces, the first letter is capitalised, and each `:` scope becomes its own part.
| Zone id | Shown as |
| :------------------------ | :-------------------------- |
| `header` | Header |
| `before-profile` | Before profile |
| `settings:before-profile` | Settings · Before profile |
The same name is used in the sidebar (_Adding to Before profile_) and in what screen readers announce during a drag. The id itself is untouched - it is still what gets stored and what you write in code.
```text
view mode before-footer (nothing)
edit mode before-footer ┌ dashed box ┐
│ + Add block │
└────────────┘
```
Finish editing and it disappears again. A page with eight placement points and two filled ones costs two in public, and shows all eight to the person arranging them.
## The editing sidebar [#the-editing-sidebar]
Everything the editor asks of you lives in one panel down the right-hand side: the block catalogue, the properties of whatever is selected, and the **Preview** / **Discard** / **Save** / **Finish editing** row at the bottom. There is no modal to open and dismiss, and no second panel competing for the same corner of the screen.
The **whole site** is padded, not covered - the header, the page and the footer all move over together, the way the AdminCP dashboard moves over for its widget panel. So the sidebar never sits on top of anything: not the zone you are arranging, and not the user menu you opened it from. Below `md` the same sidebar becomes a bottom sheet, because 360px of a phone is not a sidebar, and the padding moves underneath the site instead.
Both halves of that take 200ms and start on the same frame, in both directions: the page's edge and the sidebar's edge are the same number on every frame of it. **Finish editing** plays the whole thing backwards - the editing chrome goes at once, so the page is public again immediately, and the editor stays mounted just long enough for the sidebar to slide back off screen while the padding shrinks under it.
Which frame that is comes from the **editor**, not from the seam that loads it. On a first open the editor chunk and the sidebar's own messages take a moment to arrive, and a shell that started widening the moment edit mode was _requested_ would slide the page over to make room for a sidebar that had not loaded yet - the page moving first and the panel catching up, once, on the first click only. So `editor/root.tsx` is what asks the shell for its room, and it cannot ask before it exists. Nothing moves until the sidebar is ready; then everything moves together.
### One panel, three modes [#one-panel-three-modes]
| | |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Widgets** | A search field, a **Layout** section holding the [Area](/docs/dev/widgets/layout-areas) entry, and every block this location accepts, grouped by the namespace that provides it. |
| **Properties** | The selected block's name and type in the header, next to Duplicate and Delete, then its [variant](/docs/dev/widgets/block-variants) picker and its fields. |
| **Area properties** | Duplicate, Ungroup and Delete area in the header, then the Area's **Layout** (Columns, Alignment, Distribution) and **Spacing** (Gap and the space around it). |
Selecting a block switches to **Properties**; selecting an Area switches to **Area properties**. Each panel keeps its header pinned while its content scrolls, so the actions never scroll out of reach. The **←** button at the top (_Back to widgets_) switches back from either _and_ clears the selection, so the page stops ringing something you are no longer editing. Deleting the selection does the same thing on its own.
The footer keeps the state of the page in one glance: a coloured dot and a word (**Saved**, **Unsaved changes**, **Saving…**, **Save failed**), **Discard changes** beside it, and underneath **Preview**, **Finish editing** and **Save** - the only blue button in the panel, lit up only when there is something to save.
In **Preview** the sidebar collapses to a slim bar holding **Back to editing** and **Finish editing**. It never collapses to nothing - a preview you cannot leave is a trap - and the editor stays mounted behind it with every unsaved change intact.
## Two ways to add a block [#two-ways-to-add-a-block]
A catalogue entry is a drag source _and_ a button, because those answer two different questions.
| | |
| :----------- | :------------------------------------------------------------------------------------------------------------------------------- |
| **Drag it** | You care where it goes. An insertion line shows the exact position while you are still holding it. |
| **Click it** | You do not, or you already said where. It goes to the targeted zone - or, with nothing targeted, the first zone that accepts it. |
**Add widget** on a zone is what sets that target: the sidebar switches to **Widgets**, its header shows _Adding to Sidebar_, and the zone stays lit until a block lands or you clear it. **Add widget** on an Area targets the Area instead, and the header says so - _Adding to an area in After profile_ - because naming the zone alone would be a lie about where the block is going.
The catalogue's own **Layout** section sits above the plugin groups and holds one entry: **Area**. It works exactly like a block entry: click it and an empty Area drops into the target, or drag it and it lands where the insertion line says. An Area is not a registered block and has no type, so what travels with the drag is the layout itself rather than a block id - and dropping one onto an Area is refused, because [an Area cannot hold another Area](/docs/dev/widgets/layout-areas#areas-cannot-contain-areas). While an Area is the insertion target the Layout section disappears for the same reason.
Either gesture inserts the block, selects it and opens **Properties** in one step, so the next thing you do is fill it in. The new block fades in where it landed and scrolls into view if it landed off screen - handy when a click sent it to the bottom of a long page.
### How a drag feels [#how-a-drag-feels]
A drag is meant to feel like picking something up, not like watching a diagram.
| | |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Picking up** | The card lifts a touch (2% larger, deeper shadow). The place it came from turns into a dashed slot, so you can see the gap you are about to leave. |
| **Moving** | Every zone that accepts what you hold lights up softly; the one under the pointer lights up fully. Zones that refuse it dim instead of shouting in red. |
| **Dropping** | The card settles into its new slot in 200ms, shrinking back to its real size on the way. Drop a catalogue card nowhere useful and it glides back home. |
| **Reduced motion** | With _reduce motion_ switched on in the operating system, all of the above happens instantly - same feedback, no movement. |
### The catalogue follows the target [#the-catalogue-follows-the-target]
`allowedBlocks` on a zone is what the catalogue offers. Not everything installed - everything **allowed** in that location.
```tsx
<ContentZone
id="sidebar"
allowedBlocks={['core:text']}
blocks={content.sidebar}
/>
```
Target that sidebar and the catalogue shows exactly one block. Clear the target and it shows the union of what the page's zones accept, because now any of them could be the destination. Same `allowedBlocks` value, same format as a [`blocks()` field's `allowed`](/docs/dev/widgets/blocks-field#restricting-what-may-go-in), now doing a third job.
A zone that allows nothing the installation provides says so, rather than offering an empty list.
<Callout title="The catalogue is not the write boundary">
The allowlist on a zone describes a location. The one on the `blocks()` field
**enforces**, on every create and update. The catalogue filtering by the
zone's copy is a courtesy to the person editing - the field is what refuses a
block that should never have been stored.
</Callout>
## Drag and drop [#drag-and-drop]
Grab a block anywhere on it, or a catalogue entry anywhere on its card, and move it. A click without moving still just selects the block, and an Area is dragged by its own frame - its header or the space around its columns - so grabbing a widget inside an Area moves that widget, not the Area. On a touchscreen a swipe keeps scrolling the page; press and hold to pick a widget up.
- **Reorder** inside a zone: drop it above or below a sibling.
- **Move across zones**: drop it into another zone, or onto one of that zone's blocks to land at that position.
- **Into an empty zone**: drop it anywhere on the dashed placeholder.
Identity is the block instance id throughout - never an array index - so a block that crosses a zone keeps being the same block, with the same data, and the properties panel does not blink.
### Before or after, never into a block [#before-or-after-never-into-a-block]
Dropping onto a block inserts **before** it or **after** it, decided by which half of it the pointer is over. That blue line is the answer, shown before you let go.
Nothing ever lands _inside a block_. Dropping **into** something is the Area's gesture: drag a block onto an [Area](/docs/dev/widgets/layout-areas) and it becomes one of that Area's children, at the position the line shows. Drag a child back out and the Area keeps the rest. An Area dropped onto another Area is refused out loud - _An area cannot hold another area_ - rather than silently landing beside it.
### The keyboard does all of it too [#the-keyboard-does-all-of-it-too]
Drag and drop that needs a mouse is drag and drop half the people cannot use, so every block is a real button and every gesture has a key.
| Key | What it does |
| :------------------------ | :-------------------------------------------------------------------- |
| <kbd>Tab</kbd> | Reaches each block (and each Area's header), like any other button. |
| <kbd>Enter</kbd> | Selects the block and opens its properties. |
| <kbd>Space</kbd> | Picks the block up - and, the second time, drops it. |
| <kbd>↑</kbd> <kbd>↓</kbd> | Moves it through the positions of its zone and on into the next zone. |
| <kbd>Esc</kbd> | Puts it back where it started. |
The blue insertion line follows a keyboard drag exactly as it follows a pointer, because both are the same line: the editor asks its drop resolver where this block _would_ land right now and draws the answer. Nothing is measured twice, so the line cannot disagree with the drop - and when the answer is "nowhere" (the zone refuses the block, or it already sits in that spot) there is no line, which is the honest thing to draw.
Screen readers get the same story in words. The editor localises dnd-kit's announcements through `core.editor.dnd.*`, so picking a block up, passing over a zone, being refused by one, and landing all read out with the **block's name and the zone's id** rather than the instance ids dnd-kit would otherwise spell aloud.
```text
Picked up Callout.
Callout is over the after-profile zone, position 1 of 2.
The sidebar zone does not accept Callout.
Callout was dropped into the after-profile zone, position 1 of 2.
```
### An incompatible target refuses [#an-incompatible-target-refuses]
Drag an `example:callout` toward a zone that allows `core:text` only and the zone turns red and says it does not accept what you are dragging. Let go and nothing happens: a block stays where it was, a catalogue entry is simply not inserted.
The refusal is computed from the same `isBlockAllowed` the field and the catalogue use. One allowlist format, one function that evaluates it, three places that ask.
## The properties panel [#the-properties-panel]
Select a block and its fields appear in the sidebar: text, textarea, number, boolean, enum, date-time, and groups of those - the [field kinds a block may hold](/docs/dev/widgets/defining-a-block#which-fields-a-block-may-hold), as declared by `defineBlock`. The panel builds itself from the block definition, so a block that adds a field gets a control for it with no editor change at all.
Typing updates the block on the page **as you type**. There is no Apply button, and no preview pane to compare against, because the page _is_ the preview.
A block that declares more than one [variant](/docs/dev/widgets/block-variants) gets a **Variant** picker above those fields. Picking one is a separate action from editing content: it keeps the instance's id, leaves `data` untouched, and does not reset a field you were halfway through. A block with one variant, or none, shows no picker - there is nothing to decide. A stored variant the block no longer offers is named in the panel, with the declared ones still offered beside it.
### Area properties [#area-properties]
Select an [Area](/docs/dev/widgets/layout-areas) rather than one of its children and the same sidebar shows its layout in two groups - **Layout** (**Columns** as a one-click 1–4 switch, **Alignment**, **Distribution**) and **Spacing** (**Gap** and the space around the Area) - and re-lays the page out as you pick them. **Duplicate area**, **Ungroup** and **Delete area** sit in the panel's header.
Ungroup and Delete are deliberately different buttons. Ungroup removes the container and leaves the blocks where the Area was; Delete takes them with it, and asks first, offering _Ungroup, keep blocks_ in the same dialog. An Area holding nothing is deleted without the interrogation, because there is nothing to lose.
A block whose stored data does not match what its definition declares is not editable here - it is flagged on the page instead. Editing it would mean guessing which half is wrong, and guessing is how content gets quietly destroyed.
## Content the editor cannot read [#content-the-editor-cannot-read]
A zone is handed whatever is stored in it, and storage is older than any editor. A field can hold a value from a migration that never finished, from a plugin that wrote its own shape, or from a hand-edited row. The editor has to have an answer for that, and the answer is **never delete it**.
Every value a zone mounts with is sorted into one of two piles:
| | |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **A block with bad data** | `{ id, type, data }` is intact and `type` is registered, but `data` does not match the fields. It stays a block: selectable, movable, deletable. |
| **Something that is not a block** | No usable `id`, no `type`, an id already used **by an earlier block in the same zone**, or not an object at all. Nothing can be inferred from it, so nothing pretends to. |
The first pile keeps working exactly as before - the block renders an [`InvalidBlock`](#the-properties-panel) placeholder in place of its component, and its own shell stays draggable and keeps its delete button. Its data is bad; its identity is not.
The second pile never becomes a content node. It is kept beside them, not among them:
```ts
interface EditorZoneState {
nodes: readonly ContentNode[]
invalid: readonly { index: number; value: unknown }[]
// …
}
```
A `ContentNode` is a block instance or an [Area](/docs/dev/widgets/layout-areas). An Area whose stored `layout` is not one the editor recognises, or which holds an Area of its own, lands in the second pile with everything else: shown as-is, never rewritten.
Nothing in the editor - no reducer action, no drop resolver, no block component - is ever handed one of those values. The zone shows them at the top, prints what each one looks like, and offers exactly one action per entry: **Remove invalid entry**.
### One id per zone, not one id per page [#one-id-per-zone-not-one-id-per-page]
An instance id has to be unique **within its zone**, and only within its zone. Two blocks sharing an id in one zone are indistinguishable there, so the second one goes in the opaque pile above. Two blocks sharing an id in two _different_ zones are perfectly valid - the Content Engine validates a blocks field on its own, so nothing has ever promised otherwise, and a zone copied from one field into another would trip over any rule that did.
The editor therefore never identifies a block by its id alone. Selection, updates, deletion, duplication, moves and drag-and-drop all carry the zone:
```ts
interface EditorBlockRef {
blockId: string
zoneId: string
}
```
Drag-and-drop ids are built the same way - `blockDraggableId({ zoneId, blockId })` percent-encodes both halves, so an id survives a round trip whatever characters it contains - and the drag payload carries the ref structurally rather than being parsed back out of a string. Selecting the copy of `X` in the sidebar zone can never edit the copy of `X` above the profile form.
Zone ids run the other way: a zone id is a _place_, so one page may only have one of each. Two `<ContentZone>`s claiming the same id while the editor is open is a [developer error](/docs/dev/widgets/content-zones#one-id-one-place-on-the-page), not a merge.
### Saving is blocked until you decide [#saving-is-blocked-until-you-decide]
While a zone still holds one, the whole editor refuses to save. The **Save** button is disabled, the sidebar footer explains why, and the adapter is not called even from **Save and finish**:
> This zone contains invalid or legacy content that the Visual Editor cannot safely save. Resolve or explicitly remove the invalid content before saving.
That is deliberate, and it is the whole point of the pile. The save payload is a **replacement** array per zone - the editor hands over the blocks it understands, and the API stores exactly that. If a value the editor could not read were quietly left out of that array, editing an unrelated block in the same zone would delete it. Storing `[A, malformed, B]` and saving after a change to `A` would write `[A2, B]`, and nobody would ever be told.
So removal is a decision you make, one entry at a time, and it is an edit like any other: **Discard** brings the entries back, and the page is dirty until you save.
## Zones that leave the page [#zones-that-leave-the-page]
A page is allowed to change its mind. A tab, a feature flag, a route transition - any of them can stop rendering a `ContentZone` while edit mode is still on, and the editor has to have an answer that is not "persist it anyway".
When a zone's outlet unmounts it is **removed from the document**: out of `zones`, out of `order`, and therefore out of the next save payload entirely. A stale zone can never be written back. If it owned the selection, the selection clears and the sidebar returns to **Widgets**; if it was the target of **Add widget**, that target clears too.
What happens to unsaved work in it depends on whether there was any:
| | |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **No unsaved changes** | It is dropped silently. There was nothing to lose. |
| **Unsaved changes** | It is still dropped - the zone is gone, there is nowhere to put them back - but the sidebar footer names it, so it is never _quiet_. |
That is the rule: an unmounted zone is out of the editable document, and losing work to it is reported rather than blocked. Blocking **Save** would trap you on a page whose zone no longer exists, and keeping the zone would mean writing content the page has stopped showing. Bring the zone back and it re-mounts from whatever the page hands it, with a fresh baseline.
What the _host_ does with the gap is the host's call, and it matters. The save payload only carries zones the editor currently holds, so a save must write **only what it names** - never a whole field set composed on top of a fallback, which is how a zone that is off the page gets reset to something nobody chose. [Editable Pages](/docs/dev/widgets/editable-pages#the-two-routes) does exactly that: a zone the payload does not mention is not written, because each zone is its own row.
## Saving is the host's job [#saving-is-the-hosts-job]
The editor never fetches. Not once. The only way anything leaves it is the adapter you passed:
```ts
type VisualEditorSnapshot = Readonly<Record<string, readonly ContentNode[]>>
interface VisualEditorSaveInput {
changedZoneIds: readonly string[]
expectedZones: VisualEditorSnapshot
zones: VisualEditorSnapshot
}
interface VisualEditorSaveResult {
revision?: string
zones?: VisualEditorSnapshot
}
interface VisualEditorAdapter {
save: (
input: VisualEditorSaveInput,
) => Promise<VisualEditorSaveResult | void> | VisualEditorSaveResult | void
}
```
`zones` holds every zone on the page keyed by its id; `changedZoneIds` names the ones that actually differ from what loaded; `expectedZones` holds, under the same keys, the **baseline** each zone started from - what was there before anybody dragged anything. Resolve and the editor marks itself clean and toasts. Throw or reject and it shows an error and keeps the changes, so nothing is lost to a failed request.
Send the baseline with the write and your API can answer the only question that matters when two people are arranging one page: _is the thing I am replacing still the thing I was given?_ Zones are independent, so two moderators editing different zones both succeed, while a write to a zone that moved underneath somebody is refused instead of silently winning. [Editable Pages](/docs/dev/widgets/editable-pages#two-moderators-one-page) does exactly that with a `409`, and the editor says so - _Somebody else saved this page first_ - while keeping every change you made.
The one rule the contract asks of you: **save what you were handed**. The editor rebases its idea of "unchanged" onto the snapshot it sent, not onto the state it is in when the promise resolves - so a word typed while the request was in flight is still unsaved afterwards, exactly as it should be.
`zones` is a **complete** picture of the page, not a patch: every zone the editor mounted is in it, emptied ones included. `changedZoneIds` names the ones that differ from what loaded - send those, and leave everything else alone at the other end. What you must not do is send a partial write and let the rest fall back to defaults.
<Callout title="You probably do not write this by hand">
If the page declares its zones - and it usually should -
`createContentEditorAdapter` builds this payload for you, from the same page
definition the server reads. See [Editable
Pages](/docs/dev/widgets/editable-pages). The rest of this section is the
contract underneath it, and what to honour if you are writing an adapter for
somewhere else.
</Callout>
```tsx
const adapter = useMemo<VisualEditorAdapter>(
() => ({
save: async ({ changedZoneIds, expectedZones, zones }) => {
await fetcher({
plugin: '@vitnode/example',
method: 'patch',
module: 'pages',
path: '/{id}/zones',
args: {
param: { id: page.id },
json: { changedZoneIds, expectedZones, zones },
},
})
},
}),
[page.id],
)
```
### Answer with what you stored [#answer-with-what-you-stored]
`save` may resolve with nothing, and the editor is happy either way - but it is better if it does not. What the client sent and what the server kept are not always the same thing: an API is allowed to reorder, normalise, drop or rewrite what it is given. If the editor rebases onto its own input, it goes clean against a version that never existed, and the next save pushes the stale copy back.
So return what you stored:
```tsx
const [zones, setZones] = useState(loaderData.zones)
const save = async (input: VisualEditorSaveInput) => {
const payload = await writeChangedZones(input)
setZones((current) => ({ ...current, ...payload.zones }))
return { zones: payload.zones }
}
```
The editor then adopts that snapshot as its baseline **and** as what you are looking at - unless you edited during the request, in which case your edit stays and the zone remains dirty against the new baseline. Both halves matter: the first stops the stale re-send, the second is the [save race](#save-stays-finish-editing-leaves) rule that has always applied.
Updating the page's own state does the other half of the job: **Finish editing** shows the saved page immediately, with no reload, because the page underneath is already the new one.
This belongs to the page, not to the editor. The editor owns no layout state and never will: it is handed blocks, it hands back blocks, and the content's owner decides what is true.
### Content that changes underneath the editor [#content-that-changes-underneath-the-editor]
The same problem arrives from the other direction. A router invalidation, a refetch, or the `setZones` above all re-render your page with different `blocks`, and a zone that is already mounted has to decide what to do with them.
The rule is the one you would write yourself:
| | |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Zone is clean** | The incoming content replaces both the working copy and the baseline. The zone adopts it and stays clean. A selection whose block is gone clears. |
| **Zone is dirty** | Nothing about its content moves. Local edits win until **Save** or **Discard** resolves them. Only the allowlist and registry still refresh. |
There is deliberately no merge. Two block arrays cannot be reconciled without inventing an answer, and inventing one is how an editor loses a paragraph somebody typed.
### A failed load is not an empty page [#a-failed-load-is-not-an-empty-page]
Loading has a trap that is easy to walk into and expensive to walk out of. A route answers three different "there is nothing here" shapes, and they mean three different things:
| | |
| :-------------------------- | :--------------------------------------------------------------------------------------------- |
| **200, an empty zone** | Nothing is in that zone. Editing and **Save** are fine. |
| **200, nothing stored yet** | The page has never been rearranged, so its declared defaults come back with `updatedAt: null`. |
| **Anything non-2xx** | What is stored is **unknown** - an auth failure, a database error, a dropped connection. |
Treating the third as the first is how a page overwrites content nobody meant to touch: the load fails, something plausible renders as if it had been read, somebody tidies a heading, presses **Save**, and the real stored layout is gone. The editor cannot catch this, because by then it was handed a perfectly valid set of blocks.
So the playground loader refuses:
```ts
if (!stored.ok) {
throw new Error(`Reading this page's layout answered ${stored.status}…`)
}
```
The router's `defaultErrorComponent` takes it from there, and **Edit widgets** is never reached. The API holds the same line from the other side: a stored row that cannot be read throws rather than answering with an empty layout.
The second row is a _success_, and the distinction is the whole reason a page declares its defaults rather than inventing them at render time. Defaults that came from the declaration are content somebody shipped on purpose, so the first **Save** is entitled to replace them; defaults invented because a read failed are content nobody chose. [Editable Pages](/docs/dev/widgets/editable-pages#the-two-routes) has the longer version.
If throwing does not suit your route, return an explicit error state and disable editing on it. What you must not do is hand the editor a writable copy of something you did not actually read.
### Save stays, Finish editing leaves [#save-stays-finish-editing-leaves]
Two buttons, two different jobs, and it is worth being blunt about which is which.
| | |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| **Save** | Runs the adapter and **stays in edit mode**. The footer goes from _Unsaved changes_ to _Saved_ and you carry on arranging. |
| **Finish editing** | Leaves edit mode. With nothing unsaved it just leaves. |
| **Finish while dirty** | Asks first: **Save and finish** (saves, then leaves - and stays put if the save fails), **Leave without saving**, or **Keep editing**. |
Saving is not an exit, because the most common thing anybody does after saving is keep going. And leaving is not a save, because an editor that silently writes on the way out is an editor nobody trusts. **Discard** is the third option and the only one that throws work away - it puts every zone back to what loaded.
The same question is asked by the browser: navigate away with unsaved changes and the guard prompts before the page goes.
### Why there is no zones table [#why-there-is-no-zones-table]
The obvious alternative is a `core_content_zones` table that stores `(zoneId, blocks)` for every page in the installation, and a generic save endpoint that writes to it. It was not built, on purpose.
Block content already lives somewhere: in a [`blocks()` field](/docs/dev/widgets/blocks-field) on a content type, in a plugin's own settings row, in whatever column the page loads it from. A generic zones table would be a **second** home for the same data, and then two places to migrate, two permission models, two revision histories, and a stubborn class of bug where the page renders one copy and the editor saves the other.
The adapter is the alternative: the page that knew how to _load_ its zones is the page that knows how to _save_ them. It writes to its own column, through its own API, behind its own permission check.
What is generic is the _wiring_, not the storage. [Editable Pages](/docs/dev/widgets/editable-pages) is the one exception, and it earns it: a settings screen's zones belong to no record, so core keeps them in an internal table keyed by the page id - one row per page, holding only the zones somebody customised - and the page declares its zones instead of mapping them. A zone whose blocks _do_ live on a content type stays where it always lived, and the page that knew how to load it is still the page that knows how to save it.
## What the editor deliberately does not do [#what-the-editor-deliberately-does-not-do]
Being clear about the edges is more useful than a roadmap.
| | |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nested areas** | An [Area](/docs/dev/widgets/layout-areas) holds blocks, one level deep. No areas inside areas, and no block that contains a zone of its own. |
| **Drafts and revisions** | Save writes. There is no "unpublished version of this page" concept in the editor. |
| **Permission UI** | No roles screen. Who may edit is your page's answer, and the save route's; an [editable page](/docs/dev/widgets/editable-pages#can-i-edit-this) names the moderator permission it wants, but granting it is the ordinary staff screen's job. |
| **Layout administration** | No AdminCP section listing which pages have been rearranged, no reset-to-default, no export or import, no copying one page's layout onto another. [Deliberately left to a possible V2](/docs/dev/widgets/editable-pages#where-a-layout-is-stored) - the storage shape makes each of them a query on one table, but none is built. |
| **Live collaboration** | No shared cursors, no presence, no merging two people's edits to **one** zone. Different zones of one page do merge, and a stale write to the same zone is refused rather than applied - see [two moderators, one page](/docs/dev/widgets/editable-pages#two-moderators-one-page) - but nobody watches anybody else arrange anything in real time. |
| **File and relation fields** | The properties panel edits the [field kinds a block may hold](/docs/dev/widgets/defining-a-block#which-fields-a-block-may-hold). Blocks cannot hold uploads or references yet, so neither can the panel. |
| **Responsive breakpoint editing** | One arrangement, rendered responsively by the blocks themselves. No per-breakpoint layouts. |
| **Rich text** | A `text` or `textarea` field is a plain string, and it stays one. You type into it in the properties panel, and no block field holds bold, links or lists. Tiptap ships in this repository and is deliberately nowhere near a block. |
Everything in that table is a _later_ decision rather than a closed door - but none of it is built, and none of it is implied by the APIs above.
## Known limitations [#known-limitations]
The section above is about scope. This one is about rough edges in the part that _is_ built - the things you will notice, written down so you do not have to discover them.
**A pointer drag's spoken position lags the line it draws.** The insertion line updates continuously, but the screen-reader announcement is only refreshed when the block underneath the pointer changes - move from a block's top half to its bottom half and the line jumps, the sentence does not. That is deliberate: the alternative is announcing on every pixel of movement, which floods a live region until it is useless. Keyboard dragging is unaffected, because every arrow key changes the target.
**Locked application UI is not dimmed.** In edit mode the zones are outlined and labelled, and everything else on the page - your forms, your navigation, your buttons - looks exactly as it did. Nothing says "this part is not editable" except the absence of an outline.
Dimming it would mean fading the page and un-fading the zones, and a descendant cannot undo an ancestor's `opacity` or `filter`: those create a new compositing context that the zone inside it is stuck in. The only other route is selector-based - "dim everything that does not contain a zone" - which would have to make assumptions about a page's DOM that VitNode does not get to make, since the page is yours. So the editor emphasises the zones rather than de-emphasising the page, and a host that wants more can style `[data-vitnode-zone]` and its surroundings itself.
**Mobile is a bottom sheet, and only that.** Below `md` the sidebar becomes a sheet so it does not eat a phone screen. The page reserves room for it - `--editor-sheet-height` is padding on the canvas below `md` and the width of the sidebar above it, so the last zone always scrolls clear of the sheet and Preview takes both away - but nothing is _tuned_ for touch: a drag competes with page scrolling, and press-and-hold is the only way to tell a drag from a scroll. Arranging a page on a phone is possible. Enjoyable is a later stage.
**Blocks themselves do remount when you enter edit mode.** The page around them does not - that is the whole point of the [stable boundary](#turning-it-on-does-not-restart-your-page) - but a `ContentZone` genuinely swaps what it renders, from `ContentRenderer` output to the editor's portal, so each block component is built again. A block holding transient state of its own restarts with it: a playing video, an open accordion, a carousel's position, a `useState` counter. Content survives, because content lives in the block's data; ephemeral UI state does not. Closing that gap means hoisting block instances above the view/edit split, which is a bigger change than this stage is willing to make.
**A zone's blocks render in the editor's React tree, not your page's.** The consequence of the portal described [above](#then-how-do-zones-become-editable): context from your app root reaches a block as usual, context you provide between your page and a `ContentZone` does not. Nothing ships today that needs it, and the fix if you do is to put the value in the block's data.
**There is no end-to-end test harness.** The pure logic is covered by vitest - the reducer, the drop resolver and its insertion placement, zone drop states, the save input, the catalogue, and the module-graph boundary test that keeps the editor out of public bundles. What no test covers is a real browser actually dragging something, so the [manual checklist](#verifying-it-yourself) is the regression suite for gestures. `apps/web` has no test runner configured at all, which is why the checklist lives in this page rather than in a spec file.
## What used to be an extension point [#what-used-to-be-an-extension-point]
Two rows of that table were designed _around_ rather than merely skipped, and both have since landed. They are worth knowing as a pair, because they answer two halves of one question - and because keeping them apart is what stops a block definition turning into a settings screen.
### Presentation variants [#presentation-variants]
How a block looks, as opposed to what it says. A wide hero and a narrow hero used to be either two block types or a `width` field sitting in the middle of the copy. A [variant](/docs/dev/widgets/block-variants) pulls them apart:
```ts
interface BlockInstance {
data: BlockData
id: string
type: string
variant?: string
}
```
`variant` is optional, and nothing was migrated: an instance stored without one takes the block's `defaultVariant`, exactly as it rendered before. The workaround this replaces - a `variant`, `style` or `size` field declared on the block and stored in `data` - now has a real home, and moving one there is a data migration you write once and never again.
### Layout areas [#layout-areas]
How blocks sit next to each other, which was never one block's business. An [Area](/docs/dev/widgets/layout-areas) is a node in the zone's own list:
```ts
interface BlockAreaInstance {
children: readonly BlockInstance[]
id: string
kind: 'area'
layout: {
columns: 1 | 2 | 3 | 4
gap?: string
align?: string
justify?: string
}
}
```
It is not a block: no registry entry, no `allowedBlocks` entry, no fields of its own. It claims the drop-into gesture that was held back for exactly this, and it stops at one level - **an Area cannot contain an Area** - because nesting needs depth limits, cycle detection and an allowlist story that one level does not.
Three concerns, kept separate: **data** is what the block says, **variant** is how this instance presents it, and **an Area's layout** is how a container arranges its children. Mixing them is what turns a block definition into a settings screen.
## Verifying it yourself [#verifying-it-yourself]
`/example/zones` is the manual test page. It has four zones - two around a locked profile form, one narrower sidebar, one empty - blocks from two plugins, a block stored with a variant, an Area holding two blocks, and a second Area left empty. It draws no button of its own: **Edit widgets** is in the user menu, for anybody holding the page's own moderator permission. It is an [editable page](/docs/dev/widgets/editable-pages), so your changes survive a reload; before anybody saves, it renders the layout the page declares.
Sign in first: the action is gated on the moderator permission **Widgets → can edit** from the example plugin, and a root role holds it without being granted it.
<Steps>
<Step>
**Load the page**
```bash
pnpm dev
```
Open [http://localhost:3000/example/zones](http://localhost:3000/example/zones) with DevTools → Network open, filtered to **JS**.
</Step>
<Step>
**Confirm no editor chunk was loaded**
Reload and filter the request list to `/src/editor/`. **Nothing.** Not one editor module is requested for a page nobody is editing.
<Callout title="One dev-server caveat" type="warn">
In this repository you will also see `@dnd-kit` on *every* route, `/`
included. Those come from the AdminCP dashboard grid, which the development
module graph reaches whatever page you open - not from the zones. The honest
measurement is the production build [at the end of this
page](#against-a-production-build).
</Callout>
</Step>
<Step>
**Open the user menu and click Edit widgets**
It is in the avatar menu in the header, under your name - not on the page. Walk to `/discover` first and look again: it is gone, because no editable page is on screen there.
| | Expected |
| :--------- | :---------------------------------------------------------------------------------- |
| Network | Exactly one new chunk, on this click and not before. |
| Zones | Dashed outlines with the zone id in the corner. |
| Layout | Nothing jumped: the whole site slid over while the sidebar slid in. |
| Page state | The profile form still holds what you typed, and the counter still holds its count. |
Click **Finish editing**, then **Edit widgets** again: the second time, **no** request is made. The chunk is already in memory.
</Step>
<Step>
**The sidebar appears on the right**
| | Expected |
| :----- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| Header | _Available Widgets_. |
| Body | A search field and the installed blocks, grouped by namespace. |
| Footer | _No changes yet_, and the Preview, Discard, Save and Finish editing buttons. |
| Canvas | The page, the header and the footer are all beside the sidebar, not under it. Narrow the window below `md` and the sidebar becomes a sheet. |
</Step>
<Step>
**Search the available widgets**
Type `call` into the search field: the list narrows to `example:callout`. Clear it and everything comes back. Nothing about the page or your changes moves while you search.
</Step>
<Step>
**Drag a block from the sidebar into the empty zone**
`before-footer` is empty, so in edit mode it is a large dashed placeholder. Drag `core:text` from the sidebar onto it.
It lands, it is selected, and the sidebar is already showing its **Properties**.
</Step>
<Step>
**Drag a block between two existing blocks**
Go **← Available Widgets**, then drag `core:cta` over `before-profile` and hover the _top half_ of its second block. A blue insertion line appears above that block; hover the bottom half and it moves below.
Drop on the top half and the new block is second, not last.
</Step>
<Step>
**Move an existing block between compatible zones**
Drag the `core:text` block out of `before-profile` and into `after-profile`. It keeps its content and its instance id - the properties panel does not flicker on the way.
</Step>
<Step>
**Move a block with the keyboard only**
Put the mouse down. <kbd>Tab</kbd> to a block, press <kbd>Space</kbd>, then <kbd>↓</kbd>.
The blue insertion line appears under the block below, exactly as it does for a pointer - keep pressing <kbd>↓</kbd> and it walks into the next zone. <kbd>Space</kbd> drops the block where the line is; <kbd>Esc</kbd> puts it back. Whatever the line said, that is where the block lands.
</Step>
<Step>
**Watch an incompatible zone refuse**
Drag `example:callout` - from the sidebar, or from a zone that holds one - toward `sidebar`, which allows `core:text` only.
The zone turns red and says it does not accept the block. Release: nothing moves and nothing is inserted. Now press **Add block** inside that sidebar zone and confirm the catalogue offers `core:text` and nothing else.
</Step>
<Step>
**Select a block**
Click any block on the page. Expect a ring around it and a floating row of actions - Edit, Delete - in its corner.
</Step>
<Step>
**The sidebar switches to Properties**
Same panel, different mode. Expect the block's name, its type underneath, its fields, a Duplicate and a Delete at the bottom, and a **← Available Widgets** at the top.
</Step>
<Step>
**Edit a field**
Type into the heading or body field of the selected block.
</Step>
<Step>
**The block updates immediately**
The block on the page changes **while you type** - no Apply button, no delay - and the sidebar footer switches to _Unsaved changes_.
</Step>
<Step>
**Go back to Available Widgets**
Press **← Available Widgets**. The catalogue returns and the ring on the page disappears, because that action clears the selection as well as the panel.
</Step>
<Step>
**Switch a variant**
Select the `example:features` block in `before-profile`. Above its fields sits a **Variant** picker holding _Grid_, _List_ and _Compact_.
Move through all three. The block re-renders each time, and every word in the fields underneath stays exactly as it was - the variant is not content, so nothing about the content is touched. The footer says _Unsaved changes_, because the page did change.
</Step>
<Step>
**Add an Area, and move blocks in and out of it**
Go **← Available Widgets**. Above the plugin groups is a **Layout** section holding one entry: **Area**. Click it - an empty two-column Area lands in the page.
Now drag a root block onto it: it becomes a child, and the Area re-flows around it. Drag it back out to the zone and the Area keeps the rest. Reorder two children inside one Area and only their order changes. Try to drag an Area onto another Area: it is refused, out loud.
</Step>
<Step>
**Area properties**
Click the Area's own shell rather than one of its children. The sidebar shows **Area properties**: Columns, Gap, the space above/below and left/right, Alignment and Distribution - each re-laying the page out as you pick it - with **Duplicate area**, **Ungroup** and **Delete area** under them.
Gap and the two spacing controls are sliders measured in **pixels, 0 to 100**. Dragging one moves the page under the thumb. Gap is the room between the Area's own children; the other two are its outer margin, stored beside its columns as `marginX` and `marginY`. Pixels a person picked are not design tokens, so all three are written as an inline `style` rather than a utility class - and an Area asking for no margin renders exactly the markup Areas always have, so nothing on an existing page moves.
An Area laid out before this - one storing `gap: "md"` rather than `gap: 16` - still reads. Every door into a layout resolves the old names (`none` 0, `sm` 8, `md` 16, `lg` 32) to their number, and the next save writes the number down, so nothing has to migrate the table.
An empty Area draws one **Drop widgets here** cell per column, so a four-column Area shows the four places a widget can go before anything is in it.
Press **Ungroup**: the container goes and its blocks stay, at the position the Area held. Undo that by adding an Area back and filling it, then press **Delete area**: it asks first, and offers _Ungroup, keep widgets_ in the same dialog. Delete the empty Area the page ships with and it does not interrogate you - there is nothing inside to lose.
</Step>
<Step>
**Preview**
Press **Preview**. Outlines, handles and overlays go; the sidebar collapses to a slim bar with **Back to editing** and **Finish editing**. Click a link inside a block - it works now, because the `inert` wrapper is gone.
**Back to editing** restores everything, unsaved changes included.
</Step>
<Step>
**Save**
Press **Save** in the sidebar footer - not the profile form's own Save button, which is there to prove the form still works.
| | Expected |
| :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Toast | _Page saved_. |
| Footer | Switches from _Unsaved changes_ to _Saved_. |
| Header | The line under the title stops saying the page ships these widgets and names the time it was rearranged. |
| Payload | A **Last save payload** block appears at the bottom of the page - open it and read the JSON that went to `PUT /pages/layout`. Edit one zone and it names that zone alone. |
Check that `changedZoneIds` lists only the zones you actually touched.
</Step>
<Step>
**Finish editing, without reloading**
Press **Finish editing**. The public page is back: no outlines, no sidebar, and `before-footer` is invisible again if you left it empty.
The part worth checking is that **the page you are looking at is the page you saved** - the block you added, the one you moved and the text you typed, all in view mode, with no refresh anywhere. Then reload, and confirm you get the same thing a second time. The first comes from the API's answer to the save; the second from the route loader.
Now do it the other way round: click **Edit widgets**, change something, and press **Finish editing** without saving. The dialog offers **Save and finish**, **Leave without saving** and **Keep editing** - and note that **Save** on its own, back in the footer, would have kept you in edit mode instead.
</Step>
</Steps>
### While you are in there [#while-you-are-in-there]
- **Nothing on the page restarts.** Type a name into the profile form, press the **Local state** counter a few times, then **Edit widgets** and **Finish editing**. Both survive, both directions, because the editor mounts beside your page rather than around it.
- **Take the sidebar zone off the page** with the button above the zones, while the editor is open. It leaves the editor with it: the outline goes, an **Add widget** target pointing at it clears, and a selected block inside it returns the sidebar to _Available Widgets_. Save afterwards and the stored sidebar keeps what it had - the editor's copy is not written back, and it is not reset to defaults either. Edit it first and the footer names it rather than losing the change quietly. Put it back and it returns with a fresh baseline.
- **Discard** puts every zone back to what loaded, and the footer stops saying _Unsaved changes_.
- **An empty Area is edit-mode only.** The page ships one. In edit mode it is a two-column drop target; press **Finish editing** and it leaves no markup behind at all, exactly like an empty zone.
- **Add widget inside an Area** targets the Area, not the zone: the sidebar header reads _For: an area in after-profile_, and the **Layout** section disappears while it does, because an Area cannot hold another Area.
- **Duplicate** drops a copy directly below the original with its own instance id; **Delete** takes it away and returns the sidebar to the catalogue.
- The profile form in the middle must have **no** outline, **no** drag surface and **no** overlay, and its input must still take focus and type. It is application code.
- Navigating away with unsaved changes - a header link, or the back button - prompts, with **Keep editing** and **Leave without saving**.
- **Below `md`** the sidebar becomes a bottom sheet and the canvas gains padding to match: scroll to the end and the last zone, its **Add widget** button included, clears the sheet completely. **Preview** takes the padding away with the sheet, so the page is exactly as a visitor sees it.
- **Seed something unreadable** and the refusal is easy to see. Save the zone once first, so there is a row to corrupt:
```bash
psql "$POSTGRES_URL" -c 'update core_page_layouts set "zones" = \'{"before-profile":[{"foo":"bar"}]}\' where "pageId" = \'example:settings\';'
```
Reload, press **Edit widgets**: `before-profile` shows _This zone holds content the editor cannot read_ with `{"foo":"bar"}` printed under it, **Save** is disabled whatever else you change, and the footer says why. Press **Remove invalid entry**, and Save comes back. **Discard** puts it straight back.
### Against a production build [#against-a-production-build]
```bash
pnpm build
pnpm start
```
Then confirm the editor never reached a visitor:
```bash
curl -s http://localhost:3000/example/zones | grep -cE 'dnd-kit|editor/root'
```
`0`. The [boundary test](#the-lazy-loading-guarantee) is the standing guarantee; this is the spot check that the guarantee survived bundling.
# Email Verification (/docs/dev/working-with-users/email-verification)
When your install has an [email adapter](/docs/dev/email), every new member has to click a confirmation link before they can sign in. Without one, there is nobody to send the link, so accounts are confirmed the moment they are created and nothing changes.
That stops the oldest trick in the book: signing up with somebody else's address and using the account straight away.
## What a member sees [#what-a-member-sees]
1. They register at `/register`. Instead of being signed in, they get a "Check your email" card.
2. The email holds a link to `/login/verify-email?token=...`, valid for **24 hours**.
3. That page asks them to click **Confirm email address**. The page never confirms on load, because mail scanners and link previews open every URL in an email.
4. Once confirmed, they sign in with their password as usual.
If they try to sign in first, the sign-in form says **Confirm your email first** and offers **Send a new confirmation link**, which opens the resend form with their address already filled in.
<Callout type="info" title="The password comes first">
The "not confirmed" message only appears after the password has been checked.
A wrong password, an unknown address and an unconfirmed account with a wrong
password all get the same `403`, so the sign-in form can't be used to find out
which addresses are registered.
</Callout>
## The rules [#the-rules]
- **Password sign-in** answers `403 { "error": "email_not_verified" }` for an unconfirmed account. No session is created.
- **Passkey sign-in** follows the same rule, with the same error code.
- **AdminCP sign-in** at `/admin` is not blocked. Only staff get in, and staff are picked by an administrator, so an install that just added an email adapter can't lock its admins out.
- **SSO** sign-ups are confirmed already, since the provider vouches for the address.
- **Completing a password reset** also confirms the address - the reset link went to the same mailbox.
- **Staff** can confirm anyone by hand from the AdminCP user page.
<Callout type="warn" title="Adding an email adapter to an existing install">
Members who registered while an adapter was configured but before this feature
existed were never sent a link, so they are still unconfirmed. They can use
**Send a new confirmation link** on the sign-in form, reset their password, or
a staff member can confirm them from the AdminCP.
</Callout>
## API routes [#api-routes]
All routes live under `/api/@vitnode/core/users`.
| Method | Path | Body | Answers |
| :----- | :--------------------- | :------------------------ | :---------------------------------------------------------- |
| `POST` | `/verify-email` | `{ token }` | `200 { email }`, or `400` for a wrong, used or expired link |
| `POST` | `/verify-email/resend` | `{ email }`, plus captcha | `201` for every address; `404` with no email adapter |
`/verify-email/resend` answers the same `201` for an unknown address, a confirmed one and one waiting for confirmation, so it can't be used to check who has an account. It only sends when the account still needs confirming, and only once every five minutes. A new link replaces the old one.
Call them through the [fetcher](/docs/dev/fetcher) like any other core route:
```ts title="src/lib/confirm-email.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'
const response = await fetcher({
plugin: '@vitnode/core',
method: 'post',
module: 'users',
path: '/verify-email',
args: { body: { token } },
})
```
Confirming a link does not sign anybody in. Whoever clicks it owns the mailbox, but not necessarily the account - if a stranger registered with your address, your click must not drop you into their session.
## How links are stored [#how-links-are-stored]
Links live in `core_users_confirm_emails`, one row per account:
- The token is 32 random bytes, base64url-encoded. Only its SHA-256 digest is stored, so a leaked database dump can't confirm anything.
- A link works once. Spending it deletes the row in the same statement that reads it, so two clicks racing each other can't both win.
- The hourly `clean` [cron job](/docs/dev/cron) deletes expired rows.
## Events [#events]
Confirming an address emits `user.email.verified` with `{ userId, email }` - from the link, from a completed password reset, or from staff in the AdminCP. See [built-in events](/docs/dev/events/built-in-events).
<TypeTable
type={{
userId: { description: 'Id of the confirmed account.', type: 'number' },
email: { description: 'The address that was confirmed.', type: 'string' },
}}
/>
# Roles (/docs/dev/working-with-users/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:
| Role | Flags | Default Color | Staff Privileges |
| :---------------- | :-------- | :--------------------------- | :----------------------------------------------- |
| **Guest** | `guest` | None | None (applies to unauthenticated visitors) |
| **Member** | `default` | None | Standard registered member role |
| **Moderator** | None | Green (`hsl(122, 80%, 45%)`) | Unrestricted moderation staff |
| **Administrator** | `root` | Red (`hsl(0, 100%, 50%)`) | Unrestricted administrative staff (`root: true`) |
<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.
- `prefix`: An emoji or a Lucide icon rendered in front of the role name and in front of every member's username. Stored as `emoji:🚀` or `icon:rocket` - see the [Emoji & Icon Picker](/docs/ui/emoji-icon-picker) for the codec and the components that read it.
- `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`).
The **General** tab of the create/edit dialog carries both display fields: **Color**, which tints member usernames, and **Prefix**, which puts an emoji or an icon in front of them.
## Learn More [#learn-more]
<Cards>
<Card
title="Staff Permissions"
description="Grant granular admin and moderator privileges to roles"
href="/docs/dev/working-with-users/staff-permissions"
/>
<Card
title="Users"
description="Managing user accounts and session context"
href="/docs/dev/working-with-users/users"
/>
</Cards>
# Staff Permissions (/docs/dev/working-with-users/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"
import { manifest } from "@/manifest.gen"
export const blogApiPlugin = () =>
buildApiPlugin({
manifest,
// [!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({
// [!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.
## Moderator permissions with scopes [#moderator-permissions-with-scopes]
A moderator permission can be limited to some resources of a scope family, such as some forum sections. Declare the family with `scope` on the entry:
```ts title="config.api.ts"
permissionStaff: {
moderator: {
topics: [
{ permission: "can_view_reports", scope: "forum.section" },
{
permission: "can_manage_reports",
dependsOn: ["can_view_reports"],
scope: "forum.section",
},
],
},
},
```
Each grant then carries a scope, and dependencies are checked per resource: managing in a section needs viewing in that section. The scope families and the AdminCP picker are covered in [Scoped moderator permissions](/docs/dev/moderation/scoped-permissions).
## Learn More [#learn-more]
<Cards>
<Card
title="AdminCP Pages"
description="Build staff-only admin pages and navigation"
href="/docs/dev/plugins/admin"
/>
<Card
title="Roles & Users"
description="Configure user groups and roles"
href="/docs/dev/working-with-users/roles"
/>
</Cards>
# Users & Sessions (/docs/dev/working-with-users/users)
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 { useSessionQuery } from '@vitnode/core/tanstack/auth'
export const UserGreeting = () => {
// [!code ++:2]
const { data } = useSessionQuery()
const user = data?.user
if (!user) return <span>Welcome, guest!</span>
return <span>Welcome back, {user.name}!</span>
}
```
`useSessionQuery()` wraps `useQuery(sessionQueryOptions())`, so it never
suspends: `data` is `undefined` on the very first render of a page that did not
warm it in a loader. Routes that want the session ready before paint call
`ensureAuthState(queryClient)` in their loader.
---
### 3. In the AdminCP [#3-in-the-admincp]
The AdminCP session is a **second cookie**, and a second query. `isAdmin` on the
public session means "may be offered the AdminCP", not "is inside it" - so an
admin screen never answers an admin question with the public session.
```tsx title="plugins/blog/src/admin/current-admin.tsx"
import { useAdminSessionQuery } from '@vitnode/core/tanstack/admin'
export const CurrentAdmin = () => {
// [!code ++:1]
const { data } = useAdminSessionQuery()
if (data.status !== 'granted') return null
return <span>Signed in as {data.session.user.name}</span>
}
```
`useAdminSessionQuery()` wraps `useSuspenseQuery(adminSessionQueryOptions())`,
so `data` is always there and the screen suspends instead of rendering an empty
state. The AdminCP layout warms it, which is why every screen below it reads a
cache hit. Two shorthands sit on top of it:
| Hook | Returns |
| :----------------- | :--------------------------------------------------------------- |
| `useAdminAccess()` | The whole access state - `granted`, or the reason it was refused |
| `useAdminUser()` | The signed-in administrator, or `null` when access is refused |
---
## User Model (`core_users`) [#user-model-core_users]
The canonical user table contains:
| Column | Type | Description |
| :-------------- | :------------- | :---------------------------------------------------- |
| `id` | `serial` | Unique permanent identifier |
| `name` | `varchar(255)` | Display name |
| `nameCode` | `varchar(255)` | URL-safe slug for profile URLs (`/users/[nameCode]`) |
| `email` | `varchar(255)` | Unique account login email |
| `firstName` | `varchar(128)` | Given name, set by the user (nullable) |
| `lastName` | `varchar(128)` | Family name, set by the user (nullable) |
| `phone` | `varchar(32)` | Contact number, their own (nullable) |
| `headline` | `varchar(100)` | One line about the user, their own (nullable) |
| `showRealName` | `boolean` | Show the real name publicly instead of `name` |
| `roleId` | `integer` | Primary role ID (FK to `core_roles`) |
| `avatarColor` | `varchar(6)` | Hex color for letter avatars |
| `avatarId` | `integer` | Uploaded avatar, a `core_files` row (nullable) |
| `coverId` | `integer` | Uploaded profile cover, a `core_files` row (nullable) |
| `language` | `varchar(32)` | Preferred UI locale (defaults to `en`) |
| `timeZone` | `varchar(64)` | IANA time zone, set by the user (nullable) |
| `emailVerified` | `boolean` | Verification status |
Every user payload the API hands out - the session, the public profile, the
AdminCP list and detail, search hit authors - carries the two images resolved
to URLs as `avatarUrl` and `coverUrl`. Both are `null` until something is
uploaded, and the `Avatar` component falls back to the letter avatar on its own -
drawn from the first character of `nameCode`, never of the displayed name, so a
member who changes which name their profile shows keeps the same face in every
list they appear in.
### Personal information [#personal-information]
`firstName`, `lastName`, `phone` and `headline` are the user's own to set, at **Settings →
Overview** (`/settings`). The Profile card lists them read-only; **Edit profile**
opens one sheet with every field, the **Show my real name** switch and the time
zone, so changing three things takes one save instead of three. Every field is
optional, stored as `null` rather than an empty string when cleared, and the
session payload carries them so anything already reading the session can show
them without a second request.
| Method | Path | Who |
| :------ | :----------------------------------- | :----------------------------------- |
| `GET` | `/api/@vitnode/core/users/me/policy` | The signed-in user - may they edit? |
| `PATCH` | `/api/@vitnode/core/users/me` | The signed-in user, on their own row |
The body takes any subset of
`{ firstName, lastName, phone, headline, showRealName }` -
a field left out is left alone, and a text field sent as `""` or whitespace is
cleared. Writing invalidates the user's cached session and emits
[`user.updated`](/docs/dev/events/built-in-events).
`phone` is the one field with a shape: digits and the punctuation international
numbers are written with (`+`, spaces, `-`, `(` and `)`), up to 32 characters.
Anything else is rejected by the form and by the route. It is **not** on the
public profile payload - only the account's own session carries it.
### Time zone [#time-zone]
`timeZone` sits under **Region** in the same **Edit profile** sheet. It takes any
IANA name, like `Europe/Warsaw`, and **Use this device's time zone** fills the
field from the browser in one click - it still waits for **Save changes**. `null` means "follow my language", then UTC.
Notification digests go out in this time zone, and the session carries it, so
`c.get("user")?.timeZone` is there for anything else that wants local time.
| Method | Path | Who |
| :----- | :-------------------------------------- | :----------------------------------- |
| `PUT` | `/api/@vitnode/core/users/me/time-zone` | The signed-in user, on their own row |
The body is `{ timeZone: string | null }`. An unknown name answers `400`.
Saving invalidates the cached session and emits
[`user.updated`](/docs/dev/events/built-in-events).
### Which name the public sees [#which-name-the-public-sees]
`showRealName` decides whether a profile is headed by the nickname (`name`) or by
`firstName lastName`. The public profile route resolves it **server-side** and
returns the answer as `name`, so a real name the user has not published never
leaves the API. When the switch is on but neither half is set, the nickname is
used, so turning it on early cannot leave a profile with an empty heading.
People in content, such as a blog post's authors, carry the same answer as
`fullName`: the real name when it is published, `null` otherwise.
[`UserFormat`](/docs/ui/user-format) shows it in place of the nickname. To
publish a real name from your own route, use `publicFullNameOf` from
`@vitnode/core/lib/user-personal-information` and never send `firstName` or
`lastName` to other people.
The AdminCP and search always show `name`, the account's own nickname - staff
need the identifier the account is filed under.
### What the profile header shows [#what-the-profile-header-shows]
{/* Image prompt: VitNode public profile header at /users/aXen. Wide cover image with a rounded-square avatar overlapping its bottom-left corner, the display name and @nameCode beside it, and a single row of muted meta items with small icons - a briefcase for the headline, a shield for the primary role, a calendar for the join date - with an "Edit profile" outline button at the far right. Light theme, 1440x400. */}
`GET /api/@vitnode/core/users/profile/{nameCode}` answers with the header's whole
payload: `name` (already resolved), `nameCode`, `headline`, `avatarUrl`,
`coverUrl`, `avatarColor`, `createdAt`, the primary `role` and any
`secondaryRoles`. The header draws the headline, the role and the join date as
one row of meta items, each with its own icon, and stacks them centred under the
avatar on a phone.
`headline` follows the install switch: with `users.personalInformation.headline`
set to `false` the route returns `null` for everyone, so turning the field off
takes it off public profiles too, without touching what members had written.
The **Edit profile** button is the header's action slot. It is rendered only for
the account's own profile; a host that renders `ProfileContent` itself can pass
any `action` it likes - a follow button, a "message" link, nothing at all.
### Who may edit it [#who-may-edit-it]
Each role has **Allow editing personal information** on its **Profile** tab
(`allowEditPersonalInfo`, default `true`). A user may edit only when **every**
role they hold allows it - one role that switches it off is enough to lock the
card.
That is the opposite of the image allowances, which grant on _any_ role, and
deliberately so: this column defaults to `true`, so under "any role grants" an
administrator who switched it off on one role would find it silently re-granted
by every other role the member happens to hold, and the setting would almost
never take effect.
The **Edit profile** sheet then shows only the time zone, which every member may
change, and `PATCH /users/me` answers `403` regardless of what the UI showed.
### Turning fields off for the whole install [#turning-fields-off-for-the-whole-install]
Roles decide _who_ may edit. The API config decides _which fields exist at all_.
Every field is on unless you set it to `false` in `vitnode.api.config.ts`:
```ts title="vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
// ...
users: {
personalInformation: {
phone: false,
headline: false,
showRealName: false,
},
},
})
```
The keys are `firstName`, `lastName`, `phone`, `headline` and `showRealName`. A
field switched off disappears from the settings card and from its form, and
`PATCH /users/me` refuses to write it even if a caller sends it anyway - so a
stale browser tab or a hand-rolled request cannot get around it.
Switching a field off never deletes anything: the column keeps whatever members
had already set, so turning it back on restores their values. With
`showRealName` off, every profile is headed by the nickname again, whatever
individual members had chosen. With **every** field off there is nothing left to
edit, so the **Edit** button disappears too.
---
## 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`).
---
### Edit a user [#edit-a-user]
{/* Image prompt: VitNode AdminCP user page at /admin/core/users/1. Left column: profile card with cover, round avatar, name, @handle, Staff and Verified badges, then Personal information, Preferences, Roles, Connected accounts and Devices cards. Right column: segmented tabs Activity, Notifications, Password & passkeys above a vertical activity timeline. Dark theme, 1440x1000. */}
Open a user at `/admin/core/users/[id]`. Everything the member can change in their own `/settings` is editable here too.
| Area | What staff can change |
| :----------------------- | :------------------------------------------------------------------------------------------------------ |
| Profile card | Display name, name code, email, avatar, cover, and **Mark email as verified** |
| Personal information | First name, last name, headline, phone, birthday, **Show real name** |
| Preferences | Language, time zone (or automatic), newsletter |
| Roles | Primary role and secondary roles |
| Connected accounts | Disconnect an SSO account, choose where the avatar and name come from, turn **Sync on sign-in** on/off |
| Devices | Sign out one device, or every device at once |
| **Notifications** tab | In-app, push and email (with frequency) per notification type |
| **Password & passkeys** tab | Set a new password, rename or delete passkeys |
A few rules differ from the member's own settings:
- **Staff can edit locked fields.** The role's **Allow editing personal information** and the install's `users.personalInformation` switches limit members, not staff.
- **Notification locks still apply.** Mandatory types, and types the notification settings stop members from changing, are read-only here too, because delivery ignores stored choices for them.
- **The last sign-in method can't be removed.** Disconnecting the only SSO account or deleting the only passkey answers `409`.
- **Setting a password signs the member out everywhere**, AdminCP sessions included.
- **Sync now isn't offered.** It needs the member to sign in with the provider themselves.
Every write needs `users:can_edit`, plus `users:can_edit_admin` when the target is staff. A staff target must also sit within your own access: you need every admin and moderator permission they hold, and only a root administrator can edit a root or unrestricted account. So nobody can reset the password of, or demote, someone above them. Reads need `users:can_view`.
| Method | Path | Does |
| :------- | :------------------------------------------------------------------ | :--------------------------------------------------- |
| `PATCH` | `/api/@vitnode/core/admin/users/{id}` | Account, personal information and preferences |
| `PUT` | `/api/@vitnode/core/admin/users/{id}/password` | Sets a new password and revokes every session |
| `GET` | `/api/@vitnode/core/admin/users/{id}/devices` | Devices with an active session |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/devices/{publicId}` | Signs one device out |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/devices` | Signs every device out |
| `GET` | `/api/@vitnode/core/admin/users/{id}/passkeys` | Passkeys |
| `PATCH` | `/api/@vitnode/core/admin/users/{id}/passkeys/{passkeyId}` | Renames a passkey |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/passkeys/{passkeyId}` | Deletes a passkey |
| `GET` | `/api/@vitnode/core/admin/users/{id}/sso` | Connected accounts, sign-in summary, profile sources |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/sso/{providerId}` | Disconnects an account |
| `PUT` | `/api/@vitnode/core/admin/users/{id}/sso/preferences` | Profile sources and sync on sign-in |
| `GET` | `/api/@vitnode/core/admin/users/{id}/notification-preferences` | Notification preferences per type |
| `PUT` | `/api/@vitnode/core/admin/users/{id}/notification-preferences` | Changes notification preferences |
The `PATCH` body takes any of `email`, `name`, `nameCode`, `roleId`, `secondaryRoleIds`, `firstName`, `lastName`, `headline`, `phone`, `showRealName`, `birthday` (`YYYY-MM-DD` or `null`), `language`, `timeZone` (`null` for automatic) and `newsletter`. At least one field is required.
---
### Where it happens [#where-it-happens]
- **Profile page** (`/users/[nameCode]`): the owner sees a camera button on the
cover and on the avatar. It opens one dialog that both uploads and removes:
with a picture already set, a pair of radio buttons chooses between them and
the confirm button reads **Upload** or **Delete** to match; with nothing set
yet, the dialog goes straight to the picker.
- **Settings overview** (`/settings`): the avatar and its camera button only,
beside the name, code name, role and email the account carries, above the
personal information the user sets for themselves. The cover is
edited on the profile page.
- **AdminCP** (`/admin/core/users/[id]`): the same two buttons and the same
dialog, for anybody holding `users:can_edit` - plus `users:can_edit_admin`
when the target is an administrator. Staff can always set an image, even when
the user's own roles cannot; the role's size cap still applies.
### Role settings [#role-settings]
Each role decides, on its **Profile** tab at **Core → Users → Roles**:
| Setting | Column | Default |
| :--------------------------------- | :---------------------- | :------ |
| Allow editing personal information | `allowEditPersonalInfo` | `true` |
| Allow avatar upload | `allowUploadAvatar` | `true` |
| Maximum avatar size (kB) | `maxAvatarSize` | `2048` |
| Allow cover image upload | `allowUploadCover` | `true` |
| Maximum cover size (kB) | `maxCoverSize` | `5120` |
A user with several roles is allowed as soon as **one** of them allows the
image, and gets the **most generous** cap among those roles. The cap is shown in
the dialog before a file is picked, and checked again on the server.
### API [#api]
| Method | Path | Who |
| :------- | :-------------------------------------------------- | :--------------------------------------------------------------- |
| `GET` | `/api/@vitnode/core/users/images/policy` | Signed-in user - what they may upload, and the caps in bytes |
| `POST` | `/api/@vitnode/core/users/images/{kind}` | Signed-in user - multipart `file`, `kind` is `avatar` or `cover` |
| `DELETE` | `/api/@vitnode/core/users/images/{kind}` | Signed-in user |
| `POST` | `/api/@vitnode/core/admin/users/{id}/images/{kind}` | Staff with `users:can_edit` |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/images/{kind}` | Staff with `users:can_edit` |
Accepted types are JPEG, PNG and WebP. The browser crops to `512×512` for an
avatar and `1800×600` for a cover and sends WebP where the browser can encode
it, so uploads are usually far under the cap. A refused upload answers `400`
with `{ error }` written for the person who picked the file, and a role that
does not allow the image answers `403`.
Both writes emit an event -
[`user.avatar.updated` and `user.cover.updated`](/docs/dev/events/built-in-events)
- with the new `core_files` id, or `null` when the image was removed.
## Learn More [#learn-more]
<Cards>
<Card
title="Roles"
description="Configure permissions, color badges, and user groups"
href="/docs/dev/working-with-users/roles"
/>
<Card
title="Staff Permissions"
description="Grant administrative and moderation privileges"
href="/docs/dev/working-with-users/staff-permissions"
/>
<Card
title="SSO"
description="Configure social login providers"
href="/docs/dev/sso"
/>
</Cards>
# Install the Blog Plugin (/docs/guides/blog)
`@vitnode/blog` is the Content Engine reference plugin. It brings articles,
categories, editorial screens, revisions, a public `/blog` index, article
pages and search indexing, without making your host app impersonate a blog
plugin.
<Steps>
<Step>
### Install the package [#install-the-package]
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Install @vitnode/blog">
```bash tab="bun"
bun add @vitnode/blog@canary
```
```bash tab="pnpm"
pnpm add @vitnode/blog@canary
```
```bash tab="npm"
npm install @vitnode/blog@canary
```
</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 [#enable-the-web-plugin]
One line, and it brings the blog's pages, its AdminCP screens and its
translations with it - your build reads the factory and writes the loaders into
`src/package-messages.gen.ts` for you:
```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" persist items={["bun", "pnpm", "npm"]} label="Prepare and start the blog">
```bash tab="bun"
bun run db:migrate
bun dev
```
```bash tab="pnpm"
pnpm db:migrate
pnpm dev
```
```bash tab="npm"
npm run db:migrate
npm run dev
```
</Tabs>
In AdminCP, create a category at **Blog → Categories**, then publish an article
at **Blog → Articles**. A category's **Friendly URL** is filled in from its name
in each language when you leave it empty, like an article's. 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>
## Read the blog at /blog [#read-the-blog-at-blog]
Installing the plugin adds `/blog`: every published article, newest first, 12 to
a page. Drafts, articles scheduled for later and hidden articles never appear.
- The first page opens with the six newest articles as image tiles: one large
story, two beside it and three below. Each tile shows the article's
categories, title, authors and date on top of its cover.
- The other articles follow as cards with the cover, up to three categories,
the title, the authors with their avatars and the date. The whole card opens the article at `/blog/article/:slug`.
- A sidebar lists every category that has articles, with how many each holds.
Each one opens the category's own page at `/blog/category/:slug`, with its
articles as cards. On phones the list turns into a row of chips.
- Moving between pages animates with view transitions: an article's cover and
title grow into the article page, and the category highlight slides to the
category you picked. Visitors who prefer reduced motion get no animation.
<ImgDocs
withoutBackground
className="*:max-w-full"
src={blogIndex}
alt="The /blog page with a large story and five smaller image tiles, then article cards beside a category list with article counts"
/>
Every view has its own address, so a refresh, a shared link and the back
button all show the same view:
| URL | What it shows |
| ---------------------------------- | ------------------------------------------------------ |
| `/blog` | Every article, with the image tiles on the first page |
| `/blog?page=2` | A later page of every article |
| `/blog/category/guides` | One category's articles, using its friendly URL |
| `/blog/category/guides?page=2` | A later page of that category |
| `/blog/article/building-a-plugin` | One article |
Category and article slugs are per language: a Polish reader gets each
category's Polish friendly URL, and a category link in another language
redirects to it. Older links still work: `/blog/:slug` and `/blog?category=3`
redirect permanently to the new addresses. Any other query parameter is
ignored. There is no search box on `/blog`; readers find articles through the
site search, which indexes every published article.
The page follows the reader's language. In Polish it lists the Polish
translation of each article, or the English one where none is published yet,
and category names fall back the same way. "No articles yet" means nothing is
published; "Nothing in this category yet" means the picked category has no
articles in that language, and offers **See all articles**.
The first page of `/blog` and of every category is indexed by search engines,
with a canonical link and `hreflang` alternates that use each language's own
slug. Later pages get `noindex, follow`, so crawlers still reach every
article. Add `/blog` to your app's `/sitemap.xml`
next to the article entries; the
[sitemap route](/docs/content-engine/seo#sitemap) lists articles, not the
index.
### Read an article [#read-an-article]
An article page puts everything a reader asks first at the top, centered: a
link back to the articles, the categories, the title, the authors and a line
with the publish date, when it was last edited and how long it takes to read.
The "Edited" note only shows up when the article changed more than an hour
after it went live, so a quick fix right after publishing stays quiet.
The cover and the text share one centered column. When the article has
headings, an **On this page** list sits in the right margin and follows you as
you scroll, highlighting every section you are looking at. On phones it folds
into a box above the cover. Headings get their own link anchors, so you can
share `/blog/article/building-a-plugin#why-plugins`.
### Categories and article counts in your own pages [#categories-and-article-counts-in-your-own-pages]
The sidebar and the category tags come from a small public route that returns
each category's id, name and friendly URL in the requested language, its
friendly URL in every language, its colour and article count, plus the total
for **All articles**:
```bash
curl "http://localhost:3000/api/@vitnode/blog/categories?locale=pl"
```
```json
{
"items": [
{
"articleCount": 4,
"color": "hsl(215, 81%, 52%)",
"id": 1,
"name": "Poradniki",
"slug": "poradniki",
"slugs": { "en": "guides", "pl": "poradniki" }
}
],
"total": 4
}
```
A count only includes articles a reader can open in that language, the same
ones `/blog` lists. Names stay cached until a category changes, and counts until
an article is published, edited, hidden or deleted. To put a blog list on
another page with your own layout, see
[Add a list to another page](/docs/content-engine/public-lists-embed).
### Article authors [#article-authors]
Every article carries its authors under `authorId`, in the order the article
lists them, on both the list and the article route. The blog opts the field into
[`publicApi.people`](/docs/content-engine/reference#publicapi), so each author
is a small public profile, never a raw user row:
```bash
curl "http://localhost:3000/api/@vitnode/blog/content/blog?locale=en&first=1"
```
```json
{
"edges": [
{
"authorId": [
{
"avatarColor": "a8295c",
"avatarUrl": null,
"id": 1,
"name": "Ada",
"nameCode": "ada",
"role": { "color": null, "prefix": null }
}
],
"id": 4,
"title": "Building a plugin"
}
]
}
```
The response is trimmed here. A deleted account simply drops out of the list.
## Write and translate articles [#write-and-translate-articles]
The article editor reads top to bottom like the published article: the cover
image and its alt text, then the title, slug and content. The checks before
publishing live in the **SEO** sheet, so the text gets the whole width.
{/* Image prompt: VitNode AdminCP blog article editor at full width. A wide cover image with Replace file and Remove buttons in its corner, alt text field under it, a large article title and slug, then a TipTap editor. Header with Translate, SEO with a small amber badge "2", AI review, a muted "● Published" label and a split Save changes button with a dropdown arrow. Light theme, 1440x900. */}
### Check the article before you publish [#check-the-article-before-you-publish]
Press **SEO** in the header to open the **Ready to publish** sheet. The badge on
the button counts what is still left, so you know when it needs a look. The
sheet checks what a published article usually needs:
| Check | Passes when |
| -------------------------------- | ----------------------------------------------------------- |
| Title fits search results | Every started language has a title of 60 characters or less |
| Cover image | A cover image is set |
| URL | The language you edit has a friendly URL |
| Cover alt text in every language | Every started language describes the cover |
| Translations complete | Every language has a title, friendly URL and content |
| Translations up to date | No translation is older than the default language |
The title and alt text fields show a live counter against the
recommended length: 60 and 125 characters. They are recommendations, not
limits, so you can still save a longer title.
Each row is green when it is done and says what is missing when it is not, and
the bar on top counts how many are ready. You can fix most rows right there:
press **Edit under the cover** to jump to the alt text, or **Open** a language
that is missing a translation.
### Publish or unpublish [#publish-or-unpublish]
The header shows whether the article is a **Draft** or **Published** (hover it
to see when it went live). To change that, open the arrow next to **Save
changes** and pick **Publish** or **Unpublish**. It asks for confirmation
first, because readers see the change immediately. **Hide** and **Unhide** live
in the same menu.
### Hide or duplicate an article [#hide-or-duplicate-an-article]
The **More actions** menu of an article in the list has **Hide** and
**Duplicate**. Hiding takes a published article off the site, search and the
sitemap without unpublishing it, and **Unhide** brings it back with the same
URL and date. It needs the **Hide and unhide articles** permission. Duplicating
makes a draft copy with every translation, such as "Hello world (Copy)". See
[Hide content](/docs/content-engine/content-visibility) and
[Duplicate content](/docs/content-engine/duplicate-content).
### Translate side by side [#translate-side-by-side]
Pick a language from **Translate**. Each translated field then shows the default
language on the left, read-only, and the language you translate into on the
right. Your shared fields, such as categories and authors, stay in one place.
A translation is marked **outdated** when the default language was saved after
it. **Generate from title** builds the friendly URL from the translated title.
### Use AI helpers [#use-ai-helpers]
With AI configured, the editor adds:
- **Translate** on each field, and **Translate missing fields** for a whole
language. Content keeps its formatting.
- **AI review** in the header, which opens a sheet with suggestions about
clarity, completeness, structure and tone. When a suggestion is about the
wording, **Show fix** shows the current text next to a rewrite, and **Apply**
puts the rewrite into the article. **Dismiss** hides a suggestion you do not
agree with. The review never blocks publishing.
<Callout type="info" title="When the AI buttons appear">
The buttons appear only when the API has at least one model in `ai.models`.
The routes behind them require the `can_edit` permission on articles. See
[AI](/docs/dev/ai) to configure a model.
</Callout>
AI never saves for you. Read the suggestion, then press **Save changes**.
While others are editing the article, a translated body goes into the shared
editor as one change, so everyone sees it and you can undo it.
### Write together [#write-together]
Several people can work on one article at once. The header shows who else is
in it, and a colored outline with a name tag shows who is editing which field. The title,
slug and other plain fields are edited by one person at a time; the
article body is shared, with everyone's cursor visible. Your changes are
autosaved to a draft until someone presses **Save changes**. See
[Live editing and autosave](/docs/content-engine/live-editing) for how it
works and what it needs on your server.
### Upgrade an existing blog [#upgrade-an-existing-blog]
Articles no longer have an **Excerpt** field. The migration drops the column
with every excerpt in it, so copy any you want to keep before you run it. Search
results and the meta description now use the start of the article content. The article
content is now stored as [rich text](/docs/content-engine/rich-text) JSON
instead of HTML; the migration keeps the words of existing articles as one
paragraph, so re-check their formatting.
Articles moved from `/blog/:slug` to `/blog/article/:slug`, and categories got
a localized **Friendly URL**. The migration gives every existing category one
made from its name and id, such as `guides-3`; rename it in AdminCP if you want
a shorter one. Old article links redirect, but search results store their URL,
so rebuild the `blog.post` collection in **AdminCP → Debug Panel → Search**
afterwards. If you map the article route in `routePaths`, rename the key to
`'/blog/article/:slug'`.
Run your migrations after you upgrade `@vitnode/blog`:
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Run the blog migrations">
```bash tab="bun"
bun run db:migrate
```
```bash tab="pnpm"
pnpm db:migrate
```
```bash tab="npm"
npm run db:migrate
```
</Tabs>
## 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/content-engine/public-pages"
/>
<Card
icon={<LayoutGridIcon />}
title="Public lists"
description="Build a list page like /blog for your own content type."
href="/docs/content-engine/public-lists"
/>
<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 (/docs/guides/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" persist items={["bun", "pnpm", "npm"]} label="Generate the plugin">
```bash tab="bun"
bun create vitnode-app@canary --plugin
```
```bash tab="pnpm"
pnpm create vitnode-app@canary --plugin
```
```bash tab="npm"
npm create vitnode-app@canary -- --plugin
```
</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]
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Run the plugin">
```bash tab="bun"
bun dev
```
```bash tab="pnpm"
pnpm dev
```
```bash tab="npm"
npm run dev
```
</Tabs>
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>
# Run a Community Forum (/docs/guides/forum)
`@vitnode/forum` adds a community forum to a VitNode app: a tree of forums,
topics inside them and Reddit-style nested comments. It is built only from
Content Engine pieces - a [container](/docs/content-engine/containers) for the
forums, two content types and a [thread](/docs/content-engine/threads) - so
everything you learn here works the same way in your own plugins.
<Callout type="info" title="Lives in the monorepo">
The plugin is `private: true` and ships with the VitNode repository, like
`@vitnode/example`. It is not published to npm yet.
</Callout>
<Steps>
<Step>
### Enable the API plugin [#enable-the-api-plugin]
Add the API factory to `vitnode.api.config.ts` - in `apps/web` for a single
app, and in `apps/api` too for a split deployment.
```ts title="apps/web/src/vitnode.api.config.ts"
import { forumApiPlugin } from "@vitnode/forum/config.api"; // [!code ++]
export const vitNodeApiConfig = buildApiConfig({
plugins: [
forumApiPlugin(), // [!code ++]
],
});
```
</Step>
<Step>
### Enable the web plugin [#enable-the-web-plugin]
The web factory brings the pages, the AdminCP **Forums** screen and the
translations.
```ts title="apps/web/src/vitnode.config.ts"
import { forumPlugin } from "@vitnode/forum/config"; // [!code ++]
export const vitNodeConfig = buildConfig({
plugins: [
forumPlugin(), // [!code ++]
],
});
```
</Step>
<Step>
### Migrate and start [#migrate-and-start]
The plugin owns two tables, `forum_topics` and `forum_comments`. Run the
migrations, then start the app.
<Tabs groupId="package-manager" persist items={["bun", "pnpm", "npm"]} label="Migrate and start the forum">
```bash tab="bun"
bun run db:migrate
bun dev
```
```bash tab="pnpm"
pnpm db:migrate
pnpm dev
```
```bash tab="npm"
npm run db:migrate
npm run dev
```
</Tabs>
</Step>
<Step>
### Create your forums [#create-your-forums]
In AdminCP, open **Forums** and create a few. Forums nest up to four levels
deep, and you can drag them to reorder. A forum's **Icon** accepts the same
`icon:name` or emoji value as role prefixes.
{/* Image prompt: VitNode AdminCP Forums screen with a nested tree of forums (General, Help with two subforums, Showcase), drag handles, and a "Create forum" button. Light theme, 1440x900. */}
</Step>
</Steps>
## Pages members get [#pages-members-get]
| Page | What it does |
| ------------------------ | ---------------------------------------------------------------------- |
| `/forum` | Every forum with its topic and comment counts and its newest topic |
| `/forum/:slug` | Subforums and the topics of one forum, newest first |
| `/forum/create/topic` | Start a topic (signed-in members) |
| `/forum/topics/:slug` | The topic, its nested comments, and a comment box |
| `/forum/topics/:id/edit` | Edit your own topic |
| `/forum/comments/:slug` | Permalink of one comment - redirects to its place in the topic |
| `/forum/me/pending` | Your posts a moderator approved, declined, or has not looked at yet |
Comments nest up to six levels - hit **Reply** under any comment to answer it.
On small screens deep comments stop indenting, so the text keeps its width, and
every branch can be collapsed. A comment removed by a moderator stays as "This
comment was removed." when it has public replies, so the conversation keeps its
shape.
The forum index, forum and topic pages are cached for a minute and refreshed in the
background. Edit buttons and the comment box load in the browser, so every
visitor gets the same cached page. The comment editor itself waits for a click on
**Write a comment…**, so readers who only read never download it.
Topic and comment counts are cached too when Redis is configured (`REDIS_URL`).
Any new, published, hidden, moved or deleted topic or comment expires them on
the spot, and a five-minute limit catches anything that changed behind the
forum's back, such as a row edited by hand. Topic lists leave out the topic body,
so `GET /api/@vitnode/forum/content/topics` returns titles, slugs and dates only -
read one topic for its body. Topic pages set a canonical URL and
`DiscussionForumPosting` structured data with the comment count.
Topics also have [delivery](/docs/content-engine/seo): a renamed topic
redirects its old address to the new one, and
`/api/@vitnode/forum/content/topics/delivery/sitemap` lists every public topic
for your `sitemap.xml`. Topics waiting for approval never appear there, in
search or in any list - until a moderator says yes, they don't exist for
anyone but their author.
Topics and comments show up in [search](/docs/dev/search), on `/discover` and
on their authors' profile timelines. A comment is headed by its topic's title
and stays out of public results while its topic is not public - see
[Borrow the title from a related record](/docs/content-engine/search#borrow-the-title-from-a-related-record).
Upgrading a forum that already has posts? Rebuild the index once in
**Debug Panel → Search** (`/admin/core/debug/search`).
## Choose who publishes straight away [#choose-who-publishes-straight-away]
By default every member's topic and comment goes live immediately and authors can
edit their posts for as long as they like. Change that per forum in the forum's
**Publishing** settings - for example, require approval for new topics in
**Announcements**, or let authors edit comments for one hour only. A forum
inherits from its parent until you override a value. See
[Container policies](/docs/content-engine/container-policies) for every option.
When a post needs approval, the author sees "Waiting for a moderator", and the
post appears on `/forum/me/pending`. Moderators with the **Approve** permission for
that forum review it in ModCP. See [Approvals](/docs/content-engine/approvals).
## Grant moderators a forum [#grant-moderators-a-forum]
AdminCP only manages the forums themselves. Topics and comments live on the
public forum: authors edit their own, and moderators step in right there or in
ModCP.
Moderator permissions for topics and comments are scoped by forum. Give a
moderator role **Edit** and **Approve** on **Topics** and **Comments**, and pick
the forums it covers - a single forum, or a forum and everything below it. See
[Scoped permissions](/docs/dev/moderation/scoped-permissions).
# Guides (/docs/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.
# Accessibility (/docs/ui/accessibility)
Every interactive component sits on a [Base UI](https://base-ui.com) primitive,
so keyboard support, focus management and ARIA come built in. Your job is mostly
not to break it. Try the demos with a keyboard or a screen reader.
## Keyboard focus [#keyboard-focus]
<Preview name="accessibility-focus" className="*:max-w-full" />
Rings use `:focus-visible`, so they show up for keyboards and stay out of the
way for mice. Text fields always get one, since you're about to type. Custom
controls should borrow the same classes.
```tsx
<div
tabIndex={0}
className="outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
/>
```
## Touch targets [#touch-targets]
<Preview name="accessibility-touch-targets" className="*:max-w-full" />
Small controls keep their compact look but get an invisible `::after` hit area
of at least 44px. `Checkbox`, `RadioGroupItem` and `Switch` always have it; the
smaller icon `Button` sizes and `NumberField` steppers add it on touch screens via
`pointer-coarse:`.
## Contrast [#contrast]
<Preview name="accessibility-contrast" className="*:max-w-full" />
The ratio is computed from the live theme tokens, so flip dark mode and watch it
change. `muted-foreground` passes AA on `background` and `card` in both themes.
Filled `primary` with white text drops to about 3.8:1 in dark mode, so keep it
for short button labels.
## Screen reader text [#screen-reader-text]
<Preview name="accessibility-screen-reader" className="*:max-w-full" />
Icons are decoration; words carry the meaning. Icon-only `Button` sizes require
an `aria-label` at the type level, and `sr-only` adds context that sighted users
get from the layout.
```tsx
<Badge>
{unread}
<span className="sr-only"> unread</span>
</Badge>
```
## Announcements [#announcements]
<Preview name="accessibility-announcements" className="*:max-w-full" />
Changes that happen without a page load need to be said out loud. `role="status"`
waits politely for a pause; `role="alert"` interrupts. `Alert` picks for you:
`warning` and `destructive` are alerts, everything else is a status.
`FieldError` is an alert, `Spinner` is a labelled status, and a loading `Button`
renames itself to "Loading".
## Motion and transparency [#motion-and-transparency]
<Preview name="accessibility-preferences" className="*:max-w-full" />
These are your device's settings right now. Components respect them with
`motion-reduce:`, `reduced-transparency:` and `pointer-coarse:`, so nobody
gets a spinning headache or a blurry dialog they asked not to have. More in
[Motion](/docs/ui/motion).
## Semantic HTML [#semantic-html]
```tsx
<header>…</header>
<nav aria-label="Main">…</nav>
<main>
<h1>Settings</h1>
<img alt="Your avatar" src={avatarUrl} />
<img alt="" src="/divider.svg" />
</main>
```
- Use `header`, `nav`, `main` and real headings in order. Screen reader users
jump between them like chapters.
- Every image needs `alt`. Use `alt=""` only when it is purely decorative.
- A `button` does things, a link goes places. Never put `onClick` on a `div`.
## Related [#related]
<Cards>
<Card
title="Colors"
href="/docs/ui/colors"
description="Semantic tokens with contrast you can predict."
/>
<Card
title="Typography"
href="/docs/ui/typography"
description="Readable sizes, line heights and text rules."
/>
<Card
title="Motion"
href="/docs/ui/motion"
description="Animation rules, including reduced motion."
/>
</Cards>
# Accordion (/docs/ui/accordion)
## Preview [#preview]
<Preview name="accordion" />
## Usage [#usage]
```ts
import {
Accordion,
AccordionContent,
AccordionItem,
AccordionTrigger,
} from '@vitnode/core/components/ui/accordion'
```
```tsx
<Accordion defaultValue={['register']}>
<AccordionItem value="register">
<AccordionTrigger>How do I create an account?</AccordionTrigger>
<AccordionContent>
<p>Click Sign up in the top bar and fill in your email.</p>
</AccordionContent>
</AccordionItem>
</Accordion>
```
`defaultValue` and `value` are arrays of item values, even when only one item
can be open.
## Multiple [#multiple]
<Preview name="accordion-multiple" />
By default, opening an item closes the others. `multiple` lets several stay
open.
```tsx
<Accordion defaultValue={['kind', 'search']} multiple>
```
## Find in page [#find-in-page]
With `hiddenUntilFound`, closed panels stay in the DOM and the browser's
<kbd>Ctrl</kbd> + <kbd>F</kbd> can find and open them. Great for long FAQs.
```tsx
<Accordion hiddenUntilFound>
```
## API Reference [#api-reference]
[Base UI - Accordion](https://base-ui.com/react/components/accordion)
# Alert Dialog (/docs/ui/alert-dialog)
Unlike a [Dialog](/docs/ui/dialog), clicking outside does nothing. People
answer with a button, or back out with <kbd>Escape</kbd>.
## Preview [#preview]
<Preview name="alert-dialog" />
## 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="destructive">Delete thread</Button>}
/>
<AlertDialogContent>
<AlertDialogHeader>
<AlertDialogTitle>Delete this thread?</AlertDialogTitle>
<AlertDialogDescription>
All 42 replies go with it. This can't be undone.
</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
<AlertDialogCancel>Cancel</AlertDialogCancel>
<AlertDialogAction variant="destructive">Delete thread</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialog>
```
Both `AlertDialogAction` and `AlertDialogCancel` close the dialog. Put your
logic in the action's `onClick`.
## Icon and compact size [#icon-and-compact-size]
<Preview name="alert-dialog-media" />
`AlertDialogMedia` adds an icon tile. With `size="sm"` the dialog gets narrower,
centers its text and splits the footer into two equal buttons.
```tsx
<AlertDialogContent size="sm">
<AlertDialogHeader>
<AlertDialogMedia>
<LogOutIcon />
</AlertDialogMedia>
<AlertDialogTitle>Sign out of all devices?</AlertDialogTitle>
</AlertDialogHeader>
</AlertDialogContent>
```
Waiting on an API call before closing? [Confirm Action Alert
Dialog](/docs/ui/confirm-action-alert-dialog) handles the spinner and errors
for you.
## Props [#props]
<TypeTable
type={{
'AlertDialogContent.size': {
description: 'Compact, centered layout with `sm`.',
type: '"default" | "sm"',
default: '"default"',
},
'AlertDialogAction.variant': {
description: 'Button variant of the confirm button.',
type: 'Button["variant"]',
default: '"default"',
},
'AlertDialogCancel.variant': {
description: 'Button variant of the cancel button.',
type: 'Button["variant"]',
default: '"outline"',
},
'AlertDialog.onOpenChange': {
description: 'Called with the new open state.',
type: '(open: boolean) => void',
},
}}
/>
`AlertDialogAction` and `AlertDialogCancel` also take `size`. Read the open
state from children with `useAlertDialog()`.
## API Reference [#api-reference]
[Base UI - Alert Dialog](https://base-ui.com/react/components/alert-dialog#api-reference)
# Alert (/docs/ui/alert)
## Preview [#preview]
<Preview name="alert" />
## Usage [#usage]
```ts
import {
Alert,
AlertDescription,
AlertTitle,
} from '@vitnode/core/components/ui/alert'
```
```tsx
<Alert variant="warning">
<AlertTitle>Cron adapter missing</AlertTitle>
<AlertDescription>
Scheduled jobs won't run until you configure one.
</AlertDescription>
</Alert>
```
Alerts match the callouts in these docs and the
[Editor](/docs/ui/editor#panels) panels, so a warning reads the same
everywhere.
## Variants [#variants]
- `default` - a neutral note on a plain card, with no icon.
- `info` - useful context.
- `success` - something finished and went well.
- `warning` - a non-blocking caution worth acting on.
- `destructive` - an error or a failed action.
Every variant except `default` brings its own icon.
## Screen readers [#screen-readers]
`warning` and `destructive` get `role="alert"`, so screen readers interrupt to
read them. The rest use `role="status"` and wait their turn. For a static hint
that's on the page from the start, pass `role="note"`:
```tsx
<Alert role="note" variant="warning">
<AlertTitle>Exports run nightly</AlertTitle>
</Alert>
```
## Custom icon [#custom-icon]
<Preview name="alert-icon" />
Pass any icon to `icon`, or `null` for none.
```tsx
<Alert icon={<HardDriveIcon />} variant="info">
<AlertTitle>Storage is connected</AlertTitle>
</Alert>
```
## Dismissible [#dismissible]
<Preview name="alert-dismissible" />
`AlertAction` pins a control to the top end corner, and the alert makes room
for it.
```tsx
<Alert variant="warning">
<AlertTitle>Maintenance tonight at 22:00</AlertTitle>
<AlertAction>
<Button aria-label="Dismiss" size="icon-sm" variant="ghost">
<XIcon />
</Button>
</AlertAction>
</Alert>
```
## Props [#props]
<TypeTable
type={{
variant: {
description: 'Color, icon and default role.',
type: 'default | info | success | warning | destructive',
default: 'default',
},
icon: {
description: "Replaces the variant's icon. null hides it.",
type: 'ReactNode',
default: "the variant's icon (none for default)",
},
role: {
description: 'Overrides the ARIA role.',
type: 'AriaRole',
default: 'alert for warning and destructive, status otherwise',
},
}}
/>
# Aspect Ratio (/docs/ui/aspect-ratio)
## Preview [#preview]
<Preview name="aspect-ratio" />
## Usage [#usage]
```ts
import { AspectRatio } from '@vitnode/core/components/ui/aspect-ratio'
```
```tsx
<AspectRatio className="overflow-hidden rounded-lg" ratio={16 / 9}>
<img
alt="Forum dashboard"
className="size-full object-cover"
src="/dashboard.webp"
/>
</AspectRatio>
```
The box fills its width and derives its height from `ratio`, so nothing jumps
while the image loads. `size-full object-cover` fills it without stretching.
## Common ratios [#common-ratios]
<Preview name="aspect-ratio-ratios" />
`ratio` is width divided by height: `16 / 9` for video, `4 / 3` for photos, `1`
for avatars, `9 / 16` for phone screenshots.
## Video embed [#video-embed]
```tsx
<AspectRatio ratio={16 / 9}>
<iframe
allowFullScreen
className="size-full rounded-lg"
src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
title="Getting started with VitNode"
/>
</AspectRatio>
```
Give every `iframe` a `title`, so screen readers can name it.
## Props [#props]
<TypeTable
type={{
ratio: {
description: 'Width divided by height, for example `16 / 9`.',
type: 'number',
default: '1',
},
}}
/>
Every other prop goes to the underlying `div`.
# Attachment (/docs/ui/attachment)
## Preview [#preview]
<Preview name="attachment-auto-form" />
Pick a file and watch the progress bar. Hit × mid-upload to cancel.
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
`AutoFormFile` takes one file, `AutoFormFiles` takes many. The form stores
**file ids**: a number for one file, an array of numbers for many.
```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormFile } from '@vitnode/core/components/form/fields/file'
import { AutoFormFiles } from '@vitnode/core/components/form/fields/files'
const formSchema = z.object({
avatar: z.number().nullable().default(null),
gallery: z.array(z.number()).max(4).default([]),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'avatar',
component: (props) => (
<AutoFormFile
{...props}
allowedExtensions={['.png', '.jpg', '.webp']}
label="Avatar"
maxBytes={5 * 1024 * 1024}
onUpload={uploadFile}
/>
),
},
{
id: 'gallery',
component: (props) => (
<AutoFormFiles
{...props}
label="Gallery"
maxBytes={5 * 1024 * 1024}
maxItems={4}
onUpload={uploadFile}
/>
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
<Preview name="attachment" />
```ts
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from '@vitnode/core/components/ui/attachment'
```
```tsx
<Attachment>
<AttachmentMedia variant="image">
<img alt="" src={file.url} />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>{file.name}</AttachmentTitle>
<AttachmentDescription>48 KB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label={`Remove ${file.name}`} onClick={remove}>
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
```
</Tab>
</Tabs>
## Uploading [#uploading]
`onUpload(file, { onProgress, signal })` uploads the picked `File` and returns
the stored file (`{ id, name, size, url, mimeType? }`). The field saves its `id`.
- Call `onProgress(fraction)` with `0` to `1` to show a percentage. Skip it and
the card shimmers instead.
- Pass `signal` to your request. Cancelling from the card aborts it, and any late
response is ignored.
- Throw to fail. The file stays as an error card with a **Try again** button.
`fetch` can't report upload progress, so use `XMLHttpRequest` for the bar:
```ts
import type {
AutoFormFileValue,
FileUploadOptions,
} from '@vitnode/core/components/form/fields/file'
const uploadFile = async (
file: File,
{ onProgress, signal }: FileUploadOptions,
): Promise<AutoFormFileValue> =>
await new Promise((resolve, reject) => {
const body = new FormData()
body.append('file', file)
const xhr = new XMLHttpRequest()
xhr.open('POST', '/api/my-plugin/uploads')
xhr.responseType = 'json'
xhr.upload.onprogress = (event) => {
if (event.lengthComputable) onProgress(event.loaded / event.total)
}
xhr.onload = () =>
xhr.status < 300
? resolve(xhr.response)
: reject(new Error('Upload failed'))
xhr.onerror = () => reject(new Error('Upload failed'))
signal.addEventListener('abort', () => xhr.abort())
xhr.send(body)
})
```
## Removing and existing files [#removing-and-existing-files]
Removing a file from `AutoFormFiles` shows a toast with **Undo**, which puts it
back in the same spot. Misclicks shouldn't cost a re-upload.
Editing a record with files? Pass `file={existing}` or `files={existing}` to
show them.
## Limits [#limits]
Files are checked **before** upload, so nobody waits on a 2 GB video just to
hear it's too big.
| Prop | Field | Example |
| ------------------- | --------------- | ------------------------------ |
| `maxBytes` | both, required | `5 * 1024 * 1024` |
| `allowedExtensions` | both | `['.pdf', '.png']` (lowercase) |
| `allowedMimeTypes` | both | `['image/png']` |
| `maxItems` | files, required | `4` |
| `minItems` | files | `1` |
| `ordered` | files | `false` turns off reordering |
Files reorder by drag or keyboard. Check the same limits on your server: the
browser check can't stop someone determined.
## States [#states]
<Preview name="attachment-states" />
Set `state` on `Attachment`: `idle`, `uploading`, `processing`, `done`
(default) or `error`. In `error`, say what went wrong.
## Layouts [#layouts]
<Preview name="attachment-layouts" className="*:max-w-full" />
- `size`: `default`, `sm` or `xs` for chat composers and tight lists.
- `orientation="vertical"` turns it into a card with a big preview.
- `AttachmentGroup` makes a horizontal scroll row that fades at the edges.
- `AttachmentTrigger` makes the whole attachment clickable. Render it as a link
to open the file. Focus shows one ring on the attachment, not two.
- `AttachmentTitle` keeps the extension visible and truncates the rest:
`quarterly-rep….pdf`.
## Accessibility [#accessibility]
- Give every `AttachmentAction` an `aria-label` naming the file: "Remove
report.pdf". Plain "Remove" is a riddle when there are five files.
- Previews sit next to the file name, so `alt=""` is right.
- The fields announce reordering and list each rejected file with the reason.
- The whole drop zone is clickable. It only lights up when the drag carries
files.
- On touch screens, actions and drag handles grow to a 40px hit area.
# Auto Form (/docs/ui/auto-form)
## Preview [#preview]
<Preview name="auto-form" className="*:max-w-full" />
## Usage [#usage]
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormInput } from '@vitnode/core/components/form/fields/input'
import { z } from 'zod'
const formSchema = z.object({
username: z
.string()
.min(3, 'Usernames need at least 3 characters')
.default(''),
email: z.email().describe('Only used for notifications.').default(''),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'username',
component: (props) => <AutoFormInput {...props} label="Username" />,
},
{
id: 'email',
component: (props) => (
<AutoFormInput {...props} label="Email" type="email" />
),
},
]}
onSubmit={(values) => {
toast.success('Account created', { description: values.username })
}}
/>
```
The schema drives validation, defaults and HTML attributes. Each field's `id`
points at a schema key, and `component` decides how it looks.
## Field types [#field-types]
Import each one from `@vitnode/core/components/form/fields/<file>`. Spread
`props` first, then your own props. Spread it last and the schema's empty
`description` overwrites yours.
| Component | File | Docs |
| ------------------------ | ----------------- | ------------------------------------------------- |
| `AutoFormInput` | `input` | [Input](/docs/ui/input) |
| `AutoFormTextarea` | `textarea` | [Textarea](/docs/ui/textarea) |
| `AutoFormCheckbox` | `checkbox` | [Checkbox](/docs/ui/checkbox) |
| `AutoFormSwitch` | `switch` | [Switch](/docs/ui/switch) |
| `AutoFormRadioGroup` | `radio-group` | [Radio Group](/docs/ui/radio-group) |
| `AutoFormSelect` | `select` | [Select](/docs/ui/select) |
| `AutoFormCombobox` | `combobox` | [Combobox](/docs/ui/combobox) |
| `AutoFormCascader` | `cascader` | [Cascader](/docs/ui/cascader) |
| `AutoFormNumber` | `number` | [Number Field](/docs/ui/number-field) |
| `AutoFormNullableNumber` | `nullable-number` | [Nullable Number](/docs/ui/nullable-number) |
| `AutoFormInputOTP` | `input-otp` | [Input OTP](/docs/ui/input-otp) |
| `AutoFormColor` | `color` | [Color](/docs/ui/color) |
| `AutoFormEmojiIcon` | `emoji-icon` | [Emoji & Icon Picker](/docs/ui/emoji-icon-picker) |
| `AutoFormEditor` | `editor` | [Editor](/docs/ui/editor) |
| `AutoFormFile` | `file` | [Attachment](/docs/ui/attachment) |
| `AutoFormFiles` | `files` | [Attachment](/docs/ui/attachment) |
| `AutoFormRoles` | `input-roles` | [Roles](/docs/ui/roles) |
| `AutoFormUser` | `input-users` | [User](/docs/ui/user) |
| `AutoFormDatePicker` | `date-picker` | [Date Picker](/docs/ui/date-picker) |
| `AutoFormDateTime` | `date-time` | - |
| `AutoFormArray` | `array` | [Arrays](#arrays) |
Every field takes `label`, `labelRight` (content pinned to the label's right
edge), `description` and [`tip`](#field-tips).
## Field tips [#field-tips]
<Preview name="auto-form-tip" className="*:max-w-full" />
`tip` adds a small question-mark button right after the label. It opens a
bubble with extra help that most people can skip. Every built-in field
supports it, `AutoFormArray` included.
```tsx
{
id: "slug",
component: props => (
<AutoFormInput
{...props}
label={t("slug.label")}
description={t("slug.description")}
tip={t("slug.tip")}
labelRight={<Badge variant="secondary">{t("public")}</Badge>}
/>
),
}
```
Pick the right slot for your text:
| Prop | Shows | Use it for |
| ------------- | ------------------------------------------ | ----------------------------------------- |
| `label` | Always, above the control | The field's name |
| `description` | Always, below the control | What the field does, in one line |
| `tip` | Only when asked, in a bubble by the label | Background, edge cases, "why would I..." |
| `labelRight` | Always, at the end of the label row | Actions, badges, a language switcher |
- **Mouse:** hover the icon for a moment, then move onto the bubble to read it.
Or click the icon: the bubble stays open until you click it again or
anywhere else.
- **Touch:** tap the icon to open, tap it again or anywhere else to close.
- **Keyboard:** Tab reaches the icon, Enter or Space opens it, Escape closes it.
Pressing the icon never focuses the control, toggles a checkbox or switch, or
submits the form. When a submit fails, focus still lands on the invalid
control, not on the icon. Empty values (`undefined`, `""`, `false`) render no
icon, so `tip={isAdmin && t("slug.tip")}` is fine.
Translate the tip like the label, with `use-intl`. In a
[multi-language field](#multi-language-fields) it stays in the UI language
while you switch the language you're editing.
## Schema [#schema]
```ts
const formSchema = z.object({
username: z.string().min(3).max(20).default('captain'),
bio: z.string().describe('Shown on your profile card.').optional(),
role: z.enum(['member', 'admin']).default('member'),
})
```
- Fields are required unless the schema says `.optional()`. Optional fields get
an "Optional" hint next to the label.
- `.default()` sets the starting value. Give required strings `.default('')`:
without it an untouched field says "expected string, received undefined"
instead of your `.min()` message.
- `.describe()` becomes the description, unless you pass `description`.
- String `.min()`, `.max()` and `.regex()` become `minLength`, `maxLength` and
`pattern` on the control. `z.enum()` values feed selects and radio groups.
- Any Zod check works, `.refine()` included. Its `message` is what users see.
## Validation [#validation]
<Preview name="auto-form-validation" className="*:max-w-full" />
By default a message appears once you leave a field, then updates live as you
type. Switch the modes above to feel the difference.
| `mode` | A field's message appears… |
| ----------------------- | ------------------------------ |
| `"onTouched"` (default) | once the field has been left |
| `"onBlur"` | once the field has been left |
| `"onChange"` / `"all"` | as soon as the field is edited |
| `"onSubmit"` | after the first submit attempt |
The submit button stays enabled while the form is invalid. Pressing it never
calls `onSubmit`. Instead every message appears, invalid fields shake, and
focus jumps to the first one.
```tsx
<AutoForm formSchema={formSchema} fields={fields} mode="onChange" />
```
## Submit [#submit]
`onSubmit` receives the parsed values, the TanStack Form instance, and
`{ captchaToken, intent }`. While it runs, the button shows a spinner.
```tsx
import type { AutoFormOnSubmit } from '@vitnode/core/components/form/auto-form'
const onSubmit: AutoFormOnSubmit<typeof formSchema> = async (values, form) => {
await saveProfile(values)
form.reset()
toast.success('Profile saved', { description: values.username })
}
```
Restyle the button with `submitButtonProps`:
```tsx
<AutoForm
submitButtonProps={{ children: 'Save changes', variant: 'outline' }}
/>
```
Pass a route's `captcha` config and the button waits for the captcha to load.
Send `captchaToken` along with your request.
<Callout>
Inside a [Dialog](/docs/ui/dialog), AutoForm renders a footer with Cancel and
Submit. Any form with unsaved changes asks before the page unloads.
</Callout>
### Errors from the server [#errors-from-the-server]
<Preview name="auto-form-server-error" className="*:max-w-full" />
The API said no? Put its message on the field with `setFormFieldError`. It
focuses the field, blocks submit while the rejected value stays, and clears
once the user edits it.
```tsx
import { setFormFieldError } from "@vitnode/core/components/form/auto-form";
onSubmit={async (values, form) => {
const res = await updateUsername(values);
if (res.status === 409) {
setFormFieldError(form, "username", "That username is taken");
}
}}
```
## Tabs [#tabs]
<Preview name="auto-form-tabs" className="*:max-w-full" />
Pass `tabs` and tag fields with `tab`. Untagged fields go to the first tab. All
panels stay mounted, so values survive tab switches.
Press Save on **General** above. The error lives on **SEO**, so AutoForm
switches there, and tabs hiding an error get a red dot.
```tsx
<AutoForm
tabs={[
{ value: 'general', label: 'General' },
{ value: 'seo', label: 'SEO' },
]}
fields={[
{
id: 'name',
component: (props) => <AutoFormInput {...props} label="Name" />,
},
{
id: 'metaTitle',
tab: 'seo',
component: (props) => <AutoFormInput {...props} label="Meta title" />,
},
]}
/>
```
## Conditional fields [#conditional-fields]
<Preview name="auto-form-conditional" className="*:max-w-full" />
`hidden` gets the live values. Return `true` to hide the field.
```tsx
{
id: "password",
hidden: values => values.visibility !== "password",
component: props => <AutoFormInput {...props} label="Forum password" type="password" />,
}
```
<Callout type="warn">
Hidden fields still submit. Make them `.optional()` or give them a
`.default()`, or an invisible error blocks the form.
</Callout>
### Nested fields [#nested-fields]
<Preview name="auto-form-nested-fields" />
A switch and the settings it unlocks can share one card. Pass them as
`children` of an `AutoFormSwitch` field: they expand when it's on.
```tsx
{
id: "allow_uploads",
component: props => <AutoFormSwitch {...props} label="Allow uploads" />,
children: [
{
id: "max_storage",
component: props => <AutoFormNumber {...props} label="Maximum file size" />,
},
],
}
```
Children unmount while the switch is off, so give them a `.default()`. They can
have their own `hidden`. Their `tab` is ignored: they live in the parent's tab.
## Arrays [#arrays]
<Preview name="auto-form-array" className="*:max-w-full" />
`AutoFormArray` edits a `z.array(z.object(...))` as rows you can add and
remove. Schema `.min()` and `.max()` limit the rows.
```tsx
{
id: "links",
component: props => (
<AutoFormArray
{...props}
label="Sidebar links"
addButtonLabel="Add link"
fields={[
{ id: "title", component: p => <AutoFormInput {...p} label="Title" /> },
{ id: "url", component: p => <AutoFormInput {...p} label="URL" /> },
]}
/>
),
}
```
| Prop | Type | Default |
| ------------------ | --------------------------------- | ---------------------- |
| `fields` | `{ id, component, className? }[]` | required |
| `addButtonLabel` | `string` | `"Add Item"` |
| `minItems` | `number` | schema `.min()` or `0` |
| `maxItems` | `number` | schema `.max()` |
| `showRemoveButton` | `boolean` | `true` |
| `className` | `string` | - |
## Layout [#layout]
For a simple grid, `className` is enough:
```tsx
<AutoForm className="grid grid-cols-1 gap-4 md:grid-cols-2" />
```
<Preview name="auto-form-layout" className="*:max-w-full" />
For full control, `layout` receives every rendered field by `id`. You place
the submit button yourself with `AutoFormSubmitButton`. Give it an `intent` to
tell buttons apart in `onSubmit`.
```tsx
import {
AutoForm,
AutoFormSubmitButton,
} from '@vitnode/core/components/form/auto-form'
```
```tsx
<AutoForm
layout={(rendered) => (
<>
<div className="grid grid-cols-1 gap-6 sm:grid-cols-2">
{rendered.firstName}
{rendered.lastName}
</div>
<AutoFormSubmitButton intent="draft" variant="ghost">
Save draft
</AutoFormSubmitButton>
<AutoFormSubmitButton intent="publish">Publish</AutoFormSubmitButton>
</>
)}
onSubmit={(values, form, { intent }) => {}}
/>
```
## Custom fields [#custom-fields]
<Preview name="auto-form-custom-field" className="*:max-w-full" />
A field is any component. Build it from AutoForm's parts and it gets the same
ids, ARIA and errors as the built-in ones:
- `AutoFormLabel` and `AutoFormDesc` render the label and description. Pass
`tip` to `AutoFormLabel` for the [help icon](#field-tips).
- `FormControl` passes `id`, `aria-invalid` and `aria-describedby` to its child.
- `FormMessage` shows the field's errors.
Type `field` with `FormFieldApi<TValue>` so a wrong value is a build error.
`field.onChange` takes the value or a DOM change event.
```tsx
import type {
FormFieldApi,
ItemAutoFormComponentProps,
} from '@vitnode/core/components/form/auto-form'
import { AutoFormDesc } from '@vitnode/core/components/form/common/desc'
import { AutoFormLabel } from '@vitnode/core/components/form/common/label'
import { FormControl, FormMessage } from '@vitnode/core/components/ui/form'
const SlowModeField = ({
label,
description,
tip,
field,
}: Omit<ItemAutoFormComponentProps, 'field'> & {
field: FormFieldApi<number>
}) => (
<>
<AutoFormLabel tip={tip}>{label}</AutoFormLabel>
<FormControl>
<input
type="range"
max={120}
name={field.name}
value={field.value}
onBlur={field.onBlur}
onChange={(e) => field.onChange(Number(e.target.value))}
/>
</FormControl>
{!!description && <AutoFormDesc>{description}</AutoFormDesc>}
<FormMessage />
</>
)
```
For a two-column settings row, wrap the parts in [Field](/docs/ui/field#inside-a-custom-autoform-field).
## Multi-language fields [#multi-language-fields]
`AutoFormInput`, `AutoFormTextarea` and `AutoFormEditor` take `multiLang`. The
value becomes `{ languageCode, value }[]`, and a language select appears when
more than one language is enabled. It only switches what you're editing, not
the app locale.
```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 /> }
```
- `minLength` and `maxLength` apply to each language's value.
- Languages come from [`i18n.locales`](/docs/dev/i18n), minus any with
[`enabled: false`](/docs/dev/i18n#disabling-one).
- The select opens on the first language with text: yours, then the form's
default (a content type's `defaultLocale`), then any other. Empty editor
markup like `<p></p>` counts as empty.
### Saving to the backend [#saving-to-the-backend]
`saveLanguageWords` stores the array in `core_languages_words`, replacing the
old rows in one transaction.
```ts title="plugins/{plugin_name}/src/api/routes/create-category.route.ts"
import { saveLanguageWords } from '@vitnode/core/api/lib/save-language-words'
await saveLanguageWords(c, {
pluginCode: 'blog',
tableName: 'blog_categories',
variable: 'name',
itemId: category.id,
values: name,
})
```
To prefill an edit form, query `core_languages_words` by the same
`(pluginCode, tableName, variable, itemId)` and return
`{ languageCode, value }[]`, like
[`resolveRoleNames`](/docs/dev/working-with-users/roles) does.
## Props [#props]
<TypeTable
type={{
formSchema: {
description:
'Zod object that drives validation, defaults and attributes.',
type: 'z.ZodObject',
required: true,
},
fields: {
description: 'Field definitions, rendered in order.',
type: '{ id, component, tab?, hidden?, children? }[]',
required: true,
},
onSubmit: {
description: 'Runs with valid values only.',
type: '(values, form, { captchaToken, intent }) => void | Promise<void>',
},
mode: {
description: 'When field messages appear.',
type: '"onTouched" | "onBlur" | "onChange" | "all" | "onSubmit"',
default: '"onTouched"',
},
tabs: {
description: 'Splits fields into tabs. Fields pick one with `tab`.',
type: '{ value: string; label: ReactNode }[]',
},
layout: {
description:
'Places rendered fields yourself. No submit button is added, use `AutoFormSubmitButton`.',
type: '(rendered: Record<string, ReactNode>) => ReactNode',
},
submitButtonProps: {
description: 'Props for the default submit button.',
type: 'ButtonProps',
},
captcha: {
description: "The route's captcha config. Adds the widget and a token.",
type: 'RouteCaptcha',
},
canSubmitWhenInvalid: {
description: "Passed to TanStack Form's option of the same name.",
type: 'boolean',
default: 'true',
},
children: {
description: 'Rendered after the fields, before the submit button.',
type: 'ReactNode',
},
}}
/>
Any other `<form>` prop (`className`, `id`, `onKeyDown`) goes to the form
element.
# Avatar (/docs/ui/avatar)
## Preview [#preview]
<Preview name="avatar" />
## Usage [#usage]
```ts
import {
Avatar,
AvatarFallback,
AvatarImage,
} from '@vitnode/core/components/ui/avatar'
```
```tsx
<Avatar>
<AvatarImage alt="Ada Lovelace" src={user.avatarUrl} />
<AvatarFallback>AL</AvatarFallback>
</Avatar>
```
## Fallback [#fallback]
<Preview name="avatar-fallback" />
The fallback shows while the image loads and stays if it never arrives. Once
loaded, the image fades in instead of popping.
## Sizes [#sizes]
```tsx
<Avatar size="sm" />
<Avatar />
<Avatar size="lg" />
```
## Badge [#badge]
`AvatarBadge` adds a status dot. Give it a semantic background:
```tsx
<Avatar>
<AvatarImage alt="Ada Lovelace" src={user.avatarUrl} />
<AvatarFallback>AL</AvatarFallback>
<AvatarBadge className="bg-success" />
</Avatar>
```
A dot alone doesn't tell everyone someone is online. Say it in text too, or
give the badge an `aria-label`.
## Group [#group]
`AvatarGroup` stacks avatars. Wrap each in `AvatarGroupItem` to lift it on
hover and show a tooltip, and end with `AvatarGroupCount`:
```ts
import {
AvatarGroup,
AvatarGroupCount,
AvatarGroupItem,
} from '@vitnode/core/components/ui/avatar'
```
```tsx
<AvatarGroup>
{users.map((user) => (
<AvatarGroupItem key={user.id} label={user.name}>
<Avatar>
<AvatarImage alt={user.name} src={user.avatarUrl} />
<AvatarFallback>{user.initials}</AvatarFallback>
</Avatar>
</AvatarGroupItem>
))}
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
```
The whole group shares one tooltip, so it glides from face to face. Plain
`Avatar`s inside a group make a quiet stack with no hover effect.
## Member avatars [#member-avatars]
<Preview name="avatar-letter" />
For VitNode users, reach for `Avatar` from `@vitnode/core/components/avatar`.
It shows the stored picture, or the first letter of `nameCode` on the
member's `avatarColor` in white.
```ts
import { Avatar } from '@vitnode/core/components/avatar'
```
```tsx
<Avatar size={32} user={user} />
```
`user` needs `name`, `nameCode`, `avatarColor` (hex without `#`) and an
optional `avatarUrl`. A broken `avatarUrl` falls back to the letter.
## Accessibility [#accessibility]
- Always pass `alt` to `AvatarImage`. The person's name is usually perfect.
- An `AvatarGroupItem` with a `label` is focusable, and its tooltip opens on
focus as well as hover.
- With reduced motion, group avatars stay put and only the tooltip appears.
## Props [#props]
### Avatar [#avatar]
<TypeTable
type={{
size: {
description: 'Size of the avatar.',
type: '"sm" | "default" | "lg"',
default: '"default"',
},
}}
/>
### AvatarGroupItem [#avatargroupitem]
<TypeTable
type={{
label: {
description:
"Tooltip on hover and focus. Without it, the avatar still lifts but isn't focusable.",
type: 'ReactNode',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Avatar](https://base-ui.com/react/components/avatar)
# Badge (/docs/ui/badge)
<Preview name="badge" />
## Usage [#usage]
```ts
import { Badge } from '@vitnode/core/components/ui/badge'
```
```tsx
<Badge variant="success">Published</Badge>
```
## Variants [#variants]
Let the word carry the meaning and the color back it up.
| Variant | Use it for |
| --------------------------------- | ------------------------------------------- |
| `default` | A prominent, neutral label. |
| `secondary` / `outline` / `ghost` | Quiet labels in dense UI like tables. |
| `link` | A label that looks like a text link. |
| `success` | Healthy or done: Published, Active, Paid. |
| `warning` | Needs attention: Pending, Expiring, Draft. |
| `destructive` | Failed or blocked: Failed, Banned, Overdue. |
Status variants share their tint with the matching button, so a `success`
badge and a `success` button read as the same idea.
## With an icon [#with-an-icon]
<Preview name="badge-icon" />
Icons shrink to 12px. Mark them `data-icon="inline-start"` or
`data-icon="inline-end"` to tighten the padding on that side.
```tsx
<Badge variant="success">
<BadgeCheck data-icon="inline-start" />
Verified
</Badge>
```
## Counter [#counter]
<Preview name="badge-counter" />
Numbers are tabular, so counts don't jiggle. Add `min-w-5 px-1` for a round
pill, and `sr-only` text so "8" means something to screen readers.
```tsx
<Badge className="min-w-5 px-1">
8<span className="sr-only">unread messages</span>
</Badge>
```
## As a link [#as-a-link]
<Preview name="badge-link" />
Pass `render` to make the badge a link. Links get a hover state.
```tsx
<Badge render={<a href="/tags/announcements" />} variant="secondary">
#announcements
</Badge>
```
## Props [#props]
<TypeTable
type={{
variant: {
description: 'The look of the badge.',
type: 'default | secondary | outline | ghost | link | success | warning | destructive',
default: 'default',
},
render: {
description: 'Replaces the `span`, such as with an `a`.',
type: 'ReactElement | ((props, state) => ReactElement)',
},
}}
/>
# Bubble (/docs/ui/bubble)
## Preview [#preview]
<Preview name="bubble" />
## Usage [#usage]
```ts
import {
Bubble,
BubbleContent,
BubbleGroup,
BubbleReactions,
} from '@vitnode/core/components/ui/bubble'
```
```tsx
<Bubble>
<BubbleContent>I removed the stale route. You are welcome.</BubbleContent>
</Bubble>
```
A bubble shrinks to fit its text and never grows past 80% of the row. New
bubbles grow in from their tail corner; with reduced motion they only fade.
## Variants [#variants]
<Preview name="bubble-variants" />
`default` is usually the current user, `secondary` the standard reply. `ghost`
drops the frame and takes the full width.
## Alignment [#alignment]
Your messages go on the end side, everyone else's on the start.
```tsx
<Bubble align="end">
<BubbleContent>Sent by me.</BubbleContent>
</Bubble>
```
## Grouping [#grouping]
`BubbleGroup` tightens the spacing between consecutive bubbles from one
sender. Set `align` on each `Bubble`, not on the group.
```tsx
<BubbleGroup>
<Bubble variant="muted">
<BubbleContent>First thought.</BubbleContent>
</Bubble>
<Bubble variant="muted">
<BubbleContent>Second thought, arriving fashionably late.</BubbleContent>
</Bubble>
</BubbleGroup>
```
## Reactions [#reactions]
<Preview name="bubble-reactions" />
`BubbleReactions` pins a pill to the bubble's edge. It overlaps the bubble, so
leave extra `gap` between rows.
```tsx
<BubbleReactions aria-label="Reactions: rocket, eyes" role="img" side="top">
<span>🚀</span>
<span>👀</span>
</BubbleReactions>
```
## Links and buttons [#links-and-buttons]
Use `render` on `BubbleContent` to make a bubble a real link or button, like a
quick-reply suggestion.
```tsx
<Bubble variant="outline">
<BubbleContent render={<button onClick={onPick} type="button" />}>
Show me the plugin docs
</BubbleContent>
</Bubble>
```
## Use with Message [#use-with-message]
For an avatar, sender name or read receipt, wrap bubbles in a
[Message](/docs/ui/message). Bubbles inside follow the message's `align`.
## Accessibility [#accessibility]
- `Bubble` is only the visual surface. Put `role="log"` and an `aria-label` on
the conversation container.
- Give `BubbleReactions` `role="img"` and an `aria-label`, so screen readers
announce it once instead of reading every emoji. Interactive reactions should
be labelled buttons.
- Clickable bubbles must be a real `<button>` or `<a>` via `render`.
- Variants signal tone with color, so keep the meaning in the text too.
## Props [#props]
### Bubble [#bubble]
<TypeTable
type={{
variant: {
description: 'Visual treatment.',
type: 'default | secondary | muted | tinted | outline | ghost | destructive',
default: 'default',
},
align: {
description: 'Which side of the conversation it sits on.',
type: 'start | end',
default: 'start',
},
}}
/>
### BubbleContent [#bubblecontent]
<TypeTable
type={{
render: {
description:
'Renders the content as another element, like a link or button.',
type: 'ReactElement | function',
},
}}
/>
### BubbleReactions [#bubblereactions]
<TypeTable
type={{
side: {
description: 'Edge of the bubble the reactions sit on.',
type: 'top | bottom',
default: 'bottom',
},
align: {
description: 'Inline position along that edge.',
type: 'start | end',
default: 'end',
},
}}
/>
## API Reference [#api-reference]
[Base UI - useRender](https://base-ui.com/react/utils/use-render)
# Button Group (/docs/ui/button-group)
## Preview [#preview]
<Preview name="button-group" />
## Usage [#usage]
```ts
import {
ButtonGroup,
ButtonGroupSeparator,
ButtonGroupText,
} from '@vitnode/core/components/ui/button-group'
```
```tsx
<ButtonGroup aria-label="Message actions">
<Button variant="outline">Archive</Button>
<Button variant="outline">Report</Button>
<Button variant="outline">Snooze</Button>
</ButtonGroup>
```
Inner borders merge and only the outer corners stay round. The buttons need no
extra props.
## Orientation [#orientation]
```tsx
<ButtonGroup aria-label="Zoom" orientation="vertical">
<Button aria-label="Zoom in" size="icon-sm" variant="outline">
<ZoomInIcon />
</Button>
<Button aria-label="Zoom out" size="icon-sm" variant="outline">
<ZoomOutIcon />
</Button>
</ButtonGroup>
```
## Nested groups [#nested-groups]
Groups inside a group get a small gap between them, the classic toolbar look.
```tsx
<ButtonGroup aria-label="Message actions">
<ButtonGroup>
<Button aria-label="Go back" size="icon" variant="outline">
<ArrowLeftIcon />
</Button>
</ButtonGroup>
<ButtonGroup>
<Button variant="outline">Archive</Button>
<Button variant="outline">Report</Button>
</ButtonGroup>
</ButtonGroup>
```
## Separator [#separator]
Borderless variants like `secondary` blur into one blob. Put a
`ButtonGroupSeparator` between them.
```tsx
<ButtonGroup aria-label="Text alignment">
<Button aria-label="Align left" size="icon" variant="secondary">
<AlignLeftIcon />
</Button>
<ButtonGroupSeparator />
<Button aria-label="Align center" size="icon" variant="secondary">
<AlignCenterIcon />
</Button>
</ButtonGroup>
```
Inside a vertical group, use `<ButtonGroupSeparator orientation="horizontal" />`.
## With text [#with-text]
`ButtonGroupText` is a non-interactive segment, like a counter. Use `render`
to swap the element, for example to a `<label>`.
```tsx
<ButtonGroup aria-label="Quantity">
<Button aria-label="Decrease quantity" size="icon" variant="outline">
<MinusIcon />
</Button>
<ButtonGroupText aria-live="polite">{quantity}</ButtonGroupText>
<Button aria-label="Increase quantity" size="icon" variant="outline">
<PlusIcon />
</Button>
</ButtonGroup>
```
## With input [#with-input]
An `Input` stretches to fill the free space.
```tsx
<ButtonGroup className="w-full max-w-sm">
<Input aria-label="Search members" placeholder="Search members..." />
<Button aria-label="Search" size="icon" variant="outline">
<SearchIcon />
</Button>
</ButtonGroup>
```
## Split button [#split-button]
Pair a button with a [Dropdown Menu](/docs/ui/dropdown-menu) trigger.
```tsx
<ButtonGroup>
<Button variant="outline">Snooze</Button>
<DropdownMenu>
<DropdownMenuTrigger
render={
<Button
aria-label="More snooze options"
size="icon"
variant="outline"
/>
}
>
<ChevronDownIcon />
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
<DropdownMenuItem>Later today</DropdownMenuItem>
<DropdownMenuItem>Next week</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
</ButtonGroup>
```
## Sizes [#sizes]
The group follows its buttons. Use the same `size` on all of them so heights
match.
## Accessibility [#accessibility]
- The group has `role="group"`. Give it an `aria-label` or `aria-labelledby`.
- Icon-only buttons need their own `aria-label`.
- A focused button lifts above its neighbours, so the focus ring never hides.
- Borders and corners flip correctly in right-to-left languages.
- Need a selected state, like a segmented control? Use
[Toggle Group](/docs/ui/toggle-group).
## Props [#props]
### ButtonGroup [#buttongroup]
<TypeTable
type={{
orientation: {
description: 'Lays the items out in a row or a column.',
type: 'horizontal | vertical',
default: 'horizontal',
},
'aria-label': {
description: 'Describes what the group does.',
type: 'string',
},
}}
/>
### ButtonGroupText [#buttongrouptext]
<TypeTable
type={{
render: {
description:
'Replaces the default `<div>`, for example with a `<label>`.',
type: 'ReactElement | (props, state) => ReactElement',
},
}}
/>
### ButtonGroupSeparator [#buttongroupseparator]
<TypeTable
type={{
orientation: {
description:
'Direction of the line. Use `horizontal` in a vertical group.',
type: 'horizontal | vertical',
default: 'vertical',
},
}}
/>
All parts accept `className`.
## API Reference [#api-reference]
[shadcn/ui - Button Group](https://ui.shadcn.com/docs/components/base/button-group)
# Button (/docs/ui/button)
## Preview [#preview]
<Preview name="button" />
## Usage [#usage]
```ts
import { Button } from '@vitnode/core/components/ui/button'
```
```tsx
<Button>
<SendIcon />
Post reply
</Button>
```
A press dips the button to `active:scale-97`, so every click feels
acknowledged. Inside a [Button Group](/docs/ui/button-group) it darkens
instead, and menu triggers stay put.
## Variants [#variants]
Pick the variant by the weight of the action, not your favourite colour:
- `default` - the one primary action on the screen.
- `secondary`, `outline`, `ghost` - supporting actions, loudest to quietest.
- `link` - an action that behaves like navigation.
- `success` - approves or completes something.
- `warning` - risky but reversible, like unpublishing.
- `destructive` - deletes data for good.
Colour never carries the meaning alone. A green button still says "Approve".
## Sizes [#sizes]
<Preview name="button-sizes" />
Icon-only sizes (`icon`, `icon-xs`, `icon-sm`, `icon-lg`) require an
`aria-label`, and TypeScript will remind you. On touch screens, `icon`,
`icon-sm` and `icon-xs` get an invisible 44px hit area.
## Loading [#loading]
<Preview name="button-loading" />
`isLoading` swaps the content for a spinner and disables the button. Loading
always wins: `disabled={false}` won't re-enable it, and screen readers hear
"Loading" instead of your `aria-label`.
```tsx
<Button isLoading={isPending}>Save changes</Button>
```
## Disabled with a reason [#disabled-with-a-reason]
<Preview name="button-disabled" />
A greyed-out button with no explanation is a riddle. Add `disabledTooltip` to
say _why_.
```tsx
<Button disabled disabledTooltip="You need the Publish permission">
Publish
</Button>
```
The button then uses `aria-disabled`, so it stays focusable, clicks do nothing,
and screen readers read the reason as its description. The tooltip shows only
while `disabled` is `true` and hides during `isLoading`.
## As a link [#as-a-link]
Use `render` to compose the button with another element. Set
`nativeButton={false}` when that element isn't a `<button>`.
```ts
import { Link } from '@tanstack/react-router'
```
```tsx
<Button nativeButton={false} render={<Link to="/" />}>
Home
</Button>
```
## Props [#props]
<TypeTable
type={{
variant: {
description: 'Visual weight of the action.',
type: 'default | secondary | outline | ghost | link | success | warning | destructive',
default: 'default',
},
size: {
description: 'Height and padding. Icon sizes require aria-label.',
type: 'default | sm | lg | icon | icon-xs | icon-sm | icon-lg',
default: 'default',
},
isLoading: {
description: 'Shows a spinner and always disables the button.',
type: 'boolean',
},
disabledTooltip: {
description:
'Explains why the button is disabled. Shown on hover and focus while `disabled` is true.',
type: 'ReactNode',
},
render: {
description: 'Element to render instead of the native button.',
type: 'ReactElement',
},
nativeButton: {
description: 'Set to false when `render` is not a native button.',
type: 'boolean',
default: 'true',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Button](https://base-ui.com/react/components/button#api-reference)
# Calendar (/docs/ui/calendar)
The Calendar shows a month and lets people pick dates from it. Use it inline for booking or reporting screens. For a form field that opens on click, reach for the [Date Picker](/docs/ui/date-picker) instead.
## Preview [#preview]
<Preview name="calendar" />
## Usage [#usage]
```ts
import { Calendar } from '@vitnode/core/components/ui/calendar'
```
```tsx
const [date, setDate] = React.useState<Date>()
<Calendar mode="single" onSelect={setDate} selected={date} />
```
`Calendar` is built on [React DayPicker](https://daypicker.dev), so every DayPicker prop works.
## Date range [#date-range]
<Preview name="calendar-range" className="*:max-w-none" />
Set `mode="range"` and keep a `DateRange` in state. `numberOfMonths` shows months side by side on wider screens and stacks them on phones.
```ts
import { Calendar, type DateRange } from '@vitnode/core/components/ui/calendar'
```
```tsx
const [range, setRange] = React.useState<DateRange>()
<Calendar mode="range" numberOfMonths={2} onSelect={setRange} selected={range} />
```
## Multiple days [#multiple-days]
<Preview name="calendar-multiple" />
`mode="multiple"` collects an array of dates. `max` caps how many can be picked.
```tsx
<Calendar max={3} mode="multiple" onSelect={setDates} selected={dates} />
```
## Disabled days [#disabled-days]
<Preview name="calendar-disabled" />
`disabled` takes a date, an array of dates or a matcher. Here: no past days and no weekends.
```tsx
<Calendar
disabled={[{ before: new Date() }, { dayOfWeek: [0, 6] }]}
mode="single"
/>
```
## Month and year dropdowns [#month-and-year-dropdowns]
<Preview name="calendar-dropdown" />
Typing a birthday by clicking "previous month" 300 times is nobody's idea of fun. `captionLayout="dropdown"` adds month and year selects. Set `startMonth` and `endMonth` to bound the years.
```tsx
<Calendar
captionLayout="dropdown"
endMonth={new Date()}
mode="single"
startMonth={new Date(1926, 0)}
/>
```
Use `dropdown-months` or `dropdown-years` for only one of them.
## Week numbers [#week-numbers]
<Preview name="calendar-week-numbers" />
```tsx
<Calendar mode="single" showWeekNumber />
```
## Today button [#today-button]
<Preview name="calendar-today" />
Control the visible month with `month` and `onMonthChange`, then jump back from a footer button.
```tsx
const [month, setMonth] = React.useState(new Date())
<Calendar month={month} onMonthChange={setMonth} mode="single" />
<Button onClick={() => setMonth(new Date())}>Today</Button>
```
## Presets [#presets]
<Preview name="calendar-presets" className="*:max-w-none" />
Presets are plain buttons that set the range and move the month to it. Handy for analytics filters.
```tsx
<Button
onClick={() => {
setRange({ from: addDays(today, -6), to: today })
setMonth(today)
}}
>
Last 7 days
</Button>
```
## Custom day content [#custom-day-content]
<Preview name="calendar-pricing" />
Swap the day button through `components.DayButton` and render `CalendarDayButton` with extra children. A `<span>` inside it gets small, muted text automatically. A larger `--cell-size` makes room for it.
```tsx
import {
Calendar,
CalendarDayButton,
} from '@vitnode/core/components/ui/calendar'
const PricedDayButton = ({
children,
...props
}: React.ComponentProps<typeof CalendarDayButton>) => (
<CalendarDayButton {...props}>
{children}
<span>${priceFor(props.day.date)}</span>
</CalendarDayButton>
)
<Calendar
className="[--cell-size:--spacing(11)]"
components={{ DayButton: PricedDayButton }}
mode="single"
/>
```
Define the day button outside your component, so React does not remount every day on each render.
## Appointment picker [#appointment-picker]
<Preview name="calendar-appointment" className="*:max-w-none" />
Pair the Calendar with a list of time slots. Reset the slot when the day changes.
## Localization [#localization]
The Calendar follows the active VitNode language with no setup. Month names, weekday names, the first day of the week and screen reader labels all come from the browser's `Intl` API, so no extra locale files land in your bundle. In Polish the week starts on Monday, in the US on Sunday.
Need a date-fns locale for something `Intl` can't do? Add `react-day-picker` to your app, then pass the locale as `locale` and the Calendar uses it instead.
```tsx
import { pl } from 'react-day-picker/locale'
<Calendar locale={pl} mode="single" />
```
Force a different first day with `weekStartsOn={1}`.
## Accessibility [#accessibility]
- The grid is a real ARIA grid. Arrow keys move by day and week, Page Up and Page Down by month, Home and End to the edges of a week.
- Each day reads as its full date, plus "Today" and "selected" when they apply.
- Navigation and dropdown labels are translated through `core.global.calendar`.
- Arrows flip in right-to-left languages.
## Props [#props]
`Calendar` accepts every [DayPicker prop](https://daypicker.dev/api/type-aliases/DayPickerProps), plus:
<TypeTable
type={{
buttonVariant: {
description: 'Button variant for the previous and next month buttons.',
type: "'ghost' | 'outline' | 'secondary' | …",
default: "'ghost'",
},
captionLayout: {
description: 'Plain caption or month/year dropdowns.',
type: "'label' | 'dropdown' | 'dropdown-months' | 'dropdown-years'",
default: "'label'",
},
showOutsideDays: {
description: 'Show days from the previous and next months.',
type: 'boolean',
default: 'true',
},
locale: {
description:
'A date-fns locale. Leave empty to follow the active VitNode language.',
type: 'Locale',
},
}}
/>
## API Reference [#api-reference]
[React DayPicker](https://daypicker.dev)
# Card (/docs/ui/card)
<Preview name="card" />
## Usage [#usage]
```ts
import {
Card,
CardAction,
CardContent,
CardDescription,
CardFooter,
CardHeader,
CardTitle,
} from '@vitnode/core/components/ui/card'
```
```tsx
<Card>
<CardHeader>
<CardTitle>Weekly digest</CardTitle>
<CardDescription>Sent every Monday at 9:00</CardDescription>
</CardHeader>
<CardContent>A roundup of the top threads.</CardContent>
<CardFooter>
<Button variant="outline">Preview email</Button>
</CardFooter>
</Card>
```
`CardFooter` has a top border and a soft background, so it always reads as the
"what now?" part. An `img` as the first or last child goes edge to edge with
rounded corners.
## Size [#size]
<Preview name="card-size" />
`size="sm"` drops the spacing from 24px to 16px and shrinks the title. Use it in
dense grids and sidebars.
```tsx
<Card size="sm">...</Card>
```
## Header with border [#header-with-border]
<Preview name="card-header-border" />
Add `border-b` to `CardHeader` and it gets matching bottom padding.
```tsx
<CardHeader className="border-b">...</CardHeader>
```
## Header and footer [#header-and-footer]
<Preview name="card-header-footer" />
A bordered header plus the footer splits the card into three parts.
## Border separation [#border-separation]
<Preview name="card-border-separation" />
Drop the card padding and let the content draw the lines. `CardAction` keeps a
header button on the end side.
```tsx
<Card className="gap-0 p-0">
<CardHeader className="items-center px-4 py-2">
<CardTitle>Reports</CardTitle>
<CardAction>
<Button size="sm" variant="outline">
Filter
</Button>
</CardAction>
</CardHeader>
<CardContent className="border-y px-4 py-3">...</CardContent>
<CardFooter className="border-none px-4 py-3">...</CardFooter>
</Card>
```
## With a link [#with-a-link]
<Preview name="card-link" />
A slim footer is a good home for a "read more" link.
```tsx
<CardFooter className="py-2">
<a className={cn(buttonVariants({ variant: 'link' }), 'px-0')} href="/guide">
Read the guide
</a>
</CardFooter>
```
## Props [#props]
All parts take regular `div` props.
### Card [#card]
<TypeTable
type={{
size: {
description: 'Spacing inside the card: 24px or 16px.',
type: 'default | sm',
default: 'default',
},
}}
/>
# Carousel (/docs/ui/carousel)
## Preview [#preview]
<Preview name="carousel" />
## Usage [#usage]
```ts
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselNext,
CarouselPrevious,
} from '@vitnode/core/components/ui/carousel'
```
```tsx
<Carousel aria-label="Screenshots">
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>
```
[Embla Carousel](https://www.embla-carousel.com) does the swiping and dragging,
so it moves like a native app, not a 2009 slideshow.
The arrows sit just outside the slides, so leave room around the carousel
(`px-12`). On narrow screens, add `static` and put them in a row of their own,
like the previews.
## Sizes [#sizes]
<Preview name="carousel-sizes" />
Items are full width by default. Change it with `basis-*`, responsive classes
included.
```tsx
<Carousel opts={{ align: 'start' }}>
<CarouselContent>
<CarouselItem className="basis-1/2 sm:basis-1/3">...</CarouselItem>
</CarouselContent>
</Carousel>
```
## Spacing [#spacing]
The gap is a start padding on `CarouselItem` (`ps-4`) and a matching negative
margin on `CarouselContent` (`-ms-4`). Change both together. Both are logical,
so RTL gets the gap on the right side.
```tsx
<CarouselContent className="-ms-2 md:-ms-4">
<CarouselItem className="ps-2 md:ps-4">...</CarouselItem>
</CarouselContent>
```
## Vertical [#vertical]
<Preview name="carousel-vertical" />
`orientation="vertical"` scrolls up and down. Give `CarouselContent` a fixed
height and space with `-mt-*` / `pt-*`.
```tsx
<Carousel orientation="vertical" opts={{ align: 'start' }}>
<CarouselContent className="-mt-2 h-48">
<CarouselItem className="basis-1/2 pt-2">...</CarouselItem>
</CarouselContent>
</Carousel>
```
## Options [#options]
`opts` goes straight to Embla: `loop` for an endless ride, `align` to snap to
`start`, `center` or `end`, `dragFree` for free scrolling.
```tsx
<Carousel opts={{ align: 'start', loop: true }}>...</Carousel>
```
On a right-to-left page, tell Embla too. The layout flips by itself, but the
scroll math needs the hint:
```tsx
<Carousel dir="rtl" opts={{ direction: 'rtl' }}>
```
## API [#api]
`setApi` hands you the Embla instance for custom controls, like the dots in the
preview.
```tsx
import type { CarouselApi } from '@vitnode/core/components/ui/carousel'
const [api, setApi] = React.useState<CarouselApi>()
const [current, setCurrent] = React.useState(0)
React.useEffect(() => {
if (!api) return
const onSelect = () => {
setCurrent(api.selectedScrollSnap())
}
api.on('select', onSelect)
return () => {
api.off('select', onSelect)
}
}, [api])
<Carousel setApi={setApi}>...</Carousel>
```
`api.scrollTo(index)` is all a dot button needs. Inside the carousel,
`useCarousel()` returns `api`, `scrollPrev`, `scrollNext`, `canScrollPrev` and
`canScrollNext`.
## Plugins [#plugins]
Pass Embla plugins through `plugins`, for example autoplay:
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']} label='Install Embla Autoplay'>
```bash tab="bun"
bun i embla-carousel-autoplay
```
```bash tab="pnpm"
pnpm i embla-carousel-autoplay
```
```bash tab="npm"
npm i embla-carousel-autoplay
```
</Tabs>
```tsx
import Autoplay from 'embla-carousel-autoplay'
<Carousel plugins={[Autoplay({ delay: 4000, stopOnInteraction: true })]}>
```
Keep `stopOnInteraction` on, and skip autoplay under reduced motion. Nobody
likes chasing a runaway slide.
## Accessibility [#accessibility]
- The root is a `region` with `aria-roledescription="carousel"`. Give it an
`aria-label`.
- Each slide is a `group` with `aria-roledescription="slide"`. Add a label like
`aria-label="2 of 5"`.
- The arrows have translated "Previous" / "Next" labels and disable at the ends.
- With focus inside, arrow keys change slides: left/right when horizontal,
up/down when vertical. In RTL (`dir="rtl"` or `opts.direction`), left and
right follow the reading direction.
- Text fields keep their arrow keys, and so does any child that handled the key.
- Under reduced motion, slides change instantly instead of gliding.
## Props [#props]
<TypeTable
type={{
opts: {
description: 'Embla options, such as `loop`, `align` or `dragFree`.',
type: 'EmblaOptionsType',
},
orientation: {
description: 'Scroll direction. Sets Embla `axis` for you.',
type: 'horizontal | vertical',
default: 'horizontal',
},
plugins: {
description: 'Embla plugins, for example autoplay.',
type: 'EmblaPluginType[]',
},
setApi: {
description: 'Receives the Embla instance once ready.',
type: '(api: CarouselApi) => void',
},
}}
/>
`CarouselPrevious` and `CarouselNext` take every [Button](/docs/ui/button) prop
and default to `variant="outline"` and `size="icon-sm"`.
## API Reference [#api-reference]
[Embla Carousel - API](https://www.embla-carousel.com/api/)
# Cascader (/docs/ui/cascader)
## Preview [#preview]
<Preview name="cascader" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
<Preview name="cascader-auto-form" />
```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCascader } from '@vitnode/core/components/form/fields/cascader'
const formSchema = z.object({
office: z.string({ error: 'Pick an office to continue' }),
backupOffice: z.string().optional(),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'office',
component: (props) => (
<AutoFormCascader
{...props}
label="Office"
options={locations}
searchable
/>
),
},
]}
/>
```
The form stores the **picked leaf's value** (`"krakow"`), not the path. Optional
fields get a clear button automatically.
</Tab>
<Tab value="Manual">
```tsx
import { Cascader } from '@vitnode/core/components/ui/cascader'
const [office, setOffice] = React.useState<string | null>(null)
<Cascader
aria-labelledby="office-label"
onValueChange={setOffice}
options={locations}
value={office}
/>
```
</Tab>
</Tabs>
## Options [#options]
A plain tree. An option with `children` is a branch that opens the next level;
one without is a pickable leaf.
```ts
import type { CascaderOption } from '@vitnode/core/components/ui/cascader'
const locations: CascaderOption[] = [
{
label: 'Europe',
value: 'europe',
children: [
{
label: 'Poland',
value: 'poland',
children: [
{ label: 'Warsaw', value: 'warsaw' },
{ label: 'Kraków', value: 'krakow' },
],
},
{ label: 'Iceland', value: 'iceland', disabled: true },
],
},
]
```
Need "Europe / Poland" too? `onValueChange` also gets the full path:
```tsx
<Cascader
onValueChange={(value, path) => setTrail(path.map((option) => option.label))}
options={locations}
/>
```
## Search [#search]
`searchable` adds a box that searches every leaf at once. Type "krak" in the
preview and "Europe / Poland / Kraków" is one click away. Accents don't matter:
"sao" finds São Paulo.
## Columns [#columns]
<Preview name="cascader-columns" />
By default a branch **replaces the list** with its children, with a back button
on top. The popup stays the field's width.
`layout="columns"` shows each level in a new column, and the popup widens to
fit. Add `expandTrigger="hover"` to open branches on hover. Phones always drill
down: there's no room for columns at 375px.
```tsx
<Cascader expandTrigger="hover" layout="columns" options={locations} />
```
Levels slide in from the direction you moved. The popup's height (drill) or
width (columns) animates with them, mirrored in RTL. Reduced motion switches
everything instantly.
## Accessibility [#accessibility]
- Each level is a keyboard listbox: <kbd>↑</kbd> <kbd>↓</kbd> move,
<kbd>→</kbd> (<kbd>←</kbd> in RTL) or <kbd>Enter</kbd> opens a branch,
<kbd>←</kbd> goes back, <kbd>Home</kbd> / <kbd>End</kbd> jump,
<kbd>Escape</kbd> closes.
- Branches announce whether they're open, and the picked path is marked
selected.
- Label it. `AutoFormCascader` does it for you; a standalone `Cascader` needs
`aria-labelledby`.
## Props [#props]
<TypeTable
type={{
options: {
description: 'The tree of options.',
type: 'CascaderOption[]',
required: true,
},
value: {
description: 'Picked leaf value (controlled).',
type: 'string | null',
},
defaultValue: {
description: 'Starting value when uncontrolled.',
type: 'string | null',
default: 'null',
},
onValueChange: {
description: 'Called with the leaf value and its full path.',
type: '(value: string | null, path: CascaderOption[]) => void',
},
searchable: {
description: 'Adds a search box across every leaf.',
type: 'boolean',
default: 'false',
},
layout: {
description: 'One level at a time, or every level side by side.',
type: '"drill" | "columns"',
default: '"drill"',
},
expandTrigger: {
description: 'Columns layout: open branches on click or on hover.',
type: '"click" | "hover"',
default: '"click"',
},
showClear: {
description:
'Shows a clear button. AutoForm turns it on for optional fields.',
type: 'boolean',
default: 'false',
},
separator: {
description: 'Between labels in the trigger and search results.',
type: 'string',
default: '" / "',
},
placeholder: {
description: 'Shown while nothing is picked.',
type: 'string',
default: '"Select an option"',
},
disabled: {
description: 'Disables the trigger.',
type: 'boolean',
default: 'false',
},
}}
/>
# Chart (/docs/ui/chart)
<Preview name="chart" />
## Installation [#installation]
You write plain [TanStack Charts](https://tanstack.com/charts) and borrow the
container, colors, tooltip and legend from VitNode. Every TanStack mark, scale
and transform works out of the box.
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']} label='Install TanStack Charts'>
```bash tab="bun"
bun i @tanstack/charts
```
```bash tab="pnpm"
pnpm i @tanstack/charts
```
```bash tab="npm"
npm i @tanstack/charts
```
</Tabs>
## Create a bar chart [#create-a-bar-chart]
A chart is a **definition** (marks, scales, colors) rendered by TanStack's
`Chart` inside VitNode's `ChartContainer`.
```tsx
import type { ChartConfig } from '@vitnode/core/components/ui/chart'
import { barY, defineChart, group } from '@tanstack/charts'
import { Chart } from '@tanstack/charts/react/tooltip'
import { scaleBand } from '@tanstack/charts/scales/band'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { tooltip } from '@tanstack/charts/tooltip'
import { fold } from '@tanstack/charts/transform/fold'
import {
ChartContainer,
ChartLegend,
ChartTooltipContent,
} from '@vitnode/core/components/ui/chart'
import { chartColor } from '@vitnode/core/components/ui/chart-utils'
const chartData = [
{ month: 'January', desktop: 186, mobile: 80 },
{ month: 'February', desktop: 305, mobile: 200 },
]
const chartConfig = {
desktop: { label: 'Desktop', color: 'var(--chart-1)' },
mobile: { label: 'Mobile', color: 'var(--chart-2)' },
} satisfies ChartConfig
// One row per bar: { month, device: 'desktop' | 'mobile', visitors }
const rows = fold(chartData, {
fields: ['desktop', 'mobile'] as const,
as: { key: 'device', value: 'visitors' },
})
const definition = defineChart({
marks: [
barY(rows, {
x: 'month',
y: 'visitors',
color: 'device',
layout: group(),
radius: 4,
}),
],
scales: {
x: { scale: () => scaleBand().padding(0.2) },
y: { scale: scaleLinear, nice: true, grid: true, axis: false },
},
color: chartColor(chartConfig),
focus: 'group-x',
tooltip,
})
export const VisitorsChart = () => (
<ChartContainer config={chartConfig}>
<Chart
ariaLabel="Visitors"
definition={definition}
height={280}
renderTooltipBody={({ points }) => (
<ChartTooltipContent points={points} />
)}
/>
<ChartLegend />
</ChartContainer>
)
```
- `fold()` turns wide rows into one row per series. TanStack Charts colors and
groups marks by a field, so the series name has to live in the data.
- `color: 'device'` sends each row through `chartColor(chartConfig)`, which
paints `desktop` with `--color-desktop`.
- Import `Chart` from `@tanstack/charts/react/tooltip` whenever you pass
`renderTooltipBody`. The plain `@tanstack/charts/react` entry keeps
TanStack's built-in tooltip text.
Define charts at module scope. When a definition reads props or state, wrap
it in `useMemo`. A new definition object tells TanStack Charts to redraw.
## Chart config [#chart-config]
Each config key matches a series value (`desktop`, `mobile`) or a category
(`general`, `support`). The config holds the words and colors, so your data
stays clean.
```tsx
const chartConfig = {
desktop: { label: 'Desktop', icon: Monitor, color: 'var(--chart-1)' },
mobile: {
label: 'Mobile',
theme: { light: 'var(--chart-2)', dark: 'var(--chart-4)' },
},
} satisfies ChartConfig
```
- `label` is what the tooltip and legend show.
- `icon` replaces the color swatch in the tooltip and legend.
- `color` works in both themes. Use `theme` when light and dark need different
colors.
## Colors [#colors]
For every config key, `ChartContainer` creates a `--color-<key>` variable
scoped to that chart. There are two ways to use it:
```tsx
// Map a field to colors - the legend and tooltip swatches follow
barY(rows, { x: 'month', y: 'visitors', color: 'device' })
defineChart({ marks, scales, color: chartColor(chartConfig) })
// Or paint one mark directly
lineY(chartData, {
x: 'day',
y: 'responseTime',
stroke: 'var(--color-responseTime)',
})
```
`ChartContainer` also maps TanStack's default palette to `--chart-1` to
`--chart-5`, and styles axes, grid lines, focus rings and tooltips with
VitNode tokens. Charts follow light and dark mode without extra code.
Pick from `--chart-1` to `--chart-5` in order: blue, orange, gray, green, red.
Two or three per chart is plenty. See [Colors](/docs/ui/colors#chart-palette).
## Area chart [#area-chart]
<Preview name="chart-area" />
Stack the rows with `stackRowsY()`, then draw an area and a line from the same
endpoints. Gradients are chart resources, so they can read the color variables.
```tsx
import { areaY, defineChart, lineY } from '@tanstack/charts'
import { d3Curve } from '@tanstack/charts/d3/shape'
import { decorative } from '@tanstack/charts/mark/decorative'
import { stackRowsY } from '@tanstack/charts/transform/stack'
import { curveMonotoneX } from 'd3-shape'
const curve = d3Curve(curveMonotoneX)
const rows = stackRowsY(
fold(chartData, {
fields: ['upgrades', 'downloads'] as const,
as: { key: 'kind', value: 'installs' },
}),
{ x: 'month', y: 'installs', z: 'kind' },
)
const definition = defineChart({
marks: [
decorative(
areaY(rows, {
x: 'month',
y1: 'y1',
y2: 'y2',
z: 'kind',
fill: (row) => `url(#fill-${row.kind})`,
fillOpacity: 1,
curve,
}),
),
lineY(rows, { x: 'month', y: 'y2', z: 'kind', curve }),
],
scales: {
x: { scale: scalePoint },
y: { scale: scaleLinear, nice: true, grid: true, axis: false },
},
color: chartColor(chartConfig),
gradients: (['downloads', 'upgrades'] as const).map((kind) => ({
id: `fill-${kind}`,
y1: 0,
y2: 1,
stops: [
{ offset: 0.05, color: `var(--color-${kind})`, opacity: 0.8 },
{ offset: 0.95, color: `var(--color-${kind})`, opacity: 0.1 },
],
})),
focus: 'group-x',
tooltip,
})
```
- `decorative()` keeps the area visible but out of hover and keyboard focus,
so every month shows up in the tooltip once.
- The line sits on the stacked top (`y2`). Pass `valueKey="installs"` to the
tooltip so it shows each series' own value, not the running total.
- Smooth curves come from `d3-shape`. Install it next to `@tanstack/charts`
when you want them. Straight segments need nothing extra.
## Line chart [#line-chart]
<Preview name="chart-line" />
```tsx
import { crosshair } from '@tanstack/charts/crosshair'
const definition = defineChart({
marks: [
crosshair({ x: true, y: false }),
lineY(chartData, {
x: 'day',
y: 'responseTime',
stroke: 'var(--color-responseTime)',
points: true,
}),
],
scales: {
x: { scale: () => scalePoint().padding(0.3) },
y: { scale: scaleLinear, nice: true, grid: true, axis: false },
},
focus: 'nearest-x',
maxFocusDistance: Number.POSITIVE_INFINITY,
tooltip,
})
```
`focus: 'nearest-x'` with an infinite distance snaps to the closest day
anywhere in the plot, and `crosshair()` draws a guide at that day. A single
series has no series field, so name it in the tooltip with
`nameKey="responseTime"`.
## Pie chart [#pie-chart]
<Preview name="chart-pie" />
Each slice is a row, not a series. `pie()` turns totals into angles, and
`radialArc()` draws them inside `polar()`.
```tsx
import { pie, polar, radialArc } from '@tanstack/charts/polar'
const definition = defineChart({
marks: [
polar({
marks: [
radialArc(pie(chartData, { value: 'threads' }), {
innerRadius: ({ radius }) => radius * 0.5,
color: 'category',
key: 'category',
}),
],
scales: { angle: null, radius: null },
}),
],
scales: { x: null, y: null },
color: chartColor(chartConfig),
tooltip,
})
<ChartTooltipContent hideLabel nameKey="category" points={points} valueKey="threads" />
```
Return `0` from `innerRadius` for a full pie instead of a donut.
## Tooltip [#tooltip]
`ChartTooltipContent` renders inside TanStack's tooltip and reads labels, icons
and colors from your config. Hover the previews to compare `dashed` (bar),
`dot` (area) and `line` (line).
```tsx
<Chart
ariaLabel="Visitors"
definition={definition}
renderTooltipBody={({ points }) => (
<ChartTooltipContent indicator="line" points={points} />
)}
/>
```
<TypeTable
type={{
points: {
description: 'Focused points from renderTooltipBody.',
type: 'readonly ChartPoint[]',
required: true,
},
indicator: {
description: 'Shape next to each value.',
type: "'dot' | 'line' | 'dashed'",
default: "'dot'",
},
hideLabel: {
description: 'Hides the heading, such as the month.',
type: 'boolean',
default: 'false',
},
hideIndicator: {
description: 'Hides the indicator shape.',
type: 'boolean',
default: 'false',
},
labelKey: {
description: 'Data field for the heading. Defaults to the x value.',
type: 'string',
},
nameKey: {
description:
'Data field (or config key) for each value name. Defaults to the series.',
type: 'string',
},
valueKey: {
description: 'Data field for each value. Defaults to the y value.',
type: 'string',
},
labelFormatter: {
description: 'Formats the heading.',
type: '(label, points) => ReactNode',
},
formatter: {
description: 'Renders each row yourself.',
type: '(value, name, point, index) => ReactNode',
},
}}
/>
Placement and behavior live in the definition. A few useful options:
- `focus: 'group-x'` shows every series at the hovered category.
- `tooltip: { use: tooltip, sort: 'color-domain' }` lists rows in config order.
- `tooltip: { use: tooltip, portal }` (from `@tanstack/charts/tooltip/portal`)
lets the tooltip escape a card with `overflow: hidden`.
Click or press <kbd>Enter</kbd> to pin a tooltip, <kbd>Esc</kbd> to unpin it.
## Legend [#legend]
`ChartLegend` is a plain HTML list built from your config, so screen readers
can read it. Put it inside `ChartContainer`, after the chart.
```tsx
<ChartContainer config={chartConfig}>
<Chart ariaLabel="Threads by category" definition={definition} />
<ChartLegend />
</ChartContainer>
```
<TypeTable
type={{
keys: {
description:
'Config keys to show, in order. Defaults to every key with a color.',
type: 'readonly string[]',
},
hideIcon: {
description: 'Shows the color swatch even when the config has an icon.',
type: 'boolean',
default: 'false',
},
}}
/>
## Size [#size]
`Chart` fills the container's width. Set its height with one of:
- `height={280}` - a fixed height, the safest choice for dashboards.
- `aspectRatio={16 / 9}` - height follows the width.
Charts render on the server at `initialWidth` (640px by default), then measure
their real width after hydration.
## Animation [#animation]
Out of the box a chart paints its final state at once. `svgAnimation: true` in
the definition tweens later data updates, like switching a date range.
Want bars that grow and pies that sweep in? Swap `Chart` for `RendererChart`
and hand it the `motion()` renderer:
```tsx
import { motion } from '@tanstack/charts/motion'
import { RendererChart } from '@tanstack/charts/react/tooltip'
import { chartTooltipMotion } from '@vitnode/core/components/ui/chart-utils'
const renderer = motion({
transition: { type: 'tween', duration: 700, easing: 'ease-out' },
})
const definition = defineChart({
marks,
scales,
tooltip: { use: tooltip, motion: chartTooltipMotion },
})
<ChartContainer config={chartConfig}>
<RendererChart
ariaLabel="Visitors"
definition={definition}
height={280}
renderer={renderer}
renderTooltipBody={({ points }) => <ChartTooltipContent points={points} />}
/>
</ChartContainer>
```
- The entrance plays when the chart mounts in the browser. A server-rendered
chart skips it, so it never flashes the final bars first. To animate a chart
below the fold, mount it when it scrolls into view with
`useIntersectionObserver`, like the demos on this page.
- `chartTooltipMotion` is a quick spring with no bounce. The tooltip fades in,
glides from point to point and fades out. Give a `crosshair` the same
spring (`motion: { transition: chartTooltipMotion }`) so the guide and the
tooltip move together.
- A plain `Chart` keeps the tooltip instant: tooltip motion needs `motion()`.
- `motion()` respects `prefers-reduced-motion` and simply paints the final
state.
## Accessibility [#accessibility]
- `ariaLabel` is required. Add `ariaDescription` for a sentence about the data.
- Tab to the chart, then use the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd>
to move between points. The tooltip follows the keyboard.
- Keep a visible heading next to the chart, like a `CardTitle`. Never rely on
color alone: tooltip and legend labels tell series apart.
- Every animation respects `prefers-reduced-motion`.
## Migrate from Recharts [#migrate-from-recharts]
VitNode used Recharts before. The ideas map one to one:
| Recharts | TanStack Charts |
| ------------------------------------------- | ------------------------------------------------------ |
| `<BarChart>` + `<Bar>` children | `defineChart({ marks: [barY(...)] })` |
| Wide rows + one `dataKey` per series | `fold()` into long rows + `color: 'series'` |
| `fill="var(--color-desktop)"` on each `Bar` | `color: chartColor(chartConfig)` |
| `stackId` | Repeated x values stack by default, or `stackRowsY()` |
| `<XAxis>` / `<CartesianGrid>` | `scales.x.axis` / `scales.y.grid` |
| `type="monotone"` | `curve: d3Curve(curveMonotoneX)` |
| `<ChartTooltip content={...} />` | `tooltip` in the definition + `renderTooltipBody` |
| `<ChartLegend content={...} />` | `<ChartLegend />` |
| `accessibilityLayer`, `title`, `desc` | `ariaLabel`, `ariaDescription` (keyboard is always on) |
| `ChartContainer className="aspect-video"` | `<Chart height={280} />` or `aspectRatio={16 / 9}` |
`ChartTooltip` and `ChartLegendContent` are gone: the tooltip is configured in
the definition, and `ChartLegend` is now a component you render directly.
## API Reference [#api-reference]
- [TanStack Charts - React adapter](https://tanstack.com/charts/latest/docs/framework/react/adapter)
- [TanStack Charts - Example gallery](https://tanstack.com/charts/latest/docs/examples/index)
# Checkbox (/docs/ui/checkbox)
## Preview [#preview]
<Preview name="checkbox" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCheckbox } from '@vitnode/core/components/form/fields/checkbox'
import { z } from 'zod'
const formSchema = z.object({
acceptRules: z.boolean().refine((value) => value, {
message: 'You need to accept the rules to join',
}),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'acceptRules',
component: (props) => (
<AutoFormCheckbox {...props} label="I accept the community rules" />
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import { Checkbox } from '@vitnode/core/components/ui/checkbox'
import { Label } from '@vitnode/core/components/ui/label'
```
```tsx
<Label>
<Checkbox checked={checked} onCheckedChange={setChecked} />
Pin this thread
</Label>
```
</Tab>
</Tabs>
## States [#states]
<Preview name="checkbox-states" />
- `indeterminate` draws a dash, for "some selected".
- `disabled` dims it. Add `data-disabled` to the parent [Field](/docs/ui/field)
to dim the label too.
- `aria-invalid` turns it red. Point `aria-describedby` at the error.
```tsx
<Field data-invalid orientation="horizontal">
<Checkbox aria-describedby="rules-error" aria-invalid id="rules" />
<FieldContent>
<FieldLabel htmlFor="rules">I have read the community rules</FieldLabel>
<FieldError id="rules-error">Tick this one to post.</FieldError>
</FieldContent>
</Field>
```
Every checkbox needs a label. The hit area reaches beyond the box, so it's
easy to tap on a phone.
## Props [#props]
`AutoFormCheckbox` also accepts every [Base UI Checkbox](https://base-ui.com/react/components/checkbox#api-reference) prop.
<TypeTable
type={{
label: {
description: 'Shown next to the checkbox.',
type: 'ReactNode',
},
labelRight: {
description: "Content pinned to the label's right edge.",
type: 'ReactNode',
},
description: {
description: 'Shown below the label.',
type: 'ReactNode',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Checkbox](https://base-ui.com/react/components/checkbox#api-reference)
# Color (/docs/ui/color)
## Preview [#preview]
<Preview name="color" />
## 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'
```
```tsx
const formSchema = z.object({
color: z.string().default('hsl(215, 81%, 52%)'),
})
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'color',
component: props => <AutoFormColor {...props} label="Category color" />,
},
]}
/>
```
</Tab>
<Tab value="Manual">
```ts
import { ColorPicker } from '@vitnode/core/components/ui/color-picker'
```
```tsx
const [color, setColor] = React.useState('hsl(215, 81%, 52%)')
<ColorPicker onChange={setColor} value={color} />
```
`ColorPicker` is controlled: `onChange` gets the new color string.
</Tab>
</Tabs>
## Preset palette [#preset-palette]
<Preview name="color-presets" />
A default swatch plus seven hues and gray, in up to three tones. The default
stores `""` and renders in the theme's text color. Every tone keeps 3:1
contrast on light and dark backgrounds, and a unit test enforces it.
For the palette alone, use `ColorPresetPicker`. The values live in
`@vitnode/core/components/ui/color-presets`.
```ts
import { ColorPresetPicker } from '@vitnode/core/components/ui/color-preset-picker'
```
```tsx
<ColorPresetPicker onChange={setColor} value={color} />
```
The swatches are one radio group, so arrow keys move between them.
## Output format [#output-format]
Presets and the picker store HSL, like `hsl(215, 81%, 52%)`. The text input
stores any CSS color you type. Hex, `rgb()`, `hsl()` and `oklch()` move the
picker; anything else parks it on black.
[react-colorful](https://github.com/omgovich/react-colorful) loads only when the
popover opens.
## Clearing [#clearing]
`allowRemoveColor` adds a "Remove" button that sets `""`. The
[preview](#preview) has it on.
## Editor text color [#editor-text-color]
The [editor](/docs/ui/editor)'s text color action uses the same preset palette,
with no free-form picker. Its popover ends with a "Remove color" button.
## Props [#props]
<TypeTable
type={{
label: { description: 'Label above the field.', type: 'string' },
description: { description: 'Help text below the field.', type: 'string' },
placeholder: {
description: 'Trigger text when empty, and the text input placeholder.',
type: 'string',
default: '"Pick a color"',
},
allowRemoveColor: {
description: 'Show a "Remove" button that clears the value to `""`.',
type: 'boolean',
default: 'false',
},
}}
/>
Other props, like `disabled`, go to the trigger button.
# Colors (/docs/ui/colors)
Colors are **semantic tokens**: they name a job (`card`, `primary`), not a hue,
so every component follows your theme and dark mode for free. Flip the theme
and watch the values below change.
## Tokens [#tokens]
<Preview name="colors-tokens" className="*:max-w-full" />
Each token is a CSS variable in `src/styles.css` and a Tailwind color:
`bg-card`, `text-card-foreground`, `border-input`. Click a swatch's copy button
to grab its class.
## Written in OKLCH [#written-in-oklch]
```css
--primary: oklch(0.52 0.2 264);
```
| `L` Lightness | `C` Chroma | `H` Hue |
| --------------------- | ------------------------ | ----------------------------------- |
| `0` black - `1` white | `0` gray - `~0.37` vivid | `27` red · `155` green · `264` blue |
Same `L` means the same perceived brightness, so contrast is predictable: tune
`L` for readability, keep `H` for brand.
## Surfaces stack [#surfaces-stack]
<Preview name="colors-layers" />
`background` → `card` → `popover`. In dark mode each layer gets lighter as it
rises. Always pair a surface with its `-foreground` text.
```tsx
<div className="bg-card text-card-foreground rounded-lg border p-4">
<p className="text-muted-foreground">3 drafts waiting for review</p>
</div>
```
## Status [#status]
<Preview name="colors-status" />
Status colors have no `-foreground`. Use them as text on a soft tint of
themselves, or let the component pick for you.
```tsx
<span className="bg-success/10 text-success dark:bg-success/20 rounded-md px-2 py-1 text-sm">
Published
</span>
```
## Chart palette [#chart-palette]
<Preview name="colors-chart" className="*:max-w-full" />
Use `chart-1` to `chart-5` in order: blue, orange, gray, green, red. Green and
red are never neighbors and differ in lightness, so they stay apart for
color-blind readers.
```ts
const chartConfig = {
posts: { label: 'Posts', color: 'var(--chart-1)' },
replies: { label: 'Replies', color: 'var(--chart-2)' },
}
```
## Do and don't [#do-and-dont]
<Preview name="colors-do-dont" className="*:max-w-full" />
- Keep a screen to 3-5 colors: neutrals, primary and one status.
- Never use purple prominently, and never change `--primary`. VitNode blue
stays blue.
- Filled `primary` is for short labels. Its dark-mode contrast is too low for
paragraphs.
## Related [#related]
<Cards>
<Card
title="Typography"
href="/docs/ui/typography"
description="Font stack, type scale and text rules."
/>
<Card
title="Introduction"
href="/docs/ui"
description="Design principles and every foundation in one place."
/>
</Cards>
# Combobox (/docs/ui/combobox)
## Preview [#preview]
<Preview name="combobox" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
Options come from the `z.enum`. `labels` gives each value a readable name.
```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCombobox } from '@vitnode/core/components/form/fields/combobox'
const formSchema = z.object({
category: z.enum(['general', 'support']),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'category',
component: (props) => (
<AutoFormCombobox
{...props}
label="Category"
labels={[
{ value: 'general', label: 'General discussion' },
{ value: 'support', label: 'Help & support' },
]}
/>
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxItem,
ComboboxList,
} from '@vitnode/core/components/ui/combobox'
const categories = ['General', 'Support', 'Showcase']
;<Combobox items={categories}>
<ComboboxInput placeholder="Pick a category" />
<ComboboxContent>
<ComboboxEmpty>No categories found.</ComboboxEmpty>
<ComboboxList>
{(item) => (
<ComboboxItem key={item} value={item}>
{item}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
```
</Tab>
</Tabs>
## Groups and clear button [#groups-and-clear-button]
<Preview name="combobox-groups" />
Give options a `group` to sort them under headings. Groups follow the order they
first appear in `labels`; ungrouped options sit at the top. `showClear` adds an
× that empties the field.
```tsx
<AutoFormCombobox
{...props}
labels={[
{ group: 'Europe', label: 'Warsaw', value: 'europe-warsaw' },
{ group: 'Americas', label: 'New York', value: 'america-new-york' },
]}
showClear
/>
```
## Async search [#async-search]
<Preview name="combobox-async" />
`fetchData` loads options from your API as people type (debounced by 500ms). It
needs a stable `id` and a `queryKey` for caching. Each picked value is a
`{ value, label }` object, not a string.
```tsx
import { fetcher } from '@vitnode/core/tanstack/fetcher'
const formSchema = z.object({
moderators: z
.array(z.object({ value: z.string(), label: z.string() }))
.min(1)
.default([]),
})
;<AutoFormCombobox
{...props}
fetchData={async ({ search }) => {
const res = await fetcher({
plugin: '@acme/forum',
method: 'get',
module: 'members',
path: '/',
args: { query: { search } },
})
const data = await res.json()
return data.edges.map((member) => ({
label: member.name,
value: member.id.toString(),
}))
}}
id="moderators"
multiple
queryKey={['forum', 'members']}
renderItem={(item) => <UserRow name={item.label} />}
searchPlaceholder="Find a member..."
/>
```
`renderItem` customizes each async option, like adding an avatar.
## Multiple [#multiple]
<Preview name="combobox-multiple" />
Add `multiple` and use an array in the schema. Picks become chips, and the box
wraps when full. `.min()` and `.max()` on the array become the validation
messages.
```ts
const formSchema = z.object({
topics: z
.array(z.enum(['news', 'guides', 'releases']))
.min(1, 'Pick at least one topic')
.max(3, 'Three topics is plenty'),
})
```
```tsx
<AutoFormCombobox {...props} labels={topics} maxVisibleChips={3} multiple />
```
- `maxVisibleChips` shows the first few chips plus "+N more". Every pick is
still saved.
- `renderChip` customizes each chip.
- <kbd>Backspace</kbd> in an empty search removes the last chip.
<kbd>Escape</kbd> with the list closed clears every pick, so mind that second
Escape.
- Reduced motion turns off the chip and chevron animations.
For a manual multi-select, wrap chips in `ComboboxChips` and anchor the popup to
it:
```tsx
const anchor = useComboboxAnchor()
;<Combobox items={frameworks} multiple>
<ComboboxChips ref={anchor}>
<ComboboxValue>
{(values: string[]) => (
<>
{values.map((value) => (
<ComboboxChip key={value}>{value}</ComboboxChip>
))}
<ComboboxChipsInput placeholder="Add a framework" />
</>
)}
</ComboboxValue>
</ComboboxChips>
<ComboboxContent anchor={anchor}>
<ComboboxList>
{(item) => (
<ComboboxItem key={item} value={item}>
{item}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
```
## Props [#props]
<TypeTable
type={{
label: {
description: 'Shown above the input.',
type: 'ReactNode',
},
description: {
description: 'Shown below the input.',
type: 'ReactNode',
},
labels: {
description: 'Readable label and optional group for each enum value.',
type: '{ value: string; label: string; group?: string }[]',
default: '[]',
},
placeholder: {
description: 'Input placeholder.',
type: 'string',
default: '"Select an option"',
},
fetchData: {
description:
'Loads options for the search text. Turns on async search and requires `id` and `queryKey`.',
type: '({ search }) => { value: string; label: string }[] | Promise<...>',
},
id: {
description: 'Stable id. Required with `fetchData`.',
type: 'string',
},
queryKey: {
description:
'TanStack Query key prefix for cached results. Required with `fetchData`.',
type: 'readonly unknown[]',
},
searchPlaceholder: {
description:
'Input placeholder with `fetchData`. Falls back to `placeholder`.',
type: 'string',
},
renderItem: {
description: 'Custom content for each `fetchData` option.',
type: '(item: { value: string; label: string }) => ReactNode',
},
multiple: {
description: 'Allows many picks, shown as chips. Works with `fetchData`.',
type: 'boolean',
default: 'false',
},
maxVisibleChips: {
description: 'With `multiple`, shows this many chips plus "+N more".',
type: 'number',
},
renderChip: {
description: 'With `multiple`, custom content for each chip.',
type: '(item: { value: string; label: string }) => ReactNode',
},
showClear: {
description: 'Single select only. Shows a button that clears the value.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'Disables the combobox.',
type: 'boolean',
default: 'false',
},
}}
/>
# Command (/docs/ui/command)
## Preview [#preview]
<Preview name="command" />
## Usage [#usage]
```ts
import {
Command,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandList,
CommandSeparator,
CommandShortcut,
} from '@vitnode/core/components/ui/command'
```
```tsx
<Command>
<CommandInput placeholder="Type a command or search..." />
<CommandList>
<CommandEmpty>No results found.</CommandEmpty>
<CommandGroup heading="Suggestions">
<CommandItem>Calendar</CommandItem>
<CommandItem>Search Emoji</CommandItem>
</CommandGroup>
</CommandList>
</Command>
```
Type and the list filters itself, best matches first. Empty groups hide. Built
on [cmdk](https://cmdk.paco.me), so every cmdk prop works.
## Groups, icons and shortcuts [#groups-icons-and-shortcuts]
`CommandGroup` takes a `heading`, and `CommandSeparator` splits groups. Icons go
first and are sized for you. `CommandShortcut` is only a label: bind the keys
yourself.
```tsx
<CommandGroup heading="Settings">
<CommandItem>
<UserIcon />
<span>Profile</span>
<CommandShortcut>⌘P</CommandShortcut>
</CommandItem>
</CommandGroup>
<CommandSeparator />
```
`CommandEmpty` shows only when nothing matches. Make it kind.
## Selecting items [#selecting-items]
`onSelect` fires on click and <kbd>Enter</kbd>. `disabled` keeps an item
visible but skipped. Items match by their text: add `value` when the text isn't
unique, and `keywords` for other names people might type.
```tsx
<CommandItem onSelect={() => router.navigate({ to: '/settings' })}>
Settings
</CommandItem>
<CommandItem keywords={['theme', 'night']} value="toggle-dark-mode">
Toggle dark mode
</CommandItem>
```
## Dialog [#dialog]
<Preview name="command-dialog" />
`CommandDialog` wraps a `Command` in a [Dialog](/docs/ui/dialog) with a
screen-reader-only title and description. Control it with `open` and
`onOpenChange`, and bind a shortcut yourself.
```tsx
const [open, setOpen] = React.useState(false)
React.useEffect(() => {
const handleKeyDown = (event: KeyboardEvent) => {
if (event.key.toLowerCase() !== 'j') return
if (!event.metaKey && !event.ctrlKey) return
if (event.altKey || event.shiftKey || event.defaultPrevented) return
event.preventDefault()
setOpen(prev => !prev)
}
window.addEventListener('keydown', handleKeyDown)
return () => window.removeEventListener('keydown', handleKeyDown)
}, [])
<CommandDialog onOpenChange={setOpen} open={open}>
<Command>
<CommandInput placeholder="What do you need?" />
<CommandList>...</CommandList>
</Command>
</CommandDialog>
```
<Callout title="Why ⌘J and not ⌘K?">
The docs search and the AdminCP already own <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd>,
so the demo uses <kbd>⌘J</kbd> / <kbd>Ctrl+J</kbd>. Pick a free key and remove
the listener on unmount. Inside the open palette <kbd>Ctrl+J</kbd> moves down
a row, so <kbd>Escape</kbd> is the way out.
</Callout>
Show the shortcut next to the trigger with [`Kbd`](/docs/ui/kbd), like the demo.
## Your own filtering [#your-own-filtering]
<Preview name="command-async" />
Searching an API? Set `shouldFilter={false}` and render what your query returns.
The AdminCP search works this way.
```tsx
<Command label="Search members" shouldFilter={false}>
<CommandInput onValueChange={setSearch} value={search} />
<CommandList>
{members.map((member) => (
<CommandItem key={member.id} value={member.id}>
{member.name}
</CommandItem>
))}
</CommandList>
</Command>
```
## Accessibility [#accessibility]
- The input is a `combobox` and the list a `listbox`, so screen readers announce
the highlighted option.
- <kbd>↑</kbd> / <kbd>↓</kbd> move, <kbd>Home</kbd> / <kbd>End</kbd> jump to the
ends, <kbd>Enter</kbd> selects. `loop` wraps at the edges.
- <kbd>Ctrl+N</kbd> / <kbd>Ctrl+J</kbd> and <kbd>Ctrl+P</kbd> /<kbd>Ctrl+K</kbd>
also move. Turn them off with `vimBindings={false}`.
- Give a standalone `Command` a `label` so the input has a name.
`CommandDialog` traps focus and closes on <kbd>Escape</kbd>.
## Props [#props]
### Command [#command]
<TypeTable
type={{
label: {
description: 'Accessible label for the command menu input.',
type: 'string',
},
shouldFilter: {
description:
'Turn off the built-in filtering and sorting when you filter the items yourself.',
type: 'boolean',
default: 'true',
},
filter: {
description:
'Custom ranking function. Return `0` to hide an item and a higher number to rank it higher.',
type: '(value: string, search: string, keywords?: string[]) => number',
},
value: {
description: 'Controls the highlighted item.',
type: 'string',
},
onValueChange: {
description: 'Called when the highlighted item changes.',
type: '(value: string) => void',
},
loop: {
description: 'Wrap the keyboard selection around at the top and bottom.',
type: 'boolean',
default: 'false',
},
vimBindings: {
description: 'Enable the `Ctrl+N/J/P/K` navigation shortcuts.',
type: 'boolean',
default: 'true',
},
}}
/>
### CommandDialog [#commanddialog]
<TypeTable
type={{
open: {
description: 'Controls whether the dialog is open.',
type: 'boolean',
},
onOpenChange: {
description: 'Called when the dialog opens or closes.',
type: '(open: boolean) => void',
},
title: {
description: 'Screen-reader-only dialog title.',
type: 'string',
default: '"Command Palette"',
},
description: {
description: 'Screen-reader-only dialog description.',
type: 'string',
default: '"Search for a command to run..."',
},
showCloseButton: {
description: 'Show the close button in the corner.',
type: 'boolean',
default: 'false',
},
className: {
description: 'Classes for the dialog content.',
type: 'string',
},
}}
/>
### CommandItem [#commanditem]
<TypeTable
type={{
onSelect: {
description: 'Called when the item is clicked or chosen with Enter.',
type: '(value: string) => void',
},
value: {
description:
'A unique value used for filtering and selection. Defaults to the text content.',
type: 'string',
},
keywords: {
description: 'Extra words the item should match.',
type: 'string[]',
},
disabled: {
description: 'Keep the item visible but not selectable.',
type: 'boolean',
default: 'false',
},
forceMount: {
description: 'Always render the item, even when it does not match.',
type: 'boolean',
default: 'false',
},
}}
/>
## API Reference [#api-reference]
[cmdk](https://github.com/pacocoursey/cmdk#parts-and-styling)
# Comparison (/docs/ui/comparison)
## Preview [#preview]
<Preview name="comparison" />
## Usage [#usage]
```ts
import {
Comparison,
ComparisonHandle,
ComparisonItem,
} from '@vitnode/core/components/ui/comparison'
```
```tsx
<Comparison aria-label="Before and after" className="aspect-video">
<ComparisonItem position="left">
<img alt="" draggable={false} src={before} />
</ComparisonItem>
<ComparisonItem position="right">
<img alt="" draggable={false} src={after} />
</ComparisonItem>
<ComparisonHandle />
</Comparison>
```
`position="left"` is the image left of the handle, `right` the one on its
right. Images fill their item with `object-cover`, so give `Comparison` a size
or aspect ratio.
Tap somewhere new and the handle glides there, then follows your finger one to
one. Keyboard steps glide too.
## Hover mode [#hover-mode]
<Preview name="comparison-hover" />
With `mode="hover"` the handle follows the pointer, no click needed. Fun for
quick looks; stick with dragging for anything precise.
## Starting point and changes [#starting-point-and-changes]
```tsx
<Comparison defaultPosition={30} onPositionChange={setPosition}>
...
</Comparison>
```
`position` runs from 0 (all right image) to 100 (all left image).
## Custom handle [#custom-handle]
<Preview name="comparison-handle" />
Pass children to `ComparisonHandle` to draw your own. It still moves with the
slider.
```tsx
<ComparisonHandle>
<div className="bg-primary absolute inset-y-0 w-0.5" />
<div className="bg-primary text-primary-foreground relative flex size-8 items-center justify-center rounded-full">
<ChevronsLeftRightIcon className="size-4" />
</div>
</ComparisonHandle>
```
## Accessibility [#accessibility]
- The comparison is a slider. Arrow keys move 5% (10% with <kbd>Shift</kbd>);
<kbd>Home</kbd> and <kbd>End</kbd> jump to the ends.
- Screen readers hear the position as a percentage. Name it with `aria-label`.
- Images are decorative (`alt=""`). Describe the comparison in the label or a
caption.
- Dragging sideways never blocks vertical page scrolling on phones.
- With reduced motion, the handle jumps instead of gliding.
## Props [#props]
<TypeTable
type={{
mode: {
description: 'Drag the handle, or have it follow the pointer.',
type: '"drag" | "hover"',
default: '"drag"',
},
defaultPosition: {
description: 'Where the handle starts, from 0 to 100.',
type: 'number',
default: '50',
},
onPositionChange: {
description: 'Called with the new position as it moves.',
type: '(position: number) => void',
},
}}
/>
# Confirm Action Alert Dialog (/docs/ui/confirm-action-alert-dialog)
An [Alert Dialog](/docs/ui/alert-dialog) with the boring parts done: async
submit, spinner, locked Cancel, and a dialog that stays open when things fail.
## Preview [#preview]
<Preview name="confirm-action-alert-dialog" />
## 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
icon={<Trash2Icon />}
onSubmit={async ({ onClose }) => {
await deleteCategory(id)
onClose()
}}
title="Delete General discussion?"
>
<Button variant="destructive">Delete category</Button>
</ConfirmActionAlertDialog>
```
The child becomes the trigger. Passing an `icon` switches to the compact,
centered layout.
## Async and errors [#async-and-errors]
<Preview name="confirm-action-alert-dialog-async" />
While `onSubmit` runs, the confirm button spins and Cancel is locked. Nothing
closes until you call `onClose()`, so on an error just show a toast and return.
```tsx
onSubmit={async ({ onClose }) => {
const result = await deleteCategoryApi(id)
if (result?.error) {
toast.error(tGlobal('errors.title'), {
description: tGlobal('errors.internal_server_error'),
})
return
}
toast.success(t('success'), { description: title })
onClose()
}}
```
## Props [#props]
<TypeTable
type={{
onSubmit: {
description: 'Runs on confirm. Call `onClose` to close the dialog.',
type: '(params: { onClose: () => void }) => Promise<void> | void',
required: true,
},
children: {
description: 'The trigger. Leave it out when you control `open`.',
type: 'ReactElement',
},
title: {
description: 'Dialog title.',
type: 'ReactNode',
default: '"Are you sure?"',
},
description: {
description: 'What happens on confirm.',
type: 'ReactNode',
default: '"This action cannot be undone."',
},
icon: {
description:
'Icon above the title. Switches to the compact, centered layout.',
type: 'ReactNode',
},
textSubmit: {
description: 'Confirm button text.',
type: 'string',
default: '"Yes, confirm"',
},
submitVariant: {
description:
'Confirm button variant. `destructive` also tints the icon tile red.',
type: 'Button["variant"]',
default: '"destructive"',
},
finalFocus: {
description: 'Where focus goes after the dialog closes.',
type: 'AlertDialogContent["finalFocus"]',
},
}}
/>
It also takes every `AlertDialog` prop, such as `open` and `onOpenChange`.
Default texts are translated.
# Context Menu (/docs/ui/context-menu)
## Preview [#preview]
<Preview name="context-menu" />
## Usage [#usage]
```ts
import {
ContextMenu,
ContextMenuContent,
ContextMenuItem,
ContextMenuSeparator,
ContextMenuShortcut,
ContextMenuTrigger,
} from '@vitnode/core/components/ui/context-menu'
```
```tsx
<ContextMenu>
<ContextMenuTrigger className="flex h-40 items-center justify-center rounded-xl border-2 border-dashed">
Right-click here
</ContextMenuTrigger>
<ContextMenuContent className="w-56">
<ContextMenuItem>
Reload
<ContextMenuShortcut>⌘R</ContextMenuShortcut>
</ContextMenuItem>
<ContextMenuItem>Rename</ContextMenuItem>
<ContextMenuSeparator />
<ContextMenuItem variant="destructive">Delete</ContextMenuItem>
</ContextMenuContent>
</ContextMenu>
```
Right-click the trigger, or long-press it on touch. The menu opens right under
your cursor or finger.
## Submenus [#submenus]
Nest a `ContextMenuSub` for the rarely used stuff. It opens on hover, click or
the right arrow.
```tsx
<ContextMenuSub>
<ContextMenuSubTrigger>More tools</ContextMenuSubTrigger>
<ContextMenuSubContent className="w-48">
<ContextMenuItem>Developer tools</ContextMenuItem>
</ContextMenuSubContent>
</ContextMenuSub>
```
## Checkbox and radio items [#checkbox-and-radio-items]
`ContextMenuCheckboxItem` toggles on its own, items in a
`ContextMenuRadioGroup` pick one. Both work controlled or uncontrolled.
```tsx
<ContextMenuCheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
Show bookmarks bar
</ContextMenuCheckboxItem>
<ContextMenuRadioGroup onValueChange={setPerson} value={person}>
<ContextMenuRadioItem value="pedro">Pedro Duarte</ContextMenuRadioItem>
</ContextMenuRadioGroup>
```
The check mark sits at the start of the row, like in the
[Dropdown Menu](/docs/ui/dropdown-menu). Add `inset` to plain items, labels and
sub-triggers in the same menu so their text lines up.
## Shortcuts and destructive items [#shortcuts-and-destructive-items]
`ContextMenuShortcut` is only a label: bind the keys yourself. Use
`variant="destructive"` for actions you can't take back.
```tsx
<ContextMenuItem variant="destructive">
<Trash2Icon />
Delete
<ContextMenuShortcut>⌘⌫</ContextMenuShortcut>
</ContextMenuItem>
```
## Always offer another way [#always-offer-another-way]
<Preview name="context-menu-fallback" />
Nothing on screen says "right-click me", and keyboard users can't open a
context menu at all. Put every action somewhere visible too, like the `⋯`
[Dropdown Menu](/docs/ui/dropdown-menu) on each row above.
## Accessibility [#accessibility]
- Once open, arrow keys move between items, right opens a submenu, a letter
jumps to a match and <kbd>Escape</kbd> closes it.
- The trigger sets `select-none`, so a long-press doesn't start a text
selection. Rows grow to a 44px tap target on touch screens.
- Reduced motion turns the scale-in off.
## Props [#props]
### ContextMenu [#contextmenu]
<TypeTable
type={{
open: {
description: 'Controls whether the menu is open.',
type: 'boolean',
},
defaultOpen: {
description: 'Open on the first render.',
type: 'boolean',
default: 'false',
},
onOpenChange: {
description: 'Called when the menu opens or closes.',
type: '(open: boolean, eventDetails) => void',
},
disabled: {
description: 'Stops the menu from opening.',
type: 'boolean',
default: 'false',
},
}}
/>
### ContextMenuContent [#contextmenucontent]
<TypeTable
type={{
side: {
description: 'Preferred side of the cursor. Flips when there is no room.',
type: 'top | bottom | left | right | inline-start | inline-end',
default: 'bottom',
},
align: {
description: 'Alignment against the cursor.',
type: 'start | center | end',
default: 'start',
},
sideOffset: {
description: 'Gap from the cursor in pixels.',
type: 'number',
default: '4',
},
alignOffset: {
description: 'Shift along the alignment axis in pixels.',
type: 'number',
default: '0',
},
}}
/>
### ContextMenuItem [#contextmenuitem]
<TypeTable
type={{
variant: {
description: 'The look of the item.',
type: 'default | destructive',
default: 'default',
},
inset: {
description: 'Start padding to line up with checkbox and radio items.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'Visible but not interactive.',
type: 'boolean',
default: 'false',
},
closeOnClick: {
description: 'Close the menu when the item is chosen.',
type: 'boolean',
default: 'true',
},
onClick: {
description: 'Called on click, tap or keyboard select.',
type: '(event) => void',
},
}}
/>
`ContextMenuCheckboxItem` takes `checked`, `defaultChecked` and
`onCheckedChange`; `ContextMenuRadioGroup` takes `value`, `defaultValue` and
`onValueChange`. Both item types accept `inset` and `disabled` too.
## API Reference [#api-reference]
[Base UI - Context Menu](https://base-ui.com/react/components/context-menu#api-reference)
# Copy Button (/docs/ui/copy-button)
## Preview [#preview]
<Preview name="copy-button" />
## Usage [#usage]
```ts
import { CopyButton } from '@vitnode/core/components/ui/copy-button'
```
```tsx
<CopyButton content="pnpm create vitnode-app@canary" />
```
The check stays for `delay` (2000ms). Each new copy restarts the timer.
## With a label [#with-a-label]
Children show next to the icon and become the accessible name.
```tsx
<CopyButton content={inviteLink} variant="secondary">
Copy invite link
</CopyButton>
```
## Icon only [#icon-only]
Without children it's labelled "Copy" / "Copied". With several on a screen,
give each its own `aria-label`.
```tsx
<CopyButton
aria-label="Copy install command"
content={command}
size="icon-sm"
variant="ghost"
/>
```
## Controlled [#controlled]
<Preview name="copy-button-controlled" />
Use `copied` and `onCopiedChange` when the page should react.
```tsx
const [copied, setCopied] = React.useState(false)
<CopyButton content={inviteLink} copied={copied} onCopiedChange={setCopied} />
```
## Async content [#async-content]
Text that has to be fetched first? Pass a function instead of a string. It runs
on click, the button is `aria-busy` while it waits, and extra clicks are ignored
until it settles.
```tsx
<CopyButton
content={async () => {
const res = await fetch('/docs/dev.md')
if (!res.ok) throw new Error(`Failed to load ${res.url}`)
return await res.text()
}}
size="sm"
variant="secondary"
>
Copy Markdown
</CopyButton>
```
Safari only lets a page write to the clipboard during the click itself, so the
pending text goes in as a `ClipboardItem` promise. Browsers without
`ClipboardItem` wait for the text, then copy it. A rejected promise shows the
same error toast as a blocked clipboard.
## Accessibility [#accessibility]
- A polite live region announces "Copied".
- With reduced motion, icons just fade and the check appears fully drawn.
- A blocked clipboard (say, on plain HTTP) shows an error toast.
- `event.preventDefault()` in your own `onClick` skips the copy.
## Props [#props]
<TypeTable
type={{
content: {
description:
'Text written to the clipboard, or an async function that resolves it on click.',
type: 'string | (() => Promise<string>)',
required: true,
},
copied: { description: 'Controls the copied state.', type: 'boolean' },
onCopiedChange: {
description: '`true` after a copy, `false` when the button resets.',
type: '(copied: boolean) => void',
},
delay: {
description: 'How long the check stays, in ms. Restarts on each copy.',
type: 'number',
default: '2000',
},
variant: {
description: 'Button variant.',
type: 'default | secondary | outline | ghost | hover | link | success | warning | destructive',
default: 'outline',
},
size: {
description:
'Button size. Default: `icon` without children, `default` with.',
type: 'default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg',
},
'aria-label': {
description: 'Accessible name. Without children: "Copy" / "Copied".',
type: 'string',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Button](https://base-ui.com/react/components/button#api-reference)
# Counter (/docs/ui/counter)
## Preview [#preview]
<Preview name="counter" />
## Usage [#usage]
```ts
import { Counter } from '@vitnode/core/components/ui/counter'
```
```tsx
const [quantity, setQuantity] = React.useState(1)
<Counter aria-label="Tickets" max={10} min={1} onValueChange={setQuantity} value={quantity} />
```
Digits roll the short way round: 9 → 10 rolls to 0 as a new 1 slides in. For
uncontrolled use, pass `defaultValue`.
## Steps and limits [#steps-and-limits]
<Preview name="counter-steps" />
A step that would pass a limit stops at it: with `max={12}` and `step={5}`,
10 goes to 12. Buttons disable at `min` and `max`.
## Sliding number [#sliding-number]
<Preview name="counter-sliding-number" />
The rolling digits on their own, for any number.
```ts
import { SlidingNumber } from '@vitnode/core/components/ui/sliding-number'
```
```tsx
<SlidingNumber className="text-5xl font-semibold" value={downloads} />
```
It inherits font size and color, uses tabular figures, and handles negatives
and up to 6 decimals.
## In a form [#in-a-form]
Counter is a standalone control. To save a number with AutoForm, use
[Number Field](/docs/ui/number-field).
## Accessibility [#accessibility]
- The buttons are labelled "Decrease" / "Increase" in the user's language.
- Screen readers hear each new value, not the rolling digits.
- Name the counter with `aria-label` or `aria-labelledby`. "Increase" what?
- With reduced motion, digits change instantly.
## Props [#props]
### Counter [#counter]
<TypeTable
type={{
value: { description: 'Current value (controlled).', type: 'number' },
defaultValue: {
description: 'Starting value when uncontrolled.',
type: 'number',
default: '0',
},
onValueChange: {
description: 'Called with the new value after a click.',
type: '(value: number) => void',
},
min: { description: 'Lowest allowed value.', type: 'number' },
max: { description: 'Highest allowed value.', type: 'number' },
step: {
description: 'Amount one click adds or removes.',
type: 'number',
default: '1',
},
disabled: {
description: 'Disables both buttons.',
type: 'boolean',
default: 'false',
},
}}
/>
### SlidingNumber [#slidingnumber]
<TypeTable
type={{
value: {
description: 'The number to show. Rounded beyond 6 decimal places.',
type: 'number',
required: true,
},
}}
/>
# Bulk Actions (/docs/ui/data-table/bulk-actions)
## Preview [#preview]
<Preview name="data-table-bulk-actions" withoutBackground />
## Usage [#usage]
Passing `bulkActions` turns selection on. Each row gets a checkbox, and the
header checkbox ticks the whole page. While anything is ticked, a bar floats at
the bottom of the viewport with the count, your actions and a clear button.
```tsx
<ContentDataTable
id="users-table"
// [!code ++]
bulkActions={<DeleteBulkAction />}
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
Actions render inside the bar, so they read the ticked ids with
`useDataTableSelection()`. No props to thread through.
```tsx title="delete-bulk-action.tsx"
import { useDataTableSelection } from '@vitnode/core/components/table/selection'
import { Button } from '@vitnode/core/components/ui/button'
export const DeleteBulkAction = () => {
const { clear, selected } = useDataTableSelection()
return (
<Button
onClick={async () => {
await deleteUsers(selected)
clear()
}}
variant="destructive"
>
<Trash2Icon />
Delete
</Button>
)
}
```
## Selection is per page [#selection-is-per-page]
Selection only covers the rows on screen. When paging, search or a filter
brings different rows, ticks on rows that left are dropped. A bulk action never
touches a row nobody can see.
After a partial success, revalidate. Rows that were refused stay on screen and
stay ticked, so the bar points at the work that's left.
<Callout type="warn" title="There is no bulk endpoint">
`bulkActions` hands you ids, nothing more. If your action loops a single-row
endpoint, cap the fan-out and report outcomes per reason, so a partial success
can say so.
</Callout>
## useDataTableSelection [#usedatatableselection]
<TypeTable
type={{
selected: {
description: 'Ticked row ids, in the order they were ticked.',
type: 'number[]',
},
isSelected: {
description: 'Whether one row is ticked.',
type: '(id: number) => boolean',
},
allSelected: {
description: 'Every row on the page is ticked.',
type: 'boolean',
},
someSelected: {
description: 'Some but not all rows are ticked.',
type: 'boolean',
},
toggle: {
description: 'Ticks or unticks one row.',
type: '(id: number) => void',
},
toggleAll: {
description: 'Ticks or unticks every row on the page.',
type: '(next: boolean) => void',
},
clear: {
description: 'Unticks everything and hides the bar.',
type: '() => void',
},
}}
/>
The hook throws outside a table with `bulkActions`.
# Custom Rows (/docs/ui/data-table/custom-rows)
## Preview [#preview]
<Preview name="data-table-custom-rows" withoutBackground />
## Usage [#usage]
Columns suit data you compare across rows. When each row is more of a card
(an icon, a title, a line of description and a switch), pass `renderRow`
instead of `columns`. The Data Table draws your layout across the full width
of the row and still handles search, filters, pagination and the empty state.
```tsx
<ContentDataTable
id="plugins-table"
// [!code ++:3]
renderRow={({ row }) => (
<PluginRow plugin={row} />
)}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
- **No column headers.** A custom row has no columns to label, so the header
band is hidden. It comes back when you turn on `bulkActions`, `expandable` or
`reorderable`, because their controls live there.
- **Row features still work.** The checkbox, the expand chevron and the drag
handle sit in front of your layout, and `rowOpens` makes the whole row
clickable.
- **Controls answer for themselves.** A click on a button, link or switch
inside your layout does not trigger `rowOpens`.
- **Your layout owns its spacing.** The cell already has the row's padding, so
don't add outer padding of your own.
<Callout type="info" title="Sorting needs a column header">
`order.defaultOrder` still sets the starting order, but there are no headers
to click. To let people change the order, add a filter or sort the rows
yourself.
</Callout>
## API [#api]
<TypeTable
type={{
renderRow: {
description:
'Renders one row. `allData` holds every row on the current page. Takes over from `columns`.',
type: '(data: { row: T; allData: T[] }) => ReactNode',
},
}}
/>
Want those rows sorted into categories? Combine `renderRow` with
[grouped rows](/docs/ui/data-table/grouped-rows).
# Draggable Rows (/docs/ui/data-table/draggable-rows)
## Preview [#preview]
<Preview name="data-table-reorderable" withoutBackground />
## Usage [#usage]
When the order _is_ the data, like a backlog or an FAQ, pass `reorderable`. Each
row gets a grip handle.
```tsx
<ContentDataTable
id="backlog-table"
// [!code ++:4]
reorderable={{
getRowLabel: (task) => task.title,
onReorder: async (ids) => await saveOrder(ids),
}}
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'position', order: 'asc' } }}
/>
```
- **Optimistic.** The row moves on drop and `onReorder` runs in the background.
If it rejects, the rows jump back and an error toast appears.
- **Only the handle drags.** Links, buttons and `rowOpens` in the row keep
working.
- **Mouse, touch and keyboard.** On touch, press and hold the handle briefly so
the page still scrolls. With a keyboard, focus a handle, press Space, move
with the arrows, Space to drop, Escape to cancel. Screen readers hear every
move.
- **Plays with the rest.** Open detail panels travel with their row. With
`bulkActions`, the handle sits before the checkbox. Reduced motion swaps rows
without sliding.
<Callout type="warn" title="Reordering pauses in a filtered view">
Handles lock while a search, filter or non-default sort is active, because
dragging there would shuffle rows nobody can see. Hovering says why. Make
`defaultOrder` your stored order, like `position` ascending.
</Callout>
## API [#api]
<TypeTable
type={{
onReorder: {
description:
'Called after a drop with every row id on the page in its new order. Reject to roll back.',
required: true,
type: `(ids: number[], details: {
activeId: number;
overId: number;
from: number;
to: number;
}) => void | Promise<void>`,
},
getRowLabel: {
description:
'The handle\'s accessible name, like "Reorder Fix the login loop". Defaults to the row position.',
type: '(row: T) => string',
},
disabled: {
description: 'Shows the handles but locks them, e.g. without permission.',
type: 'boolean',
},
}}
/>
## Save the order [#save-the-order]
The table hands you ids. Three pieces make them stick.
<Steps>
<Step>
#### Add a `position` column [#add-a-position-column]
```ts title="plugins/tasks/src/database/tasks.ts"
export const tasks = camelCase.table.withRLS(
'tasks',
(t) => ({
id: t.serial().primaryKey(),
title: t.varchar({ length: 255 }).notNull(),
// [!code ++]
position: t.integer().notNull().default(0),
}),
// [!code ++]
(t) => [index('tasks_position_idx').on(t.position)],
)
```
Sort the list route by it with `orderBy: { column: tasks.position, order: 'asc' }`.
Give new rows the current maximum plus one, or ties sort at random.
</Step>
<Step>
#### Accept the order in an admin route [#accept-the-order-in-an-admin-route]
The route gets one page of ids and hands those rows the positions they already
held between them, so reordering page 3 never touches page 1. Admin routes
always need a staff permission.
```ts title="plugins/tasks/src/api/modules/admin/tasks/routes/reorder.route.ts"
export const reorderTasksRoute = buildRoute({
// [!code ++]
adminStaffPermission: { module: 'tasks', permission: 'can_reorder' },
route: {
method: 'post',
path: '/reorder',
description: 'Save the order of one page of tasks (Admin only)',
request: {
body: {
required: true,
content: {
'application/json': {
schema: z.object({
ids: z.array(z.number().int()).min(1).max(100),
}),
},
},
},
},
responses: {
200: { description: 'Tasks reordered' },
400: {
content: {
'application/json': { schema: z.object({ error: z.string() }) },
},
description: 'Duplicated or unknown ids',
},
403: { description: 'Access Denied' },
},
},
handler: async (c) => {
const { ids } = c.req.valid('json')
const db = c.get('db')
if (new Set(ids).size !== ids.length) {
return c.json({ error: 'A task appears twice in the new order' }, 400)
}
const current = await db
.select({ position: tasks.position })
.from(tasks)
.where(inArray(tasks.id, ids))
if (current.length !== ids.length) {
return c.json({ error: 'The new order names an unknown task' }, 400)
}
const slots = current.map((row) => row.position).sort((a, b) => a - b)
await db.transaction(async (tx) => {
for (const [index, id] of ids.entries()) {
await tx
.update(tasks)
.set({ position: slots[index] })
.where(eq(tasks.id, id))
}
})
return c.body(null, 200)
},
})
```
Declare the permission in the plugin's API config:
```ts title="plugins/tasks/src/config.api.ts"
permissionStaff: {
admin: {
tasks: ['can_view', { permission: 'can_reorder', dependsOn: ['can_view'] }],
},
},
```
</Step>
<Step>
#### Call it from `onReorder` [#call-it-from-onreorder]
Throw to roll back. On success, invalidate the list so other views catch up.
```tsx
reorderable={{
getRowLabel: task => task.title,
onReorder: async ids => {
const res = await fetcher({
plugin: '@acme/tasks',
method: 'post',
module: 'admin/tasks',
path: '/reorder',
args: { body: { ids } },
})
if (!res.ok) throw new Error('Saving the order failed')
await queryClient.invalidateQueries({ queryKey: tasksQueryKey })
},
}}
```
</Step>
</Steps>
# Expandable Rows (/docs/ui/data-table/expandable-rows)
## Preview [#preview]
<Preview name="data-table-expandable" withoutBackground />
## Usage [#usage]
For rows with more to say than a cell holds, like an order's line items or a
job's error log. Each row gets a chevron that opens a panel in place.
```tsx
<ContentDataTable
id="orders-table"
// [!code ++:4]
expandable={{
render: (order) => <OrderDetail order={order} />,
canExpand: (order) => order.items.length > 0,
}}
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'number', order: 'asc' } }}
/>
```
- **Several rows can be open.** Open state lives in the component, not the URL,
and rows that leave the page are forgotten.
- **The chevron is a real button** with `aria-expanded` and `aria-controls`.
Enter and Space work, and `rowOpens` clicks still work on the rest of the row.
- **Works with `bulkActions`.** The chevron sits right after the checkbox.
- **Polite motion.** The panel springs open in about 300ms. With reduced motion
it only fades.
<Callout type="info" title="Fetch heavy details in the panel">
`render` runs only while a row is open. If the panel needs data the list
didn't load, fetch it inside the panel with TanStack Query, so re-opening is
instant.
</Callout>
## API [#api]
<TypeTable
type={{
render: {
description: 'Renders the detail panel for an open row.',
required: true,
type: '(row: T) => ReactNode',
},
canExpand: {
description:
"Return false to hide a row's chevron. All rows expand by default.",
type: '(row: T) => boolean',
},
defaultExpanded: {
description: 'Row ids open on the first render.',
type: 'number[]',
},
}}
/>
# Filters (/docs/ui/data-table/filters)
## Preview [#preview]
<Preview name="data-table-filters" withoutBackground />
## Usage [#usage]
Each filter is a multi-select dropdown next to the search input. It owns one
query parameter and stores picks comma-separated, like `?roleId=1,3`. Changing a
filter returns to page one.
```tsx
<ContentDataTable
id="users-table"
// [!code ++:9]
filters={[
{
id: 'status',
label: 'Status',
options: [
{ value: 'active', label: 'Active' },
{ value: 'banned', label: 'Banned' },
],
},
]}
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
Static `options` are searched on the client.
## Async options [#async-options]
For long lists, pass `onSearch` instead. It runs when the dropdown opens and
400ms after typing stops. Return results already filtered and capped by the
server.
```tsx title="search-roles.tsx"
import type { FilterOption } from '@vitnode/core/components/table/filters'
import { RoleFormat } from '@vitnode/core/components/role-format'
import { fetcher } from '@vitnode/core/tanstack/fetcher'
export const searchRoles = async (search: string): Promise<FilterOption[]> => {
const res = await fetcher({
plugin: '@vitnode/core',
method: 'get',
module: 'admin/roles',
path: '/list',
args: { query: { search, first: '20' } },
withPagination: true,
})
if (res.status !== 200) return []
const data = await res.json()
return data.edges.map((role) => ({
value: String(role.id),
label: <RoleFormat role={role} />,
keywords: role.name.map((item) => item.name),
}))
}
```
```tsx
filters={[{ id: 'roleId', label: 'Group', onSearch: searchRoles }]}
```
## Read it in the API [#read-it-in-the-api]
A filter only writes to the URL. The API route reads the parameter and adds the
`where` clause:
```ts
const roleIds = (query.roleId?.split(',') ?? [])
.filter(Boolean)
.map(Number)
.filter(id => !Number.isNaN(id))
where: roleIds.length ? inArray(core_users.roleId, roleIds) : undefined,
```
## API [#api]
<TypeTable
type={{
id: {
description: 'The query parameter this filter reads and writes.',
required: true,
type: 'string',
},
label: {
description: 'Trigger text and search placeholder.',
required: true,
type: 'string',
},
options: {
description:
'Static options. Add `keywords` so a node `label` is searchable.',
type: `{ value: string; label: ReactNode; keywords?: string[] }[]`,
},
onSearch: {
description: 'Async source, called on open and as the user types.',
type: '(search: string) => Promise<FilterOption[]>',
},
}}
/>
# Grouped Rows (/docs/ui/data-table/grouped-rows)
## Preview [#preview]
<Preview name="data-table-grouped" withoutBackground />
## Usage [#usage]
When rows belong to a category, like plugins by type or tasks by project, pass
`groupBy`. Return the category's name from `key`, and the Data Table puts each
category's rows under a heading that shows its name and how many rows it holds.
```tsx
<ContentDataTable
id="plugins-table"
// [!code ++]
groupBy={{ key: (plugin) => plugin.category }}
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
`groupBy` works with `columns` and with [custom rows](/docs/ui/data-table/custom-rows).
The AdminCP's **AI → Actions** page uses both: one card per action, grouped by
the plugin that registers it.
### Change the heading [#change-the-heading]
The heading shows the `key` by default. Pass `label` to render something
else, such as a translated name or an icon. The row count stays next to it.
```tsx
groupBy={{
key: (action) => action.pluginId,
label: (group) => <span className="font-mono">{group.key}</span>,
}}
```
### How the groups are ordered [#how-the-groups-are-ordered]
Groups appear in the order their first row does, and rows keep their order
within a group. To get groups in a particular order, sort the rows by the
category first, then by anything else. Ordering by category on the API is
usually enough.
Grouping happens per page. If a category runs across two pages, its heading
appears on both, with the count for that page.
<Callout type="warn" title="Not with draggable rows">
When `reorderable` is set, the Data Table ignores `groupBy`. Dragging a row
across a heading would move it into another category, and only your data can
say whether that is allowed.
</Callout>
## API [#api]
<TypeTable
type={{
key: {
description: 'Returns the group a row belongs to.',
required: true,
type: '(row: T) => string',
},
label: {
description: 'Renders the group heading. Defaults to the key.',
type: '(group: { key: string; rows: T[] }) => ReactNode',
},
}}
/>
# Data Table (/docs/ui/data-table)
## Preview [#preview]
<Preview name="data-table" withoutBackground />
## Usage [#usage]
```ts
import type { ColumnDef } from '@vitnode/core/components/table/data-table-content'
import { ContentDataTable } from '@vitnode/core/components/table/content'
```
```tsx
const columns: ColumnDef<User>[] = [
{ accessorKey: 'name', header: 'Name' },
{ accessorKey: 'email', header: 'Email' },
{ accessorKey: 'status', header: 'Status', align: 'center' },
{
id: 'actions',
header: '',
align: 'right',
cell: ({ row }) => <EditUserButton id={row.id} />,
},
]
<ContentDataTable
id="users-table"
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
Every row needs a numeric `id`. Render the table inside a
`DataTableNavigationProvider`, or its controls throw.
## Connect it to the URL [#connect-it-to-the-url]
The table never talks to the router. Search, filters, sorting and the pager all
hand a new query string to `navigate`, and the table renders whatever
`searchParams` says.
```tsx
import type { DataTableNavigation } from '@vitnode/core/components/table/navigation'
import { DataTableNavigationProvider } from '@vitnode/core/components/table/navigation'
const navigation = React.useMemo<DataTableNavigation>(
() => ({
searchParams: new URLSearchParams(search),
navigate: async nextSearch => {
await navigate({
resetScroll: false,
search: Object.fromEntries(new URLSearchParams(nextSearch)),
})
},
}),
[navigate, search],
)
<DataTableNavigationProvider value={navigation}>
<ContentDataTable {...props} />
</DataTableNavigationProvider>
```
The route's loader then fetches the page those params describe:
```ts
const res = await fetcher({
plugin: '@vitnode/core',
method: 'get',
module: 'admin/users',
path: '/list',
args: { query: search },
withPagination: true,
})
```
## Columns [#columns]
An **accessor column** binds to a field with `accessorKey`, which only accepts
`keyof T`, so typos fail at compile time. A **display column** (actions,
badges) has no field and needs a string `id`.
`cell` replaces the default text and gets `{ row, allData }`. `align` sets
`'left'` (default), `'center'` or `'right'` for the header and cells. Right
suits numbers and actions.
## Sorting [#sorting]
List sortable columns in `order.columns`. Clicking a header flips between
ascending and descending and writes `?orderBy=&order=` to the URL.
`defaultOrder` applies when the URL says nothing.
```tsx
order={{
columns: ['name', 'createdAt'],
defaultOrder: { column: 'createdAt', order: 'desc' },
}}
```
## Clickable rows [#clickable-rows]
`rowOpens` makes the whole row a target. It's focusable, and Enter or Space
opens it too. Clicks on links, buttons and inputs inside the row are ignored.
```tsx
rowOpens={user => navigate({ to: `/admin/core/users/${user.id}` })}
```
## Features [#features]
<Cards>
<Card
title="Search"
href="/docs/ui/data-table/search"
description="A debounced search box that writes to the URL."
/>
<Card
title="Filters"
href="/docs/ui/data-table/filters"
description="Faceted multi-select filters, static or async."
/>
<Card
title="Pagination"
href="/docs/ui/data-table/pagination"
description="Numbered pages and a rows-per-page select."
/>
<Card
title="Bulk actions"
href="/docs/ui/data-table/bulk-actions"
description="Tick rows and act on all of them at once."
/>
<Card
title="Expandable rows"
href="/docs/ui/data-table/expandable-rows"
description="A detail panel under each row."
/>
<Card
title="Draggable rows"
href="/docs/ui/data-table/draggable-rows"
description="Reorder rows and save the order."
/>
<Card
title="Custom rows"
href="/docs/ui/data-table/custom-rows"
description="Render each row as your own layout instead of cells."
/>
<Card
title="Grouped rows"
href="/docs/ui/data-table/grouped-rows"
description="Sort rows into categories, each under its own heading."
/>
</Cards>
## API [#api]
<TypeTable
type={{
id: {
description: 'DOM id of the table.',
required: true,
type: 'string',
},
columns: {
description:
'Accessor columns (`accessorKey: keyof T`) or display columns (`id: string`). Leave out when you pass `renderRow`.',
type: `ColumnDef<T>[]`,
},
renderRow: {
description:
'Renders each row as one full-width layout instead of column cells. Takes over from `columns`.',
type: '(data: { row: T; allData: T[] }) => ReactNode',
},
groupBy: {
description: 'Puts rows under a heading for each group.',
type: 'GroupByDataTable<T>',
},
edges: {
description: 'The rows of the current page.',
required: true,
type: 'T[]',
},
pageInfo: {
description: 'Pagination info from the API, passed straight through.',
required: true,
type: `{
count: number;
totalCount: number;
totalPages: number;
pageSize: number;
currentPage: number | null;
hasNextPage: boolean;
hasPreviousPage: boolean;
startCursor: string | null;
endCursor: string | null;
}`,
},
order: {
description: 'Sortable columns and the default sort.',
required: true,
type: `{
columns?: (keyof T)[];
defaultOrder: { column: keyof T; order: 'asc' | 'desc' };
}`,
},
rowOpens: {
description: 'Makes each row clickable and keyboard-focusable.',
type: '(row: T) => void',
},
header: {
description: 'A band above the toolbar, for a title or actions.',
type: 'ReactNode',
},
customNoResults: {
description: 'Replaces the empty state.',
type: `{
title?: string;
description?: string;
icon?: ReactNode;
footer?: ReactNode;
}`,
},
search: {
description: 'Shows a search input.',
type: 'boolean',
},
searchPlaceholder: {
description: 'Placeholder for the search input.',
type: 'string',
},
filters: {
description: 'Faceted filters.',
type: 'FilterDataTable[]',
},
bulkActions: {
description: 'Turns on row selection.',
type: 'ReactNode',
},
expandable: {
description: 'Turns on detail panels.',
type: 'ExpandableDataTable<T>',
},
reorderable: {
description: 'Turns on drag-and-drop ordering.',
type: 'ReorderableDataTable<T>',
},
}}
/>
Other props go to the underlying `Table`.
# Pagination (/docs/ui/data-table/pagination)
## Preview [#preview]
<Preview name="data-table-pagination" withoutBackground />
## Usage [#usage]
There's nothing to wire up. Pass `pageInfo` from the API and the table renders
numbered pages, a rows-per-page select (10, 20, 30 or 40) and a "Showing 21–30
of 380" range.
- **Pages are real links.** `?page=3` works with middle-click and "open in new
tab", while a plain click stays client-side.
- **Phones get a label.** Below `sm`, the numbers collapse to "Page 3 of 38"
between the arrows.
- **Filters and page size reset to page one.** The old page no longer means
what it did.
- **Too far lands on the last page.** The API clamps a page past the end, so
stale links still show rows.
The API does the counting. See [Pagination](/docs/dev/database/pagination) for
the route side, including the index your sorted column needs.
# Search (/docs/ui/data-table/search)
## Preview [#preview]
<Preview name="data-table-search" withoutBackground />
## Usage [#usage]
```tsx
<ContentDataTable
id="users-table"
// [!code ++:2]
search
searchPlaceholder="Search users..."
columns={columns}
edges={data.edges}
pageInfo={data.pageInfo}
order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```
The input writes `?search=` to the URL 500ms after typing stops. Terms shorter
than 3 characters clear it. Your route then loads the matching rows.
<Callout type="info" title="Configure the API route">
`search` only renders the input. The API route decides which columns are
searched. See the [Search](/docs/dev/database/search) guide.
</Callout>
# Date Picker (/docs/ui/date-picker)
The Date Picker is a [Calendar](/docs/ui/calendar) tucked inside a popover. It takes little space until someone needs it, then closes as soon as they pick a day.
## Preview [#preview]
<Preview name="date-picker-auto-form" />
## 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 { AutoFormDatePicker } from '@vitnode/core/components/form/fields/date-picker'
```
```tsx
const formSchema = z.object({
birthday: z.iso.date('Pick your birthday'),
anniversary: z.iso.date().optional(),
})
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'birthday',
component: props => (
<AutoFormDatePicker {...props} label="Birthday" />
),
},
{
id: 'anniversary',
component: props => (
<AutoFormDatePicker {...props} label="Community anniversary" />
),
},
]}
/>
```
The value is a `YYYY-MM-DD` string, so use `z.iso.date()` in the schema. It is the user's local day, with no time zone surprises on the way to your API. Optional fields get a **Clear** button.
</Tab>
<Tab value="Manual">
<Preview name="date-picker" />
```ts
import { DatePicker } from '@vitnode/core/components/ui/date-picker'
```
```tsx
const [date, setDate] = React.useState<Date>()
<Label htmlFor="event-date">Event date</Label>
<DatePicker allowClear id="event-date" onChange={setDate} value={date} />
```
</Tab>
</Tabs>
<Callout type="warn">
`z.date()` does not work in AutoForm: the schema is turned into JSON Schema,
which has no date type. Use `z.iso.date()` and convert on the server if you
need a `Date`.
</Callout>
## Calendar options [#calendar-options]
`calendarProps` passes any [Calendar](/docs/ui/calendar) prop through, except the selection ones. A birthday field with year dropdowns and no future dates:
```tsx
<AutoFormDatePicker
{...props}
calendarProps={{
captionLayout: 'dropdown',
disabled: { after: new Date() },
endMonth: new Date(),
startMonth: new Date(1926, 0),
}}
label="Birthday"
/>
```
## Date format [#date-format]
The button shows the date in the active VitNode language, `October 7, 2026` in English. Pass `Intl.DateTimeFormat` options to change it.
```tsx
<DatePicker
dateFormat={{ dateStyle: 'short' }}
onChange={setDate}
value={date}
/>
```
## Date range [#date-range]
<Preview name="date-picker-range" className="*:max-w-none" />
`DateRangePicker` picks a start and an end day. Quick ranges on the left apply in one click; a range picked on the calendar waits for **Apply range**, so a half-finished pick never fires a request. The button shows the preset's name, or the dates like `Oct 7 – 12, 2026`.
```ts
import { DateRangePicker } from '@vitnode/core/components/ui/date-range-picker'
```
```tsx
const [range, setRange] = React.useState({ from: weekAgo, to: today })
const [preset, setPreset] = React.useState<'7d' | '30d' | null>('7d')
<DateRangePicker
activePreset={preset}
disabledDays={{ after: today }}
endMonth={today}
onChange={next => {
setPreset(null)
setRange(next)
}}
onPresetSelect={next => {
setPreset(next)
setRange(resolve(next))
}}
presets={[
{ key: '7d', label: 'Last 7 days' },
{ key: '30d', label: 'Last 30 days' },
]}
value={range}
/>
```
You own the presets: `onPresetSelect` hands you the key and you work out the dates, so "Last 7 days" can mean the site's time zone instead of the browser's. The calendar shows two months on wide screens and one on phones.
## Accessibility [#accessibility]
- `AutoFormDatePicker` wires the label, description and error to the button.
- With `DatePicker` alone, give it an `id` and a `<Label htmlFor>`.
- Opening the popover moves focus into the calendar. Escape closes it and focus returns to the button.
- A validation message waits until focus leaves the field, not when the popover opens.
## Props [#props]
### DatePicker [#datepicker]
`DatePicker` also takes every `<button>` prop.
<TypeTable
type={{
value: { description: 'The selected date.', type: 'Date' },
onChange: {
description: 'Called with the picked date, or `undefined` when cleared.',
type: '(date: Date | undefined) => void',
},
placeholder: {
description: 'Text shown before a date is picked.',
type: 'string',
default: "'Pick a date'",
},
allowClear: {
description: 'Show a Clear button in the popover.',
type: 'boolean',
default: 'false (AutoForm: true for optional fields)',
},
dateFormat: {
description: 'How the button formats the date.',
type: 'Intl.DateTimeFormatOptions',
default: "{ dateStyle: 'long' }",
},
calendarProps: {
description: 'Props for the inner Calendar, minus the selection ones.',
type: 'CalendarProps',
},
}}
/>
`AutoFormDatePicker` takes the same props, except its `onChange` receives the `YYYY-MM-DD` string.
### DateRangePicker [#daterangepicker]
`DateRangePicker` also takes every `<button>` prop.
<TypeTable
type={{
value: {
description: 'The selected range.',
type: '{ from: Date; to: Date }',
},
onChange: {
description:
'Called with a range picked on the calendar, after Apply range.',
type: '(range: { from: Date; to: Date }) => void',
},
presets: {
description: 'Quick ranges listed beside the calendar.',
type: '{ key: string; label: string }[]',
default: '[]',
},
activePreset: {
description:
'The preset the current range came from. The button shows its label.',
type: 'string | null',
},
onPresetSelect: {
description:
'Called with the key of a clicked preset. The popover closes.',
type: '(key: string) => void',
},
disabledDays: {
description: 'Days that cannot be picked, as Calendar matchers.',
type: 'Matcher | Matcher[]',
},
startMonth: {
description: 'The first month the calendar can show.',
type: 'Date',
},
endMonth: {
description: 'The last month the calendar can show.',
type: 'Date',
},
align: {
description: 'Where the popover lines up with the button.',
type: "'start' | 'center' | 'end'",
default: "'end'",
},
}}
/>
# Dialog (/docs/ui/dialog)
## Preview [#preview]
<Preview name="dialog" />
## 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">Share</Button>} />
<DialogContent>
<DialogHeader>
<DialogTitle>Share this page</DialogTitle>
<DialogDescription>Anyone with the link can read it.</DialogDescription>
</DialogHeader>
<DialogFooter>
<DialogClose render={<Button>Done</Button>} />
</DialogFooter>
</DialogContent>
</Dialog>
```
Always add a `DialogTitle`. It names the dialog for screen readers.
## Forms [#forms]
<Preview name="dialog-form" />
Put an `AutoForm` inside and it renders a Cancel + Submit footer for you. Edit a
field, then press <kbd>Escape</kbd>: the dialog asks before throwing your
changes away.
```tsx
const EditCategoryForm = () => {
const { setOpen } = useDialog()
return (
<AutoForm
fields={fields}
formSchema={formSchema}
onSubmit={async (values) => {
await save(values)
setOpen?.(false)
}}
/>
)
}
```
`useDialog()` gives children `setOpen` and `setIsDirty`. Closing with `setOpen`
skips the guard, so call it after a successful save. Lazy-load heavy forms
with `React.lazy` and `Suspense`.
## Long content [#long-content]
<Preview name="dialog-scroll" />
Content taller than the screen scrolls inside the dialog. The page behind stays
put.
## Nested dialogs [#nested-dialogs]
<Preview name="dialog-nested" />
Open an [Alert Dialog](/docs/ui/alert-dialog) from inside a dialog to confirm a
risky step. Closing it brings you back to the first dialog.
## Controlled [#controlled]
```tsx
<Dialog onOpenChange={setOpen} open={open}>
...
</Dialog>
```
`onOpenChange` receives just the new `boolean`. Clicking a toast never closes
the dialog underneath.
## Dialog or Alert Dialog? [#dialog-or-alert-dialog]
Dialog is for low-stakes tasks and closes on an outside click. Confirming
something nobody can undo? Use an [Alert Dialog](/docs/ui/alert-dialog).
## Props [#props]
<TypeTable
type={{
'DialogContent.showCloseButton': {
description: 'Shows the × button in the corner.',
type: 'boolean',
default: 'true',
},
'DialogFooter.showCloseButton': {
description: 'Adds an outline Close button to the footer.',
type: 'boolean',
default: 'false',
},
'Dialog.onOpenChange': {
description: 'Called with the new open state.',
type: '(open: boolean) => void',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)
# Drawer (/docs/ui/drawer)
## Preview [#preview]
<Preview name="drawer" />
## Usage [#usage]
```ts
import {
Drawer,
DrawerClose,
DrawerContent,
DrawerDescription,
DrawerFooter,
DrawerHeader,
DrawerTitle,
DrawerTrigger,
} from '@vitnode/core/components/ui/drawer'
```
```tsx
<Drawer>
<DrawerTrigger asChild>
<Button variant="outline">Report post</Button>
</DrawerTrigger>
<DrawerContent>
<DrawerHeader>
<DrawerTitle>What's wrong with this post?</DrawerTitle>
<DrawerDescription>Moderators see your report.</DrawerDescription>
</DrawerHeader>
<DrawerFooter>
<DrawerClose asChild>
<Button variant="ghost">Cancel</Button>
</DrawerClose>
</DrawerFooter>
</DrawerContent>
</Drawer>
```
`DrawerTrigger` and `DrawerClose` take `asChild` or Base UI's `render` to use
your own button. Wrap wide content in `mx-auto max-w-sm` so it doesn't stretch
across a desktop.
## Direction and swipe [#direction-and-swipe]
<Preview name="drawer-direction" />
`direction` picks the edge: `bottom` (default), `top`, `left` or `right`. Swipe
toward that edge to close. A quick flick closes it even from a short drag, a
slow nudge springs back, and the backdrop fades as you drag.
```tsx
<Drawer direction="right">...</Drawer>
```
Bottom drawers get a grab handle and stop at 80% of the screen height. With
reduced motion on, the drawer opens and closes instantly, but dragging still
follows your finger.
## Props [#props]
<TypeTable
type={{
direction: {
description: 'Edge the drawer slides in from and swipes back to.',
type: '"bottom" | "top" | "left" | "right"',
default: '"bottom"',
},
'DrawerTrigger.asChild': {
description: 'Render the child element as the trigger.',
type: 'boolean',
default: 'false',
},
'DrawerClose.asChild': {
description: 'Render the child element as the close button.',
type: 'boolean',
default: 'false',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Drawer](https://base-ui.com/react/components/drawer)
# Dropdown Menu (/docs/ui/dropdown-menu)
## Preview [#preview]
<Preview name="dropdown-menu" />
## Usage [#usage]
```ts
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuSeparator,
DropdownMenuShortcut,
DropdownMenuTrigger,
} from '@vitnode/core/components/ui/dropdown-menu'
```
```tsx
<DropdownMenu>
<DropdownMenuTrigger render={<Button variant="outline">Open</Button>} />
<DropdownMenuContent className="w-56">
<DropdownMenuLabel>My Account</DropdownMenuLabel>
<DropdownMenuItem>
Profile
<DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem>Log out</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
```
The menu matches the trigger's width (at least `min-w-36`). Set a width with
`className` when the trigger is small. `DropdownMenuShortcut` is only a label:
bind the keys yourself.
Nest `DropdownMenuSub`, `DropdownMenuSubTrigger` and `DropdownMenuSubContent`
for a submenu. It opens on hover, click or the right arrow.
## Icon trigger and destructive items [#icon-trigger-and-destructive-items]
<Preview name="dropdown-menu-actions" />
An icon-only trigger needs an `aria-label`. Use `align="end"` when the trigger
sits at the end of a row, and `variant="destructive"` for actions you can't
take back.
```tsx
<DropdownMenuTrigger
render={
<Button aria-label="Post actions" size="icon-sm" variant="ghost">
<EllipsisIcon />
</Button>
}
/>
<DropdownMenuContent align="end">
<DropdownMenuItem variant="destructive">
<Trash2Icon />
Delete
</DropdownMenuItem>
</DropdownMenuContent>
```
## Checkbox and radio items [#checkbox-and-radio-items]
<Preview name="dropdown-menu-checkboxes" />
`DropdownMenuCheckboxItem` toggles on its own. Items in a
`DropdownMenuRadioGroup` pick one. The check mark sits at the start of the row,
like in the [Context Menu](/docs/ui/context-menu) and
[Menubar](/docs/ui/menubar). Add `inset` to labels and plain items in the same
menu so their text lines up.
```tsx
<DropdownMenuCheckboxItem checked={showPinned} onCheckedChange={setShowPinned}>
Pinned threads
</DropdownMenuCheckboxItem>
<DropdownMenuRadioGroup onValueChange={setSort} value={sort}>
<DropdownMenuRadioItem value="latest">Latest activity</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
```
## Accessibility [#accessibility]
- Arrow keys move between items, typing a letter jumps to a match and
<kbd>Escape</kbd> closes the menu and returns focus to the trigger.
- Rows grow to a 44px tap target on touch screens. Long menus scroll without
dragging the page.
- The menu scales in from its trigger in 150ms and leaves in 100ms. Reduced
motion turns that off.
## Props [#props]
### DropdownMenuContent [#dropdownmenucontent]
<TypeTable
type={{
side: {
description:
'Preferred side of the trigger. Flips when there is no room.',
type: '"top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"',
default: '"bottom"',
},
align: {
description: 'Alignment against the trigger.',
type: '"start" | "center" | "end"',
default: '"start"',
},
sideOffset: {
description: 'Gap from the trigger in pixels.',
type: 'number',
default: '4',
},
alignOffset: {
description: 'Shift along the alignment axis in pixels.',
type: 'number',
default: '0',
},
}}
/>
`DropdownMenuSubContent` opens to the `right` with `alignOffset={-4}`, so its
first item lines up with the sub-trigger.
### DropdownMenuItem [#dropdownmenuitem]
<TypeTable
type={{
variant: {
description: 'The look of the item.',
type: '"default" | "destructive"',
default: '"default"',
},
inset: {
description: 'Start padding to line up with checkbox and radio items.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'Visible but not interactive.',
type: 'boolean',
default: 'false',
},
closeOnClick: {
description: 'Close the menu when the item is chosen.',
type: 'boolean',
default: 'true',
},
}}
/>
`DropdownMenuLabel` and `DropdownMenuSubTrigger` accept `inset` too.
## API Reference [#api-reference]
[Base UI - Menu](https://base-ui.com/react/components/menu#api-reference)
# Editor images (/docs/ui/editor-images)
Every `Editor` keeps the images a document already has, but accepts new ones only when you pass `uploads`. Turn it on where pictures belong (an article, a forum topic) and leave it off where they don't (a moderator note). Uploaded images land in `core_files`, like avatars and Content Engine files.
## Allow uploads in an editor [#allow-uploads-in-an-editor]
Add `uploads` to `Editor` or `AutoFormEditor`:
```tsx
<AutoFormEditor {...props} format="json" label="Body" uploads />
```
People can now:
- drag images from their desktop into the text,
- paste a screenshot straight from the clipboard,
- pick files from **+ Insert → Image**.
A placeholder with a spinner sits in the text while the image uploads, then the stored image takes its place. A file that isn't an image, or is too big, never leaves the browser and shows a toast instead.
### Upload from the AdminCP [#upload-from-the-admincp]
By default the editor uploads as the signed-in member (`POST /users/files/editor`). Inside the AdminCP, upload with the AdminCP session instead:
```tsx
<AutoFormEditor {...props} format="json" label="Content" uploads={{ session: 'admin' }} />
```
That posts to `POST /admin/files/editor` and needs the staff permission **Files → Upload images in editors** (`files:can_upload`).
### Attach files [#attach-files]
An AdminCP editor can also take PDF, Word, PowerPoint and ZIP files. Add `files: true`:
```tsx
<AutoFormEditor {...props} format="json" label="Content" uploads={{ files: true, session: 'admin' }} />
```
A dropped or pasted document becomes a card with its icon, name, type and size, and **+ Insert → File** opens a file picker.
<ImgDocs
alt="An article in the editor with an image wrapped by text and two attachment cards below it: price-list.pdf and brand-assets.zip, each with its type, size and an open button"
src={attachments}
withoutBackground
/>
Readers open the file in a new tab. The blog's article editor works this way. `files` needs `session: 'admin'`. The member route accepts images only, so TypeScript refuses `files` without it.
### Content Engine fields [#content-engine-fields]
A Content Engine rich text field turns uploads on with one option. The AdminCP form then uploads with the AdminCP session:
```ts
body: field.richText({ required: true, uploads: true }),
```
## Edit an image [#edit-an-image]
Click an image in the editor. A settings button appears in its corner:
<ImgDocs
alt="An image wrapped to the left of two paragraphs, with the Image settings popover open: image wrap (Default, Left wrap, Right wrap), width slider, ALT text, Replace and Remove"
src={imageSettings}
withoutBackground
/>
| Setting | What it does |
| ------------- | -------------------------------------------------------------------------------------------------- |
| **Image wrap** | `Default` puts the image on its own line, aligned like the text. `Left wrap` and `Right wrap` let the text flow around it |
| **Width** | 10–100% of the text column. Dragging the handle on the image's edge does the same |
| **ALT text** | Describe your image: screen readers say this instead of the picture. Up to 500 characters |
| **Replace** | Uploads a new file and keeps the width, wrap and ALT text |
| **Remove** | Deletes the image from the document. The file stays in `core_files` until it is deleted there |
Choosing `Left wrap` or `Right wrap` on a full-width image shrinks it to 50% to leave room for the text. On phones, wrapped images stack above the text instead of squeezing it into a thin column.
### Alignment [#alignment]
With `Default` wrap, an image follows the editor's **Alignment** like text does. A new image takes the alignment of the paragraph it lands in, and the toolbar's left, center and right alignment work on a selected image. The alignment is saved as `textAlign` on the image node.
## Reuse uploads in other languages [#reuse-uploads-in-other-languages]
A translated article usually needs the same pictures. Nobody has to upload them twice. When another language version of the field uses images or files this one doesn't have yet, a **Reuse from English** bar (named after those languages) appears right under the toolbar:
- **Click** an image or file in the bar to insert it at the cursor, or **Insert all** to add every one.
- **Drag** it from the bar to the exact spot in the text.
- You can also drag an image or file card straight from the source column in translate mode.
Both point at the same `core_files` file, so nothing is uploaded again, and deleting that file later updates every language. Each item leaves the bar once this language uses it, and the bar goes away when nothing is left. It appears in `AutoFormEditor` with `multiLang` when `uploads` is on; a plain `Editor` can pass its own list through the `reusableUploads` prop.
## When a file is deleted [#when-a-file-is-deleted]
Deleting an uploaded file, from **Settings → Files** or from **AdminCP → Files**, also removes it from every document that showed it. The image or attachment is replaced by a placeholder saying **Image deleted** or **File deleted**, with its old ALT text or file name crossed out. Nothing in it links to the removed file.
This happens once, right after the delete, in Content Engine rich text: records, translations, repeatable rows, revision history, live-editing drafts, and editors open at that moment. Cached public pages of the affected content types are expired. The author can remove the placeholder like any other block.
## Allow images from other sites [#allow-images-from-other-sites]
By default every image is uploaded to your storage. To also let people insert an image by its address, set `editor.images.remote` in the app config:
```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
editor: {
images: { remote: true },
},
})
```
**+ Insert → Image** then gets a **From URL** tab, and pasted HTML may keep images from other sites. Only `https://` addresses are accepted, so a page served over HTTPS never shows mixed-content warnings. It only applies to editors that already allow uploads.
The setting decides what the editor offers. A request sent straight to your API can still store any `http(s)` image in a rich text document, and renderers show it.
## Limits [#limits]
| Limit | Images | Attachments (`files: true`) |
| ------------ | -------------------------- | ------------------------------------------- |
| File types | PNG, JPEG, WebP, GIF, AVIF | PDF, DOC, DOCX, PPT, PPTX, ZIP |
| Size | 10 MB each | 20 MB each |
| Storage path | `editor/` folder | `editor/` folder |
| Owner | The uploader | The uploader |
SVG is left out on purpose, because an SVG can carry scripts. An attachment must have the extension that matches its type, and its first bytes must look like that format (`%PDF`, a ZIP header, or the legacy Office header), so a renamed executable is refused. With `storage.image` set in the API config, images are re-encoded (to WebP by default) like every other upload. Without a `storage.adapter`, uploads fail with a `500`.
## How images and files are stored [#how-images-and-files-are-stored]
An image is an `image` node in the document:
```json
{
"type": "image",
"attrs": {
"src": "https://cdn.example.com/2026/10/editor/4f1c.webp",
"alt": "Our booth at the conference",
"fileId": 42,
"width": 50,
"wrap": "left",
"textAlign": null,
"naturalWidth": 1600,
"naturalHeight": 900
}
}
```
`RichTextContent` and `richTextToHtml` render it as `<figure class="tiptap-image">` with a lazy-loaded `<img>`. `width` and `height` come from the stored file, so the page doesn't jump while it loads.
An attachment is an `attachment` node:
```json
{
"type": "attachment",
"attrs": {
"src": "https://cdn.example.com/2026/10/editor/9b2e.pdf",
"name": "price-list.pdf",
"mimeType": "application/pdf",
"size": 397312,
"fileId": 43
}
}
```
It renders as `<a class="tiptap-attachment">` opening the file in a new tab, labelled `PDF · 388 KB`. HTML editors store the same markup, and `EditorContent` keeps both through sanitizing.
After [the file is deleted](#when-a-file-is-deleted), the node keeps its `name` (or `alt`) and layout but has `"deleted": true`, `"src": null` and `"fileId": null`. `RichTextContent` renders the translated placeholder; `richTextToHtml` leaves it out.
- [Editor](/docs/ui/editor): toolbar, shortcuts and props.
- [Rich text](/docs/content-engine/rich-text): rendering stored documents.
# Editor (/docs/ui/editor)
## Preview [#preview]
<Preview name="editor" />
Type <kbd>/</kbd> for blocks or <kbd>:</kbd> for emoji. Your fingers never leave
the keyboard, and your coffee stays safe.
## 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'
const formSchema = z.object({
content: z.string().min(1, 'Write something first'),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'content',
component: (props) => <AutoFormEditor {...props} label="Announcement" />,
},
]}
/>
```
</Tab>
<Tab value="Manual">
`value` is the initial HTML. `onChange` gets the current HTML on every edit.
```tsx
import { Editor } from '@vitnode/core/components/ui/editor'
const [content, setContent] = useState('<p>Hello World! 🌎️</p>')
;<Editor onChange={setContent} value={content} />
```
</Tab>
</Tabs>
## Toolbar [#toolbar]
One row, even in a narrow form. Everyday tools sit up front, the rest in menus:
- **Text style**: paragraph or heading 1–4.
- **Bold**, **italic** and **…**: underline, strikethrough, inline code,
alignment, _Clear formatting_.
- **Text color**, **lists** (bulleted, numbered, task), **link**, **emoji**,
**table**, **code block**.
- **+ Insert**: quote, code block, table, divider, emoji, audio and panels,
plus images and files when the editor allows [uploads](/docs/ui/editor-images).
Images and files from other languages show in a **Reuse** bar under the toolbar.
## Slash commands [#slash-commands]
Type <kbd>/</kbd>, keep typing to filter (`/tab` finds _Table_), pick with the
arrow keys and <kbd>Enter</kbd>. Search matches translated names and English
keywords, so `/table` works in every language.
## Emoji [#emoji]
Type <kbd>:</kbd> and a few letters (`:rocket`) to get suggestions, or use the
toolbar picker. Add your own emoji for every editor in `vitnode.config.ts`:
```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
editor: {
emojis: [
{
label: 'VitNode',
emojis: [
{ name: 'vitnode', src: '/logo.svg', tags: ['logo', 'brand'] },
],
},
],
},
})
```
`name` is the shortcode (`:vitnode:`), `tags` are extra search words, and
`label` heads the section in the picker.
## Panels [#panels]
<Preview name="editor-panels" />
Callouts in four kinds: `info`, `warning`, `error`, `success`. One paragraph is
a muted note. Add a second and the first becomes the title.
Insert one from **+ Insert** or `/panel`. Picking the same kind again removes
it; another kind switches the color. Panels are saved as plain HTML,
`<div class="tiptap-panel" data-panel="info">`, so `EditorContent` renders them
as is.
## Task lists [#task-lists]
Each item stores its checkbox state, so acceptance criteria stay ticked after
saving. Start one from the toolbar, `/task`, or type `[ ]` at the start of a
line.
## Keyboard shortcuts [#keyboard-shortcuts]
| Action | Shortcut |
| --------------- | ----------------------------------------------------------------------------- |
| Submit the form | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Enter</kbd> |
| Bold / italic | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>B</kbd> / <kbd>I</kbd> |
| Underline | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>U</kbd> |
| Bulleted list | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> |
| Numbered list | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> |
| Task list | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd> |
| Undo / redo | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Z</kbd> / <kbd>Shift</kbd> + <kbd>Z</kbd> |
<kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Enter</kbd> submits the surrounding form,
like its submit button. Outside a form it does nothing.
## Accessibility [#accessibility]
- The toolbar is one tab stop. <kbd>←</kbd> <kbd>→</kbd> move between buttons,
<kbd>Home</kbd> / <kbd>End</kbd> jump to the ends.
- In AutoForm, the writing area is named by the label, described by the
description and error, and outlined red when invalid.
- The `/` and `:` menus announce the highlighted option, and open upward when
there's no room below.
- A same-size placeholder holds the spot while the editor loads, so the page
doesn't jump.
## Multi-language [#multi-language]
Add `multiLang` to edit the content in every enabled language. A language select
(shown with two or more languages) switches the language being edited, not the
app locale.
```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'
const formSchema = z.object({
content: multiLangValueSchema({ minLength: 1 }).min(1),
})
```
```tsx
<AutoFormEditor {...props} label="Content" multiLang />
```
The value becomes `{ languageCode, value }[]`, matching `core_languages_words`:
```ts
const value = [
{ languageCode: 'en', value: '<p>Hello</p>' },
{ languageCode: 'pl', value: '<p>Cześć</p>' },
]
```
Save it with `saveLanguageWords`. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).
## Rendering content [#rendering-content]
<Preview name="editor-content" />
`EditorContent` renders stored HTML read-only, for public pages. It sanitizes
the HTML first, so a sneaky `<script>` never runs.
```tsx
import { EditorContent } from '@vitnode/core/components/ui/editor-content'
;<EditorContent content={post.content} />
```
## Props [#props]
<TypeTable
type={{
value: {
description: 'Initial HTML content.',
type: 'string',
default: '""',
},
onChange: {
description: 'Called on every change with the current HTML.',
type: '(value: string) => void',
},
placeholder: {
description: 'Shown while the editor is empty.',
type: 'string',
default: '"Write something…"',
},
disableScroll: {
description:
'Removes the max-height scroll area so the editor grows with its content.',
type: 'boolean',
default: 'false',
},
className: {
description: 'Extra classes for the editor wrapper.',
type: 'string',
},
multiLang: {
description:
'AutoFormEditor only. Edit per language; the value becomes { languageCode, value }[].',
type: 'boolean',
default: 'false',
},
reusableUploads: {
description:
'Images and files from other language versions, shown in a Reuse bar under the toolbar. AutoFormEditor with multiLang fills it in.',
type: 'EditorReusableUpload[]',
},
uploads: {
description:
'Lets people drop, paste and insert images, stored in core_files. `{ session: "admin" }` uploads with the AdminCP session; add `files: true` for PDF, Word, PowerPoint and ZIP attachments. See Editor images.',
type: 'boolean | { session?: "member" } | { session: "admin"; files?: boolean }',
default: 'false',
},
}}
/>
# Radius & Elevation (/docs/ui/elevation)
One variable sets every corner, six soft shadows set every height, and in dark
mode the surfaces themselves get lighter as they rise. Depth without the drama.
## Radius scale [#radius-scale]
<Preview name="elevation-radius-scale" className="*:max-w-full" />
Every `rounded-*` class is a multiple of `--radius` (`0.75rem`). Drag the slider
to feel it: change the one variable in `src/styles.css` and the whole UI gets
rounder or sharper.
```css
:root {
--radius: 0.75rem;
}
```
## Corners nest [#corners-nest]
<Preview name="elevation-concentric" className="*:max-w-full" />
Inner radius = outer radius − padding. Copy the outer radius onto the inner box
and the corners bulge like a badly packed suitcase. That's why menus are
`rounded-lg` with `p-1` and their items are `rounded-sm`.
```tsx
<div className="rounded-lg p-1">
<button className="rounded-sm px-2 py-1.5">Edit</button>
</div>
```
## Shadow scale [#shadow-scale]
<Preview name="elevation-shadows" className="*:max-w-full" />
Shadows are soft and low-alpha: they hint at height instead of shouting it. The
higher something floats, the bigger its shadow. Flip to dark mode and they almost
vanish. That's on purpose, see below.
## Where things live [#where-things-live]
<Preview name="elevation-layers" className="*:max-w-full" />
Each level has its own surface, radius and shadow. In light mode the shadow
carries the depth. In dark mode shadows disappear, so each layer gets lighter
instead: `background` → `card` → `popover`. Dialogs share one scrim from
`modal-scrim.ts`, so every modal dims the page the same way.
| Level | Surface | Radius | Shadow |
| ----------------- | ------------ | ------------ | ---------------------- |
| Controls | `bg-card` | `rounded-md` | `shadow-xs` |
| Cards | `bg-card` | `rounded-xl` | `shadow-xs` + `ring-1` |
| Menus and selects | `bg-popover` | `rounded-lg` | `shadow-lg` + `ring-1` |
| Popovers | `bg-popover` | `rounded-xl` | `shadow-lg` + `ring-1` |
| Dialogs | `bg-popover` | `rounded-xl` | `shadow-xl` + scrim |
## Border or shadow? [#border-or-shadow]
<Preview name="elevation-border-shadow" className="*:max-w-full" />
Content that stays in the page flow gets a hairline `border`. Anything that
floats above it gets a shadow and a faint `ring-1 ring-foreground/10`, so it
still has an edge in dark mode.
## Related [#related]
<Cards>
<Card
title="Colors"
href="/docs/ui/colors"
description="Surface tokens and how they stack in dark mode."
/>
<Card
title="Spacing"
href="/docs/ui/spacing"
description="The spacing scale behind padding and nested corners."
/>
<Card
title="Motion"
href="/docs/ui/motion"
description="How floating layers enter and leave the screen."
/>
</Cards>
# Emoji & Icon Picker (/docs/ui/emoji-icon-picker)
## Preview [#preview]
<Preview name="emoji-icon-picker-auto-form" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Standalone']}>
<Tab value="Auto Form">
The field stores the serialized string, so a plain `z.string()` does the job.
```ts
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormEmojiIcon } from '@vitnode/core/components/form/fields/emoji-icon'
import { EMOJI_ICON_MAX_LENGTH } from '@vitnode/core/lib/emoji-icon'
const formSchema = z.object({
prefix: z.string().max(EMOJI_ICON_MAX_LENGTH).default(''),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'prefix',
component: (props) => (
<AutoFormEmojiIcon {...props} allowRemove label="Prefix" />
),
},
]}
/>
```
</Tab>
<Tab value="Standalone">
<Preview name="emoji-icon-picker-standalone" />
```tsx
import { EmojiIconPicker } from '@vitnode/core/components/ui/emoji-icon-picker'
import type { EmojiIconValue } from '@vitnode/core/lib/emoji-icon'
const [icon, setIcon] = useState<EmojiIconValue | undefined>()
<EmojiIconPicker allowRemove onChange={setIcon} value={icon} />
```
</Tab>
</Tabs>
## The value [#the-value]
```ts
type EmojiIconValue =
{ type: 'emoji'; value: string } | { type: 'icon'; value: string }
```
An emoji value is the character (`🚀`). An icon value is a kebab-case
[Lucide](https://lucide.dev/icons) name (`shield-check`), readable in the
database and portable to any Lucide renderer.
For storage, serialize it to `emoji:🚀` or `icon:rocket`. It fits a
`varchar(64)` column.
```ts
import {
parseEmojiIcon,
serializeEmojiIcon,
} from '@vitnode/core/lib/emoji-icon'
serializeEmojiIcon({ type: 'icon', value: 'rocket' })
parseEmojiIcon('emoji:🚀')
parseEmojiIcon('icon:../../etc/passwd')
```
These return `"icon:rocket"`, `{ type: 'emoji', value: '🚀' }` and `undefined`.
`parseEmojiIcon` is also the validator: anything that isn't exactly one emoji or
one icon name comes back `undefined`.
<Callout type="warn" title="Validate on the server too">
The picker only produces valid values. A request body can say anything, so
parse it before you write it:
```ts
prefix: serializeEmojiIcon(parseEmojiIcon(body.prefix)) || null
```
</Callout>
## Rendering a stored value [#rendering-a-stored-value]
<Preview name="emoji-icon-picker-render" />
`EmojiIcon` renders a parsed value: a glyph for an emoji, an SVG for an icon.
An invalid value renders nothing.
```tsx
import { EmojiIcon } from '@vitnode/core/components/ui/emoji-icon'
;<EmojiIcon value={parseEmojiIcon(role.prefix)} />
```
Only icon names? Use [`DynamicIcon`](/docs/ui/icons#icons-by-name). Icons
rendered on the server arrive in the first HTML, and the browser never ships the
whole icon library. That needs one line in `getRouter()`, already in the
scaffold:
```tsx title="src/router.tsx"
import { setupLucideIconSsr } from '@vitnode/core/tanstack/icons'
setupLucideIconSsr({ router })
```
Without it, `DynamicIcon` still works but loads icons in the browser after the
page renders.
Both are `aria-hidden`, since they decorate nearby text. An icon-only control
needs its own `aria-label`.
## Role prefixes [#role-prefixes]
A role's **Prefix** field (General tab of its edit dialog) uses this picker. The
prefix shows before the role name and before every member's name wherever
[`RoleFormat`](/docs/ui/role-format) or [`UserFormat`](/docs/ui/user-format) renders. It arrives as `role.prefix`
(`null | string`), and both components parse it for you.
```tsx
<UserFormat format user={user} />
```
## Performance and keyboard [#performance-and-keyboard]
- Only the trigger ships with your page. Emoji data loads when the popover
opens, and the ~1750 icons load only when someone opens the **Icon** tab.
- The icon grid is virtualized, so its size doesn't hurt scrolling.
- The grid is one tab stop. Arrows move (up and down jump a row),
<kbd>Home</kbd> / <kbd>End</kbd> go to the row's ends, <kbd>Enter</kbd> or
<kbd>Space</kbd> picks.
- The emoji picker here and in the editor toolbar share grid size, search and
skin tone switch.
## Props [#props]
### EmojiIconPicker [#emojiiconpicker]
<TypeTable
type={{
value: {
description: 'The current selection.',
type: 'EmojiIconValue | undefined',
default: 'undefined',
},
onChange: {
description:
'Called with the new selection, or `undefined` when cleared. Picking closes the popover.',
type: '(value: EmojiIconValue | undefined) => void',
required: true,
},
allow: {
description: 'Which tabs to offer. One kind shows that picker alone.',
type: "readonly ('emoji' | 'icon')[]",
default: "['emoji', 'icon']",
},
allowRemove: {
description: 'Shows a clear button once something is picked.',
type: 'boolean',
default: 'false',
},
placeholder: {
description: 'Trigger text while nothing is picked.',
type: 'string',
default: '"Pick an emoji or icon"',
},
}}
/>
Other `button` props go to the trigger. `AutoFormEmojiIcon` takes the same props
except `value` and `onChange`.
### EmojiPicker and IconPicker [#emojipicker-and-iconpicker]
<Preview name="emoji-icon-picker-panels" />
The bare panels, with no popover or trigger. Drop them into a dialog, sidebar or
toolbar.
```tsx
import { EmojiPicker } from '@vitnode/core/components/ui/emoji-picker'
import { IconPicker } from '@vitnode/core/components/ui/icon-picker'
;<IconPicker onSelect={setIcon} value={icon} />
```
<TypeTable
type={{
onSelect: {
description: 'Called with the emoji character or the Lucide icon name.',
type: '(value: string) => void',
required: true,
},
value: {
description: 'IconPicker only. Highlights the current icon.',
type: 'string',
},
height: {
description: 'Height of the scrollable list, in pixels.',
type: 'number',
default: '288',
},
autoFocus: {
description: 'Focuses the search input on mount.',
type: 'boolean',
default: 'false',
},
}}
/>
# Empty (/docs/ui/empty)
<Preview name="empty" />
## Usage [#usage]
```ts
import {
Empty,
EmptyContent,
EmptyDescription,
EmptyHeader,
EmptyMedia,
EmptyTitle,
} from '@vitnode/core/components/ui/empty'
```
```tsx
<Empty>
<EmptyHeader>
<EmptyMedia variant="icon">
<FolderCode />
</EmptyMedia>
<EmptyTitle>No projects yet</EmptyTitle>
<EmptyDescription>
Start a fresh one or import a repository.
</EmptyDescription>
</EmptyHeader>
<EmptyContent>
<Button>Create project</Button>
</EmptyContent>
</Empty>
```
Use it wherever a screen would otherwise show nothing: a blank table, a fresh
dashboard, a search with zero hits.
- `Empty` centers everything and fills its parent (`flex-1`).
- `EmptyHeader` groups media, title and description.
- `EmptyDescription` says why it's empty. Links inside get underlined.
- `EmptyContent` holds actions, a search box or anything clickable.
## Media [#media]
<Preview name="empty-avatar" />
`variant="icon"` puts the icon on a muted tile and sizes it. The `default`
variant adds no styles, so use it for avatars and illustrations.
```tsx
<EmptyMedia>
<Avatar size="lg">
<AvatarImage alt="" src={user.avatar} />
<AvatarFallback>AL</AvatarFallback>
</Avatar>
</EmptyMedia>
```
## Outline [#outline]
<Preview name="empty-outline" />
The dashed border style is built in. Add `border` for a drop-zone look, or
`border-2` when it sits alone on a page.
```tsx
<Empty className="border">...</Empty>
```
## No results [#no-results]
<Preview name="empty-search" />
A search miss is not the same as "no data yet". Echo the query back and offer a
way out.
```tsx
<EmptyDescription>Nothing matches "{query}".</EmptyDescription>
<EmptyContent>
<Button onClick={() => setQuery('')} size="sm" variant="outline">
Clear search
</Button>
</EmptyContent>
```
## Compact [#compact]
<Preview name="empty-compact" />
The default padding is `p-6 md:p-12`. In a card, sidebar or popover, keep it at
`p-6` and shrink the text.
```tsx
<Empty className="p-6">
<EmptyHeader>
<EmptyTitle className="text-sm">No widgets yet</EmptyTitle>
<EmptyDescription className="text-xs">
Widgets from your plugins will show up here.
</EmptyDescription>
</EmptyHeader>
</Empty>
```
## Writing tips [#writing-tips]
- **Say what's missing.** "No projects yet" beats "Nothing here".
- **Say why.** Brand new, filtered out, or a search miss?
- **Give one next step.** If there's nothing to do, a clear description is
enough.
- **Keep it short.** Nobody reads an essay about an empty table.
- **Skip the blame.** "No results for 'xylphone'", not "You typed it wrong".
## Accessibility [#accessibility]
- `EmptyTitle` renders an `h3`. Match your outline with `render={<h2 />}`, or
use `render={<p />}` inside a small widget that shouldn't add a heading.
- Icons and avatars are decorative, since the title says what's missing. Use
`alt=""` on images.
- When results change as the user types, announce the count in a
`role="status"` region, like an `sr-only` paragraph.
## Props [#props]
All parts take regular `div` props. `EmptyTitle` takes `h3` props plus
`render`.
### EmptyMedia [#emptymedia]
<TypeTable
type={{
variant: {
description:
'`icon` puts the child on a muted tile and sizes it. `default` adds no styles.',
type: 'default | icon',
default: 'default',
},
}}
/>
## API Reference [#api-reference]
[shadcn/ui - Empty](https://ui.shadcn.com/docs/components/base/empty)
# Field (/docs/ui/field)
## Preview [#preview]
<Preview name="field" />
## Usage [#usage]
```ts
import {
Field,
FieldContent,
FieldDescription,
FieldError,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
FieldTitle,
} from '@vitnode/core/components/ui/field'
```
```tsx
<Field>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" />
<FieldDescription>Pick something your friends can type.</FieldDescription>
</Field>
```
<Callout>
Building a form? Use [AutoForm](/docs/ui/auto-form). It already renders every
field with these parts, ids and ARIA included. Reach for `Field` in [custom
AutoForm fields](#inside-a-custom-autoform-field) and settings that save
instantly.
</Callout>
## Anatomy [#anatomy]
| Component | Renders |
| ------------------ | ------------------------------------------------------------------ |
| `FieldSet` | A `<fieldset>` grouping related fields. |
| `FieldLegend` | The fieldset's `<legend>`. `variant="label"` makes it label-sized. |
| `FieldGroup` | A stack of fields with even spacing. Enables `responsive`. |
| `Field` | One control with its label, description and error. |
| `FieldContent` | Keeps a label and description together beside a control. |
| `FieldLabel` | The control's `<label>`. Wrap a `Field` in it for a choice card. |
| `FieldTitle` | A label-styled title for content already inside a `FieldLabel`. |
| `FieldDescription` | Muted helper text. |
| `FieldError` | An error message with `role="alert"`. |
| `FieldSeparator` | A divider, optionally with text in the middle. |
## Orientation [#orientation]
`Field` is vertical by default. Use `horizontal` for checkboxes and switches.
The markup order decides the side: control first puts it on the left.
```tsx
<Field orientation="horizontal">
<FieldContent>
<FieldLabel htmlFor="digest">Weekly digest</FieldLabel>
<FieldDescription>A short recap, every Monday.</FieldDescription>
</FieldContent>
<Switch id="digest" />
</Field>
```
### Responsive [#responsive]
<Preview name="field-responsive" />
`responsive` stacks on narrow screens and goes side by side once its
`FieldGroup` is wide enough. It's a container query, so it follows the group's
width, not the window's.
```tsx
<FieldGroup>
<Field orientation="responsive">
<FieldContent>
<FieldLabel htmlFor="name">Display name</FieldLabel>
<FieldDescription>Shown next to your posts.</FieldDescription>
</FieldContent>
<Input id="name" />
</Field>
</FieldGroup>
```
## Fieldset and legend [#fieldset-and-legend]
Screen readers read the legend before each field inside, so "Mentions" becomes
"Notifications, Mentions". Free context, zero extra pixels.
```tsx
<FieldSet>
<FieldLegend>Notifications</FieldLegend>
<FieldGroup>
<Field orientation="horizontal">
<Checkbox id="mentions" />
<FieldLabel htmlFor="mentions">Mentions</FieldLabel>
</Field>
<FieldSeparator>or</FieldSeparator>
<Field>
<FieldLabel htmlFor="backup-email">Backup email</FieldLabel>
<Input id="backup-email" type="email" />
</Field>
</FieldGroup>
</FieldSet>
```
## Choice cards [#choice-cards]
<Preview name="field-choice-card" />
Wrap a `Field` in a `FieldLabel` and the whole card becomes clickable. It
highlights when checked and shows a focus ring. Use `FieldTitle` inside, since
you're already in a label.
```tsx
<RadioGroup defaultValue="team">
<FieldLabel htmlFor="plan-team">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Team</FieldTitle>
<FieldDescription>
Shared workspaces for up to 20 people.
</FieldDescription>
</FieldContent>
<RadioGroupItem id="plan-team" value="team" />
</Field>
</FieldLabel>
</RadioGroup>
```
To disable a card, put `data-disabled` on the `Field` and `disabled` on the
control. AutoForm's [Radio Group](/docs/ui/radio-group#blocks) uses this for
`variant="blocks"`.
## Errors [#errors]
Set `data-invalid` on the field, `aria-invalid` on the control, and point
`aria-describedby` at the `FieldError`. The preview above shows it live.
```tsx
<Field data-invalid={isInvalid}>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input aria-describedby="email-error" aria-invalid={isInvalid} id="email" />
{isInvalid && <FieldError id="email-error">That is not an email.</FieldError>}
</Field>
```
`FieldError` also takes `errors`. It drops duplicates, shows one message as
text and several as a list, and renders nothing when empty.
```tsx
<FieldError errors={[{ message: 'Too short' }, { message: 'Too short' }]} />
```
## Inside a custom AutoForm field [#inside-a-custom-autoform-field]
Mix `Field` with AutoForm's parts and your field matches the built-in ones:
- `AutoFormLabel` is a `FieldLabel` pointed at the control, with the "Optional" hint.
- `AutoFormDesc` renders the description.
- `FormControl` passes `id`, `aria-invalid` and `aria-describedby` to its child.
- `FormMessage` is a `FieldError` with the field's validation errors.
```tsx
import type { ItemAutoFormComponentProps } from '@vitnode/core/components/form/auto-form'
import { AutoFormDesc } from '@vitnode/core/components/form/common/desc'
import { AutoFormLabel } from '@vitnode/core/components/form/common/label'
import { Field, FieldContent } from '@vitnode/core/components/ui/field'
import { FormControl, FormMessage } from '@vitnode/core/components/ui/form'
import { Switch } from '@vitnode/core/components/ui/switch'
export const AutoFormSettingSwitch = ({
label,
description,
field,
otherProps: { isOptional },
}: ItemAutoFormComponentProps) => (
<>
<Field orientation="horizontal">
<FieldContent>
{label && (
<AutoFormLabel isOptional={isOptional}>{label}</AutoFormLabel>
)}
{description && <AutoFormDesc>{description}</AutoFormDesc>}
</FieldContent>
<FormControl>
<Switch
checked={field.value ?? false}
onCheckedChange={field.onChange}
/>
</FormControl>
</Field>
<FormMessage />
</>
)
```
Use it like any field: `component: props => <AutoFormSettingSwitch {...props} label="Weekly digest" />`.
## Accessibility [#accessibility]
- Give every control an `id` and its `FieldLabel` a matching `htmlFor`. Clicking
the label then focuses or toggles the control.
- `Field` has `role="group"`, so control, label and help text are announced
together.
- `FieldError` has `role="alert"`, so new messages are read out as they appear.
- Choice cards keep the real radio or checkbox inside. Tab, arrow keys and
Space work as usual.
## Props [#props]
Every part accepts the props of the element it renders, plus:
<TypeTable
type={{
'Field.orientation': {
description: "`responsive` follows the parent `FieldGroup`'s width.",
type: 'vertical | horizontal | responsive',
default: 'vertical',
},
'Field.data-invalid': {
description: 'Colors the field as an error.',
type: 'boolean',
},
'Field.data-disabled': {
description: 'Fades the field and its label.',
type: 'boolean',
},
'FieldLegend.variant': {
description: 'Section-sized or label-sized legend.',
type: 'legend | label',
default: 'legend',
},
'FieldError.errors': {
description:
'Errors to show, deduplicated. Ignored when `children` is set.',
type: '({ message?: string } | undefined)[]',
},
'FieldSeparator.children': {
description: 'Text in the middle of the divider.',
type: 'React.ReactNode',
},
}}
/>
## API Reference [#api-reference]
[shadcn/ui - Field](https://ui.shadcn.com/docs/components/base/field)
# Frame (/docs/ui/frame)
<Preview name="frame" />
`Frame` groups related settings or facts under one title. The title sits on a
soft outer layer, and the rows sit on a raised inner panel. It is the card the
**Settings → Overview** page is built from.
## Usage [#usage]
```ts
import {
Frame,
FrameAction,
FrameDescription,
FrameFooter,
FrameHeader,
FramePanel,
FrameTitle,
} from '@vitnode/core/components/ui/frame'
```
```tsx
<Frame>
<FrameHeader>
<FrameTitle render={<h2 />}>AI features</FrameTitle>
</FrameHeader>
<FramePanel>
<Item>
<ItemMedia aria-hidden variant="tile">
<BotIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>
Semantic search <Badge variant="outline">Smart</Badge>
</ItemTitle>
<ItemDescription>Find content by meaning, not exact wording.</ItemDescription>
</ItemContent>
<ItemActions>
<Switch aria-label="Semantic search" />
</ItemActions>
</Item>
</FramePanel>
</Frame>
```
- `FrameHeader` holds the title, an optional description and an optional action.
- `FramePanel` is the inner card. It draws a divider between its children, so
you never add separators yourself.
- Rows are regular [Item](/docs/ui/item) components. Inside a panel they lose
their own border and radius, so they line up edge to edge.
- `ItemMedia variant="tile"` gives the icon its small rounded square.
## Header description and action [#header-description-and-action]
<Preview name="frame-actions" />
Add `FrameDescription` under the title and put a button in `FrameAction`. The
action stays on the end side and centers against the title block.
```tsx
<FrameHeader>
<FrameTitle render={<h2 />}>Publishing</FrameTitle>
<FrameDescription>Where visitors find your site.</FrameDescription>
<FrameAction>
<Button size="sm" variant="ghost">
Learn more
</Button>
</FrameAction>
</FrameHeader>
```
## Footer note [#footer-note]
Put a short note under the panel with `FrameFooter`. It sits on the outer
layer, so it reads as a remark about the whole group, not as another row.
```tsx
<Frame>
<FrameHeader>...</FrameHeader>
<FramePanel>...</FramePanel>
<FrameFooter>A signed-out device has to sign in again.</FrameFooter>
</Frame>
```
## Side by side [#side-by-side]
<Preview className="*:max-w-none" name="frame-grid" />
Frames stretch to fill their grid cell, so two frames in a
`md:grid-cols-2` grid keep the same height even with different row counts.
```tsx
<div className="grid gap-4 md:grid-cols-2">
<Frame>...</Frame>
<Frame>...</Frame>
</div>
```
## Accessibility [#accessibility]
- `FrameTitle` renders a `div`. Pass `render={<h2 />}` (or the level that fits
the page) so screen readers can jump between frames.
- For a list of rows, render the panel as a list and each row as an item:
`<FramePanel render={<ul />}>` with `<Item render={<li />}>`.
- Icon tiles are decorative. Give `ItemMedia` `aria-hidden`.
- A switch or icon-only button in a row needs an `aria-label` that names the
setting.
## Props [#props]
`Frame`, `FrameHeader`, `FrameDescription`, `FrameAction` and `FrameFooter`
take regular element props.
### FrameTitle and FramePanel [#frametitle-and-framepanel]
<TypeTable
type={{
render: {
description: 'Replaces the `div`, such as with an `h2` or a `ul`.',
type: 'ReactElement | ((props, state) => ReactElement)',
},
}}
/>
## API Reference [#api-reference]
[Base UI - useRender](https://base-ui.com/react/utils/use-render)
# useBeforeUnload (/docs/ui/hooks/use-before-unload)
## Preview [#preview]
<Preview name="hook-use-before-unload" />
## Usage [#usage]
```ts
import { useBeforeUnload } from '@vitnode/core/hooks/use-before-unload'
```
```tsx
const [isDirty, setIsDirty] = React.useState(false)
useBeforeUnload(isDirty)
```
While `enabled` is `true`, closing the tab, reloading or typing a new address
makes the browser ask "Leave site?". Set it back to `false` once the changes are
saved.
## Check at the last moment [#check-at-the-last-moment]
Pass a function and the hook calls it only when someone tries to leave. Handy
when the dirty state lives in a ref that doesn't re-render:
```tsx
const hasUnsavedChanges = React.useRef(false)
useBeforeUnload(() => hasUnsavedChanges.current)
```
## Good to know [#good-to-know]
- **The browser writes the message.** Modern browsers ignore custom text.
`message` only matters for old ones.
- **In-app navigation isn't covered.** Clicking a router `Link` doesn't unload
the page, so no prompt.
- **Use it sparingly.** A prompt on every page teaches people to click "Leave"
without reading.
## Options [#options]
<TypeTable
type={{
enabled: {
description:
'Whether to warn. A function is called when someone tries to leave.',
type: 'boolean | (() => boolean)',
default: 'true',
},
message: {
description: 'Text for older browsers. Modern browsers show their own.',
type: 'string',
},
}}
/>
The hook returns nothing.
# useIntersectionObserver (/docs/ui/hooks/use-intersection-observer)
## Preview [#preview]
<Preview name="hook-use-intersection-observer" />
## Usage [#usage]
```ts
import { useIntersectionObserver } from '@vitnode/core/hooks/use-intersection-observer'
```
```tsx
const [element, setElement] = React.useState<HTMLDivElement | null>(null)
const entry = useIntersectionObserver(element, { threshold: 0.5 })
return (
<div ref={setElement}>
{entry?.isIntersecting ? 'I can see you!' : 'Nobody is looking...'}
</div>
)
```
It returns the latest
[`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry),
or `undefined` until the first report. On the server, and in browsers without
`IntersectionObserver`, it stays `undefined`.
Keep the element in state through a callback ref, not `useRef`. Then the hook
notices when the node mounts late or gets swapped.
## Load once, then stop [#load-once-then-stop]
`freezeOnceVisible` stops observing the first time the element shows up. A
positive `rootMargin` starts loading just before it reaches the screen.
```tsx
const entry = useIntersectionObserver(element, {
freezeOnceVisible: true,
rootMargin: '200px',
})
return (
<div ref={setElement}>{entry?.isIntersecting ? <HeavyChart /> : null}</div>
)
```
## Inside a scroll container [#inside-a-scroll-container]
The preview above watches its own scroll box, not the viewport. Pass that box as
`root`, stored in state the same way:
```tsx
const [root, setRoot] = React.useState<HTMLDivElement | null>(null)
const entry = useIntersectionObserver(element, { root })
```
## Options [#options]
<TypeTable
type={{
threshold: {
description:
'How much of the element (0 to 1) must be visible. An array reports at each step.',
type: 'number | number[]',
default: '0',
},
rootMargin: {
description: 'Grows or shrinks the visible area, like CSS margin.',
type: 'string',
default: '"0%"',
},
root: {
description: 'The scroll container to watch. `null` is the viewport.',
type: 'Element | null',
default: 'null',
},
freezeOnceVisible: {
description: 'Stop observing after the first time it is visible.',
type: 'boolean',
default: 'false',
},
}}
/>
# useLocalStorage (/docs/ui/hooks/use-local-storage)
## Preview [#preview]
<Preview name="hook-use-local-storage" />
## Usage [#usage]
```ts
import { useLocalStorage } from '@vitnode/core/hooks/use-local-storage'
```
```tsx
const [name, setName] = useLocalStorage('name', '')
return <input onChange={(e) => setName(e.target.value)} value={name} />
```
Pass a key and a default, get the value and a setter, just like `useState`.
Values are stored as JSON, so numbers, booleans, arrays and plain objects come
back as you saved them.
## Update and reset [#update-and-reset]
The setter takes a function that gets the freshest value. The third item
removes the key and falls back to the default.
```ts
const [count, setCount, resetCount] = useLocalStorage('count', 0)
setCount((previous) => previous + 1)
resetCount()
```
## Good to know [#good-to-know]
- **Synced everywhere.** Every component using the same key updates together,
in this tab and in other tabs.
- **Server-safe.** The server renders the default, then the browser switches to
the stored value without a hydration mismatch.
- **No crashes.** A broken stored value falls back to the default. Blocked or
full storage keeps the value in memory for the session.
- **Nice-to-haves only.** Storage lives in one browser on one device. Use it for
a collapsed panel or a draft, never for data the server needs.
## Returns [#returns]
<TypeTable
type={{
'[0] value': {
description: 'The stored value, or the default.',
type: 'T',
},
'[1] setValue': {
description: 'Saves a value, or a function of the previous one.',
type: '(value: T | ((previous: T) => T)) => void',
},
'[2] removeValue': {
description: 'Removes the key and goes back to the default.',
type: '() => void',
},
}}
/>
# useIsMobile (/docs/ui/hooks/use-mobile)
## Preview [#preview]
<Preview name="hook-use-mobile" />
## Usage [#usage]
```ts
import { useIsMobile } from '@vitnode/core/hooks/use-mobile'
```
```tsx
const isMobile = useIsMobile()
return isMobile ? <PostActionsDrawer /> : <PostActionsDropdown />
```
It returns `true` below **768px**, where Tailwind's `md:` starts, and updates
live on resize or rotation.
## Prefer CSS for layout [#prefer-css-for-layout]
If only the look changes, use responsive classes. CSS is right on the first
paint and needs no JavaScript:
```tsx
<div className="flex flex-col gap-4 md:flex-row">...</div>
```
Reach for the hook when the **behavior** changes: a
[Drawer](/docs/ui/drawer) instead of a [Dropdown Menu](/docs/ui/dropdown-menu),
skipping a heavy component, or loading fewer items.
## Server rendering [#server-rendering]
The server can't see the screen, so the hook returns `false` during SSR and
hydration, then switches without a mismatch warning. A phone may briefly see the
desktop version. Components that mount later in the browser get the real value
on their first render.
## Returns [#returns]
<TypeTable
type={{
isMobile: {
description: 'True below 768px. Always false on the server.',
type: 'boolean',
},
}}
/>
# useSlidingIndicator (/docs/ui/hooks/use-sliding-indicator)
## Preview [#preview]
<Preview name="hook-use-sliding-indicator" />
## Usage [#usage]
```ts
import {
slidingIndicatorTransitionClassName,
useSlidingIndicator,
} from '@vitnode/core/hooks/use-sliding-indicator'
```
```tsx
const [active, setActive] = React.useState(0)
const { containerRef, indicatorRef, isReady } =
useSlidingIndicator<HTMLDivElement>(active)
return (
<div
className="bg-muted relative flex gap-1 rounded-lg p-1"
ref={containerRef}
role="group"
>
<span
aria-hidden
className={cn(
'bg-background pointer-events-none absolute top-0 left-0 rounded-md opacity-0',
isReady && slidingIndicatorTransitionClassName,
)}
ref={indicatorRef}
/>
{filters.map((label, index) => (
<button
aria-pressed={active === index}
className="relative rounded-md px-3 py-1.5 text-sm"
data-sliding-indicator-item
key={label}
onClick={() => setActive(index)}
type="button"
>
{label}
</button>
))}
</div>
)
```
Mark every item with `data-sliding-indicator-item` and pass the active index.
The hook sizes and moves the indicator to sit behind that item. VitNode's theme
switcher and mobile navigation bar work this way.
## Styling checklist [#styling-checklist]
- The container is `relative`. The indicator is `absolute top-0 left-0` and
starts at `opacity-0`. The hook sets its size, position and opacity.
- Items are `relative`, so they sit above the indicator.
- The indicator is `aria-hidden`. Put the active state on the items with
`aria-pressed`, `aria-selected` or `aria-current`.
## How it behaves [#how-it-behaves]
- **Follows resizes.** A `ResizeObserver` on the container repositions the
indicator, for example when labels change language.
- **No slide on first render.** `isReady` turns `true` one frame after mount.
Add the transition class only then, or the indicator flies in from the corner.
- **Hides when nothing is active.** An index with no matching item, like `-1`,
hides the indicator.
- **Respects reduced motion.** The transition class slides for 300ms on
`ease-fluid` and turns off under `prefers-reduced-motion`.
## API [#api]
<TypeTable
type={{
activeIndex: {
description:
'Index of the active item among elements marked `data-sliding-indicator-item`.',
type: 'number',
required: true,
},
Container: {
description: 'Type parameter for the container element.',
type: 'HTMLElement',
},
}}
/>
Returns:
<TypeTable
type={{
containerRef: {
description: 'Ref for the element wrapping the items and the indicator.',
type: 'React.RefObject<Container | null>',
},
indicatorRef: {
description: 'Ref for the indicator element.',
type: 'React.RefObject<HTMLSpanElement | null>',
},
isReady: {
description:
'True one frame after mount. Gate the transition class on it.',
type: 'boolean',
},
}}
/>
# Hover Card (/docs/ui/hover-card)
## Preview [#preview]
<Preview name="hover-card" />
## Usage [#usage]
```ts
import {
HoverCard,
HoverCardContent,
HoverCardTrigger,
} from '@vitnode/core/components/ui/hover-card'
```
```tsx
<HoverCard>
<HoverCardTrigger href="/profile/axendev">@axendev</HoverCardTrigger>
<HoverCardContent>Creator of VitNode.</HoverCardContent>
</HoverCard>
```
`HoverCardTrigger` renders a real link, so give it an `href`. Clicking it goes
there like any other link.
## Inside text [#inside-text]
<Preview name="hover-card-mention" />
Mentions and thread links in a post are the classic use. The card opens after
600ms and closes 300ms after you leave. Tune both on the trigger.
```tsx
<HoverCardTrigger closeDelay={100} delay={200} href="/profile/maya">
@maya
</HoverCardTrigger>
```
## Accessibility [#accessibility]
- Keyboard focus opens the card too.
- Touch screens have no hover, so the card never shows there. Keep it a bonus:
everything in it must also live on the page the link opens.
- Don't put buttons or forms in it. Use a [Popover](/docs/ui/popover) for
anything interactive.
## Props [#props]
`HoverCardContent` takes `side` (default `bottom`), `align` (default
`center`), `sideOffset` (default `4`), `alignOffset` (default `0`) and
`anchor`, like a [Popover](/docs/ui/popover). It's `w-64` by default.
## API Reference [#api-reference]
[Base UI - Preview Card](https://base-ui.com/react/components/preview-card#api-reference)
# Icons (/docs/ui/icons)
VitNode uses [lucide-react](https://lucide.dev/icons) for icons: over 1,500
outlined icons with one stroke style. Components size them for you, so most of
the time you just drop one in.
## Size scale [#size-scale]
<Preview name="icons-sizes" className="*:max-w-full" />
`size-4` is the default. It matches `text-sm`, the size of buttons, menus and
inputs. Go up for navigation and empty states, down for badges.
## Icons in components [#icons-in-components]
<Preview name="icons-in-context" className="*:max-w-full" />
Buttons, badges and input groups size any child `svg` that has no `size-*`
class. Add `data-icon="inline-start"` or `"inline-end"` so the button trims
its padding on that side.
```tsx
<Button>
<PlusIcon data-icon="inline-start" />
New post
</Button>
```
## Stroke [#stroke]
<Preview name="icons-stroke" className="*:max-w-full" />
Keep the default `strokeWidth={2}`. It sits right next to `font-medium` text.
Thinner or bolder strokes are for big hero icons, not your toolbar.
## Icons by name [#icons-by-name]
<Preview name="icons-dynamic" />
Store an icon as a string and render it with `DynamicIcon`. Each icon loads on
its own, and icons rendered on the server arrive with the page, so nothing pops
in. An unknown name renders nothing.
```tsx
import { DynamicIcon } from '@vitnode/core/components/ui/dynamic-icon'
<DynamicIcon className="size-5" name="shield-check" />
```
Letting users pick one? The [Emoji & Icon Picker](/docs/ui/emoji-icon-picker)
returns exactly this name.
## Do and don't [#do-and-dont]
<Preview name="icons-do-dont" className="*:max-w-full" />
- Lucide hides icons from screen readers by default (`aria-hidden="true"`), so
an icon next to text needs nothing extra.
- Icon-only buttons need an `aria-label`. TypeScript asks for it on `size="icon"`.
- Lucide has no brand logos. Use an inline SVG with `fill="currentColor"` and
`aria-hidden`.
## Related [#related]
<Cards>
<Card
title="Emoji & Icon Picker"
href="/docs/ui/emoji-icon-picker"
description="Let users pick an emoji or a lucide icon."
/>
<Card
title="Typography"
href="/docs/ui/typography"
description="The text sizes your icons line up with."
/>
<Card
title="Accessibility"
href="/docs/ui/accessibility"
description="Labels, focus and screen readers."
/>
</Cards>
# Image Zoom (/docs/ui/image-zoom)
## Preview [#preview]
<Preview name="image-zoom" />
## Usage [#usage]
```ts
import { ImageZoom } from '@vitnode/core/components/ui/image-zoom'
```
```tsx
<ImageZoom
alt="The VitNode AdminCP dashboard"
height={433}
imageClassName="w-full rounded-md border"
src="/screenshots/dashboard.webp"
width={800}
/>
```
Click the image, or focus it and press <kbd>Enter</kbd>, and it glides to the
middle of the screen. Click anywhere, press <kbd>Escape</kbd> or hit × to send
it back.
## Drag to dismiss [#drag-to-dismiss]
Grab the zoomed image and drag or flick it in any direction to close. Let go
early and it springs back to the middle. The backdrop fades as you drag, so you
can see where you're headed.
## Sharper zoom [#sharper-zoom]
Show a light thumbnail and load the big file only on zoom:
```tsx
<ImageZoom
alt="The VitNode AdminCP dashboard"
src={thumbnail}
zoomSrc={fullSize}
/>
```
## Styling [#styling]
- `className` styles the clickable wrapper. Use it for layout and visibility,
like `hidden dark:block` for theme-specific screenshots.
- `imageClassName` styles the image on the page.
The zoomed image always fits the screen without cropping.
## Accessibility [#accessibility]
- The image is a real button that opens a dialog.
- `alt` is required. It labels the image and names the zoomed view.
- Focus is trapped while zoomed and returns to the image on close.
- Reduced motion zooms instantly. Reduced transparency swaps the blurred
backdrop for a solid one.
## Props [#props]
<TypeTable
type={{
src: {
description: 'The image shown on the page.',
type: 'string',
required: true,
},
alt: {
description: 'Describes the image, on the page and when zoomed.',
type: 'string',
required: true,
},
zoomSrc: {
description: 'A larger image for the zoomed view. Defaults to `src`.',
type: 'string',
},
className: {
description: 'Classes for the clickable wrapper.',
type: 'string',
},
imageClassName: {
description: 'Classes for the image on the page.',
type: 'string',
},
width: {
description:
'Intrinsic width of `src`. With `height`, it reserves space so the page does not jump while the image loads.',
type: 'number',
},
height: {
description: 'Intrinsic height of `src`.',
type: 'number',
},
loading: {
description: 'Pass `"lazy"` for images below the fold.',
type: '"eager" | "lazy"',
},
}}
/>
# Introduction (/docs/ui)
VitNode UI is the component library behind every VitNode screen, from the
AdminCP to your plugin pages. It gives you buttons, dialogs, forms, tables
and around seventy other pieces that share one set of colors, type, spacing and
motion, so a plugin looks like it belongs without extra effort.
## Use a component [#use-a-component]
Every component lives in `@vitnode/core`, which your app already depends on.
Import it from `@vitnode/core/components/ui/<name>`:
```tsx
import { Button } from '@vitnode/core/components/ui/button'
export const PublishButton = () => <Button>Publish post</Button>
```
There's nothing to install and no copy-paste step. Components are styled with
[design tokens](#foundations), so they follow your theme and switch to dark
mode automatically.
## What it's built on [#what-its-built-on]
- **[Base UI](https://base-ui.com)** (`@base-ui/react`) for the behavior:
focus management, keyboard support, ARIA and positioning.
- **[shadcn/ui](https://ui.shadcn.com)** in its `base-vega` style for the
starting point of each component's look.
- **[Tailwind CSS v4](https://tailwindcss.com)** for styling, driven by CSS
variables.
- **[Motion](https://motion.dev)** for the few animations that need springs,
like rolling numbers, the switch thumb and image zoom.
## Design principles [#design-principles]
Inspired by Apple's Human Interface Guidelines (we're not affiliated, we just
like how their stuff feels):
- **Respond on press.** Everything reacts the moment your pointer goes down.
[Motion](/docs/ui/motion)
- **Move with purpose.** Short, interruptible, no bounce for fun.
[Motion](/docs/ui/motion)
- **Respect people's settings.** Reduced motion, reduced transparency and
touch-sized targets. [Accessibility](/docs/ui/accessibility)
- **Sweat the details.** Steady numbers and nested corners.
[Typography](/docs/ui/typography) · [Radius & Elevation](/docs/ui/elevation)
## Foundations [#foundations]
Components never hardcode a color, size or curve. They read shared tokens from
your app's `src/styles.css`, and each foundation has its own page full of live
examples.
<Cards>
<Card
icon={<Palette />}
title="Colors"
href="/docs/ui/colors"
description="Semantic OKLCH tokens for surfaces, brand, status and charts."
/>
<Card
icon={<Type />}
title="Typography"
href="/docs/ui/typography"
description="System font, type scale with built-in tracking, hierarchy."
/>
<Card
icon={<Waves />}
title="Motion"
href="/docs/ui/motion"
description="Press feedback, interruptible transitions, springs, reduced motion."
/>
<Card
icon={<Ruler />}
title="Spacing & Layout"
href="/docs/ui/spacing"
description="Spacing scale, gap rules, breakpoints and line length."
/>
<Card
icon={<Layers />}
title="Radius & Elevation"
href="/docs/ui/elevation"
description="One radius variable, concentric corners and soft shadows."
/>
<Card
icon={<Shapes />}
title="Icons"
href="/docs/ui/icons"
description="Lucide sizes, icons in buttons, labels and brand logos."
/>
<Card
icon={<Accessibility />}
title="Accessibility"
href="/docs/ui/accessibility"
description="Focus rings, touch targets, contrast and announcements."
/>
</Cards>
## Popular components [#popular-components]
<Cards>
<Card
title="Button"
href="/docs/ui/button"
description="Actions in every variant, from primary to destructive."
/>
<Card
title="Dialog"
href="/docs/ui/dialog"
description="Focused tasks in a modal window."
/>
<Card
title="Auto Form"
href="/docs/ui/auto-form"
description="Forms generated from a Zod schema, with validation."
/>
<Card
title="Data Table"
href="/docs/ui/data-table"
description="Search, filters, pagination and bulk actions."
/>
<Card
title="Select"
href="/docs/ui/select"
description="Pick one option from a list."
/>
<Card
title="Toast"
href="/docs/ui/toast"
description="Quick feedback after a create, edit or delete."
/>
<Card
title="Sheet"
href="/docs/ui/sheet"
description="A side panel for details and secondary forms."
/>
<Card
title="Editor"
href="/docs/ui/editor"
description="Rich text editing for posts and pages."
/>
</Cards>
# Input Group (/docs/ui/input-group)
## Preview [#preview]
<Preview name="input-group" />
## Usage [#usage]
```ts
import {
InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupInput,
InputGroupText,
InputGroupTextarea,
} from '@vitnode/core/components/ui/input-group'
```
```tsx
<InputGroup>
<InputGroupInput aria-label="Search" placeholder="Search..." />
<InputGroupAddon>
<Search />
</InputGroupAddon>
<InputGroupAddon align="inline-end">12 results</InputGroupAddon>
</InputGroup>
```
Put the control first and the addons after it. `align` moves each addon into
place, whatever the markup order.
## Addons [#addons]
<Preview name="input-group-addons" />
An addon holds an icon, `InputGroupText`, a [`Kbd`](/docs/ui/kbd) or an
`InputGroupButton`. Icon-only buttons need an `aria-label`. Clicking an addon
outside its buttons focuses the control.
```tsx
<InputGroup>
<InputGroupInput aria-label="Invite link" readOnly value={inviteUrl} />
<InputGroupAddon align="inline-end">
<InputGroupButton aria-label="Copy invite link" size="icon-xs">
<Copy />
</InputGroupButton>
</InputGroupAddon>
</InputGroup>
```
Disable the control and the whole group dims with it.
## Alignment [#alignment]
| `align` | Position |
| ------------------------ | --------------------------------------- |
| `inline-start` (default) | Before the text |
| `inline-end` | After the text |
| `block-start` | Above the control, full width |
| `block-end` | Below the control, full width (footers) |
```tsx
<InputGroup>
<InputGroupTextarea aria-label="Describe the issue" rows={6} />
<InputGroupAddon align="block-end">
<InputGroupText className="tabular-nums">
0 of 500 characters
</InputGroupText>
</InputGroupAddon>
</InputGroup>
```
## With AutoForm [#with-autoform]
Pass addons as children of `AutoFormInput` or `AutoFormTextarea`. The field
wraps itself in an `InputGroup`.
```tsx
{
id: "description",
component: props => (
<AutoFormTextarea {...props} label="Description" rows={6}>
<InputGroupAddon align="block-end">
<InputGroupText className="tabular-nums">
{props.field.value?.toString().length ?? 0} of 500 characters
</InputGroupText>
</InputGroupAddon>
</AutoFormTextarea>
),
}
```
## Button sizes [#button-sizes]
`InputGroupButton` defaults to `variant="ghost"` and `type="button"`. Sizes:
`xs` (default), `sm`, `icon-xs` and `icon-sm`. All fit the default group height.
## API Reference [#api-reference]
[shadcn/ui - Input Group](https://ui.shadcn.com/docs/components/base/input-group)
# Input OTP (/docs/ui/input-otp)
## Preview [#preview]
<Preview name="input-otp" />
## 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 { AutoFormInputOTP } from '@vitnode/core/components/form/fields/input-otp'
```
```tsx
const formSchema = z.object({
code: z.string().length(6, 'Enter all 6 digits').regex(/^\d+$/, 'Only digits, please'),
})
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'code',
component: props => (
<AutoFormInputOTP
{...props}
description="We sent a 6-digit code to your email."
label="Verify your account"
/>
),
},
]}
/>
```
`.length(6)` sets the slot count and `.regex()` becomes the `pattern`.
</Tab>
<Tab value="Manual">
```ts
import {
InputOTP,
InputOTPGroup,
InputOTPSeparator,
InputOTPSlot,
} from '@vitnode/core/components/ui/input-otp'
```
```tsx
<InputOTP maxLength={6} onChange={setValue} value={value}>
<InputOTPGroup>
<InputOTPSlot index={0} />
<InputOTPSlot index={1} />
<InputOTPSlot index={2} />
</InputOTPGroup>
<InputOTPSeparator />
<InputOTPGroup>
<InputOTPSlot index={3} />
<InputOTPSlot index={4} />
<InputOTPSlot index={5} />
</InputOTPGroup>
</InputOTP>
```
</Tab>
</Tabs>
One real `<input>` sits underneath, so paste, password managers and SMS
autofill just work.
## Groups and patterns [#groups-and-patterns]
<Preview name="input-otp-groups" />
`AutoFormInputOTP` halves even codes of 6+ characters and keeps the rest in
one group. Pass `groups` to choose.
```tsx
<AutoFormInputOTP {...props} groups={[2, 2, 2]} label="Backup code" />
```
Without a schema, set `pattern`. Common regexes are re-exported:
```ts
import { REGEXP_ONLY_DIGITS } from '@vitnode/core/components/ui/input-otp'
```
```tsx
<InputOTP maxLength={4} pattern={REGEXP_ONLY_DIGITS}>
…
</InputOTP>
```
`REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS_AND_CHARS` too.
## Submit when complete [#submit-when-complete]
`onComplete` fires when every slot is filled, on both components.
```tsx
<AutoFormInputOTP {...props} onComplete={(code) => verify(code)} />
```
## Wrong code [#wrong-code]
A wrong code comes from your API. `setFormFieldError` turns every slot red
and shows the message. Try it in the [preview](#preview).
```ts
import { setFormFieldError } from '@vitnode/core/components/ui/form'
```
```tsx
<AutoForm
formSchema={formSchema}
onSubmit={async (values, form) => {
const res = await verifyCode(values.code)
if (!res.ok) setFormFieldError(form, 'code', "That code doesn't match.")
}}
fields={[...]}
/>
```
## Accessibility [#accessibility]
- `AutoFormInputOTP` wires the label, description and error to the input.
- With `InputOTP` alone, add an `id` and a `<Label htmlFor>`. Link help text
and errors with `aria-describedby`, and set `aria-invalid` on errors.
- Slots are hidden from screen readers, so no digit is read twice.
- Characters animate in, except with reduced motion.
## Props [#props]
`AutoFormInputOTP` takes every `InputOTP` prop except `value` and `children`,
plus:
<TypeTable
type={{
label: { description: 'Label above the slots.', type: 'ReactNode' },
description: {
description: 'Help text below the slots.',
type: 'ReactNode',
},
groups: {
description:
'Slots per group. Default: two halves for even lengths of 6+, else one group.',
type: 'number[]',
},
maxLength: {
description:
'Code length. Default: the schema `.length()` / `.max()`, then 6.',
type: 'number',
},
onChange: {
description: 'Called with the new value on every change.',
type: '(value: string) => void',
},
onComplete: {
description: 'Called once every slot is filled.',
type: '(value: string) => void',
},
pattern: {
description:
'Regex the value must match. Default: the schema `.regex()`.',
type: 'string',
},
disabled: { description: 'Disables the input.', type: 'boolean' },
}}
/>
## API Reference [#api-reference]
[input-otp](https://github.com/guilhermerodz/input-otp)
# Input (/docs/ui/input)
## Preview [#preview]
<Preview name="input" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormInput } from '@vitnode/core/components/form/fields/input'
import { z } from 'zod'
const formSchema = z.object({
username: z
.string()
.min(3, 'Usernames need at least 3 characters')
.default(''),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'username',
component: (props) => (
<AutoFormInput {...props} label="Username" autoComplete="username" />
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import { Input } from '@vitnode/core/components/ui/input'
```
```tsx
<Input aria-label="Username" autoComplete="username" />
```
</Tab>
</Tabs>
## States [#states]
<Preview name="input-states" />
Set `aria-invalid` for the error style and `disabled` to dim it. `type="file"`
gets a styled picker button. Wrap it in a [Field](/docs/ui/field) for the
label, description and error.
```tsx
<Input aria-invalid aria-describedby="email-error" id="email" type="email" />
```
## Addons [#addons]
Pass `InputGroupAddon` children to `AutoFormInput` and it renders an
[Input Group](/docs/ui/input-group): icons, prefixes, buttons.
```tsx
<AutoFormInput {...props} label="Search">
<InputGroupAddon>
<Search />
</InputGroupAddon>
</AutoFormInput>
```
## Multi-language [#multi-language]
`multiLang` collects one value per enabled language. A language select appears
inside the input when there's more than one.
```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'
const formSchema = z.object({
name: multiLangValueSchema({ minLength: 1, maxLength: 255 }).min(1),
})
```
```tsx
<AutoFormInput {...props} label="Name" multiLang />
```
The value is `{ languageCode, value }[]`. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields)
for saving it.
## Props [#props]
`AutoFormInput` also accepts every native `<input>` prop.
<TypeTable
type={{
label: {
description: 'Shown above the input.',
type: 'ReactNode',
},
labelRight: {
description: "Content pinned to the label's right edge.",
type: 'ReactNode',
},
description: {
description:
"Shown below the input. Defaults to the schema's `.describe()`.",
type: 'ReactNode',
},
type: {
description: 'Native input type.',
type: 'string',
default: '"text"',
},
placeholder: {
description: 'Hint shown while empty. Not a label replacement.',
type: 'string',
},
multiLang: {
description:
'Collect one value per language as `{ languageCode, value }[]`.',
type: 'boolean',
default: 'false',
},
children: {
description:
'`InputGroupAddon` elements. Turns the input into an input group.',
type: 'ReactNode',
},
}}
/>
# Item (/docs/ui/item)
<Preview name="item" />
## Usage [#usage]
```ts
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from '@vitnode/core/components/ui/item'
```
```tsx
<Item variant="outline">
<ItemMedia variant="icon">
<ShieldCheck />
</ItemMedia>
<ItemContent>
<ItemTitle>Two-factor authentication</ItemTitle>
<ItemDescription>Add a second lock to your account.</ItemDescription>
</ItemContent>
<ItemActions>
<Button size="sm" variant="outline">
Enable
</Button>
</ItemActions>
</Item>
```
Every app grows a dozen "icon, text, button on the right" rows. `Item` is that
row, built once.
- `ItemContent` stacks title and description and takes the free space.
- `ItemTitle` is one line and truncates.
- `ItemDescription` shows up to two muted lines. Links inside get underlined.
- `ItemActions` holds buttons, badges or a chevron at the end.
## Variants [#variants]
<Preview name="item-variants" />
```tsx
<Item variant="muted">...</Item>
```
## Sizes [#sizes]
<Preview name="item-sizes" />
`sm` and `xs` shrink padding and gaps. Image media shrinks too, and `xs` also
uses smaller description text.
```tsx
<Item size="sm">...</Item>
```
## Media [#media]
<Preview name="item-media" />
With a description present, media aligns to the top of the text.
```tsx
<ItemMedia variant="image">
<img alt="" src="/cover.webp" />
</ItemMedia>
```
## As a link [#as-a-link]
<Preview name="item-link" />
Pass an element to `render`, such as an `<a>`, a router `Link` or a `<button>`.
Put the row's content inside it so the link wraps everything. Links get a hover
background.
```tsx
<Item
render={
<a href="/docs/ui/avatar">
<ItemContent>
<ItemTitle>Read the Avatar docs</ItemTitle>
</ItemContent>
<ItemActions>
<ChevronRight aria-hidden className="size-4" />
</ItemActions>
</a>
}
/>
```
## Groups [#groups]
<Preview name="item-group" />
`ItemGroup` stacks items. `ItemSeparator` draws a line between them.
```tsx
<ItemGroup aria-label="Team members">
<Item role="listitem">...</Item>
<ItemSeparator />
<Item role="listitem">...</Item>
</ItemGroup>
```
## Header and footer [#header-and-footer]
<Preview name="item-header" />
`ItemHeader` and `ItemFooter` span the full width, above or below the content.
```tsx
<Item variant="outline">
<ItemHeader>
<Badge variant="success">Active</Badge>
</ItemHeader>
<ItemContent>...</ItemContent>
<ItemFooter>
<Button size="sm">Edit</Button>
</ItemFooter>
</Item>
```
## Accessibility [#accessibility]
- `ItemGroup` has `role="list"`. Give each `Item` `role="listitem"` and the
group an `aria-label`.
- One interactive element per row: either the whole row is a link or button,
or it holds buttons in `ItemActions`. Never a button inside a link.
- Icon-only buttons need an `aria-label` that names the row, like "Invite Ada
Lovelace", not "Invite".
- Decorative icons get `aria-hidden`. Links that open a new tab say so in
`sr-only` text.
- Rows rendered as links or buttons show a focus ring.
## Props [#props]
### Item [#item]
<TypeTable
type={{
variant: {
description: 'The look of the row.',
type: 'default | outline | muted',
default: 'default',
},
size: {
description: 'Padding and gaps.',
type: 'default | sm | xs',
default: 'default',
},
render: {
description: 'Replaces the `div`, such as with a link or button.',
type: 'ReactElement | ((props, state) => ReactElement)',
},
}}
/>
### ItemMedia [#itemmedia]
<TypeTable
type={{
variant: {
description:
'`default` adds no styles, `icon` sizes an SVG, `tile` puts an SVG on a small rounded square, `image` crops an `img` to a rounded square.',
type: 'default | icon | tile | image',
default: 'default',
},
}}
/>
## API Reference [#api-reference]
[Base UI - useRender](https://base-ui.com/react/utils/use-render)
# Kbd (/docs/ui/kbd)
## Preview [#preview]
<Preview name="kbd" />
## Usage [#usage]
```ts
import { Kbd, KbdGroup } from '@vitnode/core/components/ui/kbd'
```
```tsx
<Kbd>Esc</Kbd>
```
`Kbd` renders a real `<kbd>`, so browsers and assistive tech know it's a key.
## Shortcuts [#shortcuts]
`KbdGroup` wraps a combination. It's a `<kbd>` too, which is how HTML
describes a key combo.
```tsx
<KbdGroup>
<Kbd>Ctrl</Kbd>
<Kbd>K</Kbd>
</KbdGroup>
```
Want a visible plus? Hide it from screen readers, since they already hear two
keys:
```tsx
<KbdGroup>
<Kbd>Ctrl</Kbd>
<span aria-hidden="true">+</span>
<Kbd>C</Kbd>
</KbdGroup>
```
## In buttons, tooltips and inputs [#in-buttons-tooltips-and-inputs]
`Kbd` sizes itself to fit small buttons. Inside a [Tooltip](/docs/ui/tooltip)
it switches to a translucent style that stays readable in both themes. Next to
an [Input Group](/docs/ui/input-group) addon, it makes the classic "press ⌘ K
to search" field. No props needed for any of them.
```tsx
<Button size="sm" variant="outline">
Accept
<Kbd>Enter</Kbd>
</Button>
```
## ⌘ on Mac, Ctrl everywhere else [#-on-mac-ctrl-everywhere-else]
Detect the platform on the client, but render the same thing on the server and
during hydration. `useSyncExternalStore` does both: its third argument is used
for the server and hydration, then React switches to the real value.
```tsx
const subscribeToNothing = () => () => {}
const useIsApple = () =>
React.useSyncExternalStore(
subscribeToNothing,
() => /Mac|iPhone|iPad|iPod/.test(navigator.userAgent),
() => true,
)
const ModifierKey = () => (useIsApple() ? <Kbd>⌘</Kbd> : <Kbd>Ctrl</Kbd>)
```
## Accessibility [#accessibility]
- Keep the `<kbd>` element. A styled `<span>` doesn't say "this is a key".
- Screen readers announce ⌘ and ⇧ inconsistently. Pair each symbol with
visually hidden text, since `aria-label` on a `<kbd>` isn't reliably read:
```tsx
<Kbd title="Command">
<span aria-hidden="true">⌘</span>
<span className="sr-only">Command</span>
</Kbd>
```
- `Kbd` is a hint, not a control (`pointer-events-none`, `select-none`). Put
the action on a real button and listen for the key itself.
- Never make a shortcut the only way to do something.
## Props [#props]
Both components accept every native `<kbd>` prop.
<TypeTable
type={{
Kbd: {
description: 'A single key. Renders `<kbd data-slot="kbd">`.',
type: "React.ComponentProps<'kbd'>",
},
KbdGroup: {
description: 'A key combination. Renders `<kbd data-slot="kbd-group">`.',
type: "React.ComponentProps<'kbd'>",
},
}}
/>
## API Reference [#api-reference]
[MDN - The Keyboard Input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/kbd)
# Label (/docs/ui/label)
## Preview [#preview]
<Preview name="label" />
## Usage [#usage]
```ts
import { Label } from '@vitnode/core/components/ui/label'
```
```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />
```
`Label` is a styled native `<label>`. Point `htmlFor` at the control's `id`:
the label becomes a click target and screen readers read it on focus.
<Callout>
[AutoForm](/docs/ui/auto-form) fields render their own label from the `label`
prop. Don't add a `Label` next to one, or you'll get two. For a label with a
description and error, use [Field](/docs/ui/field).
</Callout>
## With a checkbox [#with-a-checkbox]
Put the control first. Gap and alignment are built in.
```tsx
<div className="flex items-center gap-3">
<Checkbox id="terms" />
<Label htmlFor="terms">I promise I read the terms</Label>
</div>
```
## Wrapping the control [#wrapping-the-control]
No `id` handy? Wrap the control. A `<label>` names whatever is inside it.
```tsx
<Label>
<Checkbox />
Remember me
</Label>
```
## Disabled controls [#disabled-controls]
A disabled control dims its label and shows a `not-allowed` cursor, as in the
preview's last row.
```tsx
<div className="flex items-center gap-3">
<Checkbox disabled id="newsletter" />
<Label htmlFor="newsletter">Weekly newsletter (coming soon)</Label>
</div>
```
This needs the control **before** the label, as a sibling with the `peer`
class. `Checkbox`, `Switch` and `RadioGroupItem` already have it. Label
elsewhere? Put `group` and `data-disabled="true"` on a shared parent, which is
what [Field](/docs/ui/field) does.
## Accessibility [#accessibility]
- Always connect label and control, with `htmlFor` + `id` or by wrapping. A
label merely next to an input is plain text to a screen reader.
- Placeholders are not labels. They vanish as soon as someone types.
- The label is part of the hit area, so keep it right next to small controls.
## Props [#props]
Accepts every native `<label>` prop.
<TypeTable
type={{
htmlFor: {
description: 'The `id` of the control this label names.',
type: 'string',
},
children: {
description: 'The label text. Can also wrap the control.',
type: 'React.ReactNode',
},
className: {
description: 'Extra classes merged with the defaults.',
type: 'string',
},
}}
/>
## API Reference [#api-reference]
[MDN - The Label element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label)
# Marker (/docs/ui/marker)
<Preview name="marker" />
## Usage [#usage]
```ts
import {
Marker,
MarkerContent,
MarkerIcon,
} from '@vitnode/core/components/ui/marker'
```
```tsx
<Marker>
<MarkerIcon>
<Search />
</MarkerIcon>
<MarkerContent>Explored 4 files</MarkerContent>
</Marker>
```
A marker is the quiet line between messages: "Switched branch", "Today",
"Thinking...". It pairs well with [Bubble](/docs/ui/bubble) in a chat thread.
## Variants [#variants]
<Preview name="marker-variants" />
`default` is an inline note. `separator` centers a label between two lines.
`border` adds a line under the row.
```tsx
<Marker variant="separator">
<MarkerContent>Yesterday</MarkerContent>
</Marker>
```
Keep separator labels short. The lines only get the space the label leaves.
## Tones [#tones]
<Preview name="marker-tones" />
Set `tone` when the note carries good or bad news. Colors match `Alert` and
`Badge`, mixed toward the foreground to stay readable in both themes.
```tsx
<Marker tone="success">
<MarkerIcon>
<CircleCheck />
</MarkerIcon>
<MarkerContent>Build passed</MarkerContent>
</Marker>
```
Color is a bonus, not the message. Pair it with an icon or words.
## Stacked icon [#stacked-icon]
<Preview name="marker-stacked" />
`MarkerIcon` sizes any icon to the text. Add `flex-col` to put it above the
text.
```tsx
<Marker className="flex-col">...</Marker>
```
## Status and shimmer [#status-and-shimmer]
For work in progress, set `role="status"`, put a `Spinner` in the icon slot and
add the `shimmer` utility to the text. See the last line of the preview.
```tsx
<Marker role="status">
<MarkerIcon>
<Spinner />
</MarkerIcon>
<MarkerContent className="shimmer">Thinking...</MarkerContent>
</Marker>
```
## Links and buttons [#links-and-buttons]
Pass `render` to turn the marker into a link or a button. Links get an
underline for free.
```tsx
<Marker render={<a href="/admin/plugins" />}>
<MarkerContent>View installed plugins</MarkerContent>
</Marker>
<Marker
render={<button className="hover:text-foreground" onClick={revert} type="button" />}
>
<MarkerContent>Revert this change</MarkerContent>
</Marker>
```
## Accessibility [#accessibility]
- A marker is a plain `div`. Add `role="status"` for live progress, `render` an
`a` or `button` when it's clickable, and nothing for a plain note.
- Don't add `role="separator"` to a labeled separator. It would hide the label
from assistive tech. The lines are decorative pseudo-elements.
- `MarkerIcon` is `aria-hidden`. Give an icon-only marker an `aria-label`.
- Wrap a thread in `role="log"` so new messages and markers are announced in
order.
## Props [#props]
### Marker [#marker]
<TypeTable
type={{
variant: {
description: 'How the marker sits between content.',
type: 'default | separator | border',
default: 'default',
},
tone: {
description: 'Text color, shared with Alert and Badge.',
type: 'neutral | info | success | warning | destructive',
default: 'neutral',
},
render: {
description: 'Replaces the root element, such as an `a` or `button`.',
type: 'ReactElement | ((props, state) => ReactElement)',
},
role: {
description: 'Use `status` for live progress.',
type: 'AriaRole',
},
}}
/>
### MarkerIcon and MarkerContent [#markericon-and-markercontent]
Both render a `span` and take every `span` prop.
## API Reference [#api-reference]
[Base UI - useRender](https://base-ui.com/react/utils/use-render)
# Menubar (/docs/ui/menubar)
## Preview [#preview]
<Preview name="menubar" />
## Usage [#usage]
```ts
import {
Menubar,
MenubarContent,
MenubarItem,
MenubarMenu,
MenubarSeparator,
MenubarShortcut,
MenubarTrigger,
} from '@vitnode/core/components/ui/menubar'
```
```tsx
<Menubar>
<MenubarMenu>
<MenubarTrigger>File</MenubarTrigger>
<MenubarContent className="w-56">
<MenubarItem>
New tab
<MenubarShortcut>⌘T</MenubarShortcut>
</MenubarItem>
<MenubarItem>New window</MenubarItem>
<MenubarSeparator />
<MenubarItem>Print...</MenubarItem>
</MenubarContent>
</MenubarMenu>
<MenubarMenu>
<MenubarTrigger>Edit</MenubarTrigger>
<MenubarContent className="w-56">
<MenubarItem>Undo</MenubarItem>
<MenubarItem>Redo</MenubarItem>
</MenubarContent>
</MenubarMenu>
</Menubar>
```
Each `MenubarMenu` is a trigger plus its content. Open one, then hover the next
trigger: it opens straight away, like a desktop menu bar.
## Submenus [#submenus]
Nest a `MenubarSub` to tuck actions one level deeper. It opens on hover, click
or the right arrow.
```tsx
<MenubarSub>
<MenubarSubTrigger>Share</MenubarSubTrigger>
<MenubarSubContent className="w-44">
<MenubarItem>Email link</MenubarItem>
</MenubarSubContent>
</MenubarSub>
```
## Checkbox and radio items [#checkbox-and-radio-items]
Open **View** and **Profiles** above. `MenubarCheckboxItem` toggles on its own,
items in a `MenubarRadioGroup` pick one. Both work controlled or uncontrolled.
```tsx
<MenubarCheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
Always show bookmarks bar
</MenubarCheckboxItem>
<MenubarRadioGroup onValueChange={setProfile} value={profile}>
<MenubarRadioItem value="andy">Andy</MenubarRadioItem>
</MenubarRadioGroup>
```
The check mark sits at the start of the row, like in the
[Dropdown Menu](/docs/ui/dropdown-menu). Add `inset` to plain items, labels and
sub-triggers in the same menu so their text lines up.
## Shortcuts and destructive items [#shortcuts-and-destructive-items]
`MenubarShortcut` is only a label: bind the keys yourself. Use
`variant="destructive"` for actions you can't take back.
```tsx
<MenubarItem>
Undo
<MenubarShortcut>⌘Z</MenubarShortcut>
</MenubarItem>
<MenubarItem variant="destructive">Close all windows</MenubarItem>
```
## Accessibility [#accessibility]
- The bar is one tab stop. Left and right arrows move between menus, and move
the open menu with you.
- Inside a menu, up and down move between items, right opens a submenu, a
letter jumps to a match and <kbd>Escape</kbd> returns focus to the trigger.
- Triggers and rows grow to a 44px tap target on touch screens.
- Switching between open menus is instant. Reduced motion turns the scale-in
off.
- A menu bar is a desktop pattern. On small screens keep it short, or offer the
same actions in a [Dropdown Menu](/docs/ui/dropdown-menu).
## Props [#props]
### Menubar [#menubar]
<TypeTable
type={{
loopFocus: {
description: 'Arrow keys wrap from the last menu to the first.',
type: 'boolean',
default: 'true',
},
modal: {
description: 'An open menu locks page scroll and blocks outside clicks.',
type: 'boolean',
default: 'true',
},
orientation: {
description: 'Which arrow keys move between menus.',
type: 'horizontal | vertical',
default: 'horizontal',
},
disabled: {
description: 'Disables every menu in the bar.',
type: 'boolean',
default: 'false',
},
}}
/>
### MenubarContent [#menubarcontent]
<TypeTable
type={{
side: {
description:
'Preferred side of the trigger. Flips when there is no room.',
type: 'top | bottom | left | right | inline-start | inline-end',
default: 'bottom',
},
align: {
description: 'How the menu aligns against the trigger.',
type: 'start | center | end',
default: 'start',
},
sideOffset: {
description:
'Gap from the trigger in pixels. Clears the bar padding, so the menu sits 4px below the bar.',
type: 'number',
default: '8',
},
alignOffset: {
description:
'Shift along the alignment axis. Lines the menu up with the bar edge.',
type: 'number',
default: '-4',
},
}}
/>
### MenubarItem [#menubaritem]
<TypeTable
type={{
variant: {
description: 'The look of the item.',
type: 'default | destructive',
default: 'default',
},
inset: {
description: 'Start padding to line up with checkbox and radio items.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'Visible but not interactive.',
type: 'boolean',
default: 'false',
},
closeOnClick: {
description: 'Close the menu when the item is chosen.',
type: 'boolean',
default: 'true',
},
onClick: {
description: 'Called on click, tap or keyboard select.',
type: '(event) => void',
},
}}
/>
`MenubarCheckboxItem` takes `checked`, `defaultChecked` and `onCheckedChange`.
`MenubarRadioGroup` takes `value`, `defaultValue` and `onValueChange`. Both item
types accept `inset` and `disabled`. `MenubarMenu` takes `open`, `defaultOpen`
and `onOpenChange` to drive one menu yourself.
## API Reference [#api-reference]
[Base UI - Menubar](https://base-ui.com/react/components/menubar#api-reference)
# Message (/docs/ui/message)
## Preview [#preview]
<Preview name="message" />
## Usage [#usage]
```ts
import {
Message,
MessageAvatar,
MessageContent,
MessageFooter,
MessageGroup,
MessageHeader,
} from '@vitnode/core/components/ui/message'
```
```tsx
<Message>
<MessageAvatar>
<Avatar>
<AvatarImage alt="VitNode assistant" src="/logo_vitnode_icon.svg" />
<AvatarFallback>VN</AvatarFallback>
</Avatar>
</MessageAvatar>
<MessageContent>
<Bubble variant="muted">
<BubbleContent>How can I help you today?</BubbleContent>
</Bubble>
</MessageContent>
</Message>
```
`Message` owns the row: who's talking, which side, and what sits above or
below. The speech bubble is a [Bubble](/docs/ui/bubble).
```text
MessageGroup
└── Message
├── MessageAvatar
└── MessageContent
├── MessageHeader
├── Bubble / Attachment
└── MessageFooter
```
## Alignment [#alignment]
`align="end"` marks messages the current user sent. The avatar swaps sides,
and every bubble, attachment, header and footer inside follows, so you don't
set `align` on each `Bubble`. Sides flip on their own in right-to-left
languages.
```tsx
<Message align="end">
<MessageContent>
<Bubble>
<BubbleContent>Sent by me, obviously.</BubbleContent>
</Bubble>
</MessageContent>
</Message>
```
## Avatar [#avatar]
`MessageAvatar` sits at the bottom, next to the last bubble. With a
`MessageFooter`, it lifts to line up with the bubble instead.
## Group [#group]
`MessageGroup` tightens the spacing between messages from one sender. Give the
earlier ones an empty `MessageAvatar` so their bubbles line up.
```tsx
<MessageGroup>
<Message>
<MessageAvatar />
<MessageContent>...</MessageContent>
</Message>
<Message>
<MessageAvatar>
<Avatar>
<AvatarFallback>AV</AvatarFallback>
</Avatar>
</MessageAvatar>
<MessageContent>...</MessageContent>
</Message>
</MessageGroup>
```
For several bubbles in one message, use
[`BubbleGroup`](/docs/ui/bubble#grouping) inside `MessageContent`.
## Header, footer and actions [#header-footer-and-actions]
`MessageHeader` holds the sender name and time. `MessageFooter` holds read
receipts or actions like copy and retry.
```tsx
<MessageContent>
<MessageHeader className="gap-1.5">
<span className="text-foreground">Ava</span>
<time dateTime="2026-10-02T09:41">9:41 AM</time>
</MessageHeader>
<Bubble variant="muted">
<BubbleContent>Did the plugin build pass?</BubbleContent>
</Bubble>
<MessageFooter>
<Button aria-label="Copy message" size="icon-xs" variant="ghost">
<CopyIcon />
</Button>
</MessageFooter>
</MessageContent>
```
## Attachments [#attachments]
Drop an [Attachment](/docs/ui/attachment) next to the bubble in
`MessageContent`. It follows the message's alignment.
## Accessibility [#accessibility]
- `Message` has no role. Put `role="log"` and an `aria-label` on the
conversation container.
- Alignment only helps sighted users. Name the sender in text too, with a
`MessageHeader` (`className="sr-only"` for your own messages).
- Wrap timestamps in `<time dateTime="...">`.
- Give `AvatarImage` the sender's name as `alt`. If a header already names
them, set `aria-hidden="true"` on `MessageAvatar`.
- Icon-only footer actions need an `aria-label`.
- For "someone is typing", use a [Marker](/docs/ui/marker) with
`role="status"`.
## Props [#props]
### Message [#message]
<TypeTable
type={{
align: {
description:
'Which side the message sits on. Everything inside follows it.',
type: 'start | end',
default: 'start',
},
}}
/>
The other parts accept every `div` prop, including `className`.
## API Reference [#api-reference]
[shadcn/ui - Message](https://ui.shadcn.com/docs/components/base/message)
# Motion (/docs/ui/motion)
Motion in VitNode answers one question: _where did that come from, and where
did it go?_ Everything reacts on press, moves along a real path and can change
its mind halfway. Nothing bounces for fun.
## Respond on press [#respond-on-press]
<Preview name="motion-press" className="*:max-w-full" />
A press shows up in under 150ms, or it feels broken. `Button` dips to
`active:scale-97`; tiny targets like `Checkbox` go further, to `scale-90`, so
the dip is still visible under a thumb.
## Easing [#easing]
<Preview name="motion-easing" className="*:max-w-full" />
`ease-fluid` starts at full speed and spends its time settling, so the UI looks
like it moved the instant you asked. `ease-in` waits before reacting, which
feels like lag. `linear` is for progress bars and spinners only.
```css
--ease-fluid: cubic-bezier(0.22, 1, 0.36, 1);
```
## Timing [#timing]
| What | Enter | Exit |
| ------------------------------ | ------- | ------- |
| Tooltip, popover, menu | 150ms | 100ms |
| Dialog, alert dialog | 200ms | 150ms |
| Sheet, drawer, big panels | 300ms | 200ms |
| Press feedback, hover, toggles | ≤ 150ms | ≤ 150ms |
Exits are shorter than entrances: once you're done with something, it should
get out of the way.
## Interruptible [#interruptible]
<Preview name="motion-interruptible" className="*:max-w-full" />
A transition always starts from wherever the element is right now, so it can
reverse mid-flight. A keyframe animation restarts from frame one. VitNode
overlays use transitions keyed on Base UI's `data-starting-style` and
`data-ending-style` instead of `@keyframes`.
```tsx
<div className="ease-fluid transition-[opacity,scale] duration-150 data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 data-ending-style:duration-100 motion-reduce:transition-none" />
```
## Springs [#springs]
<Preview name="motion-spring" className="*:max-w-full" />
When a component needs a spring (`Switch`, `ToggleGroup`, `Combobox` chips), it
uses `motion/react` with a critically damped spring: fast, no wobble. Save
`bounce` for when a gesture carried momentum into the release, like flinging a
drawer away.
```tsx
const SPRING = { type: 'spring', duration: 0.3, bounce: 0 } as const
<m.span layout transition={shouldReduceMotion ? { duration: 0 } : SPRING} />
```
## Grow from the trigger [#grow-from-the-trigger]
<Preview name="motion-origin" className="*:max-w-full" />
Popovers, menus and tooltips scale out of their trigger with
`origin-(--transform-origin)`, which Base UI sets from the side and alignment.
Leave and return along the same path: a sheet slides back to the edge it came
from.
## Reduced motion [#reduced-motion]
<Preview name="motion-reduced" className="*:max-w-full" />
With reduced motion on, slides become crossfades and springs run with
`duration: 0`. Fading is fine, travel isn't. CSS gets `motion-reduce:`, motion
code reads `useReducedMotion()`, and frosted surfaces drop their blur with
`reduced-transparency:`.
```tsx
<div className="bg-background/80 backdrop-blur-md motion-reduce:transition-none reduced-transparency:bg-background reduced-transparency:backdrop-blur-none" />
```
## Related [#related]
<Cards>
<Card
title="Accessibility"
href="/docs/ui/accessibility"
description="Focus, labels, contrast and user preferences."
/>
<Card
title="Elevation"
href="/docs/ui/elevation"
description="Surfaces, shadows and how layers stack."
/>
<Card
title="Colors"
href="/docs/ui/colors"
description="Semantic color tokens for text and surfaces."
/>
</Cards>
# Nullable Number (/docs/ui/nullable-number)
## Preview [#preview]
<Preview name="nullable-number" />
A [Number Field](/docs/ui/number-field) plus one checkbox, for when the honest
answer is "no limit".
## 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'
```
```tsx
const formSchema = z.object({
max_members: z.number().int().min(1).nullable().default(10),
})
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'max_members',
component: props => (
<AutoFormNullableNumber
{...props}
label="Maximum members"
min={1}
toggleLabel="Unlimited"
/>
),
},
]}
/>
```
## Value [#value]
The value is `number | null`. Checking the box stores `null` and disables the
input. Unchecking it restores the last number. Clearing the input stores `0`.
Back it with `z.number().nullable()`. If the field can be
[hidden](/docs/ui/auto-form#conditional-fields), add a `default` so it never
blocks submission.
## Labels [#labels]
The second field in the preview uses all three labels:
```tsx
<AutoFormNullableNumber
{...props}
label="Auto-logout"
orLabel="or"
toggleLabel="Never"
unitLabel="minutes"
/>
```
Every other prop (`min`, `max`, `step`, `format`, `placeholder`…) goes to the
[Number Field](/docs/ui/number-field#props). Pass `min`/`max` here and in the
schema: the schema validates, the props clamp the buttons and keys.
## Props [#props]
<TypeTable
type={{
toggleLabel: {
description: 'Checkbox label. Checking it sets the value to `null`.',
type: 'React.ReactNode',
required: true,
},
label: {
description: 'Label above the field.',
type: 'React.ReactNode',
},
description: {
description: 'Help text below the field.',
type: 'React.ReactNode',
},
unitLabel: {
description: 'Unit right after the input, like `kB` or `minutes`.',
type: 'React.ReactNode',
},
orLabel: {
description: 'Connector before the checkbox, like `or`.',
type: 'React.ReactNode',
},
placeholder: {
description: 'Placeholder of the empty input.',
type: 'string',
},
}}
/>
# Number Field (/docs/ui/number-field)
## Preview [#preview]
<Preview name="number-field" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
<Preview name="number-field-auto-form" />
```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormNumber } from '@vitnode/core/components/form/fields/number'
```
```tsx
const formSchema = z.object({
guests: z.number().int().min(1).max(12).default(2),
})
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'guests',
component: props => (
<AutoFormNumber {...props} label="Guests" max={12} min={1} unitLabel="people" />
),
},
]}
/>
```
The form stores a real `number`, or `null` when cleared. Pass `min`/`max` to
both: the schema validates, the props clamp.
Need an "unlimited" checkbox? Use [Nullable Number](/docs/ui/nullable-number).
</Tab>
<Tab value="Manual">
```ts
import {
NumberField,
NumberFieldDecrement,
NumberFieldGroup,
NumberFieldIncrement,
NumberFieldInput,
} from '@vitnode/core/components/ui/number-field'
```
```tsx
const [value, setValue] = React.useState<number | null>(2)
<NumberField max={8} min={0} onValueChange={setValue} value={value}>
<NumberFieldGroup>
<NumberFieldDecrement />
<NumberFieldInput aria-label="Coffees per day" />
<NumberFieldIncrement />
</NumberFieldGroup>
</NumberField>
```
Uncontrolled? Use `defaultValue` with `onValueCommitted`, which fires on blur
or button release instead of every keystroke.
</Tab>
</Tabs>
## Min, max and step [#min-max-and-step]
<Preview name="number-field-steps" />
`min`/`max` disable the button at a limit and clamp typed values on blur.
`step` is one press, `largeStep` adds <kbd>Shift</kbd>, `smallStep` adds
<kbd>Alt</kbd>. `snapOnStep` snaps to the nearest multiple.
```tsx
<NumberField largeStep={50} max={500} min={0} snapOnStep step={5}>
…
</NumberField>
```
## Formatting [#formatting]
<Preview name="number-field-format" />
`format` takes [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options).
The value stays a number: `0.15` shows as `15%`. Formatting follows the app
locale unless you pass `locale`.
```tsx
<NumberField
defaultValue={19.99}
format={{ style: 'currency', currency: 'USD' }}
>
…
</NumberField>
```
## Scrub area [#scrub-area]
Drag the label in the [preview](#preview) sideways. `NumberFieldScrubArea`
makes a label scrubbable. Pass the field's `id` as `htmlFor` so a click still
focuses the input.
```tsx
const id = React.useId()
<NumberField id={id} max={8} min={0}>
<NumberFieldScrubArea htmlFor={id} label="Coffees per day" />
<NumberFieldGroup>…</NumberFieldGroup>
</NumberField>
```
`allowWheelScrub` adds mouse-wheel changes while focused.
## Sizes [#sizes]
<Preview name="number-field-sizes" />
```tsx
<NumberField size="sm">…</NumberField>
```
## Disabled and read-only [#disabled-and-read-only]
<Preview name="number-field-states" />
`readOnly` stays focusable, unlike `disabled`.
## Accessibility [#accessibility]
- The input is a text field with `inputMode`, so `$19.99` fits and phones
show a number pad.
- <kbd>↑</kbd> / <kbd>↓</kbd> step, <kbd>Home</kbd> / <kbd>End</kbd> jump to
`min` / `max` when set.
- The buttons are labelled "Increase" / "Decrease", skip <kbd>Tab</kbd>, and
grow to a 44px hit area on touch.
- Name the input with a label (`htmlFor` + `id`), a scrub area or `aria-label`.
`AutoFormNumber` does it for you.
## Props [#props]
<TypeTable
type={{
value: {
description: 'The number (controlled). `null` means empty.',
type: 'number | null',
},
defaultValue: {
description: 'The starting number when uncontrolled.',
type: 'number',
},
onValueChange: {
description: 'Every change: typing, buttons, keys, scrubbing.',
type: '(value: number | null) => void',
},
onValueCommitted: {
description: 'Final change only: blur, or button/scrub release.',
type: '(value: number | null) => void',
},
min: { description: 'Lowest allowed value.', type: 'number' },
max: { description: 'Highest allowed value.', type: 'number' },
step: {
description: 'Amount per click or arrow press.',
type: 'number | "any"',
default: '1',
},
largeStep: {
description: 'Amount with Shift held.',
type: 'number',
default: '10',
},
smallStep: {
description: 'Amount with Alt held.',
type: 'number',
default: '0.1',
},
snapOnStep: {
description: 'Snap to the nearest step multiple.',
type: 'boolean',
default: 'false',
},
format: {
description: 'How the value is displayed.',
type: 'Intl.NumberFormatOptions',
},
locale: {
description: 'Locale for formatting and parsing.',
type: 'Intl.LocalesArgument',
default: 'the app locale',
},
size: {
description: 'Height of the field.',
type: '"sm" | "default" | "lg"',
default: '"default"',
},
allowWheelScrub: {
description: 'Mouse wheel changes the value while focused.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'Ignores every interaction.',
type: 'boolean',
default: 'false',
},
readOnly: {
description: 'Shows the value but blocks changes.',
type: 'boolean',
default: 'false',
},
}}
/>
`AutoFormNumber` takes all of these except `value`, `defaultValue` and
`onValueChange` (the form owns them), plus `label`, `description`,
`placeholder` and `unitLabel`.
## API Reference [#api-reference]
[Base UI - Number Field](https://base-ui.com/react/components/number-field)
# Page Title (/docs/ui/page-title)
## Preview [#preview]
<Preview className="*:max-w-3xl" name="page-title" />
## Usage [#usage]
```ts
import { PageTitle } from '@vitnode/core/components/ui/page-title'
```
```tsx
<PageTitle desc="Group users and decide what each group can do." h1="Roles">
<Button>
<PlusIcon />
Create role
</Button>
</PageTitle>
```
`children` become actions on the right. On phones everything stacks and the
actions go full width. From `sm` up, heading left, actions right.
## h1 or h2 [#h1-or-h2]
Pass exactly one of `h1` or `h2`. TypeScript complains about both or neither.
- `h1` is the page heading (`text-2xl sm:text-3xl`). One per page.
- `h2` is a section inside a page that already has an `h1`, like a settings
panel (`text-xl sm:text-2xl`).
```tsx
<PageTitle h2="Danger zone" />
```
The previews use `h2`, since this page already has an `h1`.
## Subtitle [#subtitle]
<Preview className="*:max-w-3xl" name="page-title-subtitle" />
A small muted line above the heading. Use it for where the page lives.
```tsx
<PageTitle
desc="Sign in faster with accounts you already have."
h1="Connected accounts"
subtitle="Settings"
/>
```
## Back link [#back-link]
<Preview className="*:max-w-3xl" name="page-title-back" />
`back` adds an arrow link above the heading (and above `subtitle`). Good for
edit and detail pages under a list. It's a TanStack Router `Link`, so it
navigates client-side and preloads. The actions side stays free.
```tsx
<PageTitle
back={{ href: '/admin/core/users', label: 'Back to users' }}
desc="Edit the details shown on the public profile."
h1="Edit user"
>
<Button>Save changes</Button>
</PageTitle>
```
## Multiple actions [#multiple-actions]
<Preview className="*:max-w-3xl" name="page-title-actions" />
Pass as many `children` as you need; they wrap on small screens. Keep one
primary button and make the rest `outline` or `ghost`.
```tsx
<PageTitle
desc="Everything published on the site, newest first."
h1="Blog posts"
>
<Button variant="outline">
<DownloadIcon />
Export
</Button>
<Button>
<PlusIcon />
New post
</Button>
</PageTitle>
```
## Spacing [#spacing]
`PageTitle` has a built-in `mb-6`. Drop it when the parent already uses `gap-*`:
```tsx
<div className="flex flex-col gap-4">
<PageTitle className="mb-0" h1="Devices" />
<DevicesList />
</div>
```
## Accessibility [#accessibility]
- The heading is a real `h1` or `h2`, so it appears in heading navigation.
- `subtitle` is a `p`, not a heading, so it stays out of the outline.
- Give icon-only actions an `aria-label` or `sr-only` text.
## Props [#props]
<TypeTable
type={{
h1: {
description:
'Page heading, rendered as `h1`. Use `h1` or `h2`, not both.',
type: 'ReactNode',
},
h2: {
description: 'Section heading, rendered as a smaller `h2`.',
type: 'ReactNode',
},
subtitle: {
description: 'Small muted line above the heading.',
type: 'ReactNode',
},
desc: {
description: 'Muted text below the heading.',
type: 'ReactNode',
},
back: {
description: 'Arrow link above the heading.',
type: '{ href: string; label: ReactNode }',
},
children: {
description: 'Actions next to the heading.',
type: 'ReactNode',
},
className: {
description: 'Extra wrapper classes, for example `mb-0`.',
type: 'string',
},
ref: {
description: 'Ref callback for the wrapper `div`.',
type: 'RefCallback<HTMLDivElement>',
},
}}
/>
# Pagination (/docs/ui/pagination)
## Preview [#preview]
<Preview name="pagination" />
<Callout title="Building a table?">
[Data Table](/docs/ui/data-table) already paginates, URL state included. Use
`Pagination` for your own lists, feeds and galleries.
</Callout>
## Usage [#usage]
```ts
import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
} from '@vitnode/core/components/ui/pagination'
```
```tsx
<Pagination>
<PaginationContent>
<PaginationItem>
<PaginationPrevious href="?page=1" />
</PaginationItem>
<PaginationItem>
<PaginationLink href="?page=1">1</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationLink href="?page=2" isActive>
2
</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationEllipsis />
</PaginationItem>
<PaginationItem>
<PaginationNext href="?page=3" />
</PaginationItem>
</PaginationContent>
</Pagination>
```
Every link is a real `<a>`, so pages stay crawlable and middle-click opens a new
tab. Below `sm`, previous and next shrink to a chevron that flips in RTL.
## With router links [#with-router-links]
Keep the `href` for crawlers, and let TanStack Router handle the click:
```tsx
const navigate = useNavigate()
const goTo = (page: number) => (event: React.MouseEvent<HTMLAnchorElement>) => {
event.preventDefault()
void navigate({ to: '.', search: (prev) => ({ ...prev, page }) })
}
;<PaginationLink
href={`?page=${page}`}
isActive={page === current}
onClick={goTo(page)}
>
{page}
</PaginationLink>
```
## Ellipsis [#ellipsis]
Show the first page, the last page and the current one. `PaginationEllipsis`
covers the rest. This helper keeps five slots, so the row never jumps:
```tsx
type PageSlot = 'ellipsis-end' | 'ellipsis-start' | number
const range = (from: number, to: number) =>
Array.from({ length: to - from + 1 }, (_, step) => from + step)
const pageWindow = (current: number, total: number): PageSlot[] => {
if (total <= 5) return range(1, total)
if (current <= 3) return [1, 2, 3, 'ellipsis-end', total]
if (current >= total - 2) {
return [1, 'ellipsis-start', ...range(total - 2, total)]
}
return [1, 'ellipsis-start', current, 'ellipsis-end', total]
}
```
```tsx
{
pageWindow(page, total).map((slot) => (
<PaginationItem key={slot}>
{typeof slot === 'number' ? (
<PaginationLink href={`?page=${slot}`} isActive={slot === page}>
{slot}
</PaginationLink>
) : (
<PaginationEllipsis />
)}
</PaginationItem>
))
}
```
## Small screens [#small-screens]
Shrink the preview to phone width: the numbers give way to "Page 2 of 12". Add
`hidden sm:block` to each number's item, plus one item for the phone line:
```tsx
<PaginationItem className="sm:hidden">
<span className="text-muted-foreground px-2 text-sm">
Page {page} of {total}
</span>
</PaginationItem>
```
## Disabled ends [#disabled-ends]
There is no page zero (we checked). Drop the `href` so the keyboard skips the
link, and add `role="link"` with `aria-disabled` so screen readers hear it as
unavailable:
```tsx
<PaginationPrevious
{...(page > 1
? { href: `?page=${page - 1}` }
: {
'aria-disabled': true,
className: 'pointer-events-none',
role: 'link',
})}
/>
```
## Custom labels [#custom-labels]
<Preview name="pagination-labels" />
`text` replaces the translated "Previous" / "Next". Pass a matching
`aria-label` too, or screen readers still announce "Previous page".
```tsx
<PaginationNext aria-label="Older posts" href="?page=3" text="Older posts" />
```
## Accessibility [#accessibility]
- `Pagination` is a `nav` landmark with a translated "Pagination" label.
- The active link gets `aria-current="page"`.
- Previous and next keep their translated label when only the chevron shows.
- `PaginationEllipsis` hides its icon and reads "More pages" to screen readers.
- Announce page changes that don't reload, for example with an
`aria-live="polite"` line like the preview's "1-3 of 36".
## Props [#props]
### PaginationLink [#paginationlink]
<TypeTable
type={{
href: {
description: 'Link target. Leave it out for a disabled end.',
type: 'string',
},
isActive: {
description:
'Current page: adds `aria-current="page"` and the outline style.',
type: 'boolean',
default: 'false',
},
size: {
description: 'Size of the underlying button.',
type: 'default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg',
default: 'icon',
},
}}
/>
### PaginationPrevious / PaginationNext [#paginationprevious--paginationnext]
Every `PaginationLink` prop, plus:
<TypeTable
type={{
text: {
description: 'Visible label, shown from `sm` up.',
type: 'string',
default: '"Previous" / "Next" (translated)',
},
}}
/>
## API Reference [#api-reference]
[shadcn/ui - Pagination](https://ui.shadcn.com/docs/components/base/pagination)
# Popover (/docs/ui/popover)
## Preview [#preview]
<Preview name="popover" />
## Usage [#usage]
```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
} from '@vitnode/core/components/ui/popover'
```
```tsx
<Popover>
<PopoverTrigger render={<Button variant="outline">Invite</Button>} />
<PopoverContent>
<PopoverHeader>
<PopoverTitle>Invite friends</PopoverTitle>
<PopoverDescription>The link works for 7 days.</PopoverDescription>
</PopoverHeader>
</PopoverContent>
</Popover>
```
`PopoverContent` is `w-72` with a `gap-4` column, so stacked children space
themselves. Override the width with `className`.
## With a form [#with-a-form]
<Preview name="popover-form" />
Drop an `AutoForm` in for quick edits. Control `open` so you can close it after
a successful submit.
```tsx
const [open, setOpen] = React.useState(false)
<Popover onOpenChange={setOpen} open={open}>
<PopoverTrigger render={<Button variant="outline">Add link</Button>} />
<PopoverContent align="start" className="w-80">
<AutoForm
fields={fields}
formSchema={formSchema}
onSubmit={values => {
insertLink(values)
setOpen(false)
}}
/>
</PopoverContent>
</Popover>
```
Longer forms belong in a [Dialog](/docs/ui/dialog), which also guards unsaved
changes.
## Position [#position]
<Preview name="popover-side" />
Set `side` and `align` on `PopoverContent`. It flips when there's no room and
grows out of the trigger.
## Props [#props]
<TypeTable
type={{
side: {
description: 'Preferred side of the trigger.',
type: '"top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"',
default: '"bottom"',
},
align: {
description: 'Alignment against the trigger.',
type: '"start" | "center" | "end"',
default: '"center"',
},
sideOffset: {
description: 'Gap from the trigger in pixels.',
type: 'number',
default: '4',
},
alignOffset: {
description: 'Shift along the alignment axis in pixels.',
type: 'number',
default: '0',
},
anchor: {
description: 'Position against another element instead of the trigger.',
type: 'Element | RefObject<Element>',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Popover](https://base-ui.com/react/components/popover#api-reference)
# Progress (/docs/ui/progress)
<Preview name="progress" />
## Usage [#usage]
```ts
import {
Progress,
ProgressLabel,
ProgressValue,
} from '@vitnode/core/components/ui/progress'
```
```tsx
<Progress value={42}>
<ProgressLabel>Uploading photos</ProgressLabel>
<ProgressValue />
</Progress>
```
`ProgressLabel` names the bar for screen readers. `ProgressValue` uses tabular
numbers, so digits don't wiggle as they count.
The bar grows with a `scaleX` transform, so frequent updates stay smooth. With
reduced motion it jumps straight to the new value.
## Indeterminate [#indeterminate]
Don't know how long it takes? Pass `value={null}`. A segment sweeps across in
the reading direction. With reduced motion the track shows a static tint
instead.
```tsx
<Progress value={null}>
<ProgressLabel>Preparing export</ProgressLabel>
</Progress>
```
## Custom range and format [#custom-range-and-format]
<Preview name="progress-format" />
Set `min` and `max` for any range. `format` takes `Intl.NumberFormat` options,
and `ProgressValue` takes a function for full control. Use
`getAriaValueText` when the spoken value needs more context.
```tsx
<Progress max={10} value={7}>
<ProgressLabel>Onboarding steps</ProgressLabel>
<ProgressValue>{(_, value) => `${value} of 10`}</ProgressValue>
</Progress>
```
## Props [#props]
### Progress [#progress]
<TypeTable
type={{
value: {
description: 'Current value. `null` makes the bar indeterminate.',
type: 'number | null',
required: true,
},
min: {
description: 'Lowest value.',
type: 'number',
default: '0',
},
max: {
description: 'Highest value.',
type: 'number',
default: '100',
},
format: {
description: 'Number format for the value.',
type: 'Intl.NumberFormatOptions',
},
locale: {
description: 'Locale for the number format.',
type: 'Intl.LocalesArgument',
},
getAriaValueText: {
description: 'Builds the text screen readers announce.',
type: '(formattedValue, value) => string',
},
}}
/>
### ProgressValue [#progressvalue]
<TypeTable
type={{
children: {
description: 'Renders the value yourself.',
type: '(formattedValue, value) => ReactNode',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Progress](https://base-ui.com/react/components/progress#api-reference)
# Radio Group (/docs/ui/radio-group)
## Preview [#preview]
<Preview name="radio-group" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormRadioGroup } from '@vitnode/core/components/form/fields/radio-group'
import { z } from 'zod'
const formSchema = z.object({
sort: z.enum(['latest', 'top', 'unanswered']).default('latest'),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'sort',
component: (props) => (
<AutoFormRadioGroup
{...props}
label="Default sort"
labels={[
{
value: 'latest',
label: 'Latest activity',
description: 'New replies float up.',
},
{ value: 'top', label: 'Most liked' },
{ value: 'unanswered', label: 'Unanswered first', disabled: true },
]}
/>
),
},
]}
/>
```
Options come from the `z.enum()`. `labels` only adds text: an enum value
without a label shows the raw value.
</Tab>
<Tab value="Manual">
```tsx
import {
Field,
FieldContent,
FieldDescription,
FieldLabel,
} from '@vitnode/core/components/ui/field'
import {
RadioGroup,
RadioGroupItem,
} from '@vitnode/core/components/ui/radio-group'
```
```tsx
<RadioGroup aria-label="Default sort" defaultValue="latest">
<Field orientation="horizontal">
<RadioGroupItem id="latest" value="latest" />
<FieldContent>
<FieldLabel htmlFor="latest">Latest activity</FieldLabel>
<FieldDescription>New replies float up.</FieldDescription>
</FieldContent>
</Field>
<Field data-disabled orientation="horizontal">
<RadioGroupItem disabled id="unanswered" value="unanswered" />
<FieldLabel htmlFor="unanswered">Unanswered first</FieldLabel>
</Field>
</RadioGroup>
```
</Tab>
</Tabs>
Arrow keys move between options and select them. Tab leaves the group.
## Blocks [#blocks]
<Preview name="radio-group-blocks" />
`variant="blocks"` turns each option into a clickable card. It's built from
[Field choice cards](/docs/ui/field#choice-cards).
```tsx
<AutoFormRadioGroup
{...props}
label="Registration"
labels={labels}
variant="blocks"
/>
```
## Props [#props]
`AutoFormRadioGroup` also accepts every
[Base UI Radio Group](https://base-ui.com/react/components/radio#api-reference)
prop.
<TypeTable
type={{
label: {
description: 'Shown above the options.',
type: 'ReactNode',
},
labelRight: {
description: "Content pinned to the label's right edge.",
type: 'ReactNode',
},
description: {
description: 'Shown between the label and the options.',
type: 'ReactNode',
},
labels: {
description: 'Text for each enum value. Unlisted values show as-is.',
type: '{ value: string; label: string; description?: string; disabled?: boolean }[]',
default: '[]',
},
variant: {
description:
'`default` is a list with the radio on the left. `blocks` renders cards.',
type: '"default" | "blocks"',
default: '"default"',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Radio Group](https://base-ui.com/react/components/radio#api-reference)
# Resizable (/docs/ui/resizable)
## Preview [#preview]
<Preview name="resizable" />
## Usage [#usage]
```ts
import {
ResizableHandle,
ResizablePanel,
ResizablePanelGroup,
} from '@vitnode/core/components/ui/resizable'
```
```tsx
<div className="h-80">
<ResizablePanelGroup className="rounded-lg border">
<ResizablePanel defaultSize="35%">Sidebar</ResizablePanel>
<ResizableHandle />
<ResizablePanel>Content</ResizablePanel>
</ResizablePanelGroup>
</div>
```
The group sets an inline `height: 100%`, so a height class on it is ignored.
Give the **parent** a height instead.
Groups nest: put a `ResizablePanelGroup` inside a `ResizablePanel` to split it
again, like the terminal in the preview.
## Vertical [#vertical]
<Preview name="resizable-vertical" />
```tsx
<ResizablePanelGroup orientation="vertical">
```
## With handle [#with-handle]
<Preview name="resizable-handle" />
`withHandle` adds a grip, so people know the divider can be grabbed.
```tsx
<ResizableHandle withHandle />
```
## Sizes [#sizes]
The value's type decides the unit:
- a **string** without a unit is a percentage: `"30"` equals `"30%"`;
- a **number** is pixels: `minSize={180}` is 180px, not 180%;
- other CSS units work too: `"12rem"`, `"20vw"`.
```tsx
<ResizablePanel defaultSize="25%" maxSize="40%" minSize={180}>
```
Panels without `defaultSize` share the leftover space. Double-click a handle to
reset its panel to `defaultSize`.
## Collapsible [#collapsible]
<Preview name="resizable-collapsible" />
A `collapsible` panel snaps to `collapsedSize` once dragged below `minSize`.
For a toggle button, call `collapse()` or `expand()` on its `panelRef`.
```tsx
<ResizablePanel collapsedSize="8%" collapsible defaultSize="35%" minSize="25%">
```
## Persisting the layout [#persisting-the-layout]
<Preview name="resizable-persist" />
`defaultLayout` takes a map of panel `id` to percentage. `onLayoutChanged`
fires after every finished resize. Wire both to storage, and give each panel a
stable `id`.
```tsx
const storageKey = 'my-layout'
const readLayout = () => {
try {
return localStorage.getItem(storageKey)
} catch {
return null
}
}
export const RememberedLayout = () => {
const stored = React.useSyncExternalStore(
() => () => {},
readLayout,
() => null,
)
return (
<ResizablePanelGroup
defaultLayout={stored ? JSON.parse(stored) : undefined}
onLayoutChanged={(layout, meta) => {
if (!meta.isUserInteraction) return
localStorage.setItem(
storageKey,
JSON.stringify(meta.requestedLayout ?? layout),
)
}}
>
<ResizablePanel defaultSize="40%" id="sidebar">
Sidebar
</ResizablePanel>
<ResizableHandle withHandle />
<ResizablePanel id="content">Content</ResizablePanel>
</ResizablePanelGroup>
)
}
```
The `null` server snapshot keeps SSR happy: the server renders default sizes,
then the browser swaps in the saved ones. Save `meta.requestedLayout` when it
exists. It's what the user asked for, before a small screen squeezed it.
## Accessibility [#accessibility]
- Each handle is a focusable `role="separator"` with `aria-valuenow`,
`aria-valuemin`, `aria-valuemax` and `aria-controls`.
- Arrow keys resize by 5% along the group's orientation.
- `Home` and `End` jump to the minimum or maximum size.
- `Enter` collapses or expands a `collapsible` panel.
- `F6` moves to the next handle, `Shift + F6` to the previous one.
- Touch dragging only claims the resize axis, so panels still scroll the other
way.
## Props [#props]
### ResizablePanelGroup [#resizablepanelgroup]
<TypeTable
type={{
orientation: {
description: 'Direction panels are laid out and resized in.',
type: '"horizontal" | "vertical"',
default: '"horizontal"',
},
defaultLayout: {
description: 'Initial layout as panel id → percentage (0-100).',
type: 'Record<string, number>',
},
onLayoutChange: {
description: 'Fires on every change, including each drag move.',
type: '(layout: Layout) => void',
},
onLayoutChanged: {
description: 'Fires once a resize finishes. The place to save a layout.',
type: '(layout: Layout, meta: { isUserInteraction: boolean; requestedLayout?: Layout }) => void',
},
disabled: {
description: 'Turns resizing off for the whole group.',
type: 'boolean',
default: 'false',
},
groupRef: {
description: 'Imperative API: `getLayout()`, `setLayout(layout)`.',
type: 'Ref<GroupImperativeHandle>',
},
id: {
description: 'Unique group id. Falls back to `useId`.',
type: 'string | number',
},
}}
/>
### ResizablePanel [#resizablepanel]
<TypeTable
type={{
id: {
description: 'Unique id inside the group. Required to persist a layout.',
type: 'string | number',
},
defaultSize: {
description: 'Initial size. Strings are percentages, numbers are pixels.',
type: 'string | number',
},
minSize: {
description: 'Smallest allowed size.',
type: 'string | number',
default: '"0%"',
},
maxSize: {
description: 'Largest allowed size.',
type: 'string | number',
default: '"100%"',
},
collapsible: {
description: 'Collapses when dragged below `minSize`.',
type: 'boolean',
default: 'false',
},
collapsedSize: {
description: 'Size when collapsed.',
type: 'string | number',
default: '"0%"',
},
disabled: {
description: 'Cannot be resized, directly or by a neighbour.',
type: 'boolean',
default: 'false',
},
onResize: {
description: 'Fires with the new size on every resize.',
type: '(size: { asPercentage: number; inPixels: number }) => void',
},
panelRef: {
description:
'Imperative API: `collapse()`, `expand()`, `getSize()`, `isCollapsed()`, `resize(size)`.',
type: 'Ref<PanelImperativeHandle>',
},
}}
/>
### ResizableHandle [#resizablehandle]
<TypeTable
type={{
withHandle: {
description: 'Shows a grip in the middle of the divider.',
type: 'boolean',
default: 'false',
},
disabled: {
description: 'This handle cannot resize its panels.',
type: 'boolean',
default: 'false',
},
disableDoubleClick: {
description: 'Stops double-click from resetting to default sizes.',
type: 'boolean',
default: 'false',
},
}}
/>
## API Reference [#api-reference]
[react-resizable-panels](https://react-resizable-panels.vercel.app/)
# Role Format (/docs/ui/role-format)
`RoleFormat` prints a role the way the rest of the site does: its color, its
prefix icon or emoji, and its name in the reader's language. Use it in
profiles, member tables and filters.
## Preview [#preview]
<Preview name="role-format" />
## Usage [#usage]
```ts
import { RoleFormat } from '@vitnode/core/components/role-format'
```
```tsx
<RoleFormat role={role} />
```
`role` has the same shape the roles API returns, so you can pass a role
straight from a response:
```ts
const role = {
color: '#16a34a',
id: 2,
name: [
{ languageCode: 'en', name: 'Moderator' },
{ languageCode: 'pl', name: 'Moderator' },
],
prefix: 'icon:shield',
}
```
## Names per language [#names-per-language]
`RoleFormat` picks the name for the active locale. When a role has no
translation for it, the first name in the list shows instead, and a role
with no names at all shows its id. That way a role added before a new
language still has a readable label.
## Colors and prefixes [#colors-and-prefixes]
A `null` color keeps the surrounding text color. `prefix` takes the same
`icon:<lucide-name>` or `emoji:<emoji>` value as a role's prefix in the
AdminCP. An empty or invalid prefix is skipped.
## Long names [#long-names]
In a narrow table cell or chip, add `truncate` so a long name ends in an
ellipsis instead of pushing the layout wider:
```tsx
<RoleFormat className="truncate" role={role} />
```
## Props [#props]
| Name | Type | Required | Default | Description |
| ----------- | -------------------------------------------------------- | -------- | ------- | ----------------------------------- |
| `role` | `{ id, color, name: { languageCode, name }[], prefix? }` | Yes | - | The role to show |
| `className` | `string` | No | - | Extra classes on the outer `<span>` |
Other `<span>` props, such as `style` or `title`, go to the outer `<span>`.
## See also [#see-also]
- [User Format](/docs/ui/user-format) - a member's name in their role's style.
- [Roles](/docs/ui/roles) - pick one role or many in an Auto Form field.
- [Data Table filters](/docs/ui/data-table/filters) - role filters with `RoleFormat` labels.
# Roles (/docs/ui/roles)
## Preview [#preview]
<Preview name="roles" />
Each role shows a color dot (when it has a color) and its name.
## 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'
import { searchAdminRolesInBrowser } from '@vitnode/core/tanstack/admin/roles'
```
`search` is required. In the AdminCP, use `searchAdminRolesInBrowser`: it
reads the roles list (AdminCP session required) and skips the **guest** role.
<Tabs items={['Single', 'Multiple']}>
<Tab value="Single">
```tsx
const formSchema = z.object({ roleId: z.number() })
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'roleId',
component: props => (
<AutoFormRoles
{...props}
label="Primary role"
placeholder="Select a role"
search={searchAdminRolesInBrowser}
/>
),
},
]}
/>
```
The value is one id. Picking again replaces it.
</Tab>
<Tab value="Multiple">
```tsx
const formSchema = z.object({ roleIds: z.array(z.number()).min(1) })
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'roleIds',
component: props => (
<AutoFormRoles
{...props}
label="Additional roles"
multiple
placeholder="Add a role"
search={searchAdminRolesInBrowser}
/>
),
},
]}
/>
```
The value is an array of ids, shown as removable chips. Picking a chosen role
again removes it.
</Tab>
</Tabs>
## Editing an existing record [#editing-an-existing-record]
Pass the saved roles as `selected`, or the chips show raw ids.
```tsx
<AutoFormRoles {...props} multiple search={search} selected={user.roles} />
```
## Excluding roles [#excluding-roles]
`excludeIds` hides roles another field already owns.
```tsx
<AutoFormRoles
{...props}
excludeIds={[primaryRoleId]}
multiple
search={search}
/>
```
## Names per language [#names-per-language]
The field shows the active locale's name, then the first translation, then
the id.
```ts
import { roleOptionName } from '@vitnode/core/components/form/fields/input-roles'
roleOptionName(role, 'pl')
```
## Props [#props]
| Prop | Type | Default | What it does |
| ------------------- | ------------------------------------------ | ------------------ | -------------------------------------------- |
| `search` | `(value: string) => Promise<RoleOption[]>` | required | Looks up roles |
| `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 already knows |
| `excludeIds` | `number[]` | `[]` | Roles the picker must not offer |
| `disabled` | `boolean` | `false` | Blocks opening the picker and removing chips |
`RoleOption` is `{ id, color, name }`, with `name` as
`{ languageCode, name }[]`.
## See also [#see-also]
- [Role Format](/docs/ui/role-format) - show a role outside a form.
- [User](/docs/ui/user) - the same idea for people.
- [Combobox](/docs/ui/combobox) - when the options are strings, not records.
# Scroll Area (/docs/ui/scroll-area)
## Preview [#preview]
<Preview name="scroll-area" />
## Usage [#usage]
```ts
import { ScrollArea } from '@vitnode/core/components/ui/scroll-area'
```
```tsx
<ScrollArea className="h-72 w-56 rounded-lg border">
<ul className="flex flex-col divide-y p-4">...</ul>
</ScrollArea>
```
Give it a fixed height. Everything taller than that scrolls.
## Behaviour [#behaviour]
- The scrollbar stays hidden until you scroll or hover, then fades out again.
- The top or bottom edge fades whenever there's more to scroll that way.
- The edge fade drops while the viewport has keyboard focus, so the focus ring
is never masked.
- It only renders a vertical scrollbar, and the edge fade is vertical too. For
horizontal rows, use [Scroll Fade](/docs/ui/scroll-fade).
## API Reference [#api-reference]
[Base UI - Scroll Area](https://base-ui.com/react/components/scroll-area#api-reference)
# Scroll Fade (/docs/ui/scroll-fade)
## Preview [#preview]
<Preview name="scroll-fade" />
## Usage [#usage]
Scroll Fade is a Tailwind utility, not a component, so there's nothing to
import. It ships with the `shadcn` package, which VitNode apps already load in
`src/styles.css`:
```css
@import 'shadcn/tailwind.css';
```
Put the class on the element that scrolls:
```tsx
<div className="scroll-fade h-64 overflow-y-auto">...</div>
```
Only edges with hidden content fade. Nothing overflows? Nothing fades, so it's
safe on any list. It uses `mask-image`, so it dissolves the content itself and
works on any background.
| Class | Fades |
| ------------------ | ---------------------------------------- |
| `scroll-fade` | Top and bottom (same as `scroll-fade-y`) |
| `scroll-fade-y` | Top and bottom |
| `scroll-fade-x` | Inline start and end, mirrors in RTL |
| `scroll-fade-t` | Top only |
| `scroll-fade-b` | Bottom only |
| `scroll-fade-s` | Inline start only, mirrors in RTL |
| `scroll-fade-e` | Inline end only, mirrors in RTL |
| `scroll-fade-l` | Left only, ignores reading direction |
| `scroll-fade-r` | Right only, ignores reading direction |
| `scroll-fade-none` | Nothing, turns the fade off |
## Vertical [#vertical]
<Preview name="scroll-fade-vertical" />
Keep the card's background and border on a wrapper. Put `scroll-fade` on the
inner scroller, so the list fades and the card doesn't:
```tsx
<section className="bg-card rounded-xl border">
<h3 className="border-b px-4 py-3">Notifications</h3>
<div
aria-label="Notifications"
className="scroll-fade h-64 overflow-y-auto"
role="region"
tabIndex={0}
>
<ul>...</ul>
</div>
</section>
```
## Horizontal [#horizontal]
Use `scroll-fade-x` for rows of chips or cards, as in the preview. Add
`no-scrollbar` (same package) when the scrollbar would only fade along:
```tsx
<div className="scroll-fade-x no-scrollbar overflow-x-auto">
<ul className="flex w-max gap-2">...</ul>
</div>
```
The [Attachment](/docs/ui/attachment) list and the breadcrumb trail use exactly
this.
## One edge only [#one-edge-only]
`scroll-fade-b` suits a chat log that grows downward. `scroll-fade-s` and
`scroll-fade-e` respect RTL in horizontal rows.
```tsx
<div className="scroll-fade-b h-80 overflow-y-auto">...</div>
```
## Fade size [#fade-size]
The default is 12% of the container, capped at `40px`. Use the spacing scale
(`scroll-fade-16`) or any length or percentage:
```tsx
<div className="scroll-fade scroll-fade-[15%] overflow-y-auto" />
```
`scroll-fade-t-*`, `scroll-fade-b-*`, `scroll-fade-s-*` and `scroll-fade-e-*`
size a single edge:
```tsx
<div className="scroll-fade scroll-fade-t-2 scroll-fade-b-8 overflow-y-auto" />
```
The fade eases in over `96px` of scrolling. Change that with
`--scroll-fade-reveal`:
```tsx
<div className="scroll-fade overflow-y-auto [--scroll-fade-reveal:48px]" />
```
## Turning it off [#turning-it-off]
`scroll-fade-none` removes the mask, handy with a breakpoint or state variant:
```tsx
<div className="scroll-fade-x md:scroll-fade-none overflow-x-auto" />
```
## Browser support [#browser-support]
The scroll awareness uses CSS scroll-driven animations
(`animation-timeline: scroll()`), with no JavaScript. Browsers without them get
a static fade on every covered edge. Content is never hidden; it just loses the
"you've reached the end" polish.
## Accessibility [#accessibility]
- The fade is visual only. Every item stays in the DOM and reachable.
- A scroller without focusable children needs `tabIndex={0}`, `role="region"`
and an `aria-label`, or keyboards can't scroll it.
- Put `role="region"` on a wrapper `div`, not on the `ul`, so the list keeps its
list semantics.
- The mask clips focus rings on the scroller. Show focus on a parent instead,
for example `has-focus-visible:ring-3`.
- Don't fade so much that the first or last item gets hard to read.
## Reference [#reference]
[shadcn/ui - scroll-fade](https://ui.shadcn.com/docs/utils/scroll-fade)
# Select (/docs/ui/select)
## Preview [#preview]
<Preview name="select" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
Options come from the `z.enum`. `labels` names them; a value without a label
shows as is.
```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormSelect } from '@vitnode/core/components/form/fields/select'
const formSchema = z.object({
visibility: z.enum(['public', 'members', 'staff']).default('public'),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'visibility',
component: (props) => (
<AutoFormSelect
{...props}
label="Visibility"
labels={[
{ value: 'public', label: 'Everyone' },
{ value: 'members', label: 'Signed-in members' },
{ value: 'staff', label: 'Staff only' },
]}
/>
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from '@vitnode/core/components/ui/select'
const items = [
{ label: 'Everyone', value: 'public' },
{ label: 'Staff only', value: 'staff' },
]
;<Select items={items}>
<SelectTrigger>
<SelectValue placeholder="Pick visibility" />
</SelectTrigger>
<SelectContent>
{items.map((item) => (
<SelectItem key={item.value} value={item.value}>
{item.label}
</SelectItem>
))}
</SelectContent>
</Select>
```
Pass `items` to `Select` so `SelectValue` shows the label. Without it you get
the raw `value`.
</Tab>
</Tabs>
## Groups and sizes [#groups-and-sizes]
<Preview name="select-groups" />
`SelectGroup` + `SelectLabel` add headings, `SelectSeparator` draws a line.
`SelectTrigger` takes `size="sm"` for toolbars and filters.
```tsx
<SelectTrigger size="sm">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectLabel>Members</SelectLabel>
<SelectItem value="newest">Newest first</SelectItem>
</SelectGroup>
<SelectSeparator />
</SelectContent>
```
Give a manual select a label, for example with `aria-labelledby` on the
trigger. `AutoFormSelect` does it for you.
## Motion and touch [#motion-and-touch]
- The chevron flips and the list scales in from the trigger. Reduced motion
turns both off.
- On touch screens the trigger's tap area grows to 44px and options get taller.
- Scrolling a long list never drags the page along.
## Props [#props]
<TypeTable
type={{
label: {
description: 'Shown above the select.',
type: 'ReactNode',
},
description: {
description: 'Shown below the select.',
type: 'ReactNode',
},
labels: {
description: 'Readable label for each enum value.',
type: '{ value: string; label: string }[]',
default: '[]',
},
placeholder: {
description: 'Shown while nothing is picked.',
type: 'string',
default: '"Select an option"',
},
}}
/>
`AutoFormSelect` also passes [Base UI Select](https://base-ui.com/react/components/select#api-reference)
root props through, like `disabled` and `onValueChange`.
# Separator (/docs/ui/separator)
## Preview [#preview]
<Preview name="separator" />
## Usage [#usage]
```ts
import { Separator } from '@vitnode/core/components/ui/separator'
```
```tsx
<Separator />
```
## Vertical [#vertical]
`orientation="vertical"` draws a vertical line at the parent's full height, so
give the row a height:
```tsx
<div className="flex h-5 items-center gap-4">
<span>Forum</span>
<Separator orientation="vertical" />
<span>Blog</span>
</div>
```
## Accessibility [#accessibility]
It renders `role="separator"` with the matching `aria-orientation`, so screen
readers know where one group ends.
## API Reference [#api-reference]
[Base UI - Separator](https://base-ui.com/react/components/separator#api-reference)
# Sheet (/docs/ui/sheet)
## Preview [#preview]
<Preview name="sheet" />
## 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">Notifications</Button>} />
<SheetContent>
<SheetHeader>
<SheetTitle>Notifications</SheetTitle>
<SheetDescription>Pick what lands in your inbox.</SheetDescription>
</SheetHeader>
<SheetFooter>
<SheetClose render={<Button variant="outline">Done</Button>} />
</SheetFooter>
</SheetContent>
</Sheet>
```
`SheetHeader` and `SheetFooter` bring their own padding. Give the content
between them `px-4` to line up.
## Side [#side]
<Preview name="sheet-side" />
`side` picks the edge: `right` (default), `left`, `top` or `bottom`. Left and
right sheets take 3/4 of a phone screen and cap at `max-w-sm` from `sm` up.
```tsx
<SheetContent side="left">...</SheetContent>
```
## Forms [#forms]
<Preview name="sheet-form" />
A sheet suits short settings: a handful of fields about one thing. Place the
fields with `layout` in a scrollable body, and end with `AutoFormSheetFooter`.
It shows an "Unsaved changes" note, a Cancel button that closes the sheet, and
a Save button that stays disabled until something changes.
```tsx
import { AutoFormSheetFooter } from '@vitnode/core/components/form/auto-form-sheet-footer'
```
```tsx
const [open, setOpen] = React.useState(false)
<Sheet onOpenChange={setOpen} open={open}>
<SheetContent className="w-full gap-0 data-[side=right]:w-full data-[side=right]:sm:max-w-lg">
<SheetHeader className="border-b pe-14">
<SheetTitle>Welcome message</SheetTitle>
</SheetHeader>
<AutoForm
className="flex min-h-0 flex-1 flex-col gap-0"
fields={fields}
formSchema={formSchema}
layout={(rendered) => (
<>
<div className="flex min-h-0 flex-1 flex-col gap-5 overflow-y-auto px-4 py-5">
{rendered.enabled}
{rendered.welcome}
</div>
<AutoFormSheetFooter submitLabel="Save message" />
</>
)}
onSubmit={async (values) => {
await save(values)
setOpen(false)
}}
/>
</SheetContent>
</Sheet>
```
Control `open` so a successful save can close the sheet. Pass `disabled` to the
footer when the viewer may only read the settings.
### Sheet, dialog or page? [#sheet-dialog-or-page]
Choose the surface by how much there is to edit:
| Settings | Use | Example in VitNode |
| :------- | :-- | :----------------- |
| A handful of fields about one thing | Sheet | AI settings, one AI action |
| Several sections or tabs | [Dialog](/docs/ui/dialog#forms) | A role's settings |
| A full editor with its own preview | A page | Editing an article |
## Sheet or Drawer? [#sheet-or-drawer]
A sheet is a dialog that slides. A [Drawer](/docs/ui/drawer) also follows your
finger and closes with a swipe, which feels better on phones.
## Props [#props]
<TypeTable
type={{
side: {
description: 'Edge the sheet slides in from.',
type: '"top" | "right" | "bottom" | "left"',
default: '"right"',
},
showCloseButton: {
description: 'Shows the × button in the corner.',
type: 'boolean',
default: 'true',
},
}}
/>
Both props live on `SheetContent`. `Sheet` takes `open` and `onOpenChange` like
a [Dialog](/docs/ui/dialog).
## API Reference [#api-reference]
[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)
# Shimmer (/docs/ui/shimmer)
## Preview [#preview]
<Preview name="shimmer" />
## Usage [#usage]
Shimmer is a Tailwind utility, not a component, so there's nothing to import.
It ships with the `shadcn` package, which VitNode apps already load in
`src/styles.css`:
```css
@import 'shadcn/tailwind.css';
```
```tsx
<p className="shimmer text-muted-foreground">Generating response...</p>
```
The highlight comes from `currentColor`, so it works on any text color, and it
brightens on its own in dark mode. One sweep takes two seconds, then loops.
## Variants [#variants]
<Preview name="shimmer-variants" />
| Class | What it does |
| ------------------------- | ---------------------------------------------------------------- |
| `shimmer` | Turns the effect on |
| `shimmer-color-<color>` | Highlight color: theme color, `/opacity` or `[#378ADD]` |
| `shimmer-duration-<ms>` | One sweep in milliseconds (default 2000) |
| `shimmer-spread-<number>` | Band width on the spacing scale, or `[30%]` (default 3ch + 40px) |
| `shimmer-angle-<number>` | Band tilt in degrees (default 20) |
| `shimmer-reverse` | Sweeps against the reading direction |
| `shimmer-once` | Plays a single sweep |
| `shimmer-none` | Turns it off, in any class order |
The sweep follows the reading direction, so it runs right to left in RTL.
## Play once [#play-once]
`shimmer-once` makes a nice "done!" when streaming finishes. Change the
element's `key` to replay it.
```tsx
<p className="shimmer shimmer-once shimmer-duration-1100" key={replays}>
Response generated.
</p>
```
## Turning it off [#turning-it-off]
`shimmer-none` wins regardless of class order, so it works with breakpoints and
state variants:
```tsx
<p className="shimmer md:shimmer-none">Generating response...</p>
```
## With a status line [#with-a-status-line]
Pair it with a `Spinner` and a [Marker](/docs/ui/marker):
```tsx
<Marker role="status">
<MarkerIcon>
<Spinner />
</MarkerIcon>
<MarkerContent className="shimmer">Thinking...</MarkerContent>
</Marker>
```
## Browser support [#browser-support]
Shimmer needs relative color syntax and `color-mix()`, which every current
browser has. Older ones may render the text transparent. To be safe, apply it
only where it works:
```tsx
<p className="supports-[color:oklch(from_white_l_c_h)]:shimmer">
Generating response...
</p>
```
## Accessibility [#accessibility]
- Reduced motion stops the animation automatically, but only for the plain
`shimmer` class. Behind a variant (`group-hover:shimmer`), add
`motion-reduce:shimmer-none` yourself.
- Shimmer is decoration, not a loading signal. Put real text inside
`role="status"`, like "Thinking...".
- Keep it on short status text. A whole sparkling paragraph is more disco than
progress.
## Reference [#reference]
[shadcn/ui - shimmer](https://ui.shadcn.com/docs/utils/shimmer)
# Skeleton (/docs/ui/skeleton)
<Preview name="skeleton" />
## Usage [#usage]
```ts
import { Skeleton } from '@vitnode/core/components/ui/skeleton'
```
```tsx
<Skeleton className="size-12 rounded-full" />
<Skeleton className="h-4 w-full" />
```
Size and shape it with `className`. It's a muted block with rounded corners
and nothing else.
## Match the real layout [#match-the-real-layout]
<Preview name="skeleton-card" />
Build the skeleton from the same parts as the loaded UI, so nothing jumps when
the data arrives.
```tsx
<div aria-busy={isLoading}>{isLoading ? <ThreadSkeleton /> : <Thread />}</div>
```
## Accessibility [#accessibility]
- A skeleton is decoration and ships with `aria-hidden="true"`. Mark the
region that's loading with `aria-busy="true"` instead.
- The pulse only plays when reduced motion is off. Otherwise it holds still.
# Spacing & Layout (/docs/ui/spacing)
Every gap, padding and margin in VitNode comes from one scale. Pick a step,
never a pixel, and layouts line up on their own.
## Spacing scale [#spacing-scale]
<Preview name="spacing-scale" className="*:max-w-full" />
One unit is `0.25rem` (4px), so `p-4` is 16px and `gap-6` is 24px. Stay on the
scale: `p-4`, never `p-[16px]`.
## Gap, not space-\* [#gap-not-space-]
<Preview name="spacing-gap-vs-space" className="*:max-w-full" />
Hit **Add tags** until the rows wrap. `space-x-*` puts margins on children, so
wrapped rows touch and hidden items leave holes. `gap-*` belongs to the parent
and just works.
```tsx
<ul className="flex flex-wrap gap-2">{tags}</ul>
```
Never mix margin or padding with `gap` on the same element. One job, one tool.
## Group by proximity [#group-by-proximity]
<Preview name="spacing-proximity" className="*:max-w-full" />
Distance is meaning. Things that belong together sit closer than things that
don't: `gap-1` for a title and its hint, `gap-2` for a label and its input,
`gap-8` between sections.
## Cards bring their own padding [#cards-bring-their-own-padding]
<Preview name="spacing-card" className="*:max-w-full" />
`Card` sets `--card-spacing` once (24px, or 16px with `size="sm"`) and every
part reuses it. Don't pad the card again, use `CardHeader` and `CardContent`.
## Responsive layout [#responsive-layout]
<Preview name="spacing-responsive" className="*:max-w-full" />
Drag the handle. Container queries (`@container` + `@md:`) react to the box a
component lives in, so the same widget works in a sidebar and a full page.
Page layouts use viewport breakpoints, mobile first: write the phone layout,
then add `sm:`, `md:`, `lg:` on top.
| `sm` | `md` | `lg` | `xl` | `2xl` |
| ------ | ------ | ------ | ------ | ------ |
| 640px | 768px | 1024px | 1280px | 1536px |
`useIsMobile()` flips at `md` (768px), so CSS and JS agree on what a phone is.
## Logical properties for RTL [#logical-properties-for-rtl]
<Preview name="spacing-rtl" className="*:max-w-full" />
Switch to `pl-` / `ml-` and watch the Arabic row break. `ps-`, `pe-`, `ms-`,
`me-`, `start-` and `border-s` follow the reading direction, so one class list
serves both.
```tsx
<div className="flex items-center gap-3 border-s-4 ps-3">
<ChevronRightIcon className="ms-auto rtl:rotate-180" />
</div>
```
## Layout rules [#layout-rules]
- `flex` and `grid` with `gap-*` for layout. No floats, and absolute
positioning only for real overlays.
- Semantic alignment: `items-center`, `justify-between`, `self-end`.
- Mobile first: the base class is the phone, prefixes add space.
- `max-w-prose` (65ch) on long paragraphs, so lines stay easy to follow on a
wide monitor.
## Related [#related]
<Cards>
<Card
title="Typography"
href="/docs/ui/typography"
description="Font stack, type scale and text rules."
/>
<Card
title="Colors"
href="/docs/ui/colors"
description="Semantic color tokens for text and surfaces."
/>
<Card
title="Accessibility"
href="/docs/ui/accessibility"
description="Focus, contrast, touch targets and screen readers."
/>
</Cards>
# Spinner (/docs/ui/spinner)
<Preview name="spinner" />
## Usage [#usage]
```ts
import { Spinner } from '@vitnode/core/components/ui/spinner'
```
```tsx
<Spinner size="lg" className="text-primary" />
```
It takes the text color around it, so a color change is one `text-*` class.
| Size | Pixels | Good for |
| --------- | ------ | --------------------------------- |
| `sm` | 12 | Badges, dense rows |
| `default` | 16 | Buttons, inputs, inline with text |
| `lg` | 24 | Cards and panels |
| `xl` | 40 | A whole page or section |
## In buttons [#in-buttons]
<Preview name="spinner-buttons" />
Prefer `isLoading` on [Button](/docs/ui/button). It swaps the label for a
spinner, disables the button and announces "Loading". Add a `Spinner` by hand
to keep the label visible.
```tsx
<Button disabled>
<Spinner aria-hidden="true" />
Uploading...
</Button>
```
## In badges, inputs and text [#in-badges-inputs-and-text]
<Preview name="spinner-inline" />
```tsx
<InputGroupAddon align="inline-end">
<Spinner aria-label="Searching" />
</InputGroupAddon>
```
## Loading states [#loading-states]
<Preview name="spinner-states" />
Put it in an [Empty](/docs/ui/empty) state, or over a card that's refreshing.
For a Suspense fallback, center an `xl` spinner, like the AdminCP does.
```tsx
<Suspense
fallback={
<div className="flex items-center justify-center">
<Spinner size="xl" />
</div>
}
>
<SlowThing />
</Suspense>
```
Know what's coming? A [Skeleton](/docs/ui/skeleton) of that shape usually feels
faster.
## Accessibility [#accessibility]
- A spinner has `role="status"` and the label "Loading", translated. Pass
`aria-label` for something specific, like "Searching".
- If nearby text already says what's happening, add `aria-hidden="true"` so
screen readers don't hear it twice.
- Mark the loading container with `aria-busy="true"`.
## Props [#props]
<TypeTable
type={{
size: {
description: 'How big the spinner is.',
type: '"sm" | "default" | "lg" | "xl"',
default: '"default"',
},
'aria-label': {
description: 'What is loading. Defaults to "Loading", translated.',
type: 'string',
},
}}
/>
# Switch (/docs/ui/switch)
## Preview [#preview]
<Preview name="switch" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormSwitch } from '@vitnode/core/components/form/fields/switch'
import { z } from 'zod'
const formSchema = z.object({
maintenance: z.boolean().default(false),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'maintenance',
component: (props) => (
<AutoFormSwitch {...props} label="Maintenance mode" />
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import { Switch } from '@vitnode/core/components/ui/switch'
```
```tsx
<Switch aria-label="Maintenance mode" checked={on} onCheckedChange={setOn} />
```
</Tab>
</Tabs>
## States [#states]
<Preview name="switch-states" />
- `size="sm"` fits dense lists. The default is `"default"`.
- `disabled` dims it. Add `data-disabled` to the parent [Field](/docs/ui/field)
to dim the label too.
- `aria-invalid` adds a red ring. Point `aria-describedby` at the error.
```tsx
<Field orientation="horizontal">
<FieldLabel htmlFor="compact">Compact thread list</FieldLabel>
<Switch id="compact" size="sm" />
</Field>
```
## Nested fields [#nested-fields]
`AutoFormSwitch` can reveal the settings it controls in the same card. See
[Auto Form - Nested fields](/docs/ui/auto-form#nested-fields).
## Props [#props]
<TypeTable
type={{
size: {
description: 'Track and thumb size.',
type: '"default" | "sm"',
default: '"default"',
},
label: {
description: 'AutoFormSwitch only. Shown next to the switch.',
type: 'ReactNode',
},
labelRight: {
description: "AutoFormSwitch only. Pinned to the label's right edge.",
type: 'ReactNode',
},
description: {
description: 'AutoFormSwitch only. Shown below the label.',
type: 'ReactNode',
},
}}
/>
Every [Base UI Switch](https://base-ui.com/react/components/switch#api-reference)
prop works too.
## API Reference [#api-reference]
[Base UI - Switch](https://base-ui.com/react/components/switch#api-reference)
# Tabs (/docs/ui/tabs)
## Preview [#preview]
<Preview className="items-start" name="tabs" />
## Usage [#usage]
```ts
import {
Tabs,
TabsContent,
TabsList,
TabsPanels,
TabsTrigger,
} from '@vitnode/core/components/ui/tabs'
```
```tsx
<Tabs defaultValue="overview">
<TabsList>
<TabsTrigger value="overview">Overview</TabsTrigger>
<TabsTrigger value="activity">Activity</TabsTrigger>
</TabsList>
<TabsPanels>
<TabsContent value="overview">Overview panel</TabsContent>
<TabsContent value="activity">Activity panel</TabsContent>
</TabsPanels>
</Tabs>
```
## Motion [#motion]
Click around the preview. Three things move, on the same easing:
- **The indicator** slides and resizes to the active tab. `TabsList` renders it
for you.
- **The panels** crossfade and drift in the direction you travelled: pick a tab
to the right and the new panel arrives from the right.
- **The panel area** animates its height, so the page (or dialog) never jumps.
Under reduced motion, nothing slides or resizes. Panels just crossfade.
## TabsPanels is required [#tabspanels-is-required]
`TabsPanels` measures the panels, animates the height and clips the outgoing
panel. Always wrap `TabsContent` in it. Don't add padding: it carries its own,
so focus rings aren't clipped.
## Line variant [#line-variant]
<Preview className="items-start" name="tabs-line" />
An underline instead of a filled pill. Same motion.
```tsx
<TabsList variant="line">
```
## Vertical [#vertical]
<Preview className="items-start" name="tabs-vertical" />
Triggers stack beside the panels. The indicator and panels move up and down.
```tsx
<Tabs defaultValue="general" orientation="vertical">
```
## Keep panels mounted [#keep-panels-mounted]
Inactive panels unmount. In forms, a field on a hidden tab must still submit,
so pass `keepMounted`. [Auto Form](/docs/ui/auto-form) does this for its tabs.
```tsx
<TabsContent keepMounted value="overview">
```
## API Reference [#api-reference]
[Base UI - Tabs](https://base-ui.com/react/components/tabs)
# Textarea (/docs/ui/textarea)
## Preview [#preview]
<Preview name="textarea" />
## Usage [#usage]
<Tabs items={['Auto Form', 'Manual']}>
<Tab value="Auto Form">
```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormTextarea } from '@vitnode/core/components/form/fields/textarea'
import { z } from 'zod'
const formSchema = z.object({
about: z.string().min(10, 'At least 10 characters').max(500).default(''),
})
```
```tsx
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'about',
component: (props) => (
<AutoFormTextarea
{...props}
label="About"
description="Shown on your community's home page."
/>
),
},
]}
/>
```
</Tab>
<Tab value="Manual">
```tsx
import { Textarea } from '@vitnode/core/components/ui/textarea'
```
```tsx
<Textarea aria-label="Reply" placeholder="Keep it kind." />
```
</Tab>
</Tabs>
## States [#states]
<Preview name="textarea-states" />
The textarea grows with its content (`field-sizing: content`), starting at
`min-h-16`. Add `max-h-*` to cap it. Set `aria-invalid` for the error style and `disabled` to dim it.
```tsx
<Textarea aria-invalid aria-describedby="report-error" id="report" />
```
## Character counter [#character-counter]
Pass `InputGroupAddon` children to `AutoFormTextarea` for a footer, like a
live counter. See [Input Group](/docs/ui/input-group#with-autoform).
## Multi-language [#multi-language]
`multiLang` works here too. A language select appears next to the label. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).
```tsx
<AutoFormTextarea {...props} label="Rules" multiLang />
```
## Props [#props]
`AutoFormTextarea` also accepts every native `<textarea>` prop.
<TypeTable
type={{
label: {
description: 'Shown above the textarea.',
type: 'ReactNode',
},
labelRight: {
description: "Content pinned to the label's right edge.",
type: 'ReactNode',
},
description: {
description: "Shown below. Defaults to the schema's `.describe()`.",
type: 'ReactNode',
},
placeholder: {
description: 'Hint shown while empty.',
type: 'string',
},
multiLang: {
description:
'Collect one value per language as `{ languageCode, value }[]`.',
type: 'boolean',
default: 'false',
},
children: {
description:
'`InputGroupAddon` elements, rendered inside an input group.',
type: 'ReactNode',
},
}}
/>
# Toast (/docs/ui/toast)
## Preview [#preview]
<Preview name="toast" />
## Usage [#usage]
VitNode mounts the toaster for you. Call `toast` from
[Sonner](https://sonner.emilkowal.ski/):
```ts
import { toast } from 'sonner'
toast.success('Post published', {
description: 'Your reply is live in "Login fails after reset".',
})
```
## Variants [#variants]
A variant tints the icon, title and action button. The card stays neutral.
```ts
toast('Thread moved')
toast.info('Maintenance tonight')
toast.success('Post published')
toast.warning('Running low on storage')
toast.error('Could not save the post')
```
- `success`: it worked the way the user hoped.
- `info`: good to know, nothing to worry about.
- `warning`: nothing broke yet, but take a look.
- `error`: it failed. Say what to do next in the `description`.
After a create, edit or delete, always add a `description` saying what changed.
## Actions [#actions]
<Preview name="toast-action" />
`action` adds a button in the variant's colour. `cancel` adds a quieter second
one.
```ts
toast('Thread archived', {
action: { label: 'Undo', onClick: () => restoreThread(id) },
})
```
## Avatars and messages [#avatars-and-messages]
<Preview name="toast-avatar" />
`ToastAvatar` swaps the icon for a picture, for things a person did. Without a
`src`, or while loading, it shows the first letter of `alt`. Any element works
as `icon`.
```tsx
import { ToastAvatar, ToastMessage } from '@vitnode/core/components/ui/sonner'
toast('Ada Lovelace invited you', {
icon: <ToastAvatar alt="Ada Lovelace" src={user.avatarUrl} />,
})
```
For replies, mentions and DMs, render `ToastMessage` with `toast.custom`. It
lays out avatar, sender, time, text and buttons. Give it a longer `duration`:
people need time to read and decide.
```tsx
toast.custom(
(id) => (
<ToastMessage
actions={[
{
label: 'Dismiss',
onClick: () => toast.dismiss(id),
variant: 'outline',
},
{ label: 'Reply', onClick: () => openReply(message) },
]}
avatar={{ alt: 'Alex Johnson', src: user.avatarUrl }}
description="Hey! I've finished the design review."
time="2m ago"
title="Alex Johnson"
/>
),
{ duration: 10000 },
)
```
## Promises [#promises]
<Preview name="toast-promise" />
`toast.promise` spins while the promise runs, then switches to success or error.
```ts
toast.promise(publishArticle(), {
loading: 'Publishing your article...',
success: 'Article published',
error: 'Could not publish the article',
})
```
## Placement and styles [#placement-and-styles]
Toasts live in the **top-right** corner and stretch full width on phones.
`VitNodeRootProviders` in `src/routes/__root.tsx` takes a `toaster` prop to
move them (`top-left`, `top-center`, `bottom-left`, `bottom-center`,
`bottom-right`):
```tsx
<VitNodeRootProviders config={config} toaster={{ position: 'bottom-center' }}>
{children}
</VitNodeRootProviders>
```
Pass `classNames` to restyle one toast. Your classes merge with the defaults:
```ts
toast('Saved', { classNames: { title: 'font-semibold' } })
```
## Accessibility [#accessibility]
- Toasts are announced through a polite live region.
- Hovering pauses the timer. <kbd>Alt</kbd> + <kbd>T</kbd> jumps to the toasts.
- The close button shows on hover and focus, always on touch, with a hit area
up to 44px.
- Every variant has its own icon, so colour is never the only signal.
## Documentation [#documentation]
[Sonner Documentation](https://sonner.emilkowal.ski/)
# Toggle Group (/docs/ui/toggle-group)
## Preview [#preview]
<Preview name="toggle-group" />
## Usage [#usage]
```ts
import {
ToggleGroup,
ToggleGroupItem,
} from '@vitnode/core/components/ui/toggle-group'
```
```tsx
<ToggleGroup aria-label="Text formatting" multiple variant="outline">
<ToggleGroupItem aria-label="Bold" value="bold">
<BoldIcon />
</ToggleGroupItem>
<ToggleGroupItem aria-label="Italic" value="italic">
<ItalicIcon />
</ToggleGroupItem>
</ToggleGroup>
```
`variant` and `size` go on the group, and every item follows.
## Single selection [#single-selection]
<Preview name="toggle-group-single" />
Leave out `multiple` and only one item can be pressed. The pressed background
glides between items, and jumps when the visitor prefers reduced motion.
```tsx
<ToggleGroup defaultValue={['week']} variant="outline">
<ToggleGroupItem value="day">Day</ToggleGroupItem>
<ToggleGroupItem value="week">Week</ToggleGroupItem>
<ToggleGroupItem value="month">Month</ToggleGroupItem>
</ToggleGroup>
```
The value is always an array, even in single mode. Clicking the pressed item
empties it, so ignore empty arrays in `onValueChange` when one option must stay
picked:
```tsx
<ToggleGroup
onValueChange={(next) => {
if (next.length > 0) setValue(next);
}}
value={value}
>
```
## Spacing and orientation [#spacing-and-orientation]
<Preview name="toggle-group-layout" />
`spacing` pulls the items apart on the spacing scale. At `0` (the default) they
share borders. `orientation="vertical"` stacks them.
```tsx
<ToggleGroup spacing={2} variant="outline">...</ToggleGroup>
<ToggleGroup orientation="vertical" variant="outline">...</ToggleGroup>
```
## Accessibility [#accessibility]
- Give the group an `aria-label` and every icon-only item its own.
- Arrow keys move focus between items, and <kbd>Space</kbd> or <kbd>Enter</kbd>
presses one.
## Props [#props]
<TypeTable
type={{
multiple: {
description: 'Allow more than one pressed item.',
type: 'boolean',
default: 'false',
},
value: {
description: 'Controlled pressed values.',
type: 'string[]',
},
defaultValue: {
description: 'Initial pressed values when uncontrolled.',
type: 'string[]',
},
onValueChange: {
description: 'Called with the new pressed values.',
type: '(value: string[], eventDetails) => void',
},
variant: {
description: 'Visual style for every item.',
type: 'default | outline',
default: 'default',
},
size: {
description: 'Size for every item.',
type: 'sm | default | lg',
default: 'default',
},
spacing: {
description: 'Gap between items on the spacing scale. 0 joins them.',
type: 'number',
default: '0',
},
orientation: {
description: 'Lays items out in a row or a column.',
type: 'horizontal | vertical',
default: 'horizontal',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Toggle Group](https://base-ui.com/react/components/toggle-group)
# Toggle (/docs/ui/toggle)
## Preview [#preview]
<Preview name="toggle" />
## Usage [#usage]
```ts
import { Toggle } from '@vitnode/core/components/ui/toggle'
```
```tsx
<Toggle aria-label="Bold">
<BoldIcon />
</Toggle>
```
A toggle is a button with memory. Screen readers hear it as pressed or not
pressed, thanks to `aria-pressed`.
## Controlled [#controlled]
```tsx
<Toggle onPressedChange={setIsWatching} pressed={isWatching}>
Watch thread
</Toggle>
```
Pair `pressed` with `onPressedChange`, or use `defaultPressed` when you don't
need the state.
## Outline [#outline]
<Preview name="toggle-outline" />
The `outline` variant adds a border, so the toggle reads as a control even when
it's off.
```tsx
<Toggle aria-label="Pin topic" variant="outline">
<PinIcon />
</Toggle>
```
## Sizes [#sizes]
<Preview name="toggle-sizes" />
## With text [#with-text]
<Preview name="toggle-text" />
Put `data-icon="inline-start"` (or `inline-end`) on the icon to tighten the
padding on that side.
```tsx
<Toggle variant="outline">
<BookmarkIcon data-icon="inline-start" />
Bookmark
</Toggle>
```
## Disabled [#disabled]
<Preview name="toggle-disabled" />
```tsx
<Toggle disabled>Lock topic</Toggle>
```
## Accessibility [#accessibility]
- Icon-only toggles need an `aria-label`.
- Keep the label the same in both states. "Bold" pressed says it all;
swapping it to "Not bold" confuses screen readers.
- Need several related toggles? Use [Toggle Group](/docs/ui/toggle-group).
## Props [#props]
<TypeTable
type={{
variant: {
description: 'Visual style.',
type: 'default | outline',
default: 'default',
},
size: {
description: 'Height and padding.',
type: 'sm | default | lg',
default: 'default',
},
pressed: {
description: 'Controlled pressed state.',
type: 'boolean',
},
defaultPressed: {
description: 'Initial pressed state when uncontrolled.',
type: 'boolean',
default: 'false',
},
onPressedChange: {
description: 'Called when the pressed state changes.',
type: '(pressed: boolean, eventDetails) => void',
},
disabled: {
description: 'Blocks interaction.',
type: 'boolean',
default: 'false',
},
}}
/>
## API Reference [#api-reference]
[Base UI - Toggle](https://base-ui.com/react/components/toggle)
# Tooltip (/docs/ui/tooltip)
## Preview [#preview]
<Preview name="tooltip" />
## Usage [#usage]
```ts
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from '@vitnode/core/components/ui/tooltip'
```
```tsx
<Tooltip>
<TooltipTrigger
render={
<Button aria-label="Bookmark thread" size="icon" variant="outline">
<BookmarkIcon />
</Button>
}
/>
<TooltipContent>Bookmark thread</TooltipContent>
</Tooltip>
```
A tooltip is a hint, not a label. Icon buttons still need their own
`aria-label`.
## Shorter syntax [#shorter-syntax]
`TooltipWithContent` does the same in one component when you don't need props
on the trigger.
```ts
import { TooltipWithContent } from '@vitnode/core/components/ui/tooltip'
```
```tsx
<TooltipWithContent text="Reply">
<Button aria-label="Reply" size="icon" variant="ghost">
<MessageSquareIcon />
</Button>
</TooltipWithContent>
```
## Delay and warm-up [#delay-and-warm-up]
<Preview name="tooltip-delay" />
Tooltips wait 200ms, so they don't flash as the cursor passes by. Once one is
open, its neighbours open instantly. Hover the left row, then slide along it.
VitNode already mounts a `TooltipProvider` for the whole app. Wrap a section in
another one to change its timing:
```tsx
<TooltipProvider delay={0}>
<Toolbar />
</TooltipProvider>
```
## Side and shortcuts [#side-and-shortcuts]
<Preview name="tooltip-side" />
`TooltipContent` takes `side` (default `top`), `align` and `sideOffset`
(default `8`). Drop a `Kbd` inside to show a shortcut. It restyles itself for
the dark tooltip.
```tsx
<TooltipContent side="right">
Save draft
<KbdGroup>
<Kbd>⌘</Kbd>
<Kbd>S</Kbd>
</KbdGroup>
</TooltipContent>
```
## Group [#group]
<Preview name="tooltip-group" />
In a toolbar, wrap the buttons in `TooltipGroup` and use `TooltipGroupTrigger`.
They share one tooltip that glides from button to button, resizes to fit and
slides the text in from the direction you came.
```ts
import {
TooltipGroup,
TooltipGroupTrigger,
} from '@vitnode/core/components/ui/tooltip'
```
```tsx
<TooltipGroup>
<div aria-label="Formatting" role="toolbar">
<TooltipGroupTrigger
content="Bold"
render={<Button aria-label="Bold" size="icon-sm" variant="ghost" />}
>
<BoldIcon />
</TooltipGroupTrigger>
</div>
</TooltipGroup>
```
`TooltipGroup` takes `side`, `sideOffset` and `align`. A `TooltipWithContent`
without extra props joins the group on its own. With reduced motion on, the
tooltip jumps instead of gliding.
## Props [#props]
<TypeTable
type={{
'TooltipProvider.delay': {
description: 'Wait before opening, in milliseconds.',
type: 'number',
default: '200',
},
'TooltipProvider.timeout': {
description:
'Hover another trigger within this many ms of a close and it skips the delay.',
type: 'number',
default: '400',
},
'TooltipWithContent.text': {
description: 'Tooltip content.',
type: 'ReactNode',
required: true,
},
'TooltipGroupTrigger.content': {
description: 'Tooltip content for this trigger.',
type: 'ReactNode',
required: true,
},
}}
/>
## API Reference [#api-reference]
[Base UI - Tooltip](https://base-ui.com/react/components/tooltip)
# Typography (/docs/ui/typography)
VitNode uses each device's own system font and a type scale that already knows
its letter spacing. Zero font downloads, zero layout shift.
## Font [#font]
<Preview name="typography-specimen" className="*:max-w-full" />
`font-sans` is the system UI stack: San Francisco on Apple devices, Segoe UI on
Windows, Roboto on Android. Swap `--font-sans` in `src/styles.css` for a brand
font. Stick to three weights: `font-normal`, `font-medium`, `font-semibold`.
## Type scale [#type-scale]
<Preview name="typography-scale" className="*:max-w-full" />
Every `text-*` size carries its own tracking: tighter as it grows, a little air
at `text-xs`. Pick the size and you're done. Don't add `tracking-tight` on top.
Sizes are `rem`, so the UI scales with the reader's browser font size.
## Hierarchy [#hierarchy]
<Preview name="typography-hierarchy" className="*:max-w-full" />
A few clear steps beat many similar ones. Weight and color do as much work as
size.
```tsx
<h2 className="text-2xl font-semibold text-balance">Notifications</h2>
<p className="text-muted-foreground text-sm leading-relaxed">
Choose what lands in your inbox.
</p>
```
## Balanced headings [#balanced-headings]
<Preview name="typography-balance" className="*:max-w-full" />
`text-balance` evens out heading lines, so no word is left alone. Use
`text-pretty` on paragraphs.
## Numbers that change [#numbers-that-change]
<Preview name="typography-numbers" className="*:max-w-full" />
`tabular-nums` gives every digit the same width, so counters, prices and table
columns stop jiggling.
```tsx
<span className="tabular-nums">{onlineCount} online</span>
```
## Body text rules [#body-text-rules]
- `leading-relaxed` on paragraphs, never below `text-sm` (14px) for reading.
- `max-w-prose` for long text.
- `text-xs` only for labels, badges and timestamps.
## Related [#related]
<Cards>
<Card
title="Colors"
href="/docs/ui/colors"
description="Semantic color tokens for text and surfaces."
/>
<Card
title="Introduction"
href="/docs/ui"
description="Design principles and every foundation in one place."
/>
</Cards>
# User Format (/docs/ui/user-format)
`UserFormat` prints a member's name the way the rest of the site does. Use it
anywhere a name shows up: article bylines, tables, comments, notifications.
## Preview [#preview]
<Preview name="user-format" />
## Usage [#usage]
```ts
import { UserFormat } from '@vitnode/core/components/user-format'
```
```tsx
<UserFormat format link user={user} />
```
`format` paints the name in the role's color and puts the role's prefix icon or
emoji in front. `link` turns the name into a link to the member's profile at
`/users/<nameCode>`. Without either, you get the plain name.
## Where the user comes from [#where-the-user-comes-from]
`user` only needs a name and a role, so most API responses fit as they are:
```ts
const user = {
name: 'Ada Lovelace',
nameCode: 'ada',
role: { color: '#dc2626', prefix: 'icon:crown' },
}
```
`prefix` takes the same `icon:<lucide-name>` or `emoji:<emoji>` value as a
role's prefix in the AdminCP. A `null` color keeps the surrounding text color.
## Real names [#real-names]
When a member turns on **Show my real name** in their settings, the API adds
their first and last name as `fullName`, and `UserFormat` shows it instead of
the nickname. While the switch is off, `fullName` is `null` and the real name
never reaches the browser, so there is nothing to hide on the client.
```ts
const user = {
fullName: 'Ada Lovelace',
name: 'ada92',
nameCode: 'ada92',
role: { color: '#dc2626', prefix: 'icon:crown' },
}
```
People from the [Content Engine](/docs/content-engine/public-pages) already
carry `fullName`. In your own API route, compute it with `publicFullNameOf` from
`@vitnode/core/lib/user-personal-information`.
## Links [#links]
`link` needs a `nameCode`. Without one, the name renders as plain text.
Leave `link` off when the name sits inside another link or a button, such as a
table row that already opens something. Nested links are invalid HTML and
confuse screen readers.
## Names inside a sentence [#names-inside-a-sentence]
`UserFormat` is an `inline-flex` row, which keeps the icon centered on the
name. Don't override it with `inline`, or the icon drops to the text baseline.
When the name sits in running text, add `align-bottom` so it lines up with the
words around it:
```tsx
<p>
Written by <UserFormat className="align-bottom" format link user={user} />
</p>
```
## Props [#props]
| Name | Type | Required | Default | Description |
| ----------- | ---------------------------------------------------------- | -------- | ------- | ------------------------------------------- |
| `user` | `{ name, fullName?, nameCode?, role: { color, prefix? } }` | Yes | - | The member to show |
| `format` | `boolean` | No | `false` | Adds the role color and prefix |
| `link` | `boolean` | No | `false` | Links to `/users/<nameCode>` when it is set |
| `className` | `string` | No | - | Extra classes on the outer element |
Other `<span>` props go to the outer `<span>`. With `link`, only `className`,
`style` and `title` reach the link.
## See also [#see-also]
- [Role Format](/docs/ui/role-format) - the same look for a role on its own.
- [User](/docs/ui/user) - pick a member in an Auto Form field.
# User (/docs/ui/user)
## Preview [#preview]
<Preview name="user" />
## 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'
import { searchAdminUsersInBrowser } from '@vitnode/core/tanstack/admin/users'
```
```tsx
const formSchema = z.object({ authorId: z.number() })
<AutoForm
formSchema={formSchema}
fields={[
{
id: 'authorId',
component: props => (
<AutoFormUser
{...props}
label="Author"
placeholder="Select an author"
search={searchAdminUsersInBrowser}
/>
),
},
]}
/>
```
The value is the user id, a plain number. `search` is required. In the
AdminCP, `searchAdminUsersInBrowser` reads the AdminCP users list, so it needs
an AdminCP session and returns only what that route allows.
## Editing an existing record [#editing-an-existing-record]
<Preview name="user-selected" />
A picker can't show a name it never fetched. Pass the saved person as
`selected`, or the field opens on the placeholder. `clearable` adds a button
that sets the value to `null`, so pair it with `z.number().nullable()`.
```tsx
<AutoFormUser
{...props}
clearable
label="Reviewer"
search={search}
selected={{ id: post.reviewer.id, name: post.reviewer.name }}
/>
```
`selected` can be partial: just `id` and `name`. Without `avatarColor`, the
field draws a neutral placeholder avatar instead of guessing a color.
## Role colors [#role-colors]
<Preview name="user-roles" />
Add a `role` to each option and the picker draws the name the way the rest of
the site does: in the role's color, with its prefix icon or emoji in front.
Options without a `role` keep a plain name, so you can add it gradually.
```tsx
const moderators: UserOption[] = [
{
avatarColor: '2563eb',
id: 1,
name: 'Ada Lovelace',
nameCode: 'ada',
role: { color: '#dc2626', prefix: 'icon:shield' },
},
]
```
`prefix` takes the same `icon:<lucide-name>` or `emoji:<emoji>` value as a
role's prefix in the AdminCP. In the AdminCP, `searchAdminUsersInBrowser`
already returns each person's primary role, so its pickers show colored names
without extra work.
## Custom search [#custom-search]
`search` can call any endpoint: a plugin's own members, fixtures in a test.
It runs with `""` each time the picker opens, then debounced as the person
types. Results are never cached, so deleted users don't linger.
```tsx
<AutoFormUser
{...props}
label="Reviewer"
search={(value) => searchReviewers(value)}
/>
```
## Props [#props]
| Prop | Type | Default | What it does |
| ------------------- | ------------------------------------------ | ------------------ | -------------------------------------- |
| `search` | `(value: string) => Promise<UserOption[]>` | required | Looks up people |
| `label` | `ReactNode` | - | Field label |
| `description` | `ReactNode` | - | Help text under the control |
| `placeholder` | `string` | `Select an option` | Shown while nobody is chosen |
| `searchPlaceholder` | `string` | `Search...` | Placeholder inside the search box |
| `selected` | `PartialUserOption \| null` | - | The person the field opens on |
| `clearable` | `boolean` | `false` | Adds a button that sets `null` |
| `disabled` | `boolean` | `false` | Blocks opening the picker and clearing |
`UserOption` is `{ id, name, nameCode, avatarColor, role? }`, where `role` is
`{ color: string | null, prefix?: string | null }`. `PartialUserOption` makes
`nameCode` and `avatarColor` optional.
## In the Content Engine [#in-the-content-engine]
A [`field.user()`](/docs/content-engine/fields) renders this field, like
the blog post author picker. Its options come from the content type's own
picker route, so editors can pick an author without browsing the member list.
## See also [#see-also]
- [User Format](/docs/ui/user-format) - show a member's name outside a form.
- [Roles](/docs/ui/roles) - the same idea for roles, single or multiple.
- [Combobox](/docs/ui/combobox) - when the options are strings, not people.
# View transitions (/docs/ui/view-transitions)
VitNode uses the browser's View Transition API in two places. Every navigation
to another page crossfades in 150ms, and the logo glides from the site header
to the docs header. Inside a page, React's
[`<ViewTransition>`](https://react.dev/reference/react/ViewTransition) animates
a component when it appears, leaves or changes.
## Page transitions [#page-transitions]
Click any link in the sidebar: the old page fades out while the new one fades
in. Your router turns this on with `navigationViewTransition`:
```tsx title="src/router.tsx"
import { navigationViewTransition } from '@vitnode/core/tanstack/view-transitions'
import { vitNodeConfig } from './vitnode.config'
const router = createTanStackRouter({
defaultViewTransition: navigationViewTransition(
vitNodeConfig.viewTransitions,
),
// ...
})
```
The router starts the transition only after the next page has loaded, so the
old page never freezes while data is fetched. Changes that only touch the
query string, like paging a table or typing in a filter, skip the animation.
The timing lives in `@vitnode/core/styles/view-transitions.css`, which your
`styles.css` imports:
```css title="src/styles.css"
@import '@vitnode/core/styles/view-transitions.css';
```
## Morph the logo between layouts [#morph-the-logo-between-layouts]
Go to the [home page](/) and click **Docs** in the header. The logo moves and
resizes into the docs header instead of fading. Both logos carry the same
`view-transition-name`, so the browser treats them as one element:
```tsx
import { LOGO_VIEW_TRANSITION_NAME } from '@vitnode/core/tanstack/view-transitions'
;<Link style={{ viewTransitionName: LOGO_VIEW_TRANSITION_NAME }} to="/">
<Logo />
</Link>
```
The site header already does this for the logo you set in
[`vitnode.config.ts`](/docs/dev/configuration#logo). Add the same style to a
logo in your own layout to join in.
<Callout type="warn" title="One name per page">
A `view-transition-name` must be unique among the visible elements on a page.
If two visible elements share a name, the browser skips the whole transition.
Put the name on one wrapper, not on a logo component that a footer renders
too.
</Callout>
## Login and register [#login-and-register]
Click **Sign up** under the login form. The card doesn't blink out and back:
it glides to its new size while the old fields fade out and the new ones fade
in. The card carries the `vitnode-auth-card` name, and
`@vitnode/core/styles/view-transitions.css` styles it with no extra code on
your side. The "Last used" badge on a sign-in button fades in on its own once
the browser knows which method you picked last time.
## Animate a component with ViewTransition [#animate-a-component-with-viewtransition]
<Preview name="view-transition-enter-exit" className="*:max-w-full" />
Wrap the element in `<ViewTransition>` and change state inside
`startTransition`. React animates the element with the class you pass to
`enter` or `exit`:
```tsx
import { startTransition, ViewTransition } from 'react'
{
isOpen && (
<ViewTransition enter="vt-slide-up" exit="vt-slide-down">
<Notification />
</ViewTransition>
)
}
;<Button onClick={() => startTransition(() => setIsOpen((open) => !open))}>
Toggle
</Button>
```
The class becomes a view transition class, so you style it with the
`::view-transition-*` pseudo-elements:
```css
@keyframes vt-slide-in {
from {
opacity: 0;
translate: 0 0.5rem;
scale: 0.97;
}
}
@keyframes vt-slide-out {
to {
opacity: 0;
translate: 0 0.25rem;
scale: 0.98;
}
}
::view-transition-new(.vt-slide-up) {
animation: vt-slide-in 200ms cubic-bezier(0.23, 1, 0.32, 1) both;
}
::view-transition-old(.vt-slide-down) {
animation: vt-slide-out 150ms cubic-bezier(0.4, 0, 1, 1) both;
}
```
The exit is shorter and travels less than the enter: once something is
dismissed, it should get out of the way. A plain `setState` outside
`startTransition` updates instantly, with no animation.
## Shared element transitions [#shared-element-transitions]
<Preview name="view-transition-shared" className="*:max-w-full" />
Give two `<ViewTransition>` boundaries the same `name`. When one unmounts and
the other mounts in the same transition, React morphs the first into the
second:
```tsx
<ViewTransition name={`plugin-${plugin.id}`} share="vt-morph">
<PluginCard plugin={plugin} />
</ViewTransition>
```
Build each name from a stable id, so a list item and its detail view match.
The same uniqueness rule as the logo applies.
The browser stretches both snapshots to the morphing box by default, which
squashes text when the shape changes. Keep them at their natural size and let
the box clip them instead:
```css
::view-transition-group(.vt-morph) {
overflow: clip;
border-radius: var(--radius-xl);
animation-duration: 250ms;
animation-timing-function: cubic-bezier(0.645, 0.045, 0.355, 1);
}
::view-transition-old(.vt-morph),
::view-transition-new(.vt-morph) {
height: 100%;
object-fit: none;
object-position: left top;
}
```
A shared element is already on screen, so it moves with an ease-in-out curve
rather than the ease-out used for things that appear. When the icon or title
sits in a different spot in each view, give it its own `name` too
(`${name}-mark`, `${name}-title`). It then travels on its own path instead of
showing up twice while the boxes crossfade.
## Direction with transition types [#direction-with-transition-types]
<Preview name="view-transition-types" className="*:max-w-full" />
Call `addTransitionType` inside `startTransition` to tag the update, then map
each type to a class. Here **Next** slides in from the right and **Back** from
the left:
```tsx
import { addTransitionType, startTransition, ViewTransition } from 'react'
const go = (direction: 'back' | 'forward') => {
startTransition(() => {
addTransitionType(direction)
setIndex((index) => index + (direction === 'forward' ? 1 : -1))
})
}
;<ViewTransition
default="none"
enter={{
back: 'vt-from-left',
default: 'none',
forward: 'vt-from-right',
}}
exit={{
back: 'vt-to-right',
default: 'none',
forward: 'vt-to-left',
}}
key={index}
>
<Step index={index} />
</ViewTransition>
```
Changing `key` makes React treat each step as a new element, so the old step
exits while the new one enters. Keep the card's border and background outside
the `<ViewTransition>`: snapshots are drawn above the page and ignore
`overflow: hidden`, so only content that stays inside the padding should move.
<Callout title="Why page changes don't use ViewTransition">
TanStack Router renders a route change as a synchronous update, and React
only runs `<ViewTransition>` animations for updates inside `startTransition`.
That is why navigations use the router's `defaultViewTransition` and
`<ViewTransition>` covers changes inside a page.
</Callout>
## Turn view transitions off [#turn-view-transitions-off]
Set `viewTransitions` to `false` in your shared config:
```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
// ...
viewTransitions: false,
})
```
Navigations then swap pages instantly and the logo no longer morphs. The
option is `true` by default. React `<ViewTransition>` boundaries in your own
components still animate, because they don't go through the router.
## Reduced motion [#reduced-motion]
When the system asks for reduced motion, the router skips page transitions and
`view-transitions.css` turns off every view transition animation, including
your own `<ViewTransition>` classes. Browsers without the View Transition API
just swap the content instantly.
## Related [#related]
<Cards>
<Card
title="Motion"
href="/docs/ui/motion"
description="Easing, timing and interruptible transitions."
/>
<Card
title="Configuration"
href="/docs/dev/configuration"
description="Every option in vitnode.config.ts."
/>
<Card
title="Accessibility"
href="/docs/ui/accessibility"
description="Focus, labels, contrast and user preferences."
/>
</Cards>