# Nextly Documentation

> Open-source CMS and visual page builder for Next.js.

Nextly is an open-source CMS and visual page builder for Next.js. Model content, build pages, localize, version and release from your own stack. Define your schema in TypeScript or build it visually in the Schema Builder; both produce the same APIs and the same database schema. Supports PostgreSQL, MySQL and SQLite. MIT licensed.

This file contains the complete Nextly documentation for use by AI coding assistants.
For a lightweight index, see https://nextlyhq.com/llms.txt

---
title: Nextly Documentation
description: Nextly is an open-source CMS and visual page builder for Next.js. Model content, build pages, localize, version and release from your own stack.
url: https://nextlyhq.com/docs
---

Nextly is an open-source content platform for Next.js. Developers define the content model in TypeScript, or build it in the admin with the Visual Schema Builder; either way it is the same data model, the same type-safe API and the same admin interface. Your team then composes pages in the Visual Page Builder, translates them, keeps a version history, and schedules what goes live. It all runs inside your own Next.js app, on your own database.

## Why Nextly?

- **Next.js Native** -- Runs as part of your Next.js app. No separate server, no external API to manage.
- **Code-First + Visual** -- Define collections in TypeScript for version control, or build them visually in the admin panel. Mix both approaches freely.
- **Type-Safe** -- Full TypeScript support with auto-generated types for your content schema.
- **Direct API** -- Query content directly in Server Components with `nextly.find()` and `nextly.findByID()`. No HTTP overhead.
- **Flexible Database** -- PostgreSQL, MySQL, or SQLite via swappable Drizzle adapters.
- **Admin Panel** -- A full-featured admin UI at `/admin` with RBAC, media library, and rich text editing out of the box.

## Quick Links

- [Getting Started](https://nextlyhq.com/docs/getting-started) -- What Nextly is and core concepts
- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Install Nextly in a new or existing Next.js project
- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Build a blog in 5 minutes
- [Configuration](https://nextlyhq.com/docs/configuration) -- Configure collections, singles, fields, and plugins
- [REST API](https://nextlyhq.com/docs/api-reference/rest-api) -- HTTP endpoints, auth, response shapes
- [Direct API](https://nextlyhq.com/docs/api-reference/direct-api) -- Server-side query layer for Server Components

## Get Started

The fastest way to start is with the scaffolding CLI:

**pnpm:**

```bash
pnpm create nextly-app@alpha my-app
```

**npm:**

```bash
npx create-nextly-app@alpha my-app
```

**yarn:**

```bash
yarn create nextly-app@alpha my-app
```

**bun:**

```bash
bun create nextly-app@alpha my-app
```

Or follow the [Quick Start guide](https://nextlyhq.com/docs/getting-started/quick-start) to add Nextly to an existing Next.js project and build a blog in 5 minutes.

## Next Steps

- [Getting Started](https://nextlyhq.com/docs/getting-started) -- Core concepts and prerequisites
- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Install Nextly in your project
- [Configuration](https://nextlyhq.com/docs/configuration) -- Configure collections, singles, fields, and plugins
- [Database](https://nextlyhq.com/docs/database) -- Choose and configure PostgreSQL, MySQL, or SQLite
- [Deployment](https://nextlyhq.com/docs/guides/deployment) -- Deploy to Vercel or self-host on Node.js

---
title: Getting Started
description: Learn what Nextly is, understand its core concepts, and get up and running quickly.
url: https://nextlyhq.com/docs/getting-started
---

Nextly is an open-source content platform that embeds directly into your Next.js application. Instead of running a separate server, Nextly lives alongside your frontend code -- same repo, same deployment, same database.

## Two Ways to Build

Nextly supports two approaches to defining your content model. You can use either one, or mix them in the same project.

### Code-First

Define collections and singles in TypeScript. Your content schema lives in `nextly.config.ts`, is version-controlled, and generates types automatically.

```typescript title="nextly.config.ts"
import { defineConfig, defineCollection, text, richText } from "nextly/config";

const posts = defineCollection({
  slug: "posts",
  labels: { singular: "Post", plural: "Posts" },
  fields: [
    text({ name: "title", required: true }),
    richText({ name: "content" }),
  ],
  // Built-in Draft/Published lifecycle: injects a `status` system column
  // (default 'draft') and adds Save Draft / Publish buttons in the admin.
  status: true,
});

export default defineConfig({
  collections: [posts],
});
```

### Visual Schema Builder

Create and modify collections visually through the admin panel at `/admin`. The Visual Schema Builder lets you add fields with drag-and-drop, configure validation, and set up relationships -- all without writing config code. Collections created this way generate database tables dynamically and are immediately available through the same API. See [Schema Builder](https://nextlyhq.com/docs/schema-builder) for the full walkthrough.

### Same API, Either Way

Regardless of how you create a collection, you query it the same way:

```typescript title="app/blog/page.tsx"
import { nextly } from "nextly";

export default async function BlogPage() {
  const { items: posts } = await nextly.find({
    collection: "posts",
    limit: 10,
  });

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}
```

## Core Concepts

### Collections

Collections are repeatable content types -- like blog posts, products, or team members. Each collection gets its own database table and admin UI for managing entries. See [Collections](https://nextlyhq.com/docs/configuration/collections) for the full reference.

### Singles

Singles store one-of-a-kind content -- site settings, navigation menus, footer content. They work like collections but hold a single document instead of many. See [Singles](https://nextlyhq.com/docs/configuration/singles).

### Fields

Fields define the shape of your content. Nextly ships eighteen field types organised by category:

- **Basic:** [`text`](https://nextlyhq.com/docs/configuration/fields#text), [`textarea`](https://nextlyhq.com/docs/configuration/fields#textarea), [`richText`](https://nextlyhq.com/docs/configuration/fields#rich-text), [`email`](https://nextlyhq.com/docs/configuration/fields#email), [`password`](https://nextlyhq.com/docs/configuration/fields#password), [`code`](https://nextlyhq.com/docs/configuration/fields#code), [`number`](https://nextlyhq.com/docs/configuration/fields#number), [`checkbox`](https://nextlyhq.com/docs/configuration/fields#checkbox), [`date`](https://nextlyhq.com/docs/configuration/fields#date)
- **Selection:** [`select`](https://nextlyhq.com/docs/configuration/fields#select), [`radio`](https://nextlyhq.com/docs/configuration/fields#radio), [`chips`](https://nextlyhq.com/docs/configuration/fields#chips)
- **Media:** [`upload`](https://nextlyhq.com/docs/configuration/fields#upload)
- **Relationship:** [`relationship`](https://nextlyhq.com/docs/configuration/fields#relationship)
- **Layout:** [`repeater`](https://nextlyhq.com/docs/configuration/fields#repeater), [`group`](https://nextlyhq.com/docs/configuration/fields#group)
- **Component:** [`component`](https://nextlyhq.com/docs/configuration/fields#component)
- **Advanced:** [`json`](https://nextlyhq.com/docs/configuration/fields#json)
- **Virtual:** [`join`](https://nextlyhq.com/docs/configuration/fields#join)

See [Fields](https://nextlyhq.com/docs/configuration/fields) for every option per field with examples.

### Field Groups

Field groups are reusable field structures that can be embedded in collections, singles, or other field groups. Define a field group once (like an SEO block or a CTA section), then use it across multiple content types. See [Field Groups](https://nextlyhq.com/docs/configuration/field-groups).

### Admin Panel

Nextly includes a full admin interface at `/admin` with role-based access control, a media library, and rich text editing. The admin panel works with both code-first and Visual Schema Builder content. See [Admin Panel](https://nextlyhq.com/docs/admin) for the full overview.

## Prerequisites

- **Node.js 20** or later
- **Next.js 16+** (App Router required)
- **React 19+**
- **TypeScript 5+**
- A supported database: **PostgreSQL** (recommended for production), **MySQL**, or **SQLite** (local demo only — see the [SQLite caveats](https://nextlyhq.com/docs/database/sqlite))
- Basic familiarity with Next.js and TypeScript

## Next Steps

- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Install Nextly in your project
- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Build a blog in 5 minutes
- [Project Structure](https://nextlyhq.com/docs/getting-started/project-structure) -- Understand how a Nextly project is organised
- [Configuration](https://nextlyhq.com/docs/configuration) -- Full configuration reference for collections, singles, and fields

---
title: Installation
description: Install Nextly in a new or existing Next.js project with step-by-step instructions.
url: https://nextlyhq.com/docs/getting-started/installation
---

There are two ways to install Nextly: scaffold a new project with the CLI, or add Nextly to an existing Next.js app manually. Both paths take a few minutes.

## Option A: Create a New Project (Recommended)

The `create-nextly-app` CLI scaffolds a complete Nextly project with your choice of database and template. Storage defaults to local disk, so you don't need to configure cloud storage to get started.

**pnpm:**

```bash
pnpm create nextly-app@alpha my-app
```

**npm:**

```bash
npx create-nextly-app@alpha my-app
```

**yarn:**

```bash
yarn create nextly-app@alpha my-app
```

**bun:**

```bash
bun create nextly-app@alpha my-app
```

The CLI will prompt you to:

1. **Project name** -- defaults to the directory name. Use `.` to scaffold into the current folder.
2. **Template** -- `Blank` (empty config) or `Blog` (a complete blog with posts, authors, categories, and frontend pages). See [Templates](https://nextlyhq.com/docs/templates) for what each one ships with.
3. **Schema approach** (only for templates that support both) -- `code-first` (default for Blog) or `visual` (Visual Schema Builder).
4. **Database** -- `SQLite` (default), `PostgreSQL`, or `MySQL`.
5. **Database connection string** -- skipped for SQLite (defaults to `file:./data/nextly.db`); required for PostgreSQL/MySQL.

Once the CLI completes, change into the project and start the dev server:

**pnpm:**

```bash
cd my-app
pnpm dev
```

**npm:**

```bash
cd my-app
npm run dev
```

**yarn:**

```bash
cd my-app
yarn dev
```

**bun:**

```bash
cd my-app
bun run dev
```

### Create the super admin

The first time you run the dev server, the database is empty -- there's no admin account yet. Open the setup page to create one:

```
http://localhost:3000/admin/setup
```

Enter an email, password, and name. The first user is bootstrapped with a `Super Admin` role that has every permission. After that, you'll be redirected to the login screen at `/admin`.

### Default storage is local disk

Out of the box, Nextly uses your project's `./public/uploads/` directory as the media store -- no env vars, no cloud account, no credentials. Files you upload through the admin's media library land there and are served by Next.js as static assets. When you're ready to move to S3, Vercel Blob, or Uploadthing, see [Media & Storage](https://nextlyhq.com/docs/guides/media-storage).

## Option B: Add to an Existing Next.js Project

### 1. Install Packages

Install the runtime, admin panel, and database adapter:

**pnpm:**

```bash
pnpm add nextly @nextlyhq/admin
```

**npm:**

```bash
npm install nextly @nextlyhq/admin
```

**yarn:**

```bash
yarn add nextly @nextlyhq/admin
```

**bun:**

```bash
bun add nextly @nextlyhq/admin
```

Then install your database driver:

**PostgreSQL:**

```bash
pnpm add @nextlyhq/adapter-postgres pg
```

**MySQL:**

```bash
pnpm add @nextlyhq/adapter-mysql mysql2
```

**SQLite:**

```bash
pnpm add @nextlyhq/adapter-sqlite better-sqlite3
```

Cloud storage is optional -- Nextly's default is local disk under `./public/uploads/`. Install a storage adapter only if you need one:

**S3 / R2 / DigitalOcean Spaces:**

```bash
pnpm add @nextlyhq/storage-s3
```

**Vercel Blob:**

```bash
pnpm add @nextlyhq/storage-vercel-blob
```

**Uploadthing:**

```bash
pnpm add @nextlyhq/storage-uploadthing
```

### 2. Create `nextly.config.ts`

Create a `nextly.config.ts` file in your project root:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly/config";

export default defineConfig({
  collections: [],
  singles: [],

  typescript: {
    outputFile: "./src/types/generated/nextly-types.ts",
  },
});
```

### 3. Update `next.config.ts`

Add `serverExternalPackages` so Next.js doesn't try to bundle server-only dependencies:

```typescript title="next.config.ts"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: [
    "nextly",
    "@nextlyhq/adapter-drizzle",
    "@nextlyhq/adapter-postgres",
    "@nextlyhq/adapter-mysql",
    "@nextlyhq/adapter-sqlite",
    "drizzle-orm",
    "drizzle-kit",
    "pg",
    "mysql2",
    "better-sqlite3",
    "bcryptjs",
    "sharp",
    "esbuild",
  ],
};

export default nextConfig;
```

Drop adapters and drivers your project doesn't actually use.

### 4. Set Up Admin Routes

Create the admin panel page and layout:

```tsx title="src/app/admin/[[...params]]/page.tsx"
"use client";

import "@nextlyhq/admin/style.css";
import { RootLayout, QueryProvider, ErrorBoundary } from "@nextlyhq/admin";

export default function AdminPage() {
  return (
    <ErrorBoundary
      onError={(error, errorInfo) => {
        console.error("Admin error:", error, errorInfo);
      }}
    >
      <QueryProvider>
        <RootLayout />
      </QueryProvider>
    </ErrorBoundary>
  );
}
```

```tsx title="src/app/admin/[[...params]]/layout.tsx"
import { getBrandingCss } from "nextly/config";

import config from "../../../../nextly.config";

const brandingCss = getBrandingCss(config.admin?.branding);

export default function AdminLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      {brandingCss && (
        <style dangerouslySetInnerHTML={{ __html: brandingCss }} />
      )}
      {children}
    </>
  );
}
```

Create the admin API catch-all route:

```typescript title="src/app/admin/api/[[...params]]/route.ts"
import { getNextly } from "nextly";
import { createDynamicHandlers } from "nextly/runtime";

import nextlyConfig from "../../../../../nextly.config";

const handlers = createDynamicHandlers({ config: nextlyConfig });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PUT = handlers.PUT;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;
```

### 5. Set Up Environment Variables

Create a `.env` file with your database and auth configuration:

```bash title=".env"
# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@localhost:5432/nextly

# Authentication (REQUIRED, min 32 chars)
# Generate with: openssl rand -base64 32
NEXTLY_SECRET=change-me-generate-a-secure-secret

# Application URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

That's the minimum. For storage, email, and other optional settings see [Environment Variables](https://nextlyhq.com/docs/configuration/environment).

### 6. Run Migrations

Initialize the database schema. Nextly seeds default RBAC roles and permissions on first run:

**pnpm:**

```bash
pnpm nextly migrate
```

**npm:**

```bash
npx nextly migrate
```

**yarn:**

```bash
yarn nextly migrate
```

**bun:**

```bash
bunx nextly migrate
```

In development, Nextly auto-syncs schema changes when you save `nextly.config.ts`, so you usually only need `nextly migrate` for initial setup and production deploys. See [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) for the production flow.

### 7. Verify

Start the development server:

**pnpm:**

```bash
pnpm dev
```

**npm:**

```bash
npm run dev
```

**yarn:**

```bash
yarn dev
```

**bun:**

```bash
bun run dev
```

Open [http://localhost:3000/admin/setup](http://localhost:3000/admin/setup) to create the first super admin account, then log in at [http://localhost:3000/admin](http://localhost:3000/admin).

## Requirements

| Requirement | Version |
| --- | --- |
| Node.js | 20 or later |
| Next.js | 16+ (App Router required) |
| React | 19+ |
| TypeScript | 5+ |
| Database | PostgreSQL (recommended for production), MySQL, or SQLite (local demo only) |

## Next Steps

- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Build a blog in 5 minutes
- [Project Structure](https://nextlyhq.com/docs/getting-started/project-structure) -- Understand the file layout
- [Configuration](https://nextlyhq.com/docs/configuration) -- Full configuration reference
- [Environment Variables](https://nextlyhq.com/docs/configuration/environment) -- All environment variables explained

---
title: Quick Start: Build a Blog in 5 Minutes
description: Create a blog with posts and categories using Nextly. Define content with code or build it visually.
url: https://nextlyhq.com/docs/getting-started/quick-start
---

This guide walks you through building a blog with posts and categories. You will define a content model, run migrations, create content in the admin panel, and query it in a Next.js page.

**Prerequisites:** Complete the [Installation](https://nextlyhq.com/docs/getting-started/installation) steps first, including creating the super admin at `/admin/setup`.

## 1. Define Your Collections

**Code-First:**

Open `nextly.config.ts` and define a `posts` collection and a `categories` collection:

```typescript title="nextly.config.ts"
import {
  defineConfig,
  defineCollection,
  text,
  richText,
  relationship,
  date,
} from "nextly/config";

const posts = defineCollection({
  slug: "posts",
  labels: { singular: "Post", plural: "Posts" },
  fields: [
    text({ name: "title", required: true }),
    text({ name: "slug", required: true, unique: true }),
    richText({ name: "content" }),
    relationship({ name: "category", relationTo: "categories" }),
    date({ name: "publishedAt" }),
  ],
  // Built-in Draft/Published lifecycle: injects a NOT NULL `status`
  // system column (default 'draft') and adds Save Draft / Publish
  // buttons in the admin entry editor.
  status: true,
});

const categories = defineCollection({
  slug: "categories",
  labels: { singular: "Category", plural: "Categories" },
  fields: [
    text({ name: "name", required: true }),
    text({ name: "slug", required: true, unique: true }),
  ],
});

export default defineConfig({
  collections: [posts, categories],
  singles: [],

  typescript: {
    outputFile: "./src/types/generated/nextly-types.ts",
  },
});
```

In development, Nextly auto-syncs schema changes when you save `nextly.config.ts`. For production, run:

```bash
pnpm nextly migrate
```

**Visual Schema Builder:**

1. Open the admin panel at [http://localhost:3000/admin](http://localhost:3000/admin)
2. Navigate to **Collections** in the sidebar
3. Click **Create Collection**
4. Name it `Posts` (slug: `posts`)
5. Add fields:
   - `title` -- Text, required
   - `slug` -- Text, required, unique
   - `content` -- Rich Text
   - `publishedAt` -- Date
6. Open the **Advanced** tab on the collection and toggle **Status (Draft / Published)** on. This adds the system status column without you having to declare a `status` field by hand.
7. Click **Save**
8. Repeat to create a `Categories` collection with fields:
   - `name` -- Text, required
   - `slug` -- Text, required, unique

The Visual Schema Builder creates the database tables automatically. No migration step needed in development.

## 2. Add Content

Open the admin panel at [http://localhost:3000/admin](http://localhost:3000/admin).

1. Go to **Categories** and create a few categories (e.g., "Technology", "Design")
2. Go to **Posts** and create a post:
   - Set a title and slug
   - Write some content in the rich text editor
   - Select a category
   - Set status to "Published"
   - Set a publish date

## 3. Query Content in Your App

Use the Direct API to fetch posts in a Server Component. The Direct API runs on the server -- no HTTP requests, no REST endpoints needed.

```typescript title="src/app/blog/page.tsx"
import { nextly } from "nextly";

export default async function BlogPage() {
  const { items: posts } = await nextly.find({
    collection: "posts",
    where: {
      status: { equals: "published" },
    },
    sort: "-publishedAt",
    limit: 10,
  });

  return (
    <div>
      <h1>Blog</h1>
      {posts.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <time>{new Date(post.publishedAt).toLocaleDateString()}</time>
        </article>
      ))}
    </div>
  );
}
```

### Fetch a Single Post

```typescript title="src/app/blog/[slug]/page.tsx"
import { nextly } from "nextly";
import { notFound } from "next/navigation";

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;

  const { items } = await nextly.find({
    collection: "posts",
    where: {
      slug: { equals: slug },
      status: { equals: "published" },
    },
    limit: 1,
  });

  const post = items[0];
  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}
```

## 4. Add a Single

Singles are perfect for site-wide settings. Add a blog settings single to your config:

**Code-First:**

```typescript title="nextly.config.ts"
import { defineSingle, text, number } from "nextly/config";

const blogSettings = defineSingle({
  slug: "blog-settings",
  label: { singular: "Blog Settings" },
  fields: [
    text({ name: "blogTitle", required: true, label: "Blog Title" }),
    text({ name: "tagline", label: "Tagline" }),
    number({ name: "postsPerPage", defaultValue: 10 }),
  ],
});

export default defineConfig({
  collections: [posts, categories],
  singles: [blogSettings],
  // ... rest of config
});
```

In development, save `nextly.config.ts` and the schema syncs automatically. For production, run `pnpm nextly migrate`.

**Visual Schema Builder:**

1. In the admin panel, go to **Singles**
2. Click **Create Single**
3. Name it `Blog Settings` (slug: `blog-settings`)
4. Add fields: `blogTitle` (Text, required), `tagline` (Text), `postsPerPage` (Number, default: 10)
5. Click **Save**

Query the single in your layout:

```typescript title="src/app/blog/layout.tsx"
import { nextly } from "nextly";

export default async function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const settings = await nextly.findSingle({
    slug: "blog-settings",
  });

  return (
    <div>
      <header>
        <h1>{settings?.blogTitle}</h1>
        <p>{settings?.tagline}</p>
      </header>
      {children}
    </div>
  );
}
```

## What You Built

In 5 minutes, you have:

- Two collections (`posts` and `categories`) with typed fields
- A single (`blog-settings`) for site-wide configuration
- An admin panel to manage all content at `/admin`
- Server-rendered pages that query content directly with the Direct API

## Next Steps

- [Project Structure](https://nextlyhq.com/docs/getting-started/project-structure) -- Understand how the project is organised
- [Fields](https://nextlyhq.com/docs/configuration/fields) -- Explore all available field types
- [Direct API](https://nextlyhq.com/docs/api-reference/direct-api) -- Full API reference for querying content
- [Media Storage](https://nextlyhq.com/docs/guides/media-storage) -- Set up image and file uploads

---
title: Project Structure
description: Understand how a Nextly project is organized, where key files live, and what each directory does.
url: https://nextlyhq.com/docs/getting-started/project-structure
---

A Nextly project follows the standard Next.js App Router structure with a few additions: a `nextly.config.ts` at the root, admin routes under `src/app/admin/`, and API routes for the backend. This page explains where everything lives and what each part does.

## Directory Overview

Here is the structure of a project scaffolded with `create-nextly-app` (Blank template, with `src/` directory):

```
my-nextly-app/
├── src/
│   ├── app/
│   │   ├── admin/
│   │   │   ├── [[...params]]/
│   │   │   │   ├── page.tsx          # Admin panel UI (client component)
│   │   │   │   └── layout.tsx        # Admin layout — injects branding CSS
│   │   │   └── api/
│   │   │       └── [[...params]]/
│   │   │           └── route.ts      # Admin API catch-all handler
│   │   ├── api/
│   │   │   ├── health/
│   │   │   │   └── route.ts          # Health check endpoint
│   │   │   ├── media/
│   │   │   │   └── [[...path]]/
│   │   │   │       └── route.ts      # Media upload + serving
│   │   │   ├── media-folders/
│   │   │   │   └── route.ts          # Media folder management
│   │   │   └── [[...params]]/
│   │   │       └── route.ts          # REST API catch-all
│   │   ├── layout.tsx                # Root layout
│   │   ├── page.tsx                  # Home page
│   │   ├── globals.css               # Global styles
│   │   └── favicon.ico
│   └── types/
│       └── generated/
│           └── nextly-types.ts       # Auto-generated TypeScript types
├── public/
│   └── uploads/                      # Default local-disk media storage
├── nextly.config.ts                  # Nextly configuration
├── next.config.ts                    # Next.js configuration
├── eslint.config.mjs
├── postcss.config.mjs
├── tsconfig.json
├── package.json
├── .env                              # Environment variables (gitignored)
└── .env.example                      # Environment template
```

The Blog template adds a few more folders -- `src/collections/`, `src/singles/`, `src/components/`, `src/access/`, `src/actions/`, `src/lib/`, plus a `(frontend)` route group for the public-facing blog pages. See [Templates → Blog](https://nextlyhq.com/docs/templates/blog) for the blog-specific layout.

## Key Files

### `nextly.config.ts`

The central configuration file. This is where you define code-first collections, singles, plugins, storage adapters, email configuration, and admin branding. It lives at the project root.

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly/config";

export default defineConfig({
  collections: [/* your collections */],
  singles: [/* your singles */],
  plugins: [/* your plugins */],

  storage: [/* storage adapters */],
  email: { /* email provider config */ },

  admin: {
    branding: {
      logoText: "My App",
      colors: { primary: "#387c26" },
    },
  },

  typescript: {
    outputFile: "./src/types/generated/nextly-types.ts",
  },
});
```

See [Configuration](https://nextlyhq.com/docs/configuration) for the full reference.

### `next.config.ts`

Standard Next.js configuration. The main Nextly-specific addition is `serverExternalPackages`, which prevents Next.js from bundling server-only dependencies like database drivers:

```typescript title="next.config.ts"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: [
    "nextly",
    "@nextlyhq/adapter-drizzle",
    "@nextlyhq/adapter-postgres",
    "@nextlyhq/adapter-mysql",
    "@nextlyhq/adapter-sqlite",
    "drizzle-orm",
    "drizzle-kit",
    "pg",
    "mysql2",
    "better-sqlite3",
    "bcryptjs",
    "sharp",
    "esbuild",
  ],
};

export default nextConfig;
```

The Blank template ships with all dialect adapters listed; remove the ones you aren't using to keep the dev server tree clean.

### `.env`

Environment variables for database connection and authentication. The CLI generates a complete `.env` with secure defaults; the essentials are:

| Variable | Required | Purpose |
| --- | --- | --- |
| `DB_DIALECT` | Yes | Database type (`postgresql`, `mysql`, `sqlite`) |
| `DATABASE_URL` | Yes (PG/MySQL) | Database connection string. SQLite falls back to `file:./data/nextly.db` |
| `NEXTLY_SECRET` | Yes (production) | Secret for JWT signing and session encryption. Min 32 chars; the CLI auto-generates a base64 value |
| `NEXT_PUBLIC_APP_URL` | Yes (production) | Public URL of your app, used by metadata and the admin |

Storage env vars are only needed when you opt in to a cloud adapter -- the default is local disk under `public/uploads/`. See [Environment Variables](https://nextlyhq.com/docs/configuration/environment) for the full list.

## Key Directories

### `src/app/admin/`

The admin panel lives here as a standard Next.js route. The catch-all `[[...params]]` pattern lets Nextly handle all admin panel routing internally.

- **`page.tsx`** -- Renders the admin panel UI. This is a client component that imports `RootLayout`, `QueryProvider`, and `ErrorBoundary` from `@nextlyhq/admin`.
- **`layout.tsx`** -- Reads `admin.branding` from `nextly.config.ts` and injects the generated CSS so logos and colors apply on every admin page.
- **`api/[[...params]]/route.ts`** -- The admin API. Handles all CRUD operations for collections, singles, users, roles, permissions, and media.

### `src/app/api/`

Public REST API routes. The catch-all `[[...params]]/route.ts` dispatches every endpoint Nextly ships -- collections, singles, auth, image sizes, email -- through one handler that reads your config. Health, media, and media-folders are split into their own routes for clarity. See [REST API](https://nextlyhq.com/docs/api-reference/rest-api) for every endpoint.

### `public/uploads/`

Default media store when no storage adapter is configured in `nextly.config.ts`. Files uploaded through the admin's media library land here and are served directly by Next.js. To switch to S3, Vercel Blob, or Uploadthing, see [Media & Storage](https://nextlyhq.com/docs/guides/media-storage).

### `src/types/generated/`

Auto-generated TypeScript types for your content schema. The output path is configured in `nextly.config.ts` under `typescript.outputFile`. In development the types are regenerated automatically when you save `nextly.config.ts`; in production run:

```bash
pnpm nextly generate:types
```

### Schema files (Visual Schema Builder)

When you create collections through the Visual Schema Builder, Nextly writes the generated TypeScript schema files alongside your project under the directory configured in `nextly.config.ts` -- by default `./src/db/schemas/`. Those files are regular `defineCollection()` exports you can commit to version control. Code-first collections live in `nextly.config.ts` (or wherever you import them from); the two approaches coexist freely.

## Code-First vs Visual Schema Builder: Where Content Is Defined

| Approach | Where collections are defined | Schema location |
| --- | --- | --- |
| **Code-First** | `nextly.config.ts` (or files you import from it) | Generated during `pnpm nextly migrate` (production) or auto-synced on save (dev) |
| **Visual Schema Builder** | Admin panel at `/admin/builder/collections` | TypeScript files written to disk under `./src/db/schemas/` |

Both approaches produce the same result: database tables, admin UI, REST endpoints, and Direct API access. You can mix them -- define some collections in config and create others through the Visual Schema Builder.

## Next Steps

- [Configuration](https://nextlyhq.com/docs/configuration) -- Full `nextly.config.ts` reference
- [Fields](https://nextlyhq.com/docs/configuration/fields) -- All available field types
- [Admin Panel](https://nextlyhq.com/docs/admin) -- Overview of the admin panel features
- [Environment Variables](https://nextlyhq.com/docs/configuration/environment) -- All environment variables explained

---
title: Configuration
description: Configure your Nextly application with collections, singles, field groups, fields, storage, security, and more.
url: https://nextlyhq.com/docs/configuration
---

Nextly is configured through a single `nextly.config.ts` file at the root of your project. That file is the source of truth for your content model, database output paths, storage backends, security settings, email, and admin panel branding.

## The config file

Every Nextly project has a `nextly.config.ts` that exports a config built with `defineConfig()`:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";
import Posts from "./src/collections/posts";
import Media from "./src/collections/media";
import SiteSettings from "./src/singles/site-settings";

export default defineConfig({
  collections: [Posts, Media],
  singles: [SiteSettings],
  db: {
    schemasDir: "./src/db/schemas/collections",
    migrationsDir: "./src/db/migrations",
  },
  typescript: {
    outputFile: "./src/types/generated/payload-types.ts",
  },
});
```

## What you can configure

| Area | Description |
|------|-------------|
| [Nextly config](https://nextlyhq.com/docs/configuration/nextly-config) | Every option in `defineConfig()` with types and defaults |
| [Collections](https://nextlyhq.com/docs/configuration/collections) | Content types with multiple entries (blog posts, products, media) |
| [Singles](https://nextlyhq.com/docs/configuration/singles) | One-off documents (site settings, header, footer) |
| [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) | Reusable field groups embedded in collections and singles |
| [Fields](https://nextlyhq.com/docs/configuration/fields) | Field types, options, validation, and helpers |
| [Environment variables](https://nextlyhq.com/docs/configuration/environment) | Every environment variable Nextly reads |

## Visual Schema Builder vs code-first

Collections, singles, and field groups can also be created visually in the Visual Schema Builder (the "Schema Builder" link inside the admin panel). The Schema Builder writes the same `CollectionConfig`, `SingleConfig`, and `FieldGroupConfig` shapes documented in this section, so anything you build visually maps 1:1 to a `defineCollection`, `defineSingle`, or `defineFieldGroup` call.

## Next steps

- [Nextly config reference](https://nextlyhq.com/docs/configuration/nextly-config) — every top-level option in `defineConfig()`
- [Collections](https://nextlyhq.com/docs/configuration/collections) — content types with multiple entries
- [Singles](https://nextlyhq.com/docs/configuration/singles) — single-document content like site settings
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) — reusable field groups for collections and singles
- [Fields](https://nextlyhq.com/docs/configuration/fields) — every available field type
- [Environment variables](https://nextlyhq.com/docs/configuration/environment) — what to set in `.env`

---
title: Nextly Config Reference
description: Complete reference for every option accepted by defineConfig() in nextly.config.ts.
url: https://nextlyhq.com/docs/configuration/nextly-config
---

The `nextly.config.ts` file is the central configuration for your Nextly application. The `defineConfig()` function validates your config, applies defaults, and returns a sanitized `SanitizedNextlyConfig` consumed by the rest of the runtime.

> **Source of truth:** the `NextlyConfig` interface in `packages/nextly/src/shared/types/config.ts` defines the shape this page documents. The `defineConfig()` helper in `packages/nextly/src/collections/config/define-config.ts` wires it up.

## Full example

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";
import { s3Storage } from "@nextlyhq/storage-s3";
import Posts from "./src/collections/posts";
import Media from "./src/collections/media";
import SiteSettings from "./src/singles/site-settings";
import Header from "./src/singles/header";
import Footer from "./src/singles/footer";
import { Seo, Hero } from "./src/field-groups";

export default defineConfig({
  // Content model
  collections: [Posts, Media],
  singles: [SiteSettings, Header, Footer],
  fieldGroups: [Seo, Hero],

  // Built-in user model extensions
  users: {
    fields: [
      // imported from "nextly"
      // text({ name: "company", label: "Company" }),
    ],
  },

  // Output paths
  typescript: {
    outputFile: "./src/types/generated/payload-types.ts",
    declare: true,
  },
  db: {
    schemasDir: "./src/db/schemas/collections",
    migrationsDir: "./src/db/migrations",
  },

  // Cloud storage (optional — defaults to local disk under ./public/uploads/)
  storage: [
    s3Storage({
      bucket: process.env.S3_BUCKET!,
      region: process.env.AWS_REGION!,
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
      collections: {
        media: true,
      },
    }),
  ],

  // Security
  security: {
    cors: {
      origin: ["https://example.com"],
      credentials: true,
    },
    sanitization: { enabled: true },
  },

  // Rate limiting (enabled by default — opt out with enabled: false)
  rateLimit: {
    enabled: true,
    readLimit: 100,
    writeLimit: 30,
    windowMs: 60_000,
  },

  // Per-API-key rate limit
  apiKeys: {
    rateLimit: { requestsPerHour: 1000, windowMs: 3_600_000 },
  },

  // Auth opt-in flags
  auth: {
    revealRegistrationConflict: false,
  },

  // Email
  email: {
    providerConfig: {
      provider: "resend",
      apiKey: process.env.RESEND_API_KEY!,
    },
    from: "My App <noreply@example.com>",
    baseUrl: "https://example.com",
  },

  // Admin panel branding & plugin overrides
  admin: {
    branding: {
      logoUrl: "/logo.svg",
      logoText: "My App",
      favicon: "/favicon.ico",
      colors: {
        primary: "#6366f1",
        accent: "#f59e0b",
      },
    },
  },
});
```

## Top-level options

| Option | Type | Default | Description |
|---|---|---|---|
| `collections` | `CollectionConfig[]` | `[]` | Content types with multiple entries. See [Collections](https://nextlyhq.com/docs/configuration/collections). |
| `singles` | `SingleConfig[]` | `[]` | Single-document content (site settings, header, etc.). See [Singles](https://nextlyhq.com/docs/configuration/singles). |
| `fieldGroups` | `FieldGroupConfig[]` | `[]` | Reusable field groups. See [Field Groups](https://nextlyhq.com/docs/configuration/field-groups). |
| `users` | `UserConfig` | `undefined` | Extend the built-in user model with custom fields. |
| `typescript` | `TypeScriptConfig` | See below | Generated types path and module augmentation. |
| `db` | `DatabaseConfig` | See below | Where Drizzle schema and migration files are written. |
| `rateLimit` | `RateLimitingConfig` | Enabled (100 read / 30 write per minute) | Global API rate limiting. |
| `apiKeys` | `ApiKeysConfig` | 1000 req/hour, 1-hour window | Per-API-key rate limit (applies when `Authorization: Bearer nx_live_...` is used). |
| `auth` | `AuthConfig` | `{ revealRegistrationConflict: false }` | Auth-related opt-in flags. |
| `storage` | `StoragePlugin[]` | `[]` (local disk used) | Cloud storage plugins. Default storage is local disk under `./public/uploads/`. |
| `plugins` | `PluginDefinition[]` | `[]` | Plugins extending Nextly with collections, hooks, sidebar items, etc. |
| `email` | `EmailConfig` | `undefined` | Email provider for password resets and notifications. |
| `security` | `SecurityConfig` | Secure defaults | CORS, security headers, upload restrictions, sanitization, auth-rate-limit, body-size limits. |
| `admin` | `AdminConfig` | `undefined` | Admin panel branding and plugin sidebar overrides. |

The next sections walk through each option.

---

### `collections`

```ts
collections?: CollectionConfig[];
```

Array of collection configurations created with `defineCollection()`. Each collection becomes a database table, an admin panel section, and a set of REST endpoints under `/api/[slug]`.

```typescript
import Posts from "./src/collections/posts";
import Media from "./src/collections/media";

export default defineConfig({
  collections: [Posts, Media],
});
```

See [Collections](https://nextlyhq.com/docs/configuration/collections) for the full `CollectionConfig` shape.

---

### `singles`

```ts
singles?: SingleConfig[];
```

Array of single-document configurations created with `defineSingle()`. A single is an auto-created, non-deletable document (site settings, header, footer, homepage). Slugs must be unique across collections, singles, and field groups.

```typescript
import SiteSettings from "./src/singles/site-settings";

export default defineConfig({
  singles: [SiteSettings],
});
```

See [Singles](https://nextlyhq.com/docs/configuration/singles) for the full `SingleConfig` shape.

---

### `fieldGroups`

```ts
fieldGroups?: FieldGroupConfig[];
```

Array of reusable field structures created with `defineFieldGroup()`. Field groups are embedded inside collections, singles, or other field groups via the `component` field type. Slugs must be unique across collections, singles, and field groups.

```typescript
import { Seo, Hero } from "./src/field-groups";

export default defineConfig({
  fieldGroups: [Seo, Hero],
});
```

See [Field Groups](https://nextlyhq.com/docs/configuration/field-groups).

---

### `users`

```ts
users?: UserConfig;
```

Extend the built-in user model with custom fields. Custom fields are stored in a separate `user_ext` table with proper typed columns. Only scalar field types are accepted: `text`, `textarea`, `number`, `email`, `select`, `radio`, `checkbox`, `date`.

```typescript
import { text, select, option } from "nextly";

export default defineConfig({
  users: {
    fields: [
      text({ name: "company", label: "Company" }),
      select({
        name: "department",
        options: [option("Engineering"), option("Sales"), option("Marketing")],
      }),
    ],
    admin: {
      // Show these custom columns in the user list
      listFields: ["company", "department"],
      // Override the form-section group label (default: "Additional Information")
      group: "Profile",
    },
  },
});
```

---

### `typescript`

```ts
typescript?: { outputFile?: string; declare?: boolean };
```

Controls TypeScript type generation.

| Property | Type | Default | Description |
|---|---|---|---|
| `outputFile` | `string` | `"./src/types/generated/payload-types.ts"` | Path the generator writes types to. |
| `declare` | `boolean` | `true` | Whether to add `declare module` blocks for runtime type inference. |

---

### `db`

```ts
db?: { schemasDir?: string; migrationsDir?: string };
```

Where Drizzle schema files and migration files are written.

| Property | Type | Default | Description |
|---|---|---|---|
| `schemasDir` | `string` | `"./src/db/schemas/collections"` | Per-collection Drizzle schema files. |
| `migrationsDir` | `string` | `"./src/db/migrations"` | Generated migration files. |

See [Environment variables](https://nextlyhq.com/docs/configuration/environment) for the runtime database connection settings.

---

### `rateLimit`

```ts
rateLimit?: RateLimitingConfig;
```

Global API rate limiting. **Enabled by default** with 100 read / 30 write requests per minute. Opt out with `rateLimit: { enabled: false }`.

| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Toggle rate limiting. |
| `readLimit` | `number` | `100` | Max GET requests per window. |
| `writeLimit` | `number` | `30` | Max POST/PATCH/PUT/DELETE per window. |
| `windowMs` | `number` | `60_000` | Window in milliseconds. |
| `store` | `RateLimitStore` | In-memory | Pluggable store; use a Redis store across multi-instance deployments. |
| `keyGenerator` | `(request: Request) => string` | Client IP | Custom rate-limit key. |
| `skip` | `(request: Request) => boolean \| Promise<boolean>` | None | Skip rate limiting for matching requests. |
| `collections` | `Record<string, { readLimit?: number; writeLimit?: number }>` | None | Per-collection overrides. |

```typescript
rateLimit: {
  enabled: true,
  readLimit: 100,
  writeLimit: 30,
  collections: {
    media: { readLimit: 50, writeLimit: 10 },
    logs: { readLimit: 200 },
  },
}
```

---

### `apiKeys`

```ts
apiKeys?: { rateLimit?: { requestsPerHour?: number; windowMs?: number } };
```

Per-key rate limit applied when a request authenticates with an API key (`Authorization: Bearer nx_live_...`). Session-cookie requests use the global `rateLimit` block instead. Omitting this block falls back to built-in defaults.

| Property | Type | Default | Description |
|---|---|---|---|
| `rateLimit.requestsPerHour` | `number` | `1000` | Maximum requests per sliding window. Must be a positive integer. |
| `rateLimit.windowMs` | `number` | `3_600_000` | Sliding window duration in milliseconds. |

`defineConfig()` throws at startup if either value is non-positive.

---

### `auth`

```ts
auth?: { revealRegistrationConflict?: boolean };
```

Auth-related opt-in flags. Today this block exposes a single flag.

| Property | Type | Default | Description |
|---|---|---|---|
| `revealRegistrationConflict` | `boolean` | `false` | When `false` (default), `/auth/register` returns the same "we've sent a confirmation link" response whether or not the email exists, to prevent account enumeration. Set to `true` only if your threat model genuinely doesn't care about email enumeration (e.g. closed admin tool with controlled signup). |

Authentication is custom: email + password, JWT access/refresh tokens, sessions, API keys, RBAC. There is no OAuth.

---

### `storage`

```ts
storage?: StoragePlugin[];
```

Cloud storage plugins. **The default is local disk** — Nextly writes uploads to `./public/uploads/` if `storage` is empty or omitted.

Available adapters:

- `@nextlyhq/storage-s3` — AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces
- `@nextlyhq/storage-vercel-blob` — Vercel Blob Storage
- `@nextlyhq/storage-uploadthing` — UploadThing

Install whichever adapter you need:

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

**pnpm:**

```bash
pnpm add @nextlyhq/storage-s3
```

**npm:**

```bash
npm install @nextlyhq/storage-s3
```

**yarn:**

```bash
yarn add @nextlyhq/storage-s3
```

**bun:**

```bash
bun add @nextlyhq/storage-s3
```

```typescript
import { s3Storage } from "@nextlyhq/storage-s3";

export default defineConfig({
  storage: [
    s3Storage({
      bucket: process.env.S3_BUCKET!,
      region: process.env.AWS_REGION!,
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
      collections: {
        media: true,
        "private-docs": {
          prefix: "private/",
          signedDownloads: true,
          clientUploads: true,
        },
      },
    }),
  ],
});
```

See [Environment variables — Storage](https://nextlyhq.com/docs/configuration/environment#storage-per-adapter) for adapter-specific env vars.

---

### `plugins`

```ts
plugins?: PluginDefinition[];
```

Plugins extend Nextly with extra collections, hooks, sidebar items, and admin views.

```typescript
import { formBuilder } from "@nextlyhq/plugin-form-builder";

const formBuilderPlugin = formBuilder();

export default defineConfig({
  plugins: [formBuilderPlugin.plugin],
  collections: [Posts],
});
```

---

### `email`

```ts
email?: EmailConfig;
```

Email provider for password resets, email verification, and other transactional emails. The provider configured here is the **code-first fallback**; database-managed providers configured via the admin Settings UI take precedence at runtime.

| Property | Type | Required | Description |
|---|---|---|---|
| `providerConfig` | `SmtpConfig \| ResendConfig \| SendLayerConfig` | Yes | Provider details. |
| `from` | `string` | Yes | Default From address (e.g., `"App <noreply@example.com>"`). |
| `baseUrl` | `string` | No | Used for password reset and verify links; falls back to `NEXT_PUBLIC_APP_URL`. |
| `resetPasswordPath` | `string` | No (default `"/admin/reset-password"`) | Reset-password page path appended to `baseUrl`. |
| `verifyEmailPath` | `string` | No (default `"/admin/verify-email"`) | Email verification page path appended to `baseUrl`. |
| `templates` | `{ welcome?, passwordReset?, emailVerification? }` | No | Override the default HTML templates. |

```typescript
email: {
  providerConfig: {
    provider: "resend",
    apiKey: process.env.RESEND_API_KEY!,
  },
  from: "My App <noreply@example.com>",
  baseUrl: "https://example.com",
}
```

---

### `security`

```ts
security?: SecurityConfig;
```

Security configuration. All sub-sections are optional — secure defaults are applied by middleware.

| Property | Type | Description |
|---|---|---|
| `headers` | `SecurityHeadersConfig` | CSP, X-Content-Type-Options, X-Frame-Options, HSTS, Referrer-Policy, Permissions-Policy. |
| `cors` | `CorsConfig` | Cross-Origin Resource Sharing. Default: same-origin only. |
| `uploads` | `UploadSecurityConfigInput` | MIME-type allowlist and SVG serving behavior. |
| `sanitization` | `SanitizationConfigInput` | HTML stripping for plain-text fields, CSS validation in rich text, URL protocol validation. |
| `limits` | `{ json?, multipart?, fileSize?, fileCount?, fieldCount?, fieldSize? }` | Body and multipart size caps. Defaults: `json` 1mb / `multipart` 50mb / `fileSize` 10mb / `fileCount` 10 / `fieldCount` 50 / `fieldSize` 100kb. Numeric values accept `"1mb"`-style suffixes. |
| `authRateLimit` | `{ requestsPerHour?: number; windowMs?: number }` | Per-IP rate limit shared across `/auth/login`, `/auth/register`, `/auth/forgot-password`, and `/auth/reset-password`. Default: 30 req/hour. Set `requestsPerHour: 0` to disable (test/dev only). |
| `trustProxy` | `boolean` | Trust `X-Forwarded-For` (filtered through the `TRUSTED_PROXY_IPS` env-var CIDR list) for client-IP resolution. Default: `false`. |

```typescript
security: {
  cors: {
    origin: ["https://example.com", "https://app.example.com"],
    credentials: true,
  },
  headers: {
    contentSecurityPolicy: "default-src 'self'",
  },
  uploads: {
    additionalMimeTypes: ["application/xml"],
  },
  sanitization: {
    enabled: true,
    stripHtmlFromText: true,
  },
  limits: {
    multipart: "20mb",
    fileSize: "5mb",
  },
  authRateLimit: {
    requestsPerHour: 30,
  },
  trustProxy: true,
}
```

---

### `admin`

```ts
admin?: AdminConfig;
```

Admin panel branding and per-plugin sidebar overrides.

#### `admin.branding`

| Property | Type | Default | Description |
|---|---|---|---|
| `logoUrl` | `string` | None | Logo image URL (replaces text logo when set). |
| `logoUrlLight` | `string` | None | Light-mode logo URL (used when `logoUrl` is not set). |
| `logoUrlDark` | `string` | None | Dark-mode logo URL (used when `logoUrl` is not set). |
| `logoText` | `string` | `"Nextly"` | Sidebar text label and `alt` text when `logoUrl` is set. |
| `favicon` | `string` | None | Custom favicon URL. |
| `colors.primary` | `string` (6-digit hex) | None | Primary brand color (e.g. `"#6366f1"`). Foreground colors auto-calculated for WCAG AA contrast. |
| `colors.accent` | `string` (6-digit hex) | None | Accent brand color (e.g. `"#f59e0b"`). |
| `showBuilder` | `boolean` | `process.env.NODE_ENV !== "production"` | Show or hide the Visual Schema Builder navigation in the admin. Defaults to visible in dev/test, hidden in production. |

#### `admin.pluginOverrides`

Override any plugin's sidebar placement and appearance without modifying the plugin's source.

```typescript
import { defineConfig, AdminPlacement } from "nextly";

export default defineConfig({
  admin: {
    pluginOverrides: {
      "form-builder": {
        placement: AdminPlacement.SETTINGS, // "collections" | "singles" | "users" | "settings" | "plugins" | "standalone"
        order: 80,
        after: "settings",
        appearance: { icon: "FileText" },
      },
    },
  },
});
```

| Property | Type | Description |
|---|---|---|
| `placement` | `AdminPlacement` | Sidebar section the plugin appears in. Values: `"collections"`, `"singles"`, `"users"`, `"settings"`, `"plugins"`, `"standalone"`. |
| `order` | `number` | Sort order within the section. |
| `after` | `"dashboard" \| "collections" \| "singles" \| "media" \| "plugins" \| "users" \| "settings"` | Position anchor for `STANDALONE` plugins (which built-in section to appear after). |
| `appearance` | `Partial<PluginAdminAppearance>` | Shallow-merged onto the plugin's own appearance (icon, label, etc.). |

---

## Validation

`defineConfig()` performs these checks at startup:

- **Duplicate slugs.** Collection, single, and field group slugs must be unique across all three.
- **Cross-type conflicts.** A single cannot share a slug with a collection or field group.
- **Field group nesting.** Circular field group references and excessive nesting (max depth 3) are rejected.
- **User config.** Only the allowed scalar field types are accepted.
- **API-key bounds.** `apiKeys.rateLimit.requestsPerHour` and `apiKeys.rateLimit.windowMs` must be positive.

Validation failures throw a descriptive error at startup so misconfigurations surface immediately.

## Next steps

- [Collections](https://nextlyhq.com/docs/configuration/collections) — define content types with multiple entries
- [Singles](https://nextlyhq.com/docs/configuration/singles) — define single-document content
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) — reusable field groups
- [Fields](https://nextlyhq.com/docs/configuration/fields) — every available field type
- [Environment variables](https://nextlyhq.com/docs/configuration/environment) — every env var explained

---
title: Collections
description: Define content types with multiple entries using collections.
url: https://nextlyhq.com/docs/configuration/collections
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A collection is a content type that stores multiple entries - blog posts, products, users, media files. Each collection maps to a database table, gets automatic REST endpoints under `/api/[slug]`, and appears in the admin panel with list and edit views.

> **Source of truth:** the `CollectionConfig` interface and `defineCollection()` helper live in `packages/nextly/src/collections/config/define-collection.ts`. Hooks and access-control types are imported from `packages/nextly/src/shared/types/access.ts` and `packages/nextly/src/hooks/types.ts`.

**Code-first:**

## Defining a collection

Use `defineCollection()` from `nextly`:

```typescript title="src/collections/posts.ts"
import {
  defineCollection,
  text,
  richText,
  relationship,
  date,
} from "nextly";

export default defineCollection({
  slug: "posts",
  labels: {
    singular: "Post",
    plural: "Posts",
  },
  fields: [
    text({ name: "title", required: true }),
    text({ name: "slug", unique: true }),
    richText({ name: "content" }),
    relationship({ name: "author", relationTo: "users" }),
    date({ name: "publishedAt" }),
  ],
  // Built-in Draft/Published lifecycle (replaces the user-defined
  // `select({ name: "status" })` pattern). See the dedicated guide:
  // /docs/guides/draft-published-status.
  status: true,
  timestamps: true,
  admin: {
    group: "Content",
    icon: "FileText",
    useAsTitle: "title",
    pagination: { defaultLimit: 25 },
    description: "Blog posts and articles",
  },
  access: {
    read: true,
    create: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
    update: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
    delete: ({ roles }) => roles.includes("admin"),
  },
  hooks: {
    beforeChange: [
      async ({ data, operation }) => {
        if (operation === "create" && data?.title && !data.slug) {
          return {
            ...data,
            slug: data.title.toLowerCase().replace(/\s+/g, "-"),
          };
        }
        return data;
      },
    ],
  },
});
```

Then register it in your config:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";
import Posts from "./src/collections/posts";

export default defineConfig({
  collections: [Posts],
});
```

**Visual Schema Builder:**

## Creating a collection in the Visual Schema Builder

The Nextly admin panel ships with a Visual Schema Builder for creating collections without writing code. (In subsequent prose we'll just call it the Schema Builder.)

1. Open the admin panel and navigate to **Builder > Collections**.
2. Click **Create Collection**.
3. Enter a slug (e.g. `posts`) and display labels.
4. Add fields using the drag-and-drop field editor.
5. Configure admin options, access control, and hooks through the UI.
6. Click **Save** to generate the collection.

The Schema Builder produces the same `CollectionConfig` that code-first collections use; you can export a builder-created collection to TypeScript at any time.

## System fields

Collections have three categories of fields. Knowing which is which avoids redundant declarations and column-shape surprises.

### Always auto-injected (you cannot opt out)

Every collection row has these. Never declare them yourself.

- `id` - primary key, auto-generated
- `createdAt` - set on insert (when `timestamps: true`, the default)
- `updatedAt` - refreshed on every save (when `timestamps: true`)

### Conditionally auto-injected (declared definition wins)

`defineCollection()` adds these as `text NOT NULL` columns *only if you don't declare them yourself*:

- `title`
- `slug`

If your `fields` array includes a field named `title` or `slug`, your definition replaces the auto-inject - same column, your shape. If you don't declare them, Nextly adds bare-bones columns with no validation, no uniqueness, no admin form input.

### Should you redeclare `title` and `slug`?

Almost always **yes**, even though Nextly will inject them anyway. Five reasons:

1. **Uniqueness on `slug`** - the auto-injected `slug` is a plain `text NOT NULL` column with no unique constraint. To require unique slugs (the typical case for URL-routed content), declare your own field with `unique: true`.
2. **Admin form visibility** - Nextly's admin builds the create/edit form from your `fields` array. The auto-injected columns are database-only and don't appear in the form. If you don't declare `title`, the admin shows no title input.
3. **Validation and hooks** - auto-injected columns have no field config. Declared fields can attach `required`, `minLength`, `beforeChange` hooks (e.g. `auto-slug` to derive slug from title), defaults, and so on.
4. **Custom UI** - placeholders, descriptions, field ordering, `admin: { readOnly: true }` all live on the field declaration.
5. **Self-documentation** - a contributor reading the collection file sees the full surface in one place, without having to know Nextly's reserved-column behavior.

You can legitimately skip declaring them when the collection is internal-only (e.g. an `audit-log`) and you don't need form visibility, validation, or unique slugs.

```ts
// Good: declared explicitly so slug can be unique and the admin shows inputs.
import { defineCollection, text, textarea } from "nextly/config";

export const Categories = defineCollection({
  slug: "categories",
  fields: [
    text({ name: "title", required: true }),
    text({ name: "slug", required: true, unique: true }),
    textarea({ name: "description" }),
  ],
});
```

> **Don't mix conventions.** If you declare a field named `name` for the user-facing label and don't declare `title`, the auto-injected `title` column still exists alongside `name` - you'll have a redundant database column you have to populate via API on every create. Pick `title` (matches the auto-inject and is what most callers expect) or be intentional about why you're using `name`.

## Collection options

Only `slug` and `fields` are required.

### `slug`

| | |
|---|---|
| **Type** | `string` |
| **Required** | Yes |

Unique identifier used as the database table name (unless `dbName` is set), the API endpoint path (`/api/[slug]`), and the internal reference. Must be lowercase, URL-friendly, and not a reserved SQL keyword.

### `fields`

| | |
|---|---|
| **Type** | `FieldConfig[]` |
| **Required** | Yes |

Array of field definitions. See [Fields](https://nextlyhq.com/docs/configuration/fields) for the full inventory.

### `labels`

| | |
|---|---|
| **Type** | `{ singular?: string; plural?: string }` |
| **Default** | Auto-generated from slug |

Display names in the admin UI. If omitted, the singular label is derived from the slug (`blog-posts` → `Blog Posts`) and the plural is generated from the singular.

### `timestamps`

| | |
|---|---|
| **Type** | `boolean` |
| **Default** | `true` |

When `true`, every entry gets `createdAt` (set on insert) and `updatedAt` (refreshed on every save) columns.

### `dbName`

| | |
|---|---|
| **Type** | `string` |
| **Default** | Same as `slug` |

Custom database table name. Useful for legacy schemas or when the slug doesn't match your naming convention.

### `description`

| | |
|---|---|
| **Type** | `string` |
| **Default** | `undefined` |

Description displayed in the admin UI. Falls back to `admin.description` when reading from the type.

### `sanitize`

| | |
|---|---|
| **Type** | `boolean` |
| **Default** | `true` |

When enabled, the global sanitization hook strips HTML tags from plain-text fields (`text`, `textarea`, `email`) before storage. Set to `false` only if the collection intentionally stores HTML in those fields.

### `search`

| | |
|---|---|
| **Type** | `SearchConfig` |
| **Default** | Auto-detects `text`/`textarea`/`email` fields |

| Property | Type | Default | Description |
|---|---|---|---|
| `searchableFields` | `string[]` | All `text`/`textarea`/`email` fields | Fields included in search queries. |
| `minSearchLength` | `number` | `2` | Minimum query length before search runs. |

### `indexes`

| | |
|---|---|
| **Type** | `IndexConfig[]` |
| **Default** | `undefined` |

Compound database indexes. For single-field indexes, use `index: true` directly on the field. The `id`, `createdAt`, and `updatedAt` columns are indexed automatically.

```typescript
indexes: [
  { fields: ["authorId", "createdAt"] },
  { fields: ["slug", "locale"], unique: true, name: "slug_locale_unique" },
]
```

### `endpoints`

| | |
|---|---|
| **Type** | `CustomEndpoint[]` |
| **Default** | `undefined` |

Additional REST endpoints mounted at `/api/[slug]/[path]`. Each entry is `{ path, method, handler }` where `handler` is a Web-API `(req: Request) => Response | Promise<Response>` function.

```typescript
endpoints: [
  {
    path: "/publish",
    method: "post",
    handler: async (req) => {
      const { id } = await req.json();
      return Response.json({ success: true });
    },
  },
]
```

### `custom`

| | |
|---|---|
| **Type** | `Record<string, unknown>` |
| **Default** | `undefined` |

Arbitrary metadata for hooks, plugins, or custom code. Not persisted to the database.

## Admin options

Configure how the collection appears in the admin panel via the `admin` property.

| Property | Type | Default | Description |
|---|---|---|---|
| `group` | `string` | None | Sidebar group name; collections sharing a group appear together. |
| `icon` | `string` | None | Lucide icon name (e.g. `"FileText"`, `"Users"`). |
| `hidden` | `boolean` | `false` | Hide from sidebar navigation (still reachable via direct URL and API). |
| `order` | `number` | `100` | Sort order within sidebar group (lower = higher). |
| `sidebarGroup` | `string` | None | Custom sidebar group slug; moves the entry from its default section to a custom group. |
| `isPlugin` | `boolean` | `false` | Render under the "Plugins" sidebar section instead of "Collections". |
| `useAsTitle` | `string` | Document ID | Field name used as the entry title in lists and breadcrumbs. |
| `pagination.defaultLimit` | `number` | `10` | Default entries per page. |
| `pagination.limits` | `number[]` | `[10, 25, 50, 100]` | Available page-size options. |
| `description` | `string` | None | Help text below the collection title. |
| `preview` | `CollectionPreviewConfig` | None | Adds a "Preview" button to the entry form. See below. |
| `components` | `CollectionAdminComponents` | None | Override default views and inject custom React components. See below. |

### Preview URLs

```typescript
admin: {
  preview: {
    url: (entry) => `/preview/posts/${entry.slug}`,
    openInNewTab: true,         // default true
    label: "Preview Post",      // default "Preview"
  },
}
```

The `url` function receives the current entry data (which may include unsaved changes) and returns either a URL string or `null` to hide the button for that entry.

### Custom admin components

Override default admin views or inject components at specific positions. Each entry uses the `"package-name/path#ExportName"` component-path format.

```typescript
admin: {
  components: {
    views: {
      Edit: { Component: "@nextlyhq/plugin-form-builder/admin#FormBuilderView" },
      List: { Component: "@nextlyhq/plugin-form-builder/admin#FormsListView" },
    },
    BeforeListTable: "@nextlyhq/plugin-form-builder/admin#CreateFormButton",
    AfterListTable: "@nextlyhq/plugin-form-builder/admin#FormsFooter",
    BeforeEdit: "@nextlyhq/plugin-form-builder/admin#FormBuilderHeader",
    AfterEdit: "@nextlyhq/plugin-form-builder/admin#FormBuilderFooter",
  },
}
```

Available view overrides: `Edit`, `List`. Available injection points: `BeforeListTable`, `AfterListTable`, `BeforeEdit`, `AfterEdit`.

## Access control

Each CRUD operation accepts a function (returning `boolean | Promise<boolean>`), a literal `boolean`, or can be omitted to fall back to the database role/permission system.

```typescript
access: {
  create: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
  read: true,
  update: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
  delete: ({ roles }) => roles.includes("admin"),
}
```

The `AccessControlContext` passed to functions has the following shape:

| Property | Type | Description |
|---|---|---|
| `user` | `MinimalUser \| null` | The authenticated user (or `null` for unauthenticated requests). |
| `roles` | `string[]` | The user's role slugs (resolved from DB, includes inherited roles). |
| `permissions` | `string[]` | Effective permissions in `"resource:action"` format. |
| `operation` | `"create" \| "read" \| "update" \| "delete"` | The operation being checked. |
| `collection` | `string` | The collection slug. |

**Rules:**

- Code-defined access always takes precedence over database role/permission checks.
- Omitting an operation falls back to the database role/permission system.
- Super-admin always bypasses all access checks.

## Hooks

Hooks let you run custom logic at specific points in a document's lifecycle. Every hook property is an array of handlers - they run in array order and can modify the data flowing through (for `before*` hooks).

### Eight available hooks

| Hook | Triggers on | Can modify |
|---|---|---|
| `beforeOperation` | Before any operation begins. | Yes (operation arguments) |
| `beforeValidate` | Before validation during create/update. | Yes (data) |
| `beforeChange` | After validation passes, before the database write during create/update. | Yes (data) |
| `afterChange` | After the database write during create/update. | No (side effects) |
| `beforeRead` | Before reading from the database. | Yes (query parameters) |
| `afterRead` | After reading from the database. | Yes (transform output) |
| `beforeDelete` | Before deletion. Throw to prevent. | No |
| `afterDelete` | After deletion. | No (side effects) |

### Execution order

1. `beforeOperation`
2. `beforeValidate` (create/update)
3. **Validation** - the schema's declared rules are enforced
4. `beforeChange` (create/update)
5. **Database write or read**
6. `afterChange` (create/update) **or** `afterRead` (reads)
7. `beforeDelete` / `afterDelete` (deletes)

The validation gate is what separates the two write hooks. Use `beforeValidate`
to supply or repair a value you want the rules applied to; use `beforeChange` to
derive the value that gets stored, knowing the document has already passed them.
What a `beforeChange` handler returns is written without being re-validated.

### Hook handler signature

Every handler receives a `HookContext` object:

```typescript
hooks: {
  beforeChange: [
    async ({ data, operation, collection, user, context, req }) => {
      if (operation === "create" && !data.slug) {
        return { ...data, slug: slugify(data.title) };
      }
      return data;
    },
  ],
  afterChange: [
    async ({ data, req }) => {
      // Use req.nextly for the Direct API inside hooks
      await req?.nextly?.create({
        collection: "activity-logs",
        data: { action: "post_updated", postId: data.id },
      });
    },
  ],
}
```

**Return-value behavior:**

- `before*` hooks: return modified data to pass to the next hook (or the DB).
- `after*` hooks: return value is ignored; use these for side effects.
- Throwing aborts the operation and rolls back the transaction.

### When to use which hook

- `beforeOperation` - validate the request, short-circuit before reading args (rate-limit metadata, audit logging entry).
- `beforeValidate` - coerce inputs (trim strings, normalize emails, derive slugs).
- `beforeChange` - final mutations before the row is persisted (hash passwords, stamp metadata).
- `afterChange` - outbound side effects (cache busting, webhooks, queue jobs).
- `beforeRead` - modify query filters (multi-tenant scoping, soft-delete filtering).
- `afterRead` - shape the response (compute virtual fields, redact sensitive properties).
- `beforeDelete` - block deletes when there are dependents.
- `afterDelete` - cascade cleanup (delete files, revoke tokens, audit log).

## Next steps

- [Fields](https://nextlyhq.com/docs/configuration/fields) - every field type and validation option
- [Singles](https://nextlyhq.com/docs/configuration/singles) - single-document content like site settings
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) - reusable field groups for collections and singles
- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) - create collections visually with drag-and-drop
- [Direct API](https://nextlyhq.com/docs/api-reference/direct-api) - query collections from server-side code

---
title: Singles
description: Define single-document content like site settings, headers, and footers.
url: https://nextlyhq.com/docs/configuration/singles
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A single is a one-off document — content that exists as exactly one instance. Site settings, navigation headers, footers, and homepage configurations are typical singles. Unlike [collections](https://nextlyhq.com/docs/configuration/collections), singles have no list view, no create/delete operations, and are auto-created on first access.

> **Source of truth:** the `SingleConfig` interface lives in `packages/nextly/src/singles/config/types.ts`. The `defineSingle()` helper is in `packages/nextly/src/singles/config/define-single.ts`.

**Code-first:**

## Defining a single

Use `defineSingle()` from `nextly`:

```typescript title="src/singles/site-settings.ts"
import {
  defineSingle,
  text,
  upload,
  group,
  repeater,
} from "nextly";

export default defineSingle({
  slug: "site-settings",
  label: { singular: "Site Settings" },
  admin: {
    group: "Settings",
    icon: "Settings",
    description: "Global site configuration",
  },
  fields: [
    text({ name: "siteName", required: true, label: "Site Name" }),
    text({ name: "tagline", label: "Tagline" }),
    upload({ name: "logo", relationTo: "media", label: "Logo" }),
    upload({ name: "favicon", relationTo: "media", label: "Favicon" }),
    group({
      name: "seo",
      label: "SEO Defaults",
      fields: [
        text({ name: "metaTitle", label: "Default Meta Title" }),
        text({ name: "metaDescription", label: "Default Meta Description" }),
      ],
    }),
    repeater({
      name: "socialLinks",
      label: "Social Links",
      fields: [
        text({ name: "platform", required: true }),
        text({ name: "url", required: true }),
      ],
    }),
  ],
  access: {
    read: true,
    update: ({ roles }) => roles.includes("admin"),
  },
  hooks: {
    afterChange: [
      async ({ data }) => {
        await fetch("/api/revalidate?tag=site-settings", { method: "POST" });
      },
    ],
  },
});
```

Then register it in your config:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";
import SiteSettings from "./src/singles/site-settings";
import Header from "./src/singles/header";
import Footer from "./src/singles/footer";

export default defineConfig({
  singles: [SiteSettings, Header, Footer],
});
```

**Visual Schema Builder:**

## Creating a single in the Visual Schema Builder

The Nextly admin panel ships with a Visual Schema Builder for creating singles without writing code. (We'll just call it the Schema Builder below.)

1. Open the admin panel and navigate to **Builder > Singles**.
2. Click **Create Single**.
3. Enter a slug (e.g. `site-settings`) and a display label.
4. Add fields using the drag-and-drop field editor.
5. Configure access control and hooks through the UI.
6. Click **Save**.

The Schema Builder produces the same `SingleConfig` that code-first singles use. Builder-created singles can be exported to TypeScript at any time.

## How singles differ from collections

| | Collections | Singles |
|---|---|---|
| **Entries** | Many | Exactly one |
| **List view** | Yes | No |
| **Create/Delete** | Yes | No (auto-created on first access; cannot be deleted) |
| **Access control operations** | `create`, `read`, `update`, `delete` | `read`, `update` only |
| **Hooks** | 8 hooks | 4 hooks (`beforeRead`, `afterRead`, `beforeChange`, `afterChange`) |
| **Default table prefix** | None — uses slug as table name | `single_` (e.g. `single_site_settings`) |
| **API endpoint** | `/api/[slug]` | `/api/singles/[slug]` |

## Single options

Only `slug` and `fields` are required.

### `slug`

| | |
|---|---|
| **Type** | `string` |
| **Required** | Yes |

Unique identifier across all singles **and** collections **and** field groups. Used as the API endpoint path and database table name (with the `single_` prefix unless `dbName` is set). Must be lowercase and URL-friendly.

### `fields`

| | |
|---|---|
| **Type** | `FieldConfig[]` |
| **Required** | Yes |

Array of field definitions. Singles support the same field types as collections. See [Fields](https://nextlyhq.com/docs/configuration/fields).

### `label`

| | |
|---|---|
| **Type** | `{ singular: string }` |
| **Default** | Auto-generated from slug |

Display label in the admin sidebar, breadcrumbs, and page titles. Singles only need a singular label since there is exactly one document.

### `dbName`

| | |
|---|---|
| **Type** | `string` |
| **Default** | `single_[slug]` (e.g. `single_site_settings`) |

Custom database table name.

### `description`

| | |
|---|---|
| **Type** | `string` |
| **Default** | `undefined` |

Description displayed in the admin UI. Falls back to `admin.description`.

### `sanitize`

| | |
|---|---|
| **Type** | `boolean` |
| **Default** | `true` |

When enabled, the global sanitization hook strips HTML tags from plain-text fields (`text`, `textarea`, `email`) before storage. Set to `false` only if the single intentionally stores HTML in those fields.

### `custom`

| | |
|---|---|
| **Type** | `Record<string, unknown>` |
| **Default** | `undefined` |

Arbitrary metadata for hooks, plugins, or custom code. Not persisted to the database.

## Admin options

Configure how the single appears in the admin panel via the `admin` property.

| Property | Type | Default | Description |
|---|---|---|---|
| `group` | `string` | None | Sidebar group name. |
| `icon` | `string` | None | Lucide icon name (e.g. `"Settings"`, `"Menu"`, `"Home"`). |
| `hidden` | `boolean` | `false` | Hide from sidebar navigation (still reachable via direct URL and API). |
| `order` | `number` | `100` | Sort order within sidebar group (lower = higher). |
| `sidebarGroup` | `string` | None | Custom sidebar group slug; moves the entry from its default section to a custom group. |
| `description` | `string` | None | Help text below the single title. |

> **Singles do not support `useAsTitle`, `pagination`, `preview`, or admin-component overrides** — those concepts are collection-specific.

## Access control

Singles only support `read` and `update` — there is no create or delete since the document is auto-created on first access and cannot be removed.

```typescript
access: {
  read: true,
  update: ({ roles }) => roles.includes("admin"),
}
```

Each operation accepts a function (returning `boolean | Promise<boolean>`), a literal `boolean`, or can be omitted to fall back to database role/permission checks. Code-defined access takes precedence; super-admin always bypasses checks. The `AccessControlContext` shape is the same as for [collections](https://nextlyhq.com/docs/configuration/collections#access-control).

## Hooks

Singles support four lifecycle hooks — a subset of the eight available on collections.

### Five available hooks

| Hook | Triggers on | Can modify |
|---|---|---|
| `beforeRead` | Before reading from the database. | Yes (query parameters) |
| `afterRead` | After reading from the database. | Yes (transform output) |
| `beforeValidate` | Before the schema's rules are enforced on an update. | Yes (data) |
| `beforeChange` | After validation passes, before the database write. | Yes (data) |
| `afterChange` | After the database write. | No (side effects) |

### Execution order — read

1. `beforeRead`
2. **Database read**
3. `afterRead`

### Execution order — update

1. `beforeValidate`
2. **Validation** - the schema's declared rules are enforced
3. `beforeChange`
4. **Database update**
5. `afterChange`

The validation gate is what separates the two write hooks. Use `beforeValidate`
to supply or repair a value you want the rules applied to; use `beforeChange` to
derive the value that gets stored, knowing the document has already passed them.
What a `beforeChange` handler returns is written without being re-validated.

### Example: cache invalidation

```typescript title="src/singles/site-settings.ts"
hooks: {
  afterChange: [
    async ({ data }) => {
      // Invalidate ISR / CDN caches when settings change
      await fetch("/api/revalidate?tag=site-settings", { method: "POST" });
    },
  ],
  afterRead: [
    async ({ data }) => {
      // Add a computed field
      return { ...data, fullTitle: `${data.siteName} - ${data.tagline}` };
    },
  ],
}
```

### When to use which hook

- `beforeRead` — modify query filters (e.g., scope to the current tenant), audit logging.
- `afterRead` — compute virtual properties, redact sensitive fields.
- `beforeValidate` — coerce inputs (trim strings, normalize casing), or supply a value the rules require.
- `beforeChange` — final mutations before the row is persisted, on data already known to be valid.
- `afterChange` — cache busting, webhooks, queue jobs.

Throwing inside any hook aborts the operation and rolls back the transaction.

## Example: header navigation

```typescript title="src/singles/header.ts"
import { defineSingle, repeater, text, relationship } from "nextly";

export default defineSingle({
  slug: "header",
  label: { singular: "Header Navigation" },
  admin: {
    group: "Navigation",
    icon: "Menu",
  },
  fields: [
    repeater({
      name: "navItems",
      label: "Navigation Items",
      fields: [
        text({ name: "label", required: true }),
        text({ name: "url" }),
        relationship({ name: "page", relationTo: "pages" }),
      ],
    }),
  ],
  access: {
    read: true,
    update: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
  },
});
```

## Next steps

- [Collections](https://nextlyhq.com/docs/configuration/collections) — content types with multiple entries
- [Fields](https://nextlyhq.com/docs/configuration/fields) — every field type and validation option
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) — reusable field groups for collections and singles
- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — create singles visually with drag-and-drop

---
title: Field Groups
description: Define reusable field groups that can be shared across collections and singles.
url: https://nextlyhq.com/docs/configuration/field-groups
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Field groups are reusable field structures. Define a set of fields once as a field group, then embed it in any number of collections or singles. Each usage creates a separate data instance — field groups are schemas, not shared documents.

> **Source of truth:** the `FieldGroupConfig` interface lives in `packages/nextly/src/field-groups/config/types.ts`. The `defineFieldGroup()` helper is in `packages/nextly/src/field-groups/config/define-field-group.ts`.

Key characteristics:

- **Templates, not documents.** Field groups define a field structure; each embed creates its own data row.
- **Own database table.** Each field group gets a table derived from its slug and prefixed with `comp_` (e.g. `comp_seo`). The name is always derived; it cannot be overridden.
- **Nesting.** A field group's fields can include `component` fields referencing other field groups (max depth: 3 levels).
- **Slug uniqueness.** Field group slugs must be unique across field groups, collections, **and** singles.
- **Dual creation.** Define in code with `defineFieldGroup()` or visually in the Visual Schema Builder.

**Code-first:**

Use `defineFieldGroup()` from `nextly` to create field groups in TypeScript:

```typescript title="src/field-groups/seo.ts"
import {
  defineFieldGroup,
  text,
  textarea,
  upload,
} from "nextly";

export default defineFieldGroup({
  slug: "seo",
  label: { singular: "SEO Metadata" },
  admin: {
    category: "Shared",
    icon: "Search",
    description: "Search engine optimization metadata",
  },
  fields: [
    text({ name: "metaTitle", required: true, label: "Meta Title" }),
    textarea({
      name: "metaDescription",
      label: "Meta Description",
      maxLength: 160,
    }),
    upload({ name: "ogImage", relationTo: "media", label: "OG Image" }),
    text({ name: "canonicalUrl", label: "Canonical URL" }),
  ],
});
```

**Visual Schema Builder:**

Field groups can also be created visually in the admin UI:

1. Navigate to **Field Groups** in the sidebar.
2. Click **Create Field Group**.
3. Name it and add fields using the drag-and-drop Schema Builder.
4. Save — the field group is immediately available for use.

Builder-created field groups work identically to code-defined ones; both produce the same database schema and API behavior.

## Field group options

Only `slug` and `fields` are required.

| Option | Type | Required | Description |
|---|---|---|---|
| `slug` | `string` | Yes | Unique identifier across field groups, collections, and singles. Used as the DB table prefix (`comp_{slug}`). Must be URL-friendly. |
| `fields` | `FieldConfig[]` | Yes | Array of [field definitions](https://nextlyhq.com/docs/configuration/fields). |
| `label` | `{ singular: string }` | No | Display name in the admin UI. Auto-generated from slug if omitted (e.g. `social-link` → `Social Link`). |
| `admin.category` | `string` | No | Category that groups field groups in the sidebar and selector modal (e.g. `"Shared"`, `"Blocks"`). |
| `admin.icon` | `string` | No | Lucide icon name shown in sidebar and field group selector. |
| `admin.description` | `string` | No | Help text in the field group selector modal. |
| `admin.hidden` | `boolean` | No | Hide from admin navigation. Still usable in code and via API. |
| `admin.imageURL` | `string` | No | Preview image URL shown in the field group selector. |
| `description` | `string` | No | General description; falls back to `admin.description`. |
| `custom` | `Record<string, unknown>` | No | Arbitrary metadata for plugins or custom code. Not persisted. |

> **Field groups do not have hooks or access control of their own.** They inherit hook execution and access checks from the collection or single they're embedded in.

## Using field groups in collections and singles

Once defined, embed a field group in any collection or single using the `fieldGroup()` field helper. There are three usage modes.

### Single field group (fixed type)

Embed exactly one instance of a specific field group:

```typescript title="src/collections/pages.ts"
import { defineCollection, fieldGroup, text, richText } from "nextly";

export default defineCollection({
  slug: "pages",
  fields: [
    text({ name: "title", required: true }),
    richText({ name: "content" }),
    fieldGroup({ name: "seo", component: "seo" }),
  ],
});
```

### Dynamic zone (multiple field group types)

Let editors choose from several field group types, which suits flexible page builders:

```typescript title="src/collections/pages.ts"
import { defineCollection, fieldGroup, text } from "nextly";

export default defineCollection({
  slug: "pages",
  fields: [
    text({ name: "title", required: true }),
    fieldGroup({
      name: "layout",
      components: ["hero", "cta", "content-block", "image-gallery"],
      repeatable: true,
    }),
  ],
});
```

### Repeatable single field group

An array of the same field group, for example a list of feature cards:

```typescript title="src/collections/landing-pages.ts"
import { defineCollection, fieldGroup, text } from "nextly";

export default defineCollection({
  slug: "landing-pages",
  fields: [
    text({ name: "title", required: true }),
    fieldGroup({
      name: "features",
      component: "feature-card",
      repeatable: true,
      minRows: 1,
      maxRows: 12,
    }),
  ],
});
```

The `component` field's full option reference lives in [Fields → Component](https://nextlyhq.com/docs/configuration/fields#component).

## Example: hero section field group

```typescript title="src/field-groups/hero.ts"
import {
  defineFieldGroup,
  text,
  upload,
  select,
  option,
} from "nextly";

export default defineFieldGroup({
  slug: "hero",
  label: { singular: "Hero Section" },
  admin: {
    category: "Blocks",
    icon: "Image",
    description: "Full-width hero banner with heading and CTA",
  },
  fields: [
    text({ name: "heading", required: true, label: "Heading" }),
    text({ name: "subheading", label: "Subheading" }),
    upload({
      name: "backgroundImage",
      relationTo: "media",
      label: "Background Image",
    }),
    text({ name: "ctaText", label: "CTA Button Text" }),
    text({ name: "ctaLink", label: "CTA Button Link" }),
    select({
      name: "alignment",
      label: "Content Alignment",
      options: [option("Left"), option("Center"), option("Right")],
      defaultValue: "center",
    }),
  ],
});
```

## Field group nesting

Field groups can embed other field groups using the `component` field type, up to **3 levels deep**. `defineConfig()` rejects circular references and configurations that exceed the depth limit at startup.

```typescript title="src/field-groups/faq-item.ts"
import { defineFieldGroup, text, fieldGroup } from "nextly";

export default defineFieldGroup({
  slug: "faq-item",
  label: { singular: "FAQ Item" },
  fields: [
    text({ name: "question", required: true }),
    text({ name: "answer", required: true }),
    fieldGroup({ name: "cta", component: "cta" }),
  ],
});
```

## Next steps

- [Fields](https://nextlyhq.com/docs/configuration/fields) — all field types available inside field groups
- [Collections](https://nextlyhq.com/docs/configuration/collections) — where field groups are most commonly used
- [Singles](https://nextlyhq.com/docs/configuration/singles) — embed field groups in single-document content

---
title: Fields
description: Complete reference for every field type, their options, and usage patterns.
url: https://nextlyhq.com/docs/configuration/fields
---

Fields define the shape of your content. Every [collection](https://nextlyhq.com/docs/configuration/collections), [single](https://nextlyhq.com/docs/configuration/singles), and [field group](https://nextlyhq.com/docs/configuration/field-groups) is composed of fields.

Nextly exports field-helper functions from `nextly`. They eliminate the need to set the `type` property manually and give you full TypeScript autocomplete.

```typescript
import { text, number, select, option } from "nextly";

const fields = [
  text({ name: "title", required: true }),
  number({ name: "price", min: 0 }),
  select({
    name: "priority",
    options: [option("Low"), option("Medium"), option("High")],
  }),
];
```

> **Status / Draft-Published is not a `select` field.** If you want a Draft / Published lifecycle on a collection, use the built-in `status: true` flag on `defineCollection` (or the Advanced-tab toggle in the Schema Builder) -- not a hand-rolled `select` field. See [Draft / Published status](https://nextlyhq.com/docs/guides/draft-published-status).

> **Source of truth:** `packages/nextly/src/collections/fields/types/` (one file per field type) and `packages/nextly/src/collections/fields/helpers.ts` (the helper exports).

## Field categories

Eight categories partition the field inventory.

| Category | Fields |
|---|---|
| [Basic](#basic) | `text`, `textarea`, `richText`, `email`, `password`, `code`, `number`, `checkbox`, `date` |
| [Selection](#selection) | `select`, `radio`, `chips` |
| [Media](#media) | `upload` |
| [Relationship](#relationship) | `relationship` |
| [Layout](#layout) | `repeater`, `group` |
| [Component](#component-1) | `component` |
| [Advanced](#advanced) | `json` |
| [Virtual](#virtual) | `join` |

The "Common options across fields" section at the bottom lists the shared properties (name, label, required, admin, access, hooks, validate, custom).

---

## Basic

### text

Single-line text input. Supports `hasMany` mode for storing arrays of strings (tag-style input).

```typescript
text({ name: "title", required: true })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | **Required.** Unique field identifier. Lowercase, no spaces. |
| `minLength` | `number` | — | Minimum string length. |
| `maxLength` | `number` | — | Maximum string length. Also sets the DB column size. |
| `hasMany` | `boolean` | `false` | Accept an array of strings. |
| `minRows` | `number` | — | Min items when `hasMany: true`. |
| `maxRows` | `number` | — | Max items when `hasMany: true`. |
| `defaultValue` | `string \| string[] \| (data) => …` | — | Static default or function. |
| `admin.autoComplete` | `string` | — | HTML `autocomplete` attribute (e.g. `"name"`, `"tel"`). |

```typescript
text({ name: "title", required: true, maxLength: 200 });

// Multiple values (tags)
text({
  name: "tags",
  hasMany: true,
  minRows: 1,
  maxRows: 10,
});
```

**Gotchas:** `maxLength` is the database column width — pick it once and migrate carefully if you change it.

---

### textarea

Multi-line text input.

```typescript
textarea({ name: "description", maxLength: 1000 })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `minLength` | `number` | — | Minimum string length. |
| `maxLength` | `number` | — | Maximum string length. |
| `defaultValue` | `string \| (data) => string` | — | Static default or function. |
| `admin.rows` | `number` | `3` | Number of visible text rows. |
| `admin.resize` | `"vertical" \| "horizontal" \| "both" \| "none"` | `"vertical"` | Resize behavior. |

```typescript
textarea({
  name: "bio",
  admin: { rows: 5, resize: "none" },
});
```

---

### richText

Full-featured WYSIWYG editor powered by Lexical. Content is stored as a Lexical editor-state JSON object.

```typescript
richText({ name: "content" })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `features` | `RichTextFeature[]` | See "Default features" below | Enabled editor features. Pass `[]` for plain text. |
| `defaultValue` | `RichTextValue \| (data) => RichTextValue` | — | Static default or function. |
| `admin.hideToolbar` | `boolean` | `false` | Hide the editor toolbar (keyboard shortcuts still work). |

**Default features** when `features` is omitted: `bold`, `italic`, `underline`, `strikethrough`, `code`, `h1`–`h4`, `orderedList`, `unorderedList`, `indent`, `blockquote`, `link`.

**All available features** (`RichTextFeature` union):

| Category | Features |
|---|---|
| Formatting | `bold`, `italic`, `underline`, `strikethrough`, `code`, `subscript`, `superscript` |
| Text styling | `fontFamily`, `fontSize`, `fontColor`, `bgColor` |
| Headings | `h1`, `h2`, `h3`, `h4`, `h5`, `h6` |
| Lists | `orderedList`, `unorderedList`, `checkList`, `indent` |
| Links and media | `link`, `upload`, `relationship` |
| Advanced | `table`, `horizontalRule`, `codeBlock`, `align` |
| Rich media | `video`, `buttonLink`, `collapsible`, `gallery` |

```typescript
// Simple blog editor
richText({
  name: "content",
  features: ["bold", "italic", "link", "h2", "h3", "orderedList", "unorderedList"],
});

// Full-featured editor
richText({
  name: "body",
  features: [
    "bold", "italic", "underline", "strikethrough", "code",
    "h1", "h2", "h3", "blockquote",
    "orderedList", "unorderedList", "checkList",
    "link", "upload", "table", "codeBlock",
  ],
});
```

**Gotchas:** the value is a JSON object (`{ root: { children: […] } }`) — not an HTML string. Use the REST endpoint's `?richTextFormat=html` query param if you want pre-rendered HTML.

---

### email

Specialised text input with built-in email-format validation.

```typescript
email({ name: "email", required: true, unique: true })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `string \| (data) => string` | — | Static default or function. |
| `admin.autoComplete` | `string` | `"email"` | HTML `autocomplete` attribute. |

Custom `validate` runs **in addition to** the built-in email-format check, so you can layer on domain restrictions without losing format validation.

```typescript
email({
  name: "workEmail",
  validate: (value) =>
    !value || value.endsWith("@company.com")
      ? true
      : "Must be a company email address",
});
```

---

### password

Masked text input for passwords. Values should be hashed before storage using a `beforeChange` hook, and `read` access should return `false` so hashed values don't escape the database.

```typescript
password({
  name: "password",
  required: true,
  minLength: 8,
})
```

| Option | Type | Default | Description |
|---|---|---|---|
| `minLength` | `number` | — | Minimum password length. (Helper-level default is none; documented recommended minimum is 8.) |
| `maxLength` | `number` | — | Maximum password length. Most hashing algorithms cap around 72–128 bytes. |
| `defaultValue` | `string \| (data) => string` | — | Static default. Setting one is rarely a good idea security-wise. |
| `admin.autoComplete` | `"new-password" \| "current-password" \| "off"` | `"new-password"` | HTML `autocomplete` attribute. |
| `admin.showStrengthIndicator` | `boolean` | `false` | Show a visual password-strength meter. |

Full working example:

```typescript
password({
  name: "password",
  required: true,
  minLength: 8,
  access: { read: () => false },
  hooks: {
    beforeChange: [
      async ({ value }) => (value ? await bcrypt.hash(value, 10) : value),
    ],
  },
});
```

**Gotchas:** there is no built-in hashing — the field type stores whatever you give it. Always pair with a hashing hook and a `read: () => false` field-level access rule.

---

### code

Code editor with syntax highlighting. Supports 29 languages.

```typescript
code({
  name: "snippet",
  admin: { language: "javascript" },
})
```

| Option | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `string \| (data) => string` | — | Static default or function. |
| `admin.language` | `CodeLanguage` | `"plaintext"` | Syntax-highlighting language. |
| `admin.editorOptions.lineNumbers` | `boolean` | `true` | Show line numbers. |
| `admin.editorOptions.wordWrap` | `boolean` | `false` | Enable word wrapping. |
| `admin.editorOptions.tabSize` | `number` | `2` | Tab width in spaces. |
| `admin.editorOptions.useTabs` | `boolean` | `false` | Use tabs instead of spaces. |
| `admin.editorOptions.minHeight` | `number` | `200` | Minimum editor height in px. |
| `admin.editorOptions.maxHeight` | `number` | — | Maximum editor height in px. |
| `admin.editorOptions.fontSize` | `number` | `14` | Font size in px. |
| `admin.editorOptions.fontFamily` | `string` | `"monospace"` | Editor font family. |
| `admin.editorOptions.folding` | `boolean` | `true` | Enable code folding. |
| `admin.editorOptions.matchBrackets` | `boolean` | `true` | Highlight matching brackets. |
| `admin.editorOptions.autoCloseBrackets` | `boolean` | `true` | Auto-close brackets and quotes. |

**Supported `CodeLanguage` values:** `javascript`, `typescript`, `jsx`, `tsx`, `html`, `css`, `scss`, `less`, `json`, `markdown`, `yaml`, `xml`, `sql`, `graphql`, `python`, `ruby`, `php`, `java`, `c`, `cpp`, `csharp`, `go`, `rust`, `swift`, `kotlin`, `shell`, `bash`, `powershell`, `dockerfile`, `plaintext`.

```typescript
code({
  name: "snippet",
  admin: {
    language: "javascript",
    editorOptions: { lineNumbers: true, minHeight: 300 },
  },
});
```

---

### number

Numeric input for integers or decimals. Supports `hasMany` mode for arrays of numbers.

```typescript
number({ name: "price", required: true, min: 0, admin: { step: 0.01 } })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `min` | `number` | — | Minimum allowed value. |
| `max` | `number` | — | Maximum allowed value. |
| `hasMany` | `boolean` | `false` | Accept an array of numbers. |
| `minRows` | `number` | — | Min items when `hasMany: true`. |
| `maxRows` | `number` | — | Max items when `hasMany: true`. |
| `defaultValue` | `number \| number[] \| (data) => …` | — | Static default or function. |
| `admin.step` | `number` | `1` | Increment step for spinner buttons. |
| `admin.placeholder` | `string` | — | Placeholder text. |

```typescript
number({ name: "rating", min: 1, max: 5, admin: { step: 1 } });
```

---

### checkbox

Boolean true/false toggle.

```typescript
checkbox({ name: "published", defaultValue: false })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `boolean \| (data) => boolean` | — | Initial value. If `required: true` and unset, defaults to `false`. |

```typescript
checkbox({
  name: "featured",
  label: "Featured Post",
  admin: { position: "sidebar" },
});

// Required terms-acceptance
checkbox({
  name: "termsAccepted",
  required: true,
  validate: (value) =>
    value === true ? true : "You must accept the terms to continue",
});
```

---

### date

Date and/or time picker. Dates are stored in UTC as ISO 8601 strings.

```typescript
date({ name: "publishedAt" })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `string \| Date \| (data) => string \| Date` | — | Static default or function. |
| `admin.date.pickerAppearance` | `"dayOnly" \| "dayAndTime" \| "timeOnly" \| "monthOnly"` | `"dayOnly"` | Picker mode. |
| `admin.date.displayFormat` | `string` | — | Display format string (date-fns format). |
| `admin.date.monthsToShow` | `1 \| 2` | `1` | Months visible in the picker (max 2). |
| `admin.date.minDate` | `Date \| string` | — | Earliest selectable date. |
| `admin.date.maxDate` | `Date \| string` | — | Latest selectable date. |
| `admin.date.minTime` | `Date \| string` | — | Earliest selectable time (when picker includes time). |
| `admin.date.maxTime` | `Date \| string` | — | Latest selectable time. |
| `admin.date.timeIntervals` | `number` | `30` | Time step in minutes. |
| `admin.date.timeFormat` | `string` | `"h:mm aa"` | Time display format. |

```typescript
// Date and time
date({
  name: "eventStart",
  admin: {
    date: { pickerAppearance: "dayAndTime", timeIntervals: 15 },
  },
});

// Time only
date({
  name: "openingTime",
  admin: {
    date: { pickerAppearance: "timeOnly", timeFormat: "HH:mm" },
  },
});

// Month only (e.g., card expiration)
date({
  name: "expirationMonth",
  admin: {
    date: { pickerAppearance: "monthOnly", displayFormat: "MM/yyyy" },
  },
});
```

**Gotchas:** values are stored in UTC; format display in the client when displaying to users.

---

## Selection

### select

Dropdown for choosing from predefined options. Supports single or multi-select with searchable input.

```typescript
import { select, option } from "nextly";

select({
  name: "priority",
  options: [option("Low"), option("Medium"), option("High")],
})
```

> Use `select` for arbitrary categorical options (priority, region, theme, etc.). For a collection's Draft / Published lifecycle, prefer the built-in `status: true` flag on `defineCollection` -- see [Draft / Published status](https://nextlyhq.com/docs/guides/draft-published-status).

| Option | Type | Default | Description |
|---|---|---|---|
| `options` | `SelectOption[]` | — | **Required.** Array of `{ label, value }` objects. |
| `hasMany` | `boolean` | `false` | Allow multiple selections. |
| `enumName` | `string` | Auto | Custom SQL enum name. |
| `interfaceName` | `string` | — | TypeScript interface name for code generation. |
| `filterOptions` | `(args) => SelectOption[]` | — | Dynamically filter options based on data, sibling data, and user. |
| `defaultValue` | `string \| string[] \| (data) => …` | — | Default value(s). |
| `admin.isClearable` | `boolean` | `false` | Show a clear button. |
| `admin.isSortable` | `boolean` | `false` | Enable drag-and-drop reorder (multi-select only). |

The `option()` helper auto-generates the value from the label by lowercasing it and replacing spaces with underscores. Pass an explicit second arg if you want a different value.

```typescript
option("Draft");        // { label: "Draft", value: "draft" }
option("In Review");    // { label: "In Review", value: "in_review" }
option("Active", "active");
```

```typescript
// Multi-select
select({
  name: "categories",
  hasMany: true,
  options: [option("Tech"), option("Business"), option("Design")],
  admin: { isClearable: true, isSortable: true },
});

// Cascading dropdown
select({
  name: "subcategory",
  options: allSubcategories,
  filterOptions: ({ data }) =>
    allSubcategories.filter((s) => s.parentId === data.category),
});
```

**Gotchas:** option `value` strings should not contain hyphens or special characters — that's a GraphQL enum constraint. Underscores are fine.

---

### radio

Radio button group for single selection. Best when all options should be visible at once.

```typescript
radio({
  name: "priority",
  options: [option("Low"), option("Medium"), option("High")],
})
```

| Option | Type | Default | Description |
|---|---|---|---|
| `options` | `SelectOption[]` | — | **Required.** Array of `{ label, value }` objects. |
| `enumName` | `string` | Auto | Custom SQL enum name. |
| `interfaceName` | `string` | — | TypeScript interface name for code generation. |
| `defaultValue` | `string \| (data) => string` | — | Default value (must match an option). |
| `admin.layout` | `"horizontal" \| "vertical"` | `"horizontal"` | Button layout direction. |

```typescript
radio({
  name: "size",
  options: [option("S"), option("M"), option("L"), option("XL")],
  admin: { layout: "horizontal" },
});
```

---

### chips

Free-form multi-value string field that stores an array of unique strings. Renders as interactive chips/tags. Duplicate entries are automatically prevented.

```typescript
chips({ name: "tags" })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `string[] \| (data) => string[]` | — | Initial chips. |
| `maxChips` | `number` | — | Maximum number of chips allowed. The add input is hidden once reached. |
| `minChips` | `number` | — | Minimum number of chips required (validation). |
| `admin.placeholder` | `string` | `"Type and press Enter to add"` | Placeholder text for the input. |

```typescript
chips({
  name: "keywords",
  required: true,
  minChips: 1,
  maxChips: 10,
});
```

---

## Media

### upload

Reference files from upload-enabled collections. Works like `relationship` but with media-specific UI (thumbnails) and a richer `filterOptions` query schema.

```typescript
upload({ name: "featuredImage", relationTo: "media" })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `relationTo` | `string \| string[]` | — | **Required.** Upload-collection slug or array of slugs (polymorphic). |
| `hasMany` | `boolean` | `false` | Allow multiple file selections. |
| `minRows` | `number` | — | Min uploads when `hasMany: true`. |
| `maxRows` | `number` | — | Max uploads when `hasMany: true`. |
| `maxDepth` | `number` | `1` | Population depth for the related document. |
| `maxFileSize` | `number` | — | Max file size in bytes (rejected before upload). |
| `mimeTypes` | `string` | — | Comma-separated allowed MIME types (e.g. `"image/*"` or `"image/png,application/pdf"`). |
| `filterOptions` | `UploadFilterQuery \| (args) => boolean \| UploadFilterQuery \| Promise<…>` | — | Filter available uploads. Static query or dynamic function. |
| `defaultValue` | See type union | — | Static default ID, array of IDs, polymorphic ref, or function. |
| `admin.allowCreate` | `boolean` | `true` | Allow uploading new files from the field. |
| `admin.allowEdit` | `boolean` | `true` | Allow editing upload metadata. |
| `admin.isSortable` | `boolean` | `true` | Drag-and-drop reorder when `hasMany: true`. |
| `admin.displayPreview` | `boolean` | inherited from collection | Show thumbnail preview. |

`filterOptions` static-query operators: `equals`, `not_equals`, `contains`, `in`, `not_in`, `exists` (strings); `equals`, `not_equals`, `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `exists` (numbers). Available filterable keys: `mimeType`, `filesize`, `width`, `height`, `filename`, `alt`, plus any custom field on the upload collection.

```typescript
// Gallery with constraints
upload({
  name: "gallery",
  relationTo: "media",
  hasMany: true,
  maxRows: 10,
  filterOptions: { mimeType: { contains: "image" } },
});

// Polymorphic uploads
upload({
  name: "attachment",
  relationTo: ["media", "documents"],
});

// Dynamic filter — require HD images for hero
upload({
  name: "heroImage",
  relationTo: "media",
  filterOptions: () => ({
    mimeType: { contains: "image" },
    width: { greater_than_equal: 1920 },
    height: { greater_than_equal: 1080 },
  }),
});
```

---

## Relationship

### relationship

Reference documents from other collections. Supports single, multi, and polymorphic relationships.

```typescript
relationship({ name: "author", relationTo: "users", required: true })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `relationTo` | `string \| string[]` | — | **Required.** Target collection slug or array of slugs (polymorphic). |
| `hasMany` | `boolean` | `false` | Allow multiple document references. |
| `minRows` | `number` | — | Min selections when `hasMany: true`. |
| `maxRows` | `number` | — | Max selections when `hasMany: true`. |
| `maxDepth` | `number` | `1` | Population depth for nested relationships. |
| `filterOptions` | `RelationshipFilterQuery \| (args) => boolean \| RelationshipFilterQuery \| Promise<…>` | — | Filter available documents. Static query or dynamic function. |
| `defaultValue` | See type union | — | Static default ID, array of IDs, polymorphic ref, or function. |
| `admin.allowCreate` | `boolean` | `true` | Allow creating new documents from the field. |
| `admin.allowEdit` | `boolean` | `true` | Allow editing related documents. |
| `admin.isSortable` | `boolean` | `true` | Enable drag-and-drop reorder (multi only). |
| `admin.sortOptions` | `string \| Record<string, string>` | — | Default sort. Prefix with `-` for descending. Per-collection mapping for polymorphic. |
| `admin.appearance` | `"select" \| "drawer"` | `"select"` | Picker UI style. Use `"drawer"` for large lists. |

```typescript
// Has many
relationship({
  name: "categories",
  relationTo: "categories",
  hasMany: true,
  maxRows: 5,
});

// Polymorphic
relationship({
  name: "relatedContent",
  relationTo: ["posts", "pages", "products"],
  hasMany: true,
});

// Self-reference, exclude self
relationship({
  name: "parent",
  relationTo: "pages",
  filterOptions: ({ id }) =>
    id ? { id: { not_equals: id } } : true,
});

// Drawer picker for big lists
relationship({
  name: "featuredProducts",
  relationTo: "products",
  hasMany: true,
  admin: { appearance: "drawer", sortOptions: "-sales" },
});
```

**Gotchas:** when both `filterOptions` and `validate` are set, the filter is **not** automatically re-validated server-side — include the same constraint in `validate` if you need it enforced.

---

## Layout

### repeater

Repeatable sets of fields. Each row contains the same field structure. Rows can be added, removed, and reordered.

```typescript
repeater({
  name: "links",
  labels: { singular: "Link", plural: "Links" },
  fields: [
    text({ name: "label", required: true }),
    text({ name: "url", required: true }),
  ],
})
```

| Option | Type | Default | Description |
|---|---|---|---|
| `fields` | `FieldConfig[]` | — | **Required.** Field definitions for each row. |
| `minRows` | `number` | — | Minimum rows. |
| `maxRows` | `number` | — | Maximum rows. The Add button is disabled when reached. |
| `labels` | `{ singular?: string; plural?: string }` | — | Custom row labels (e.g. `"Link"` / `"Links"`). |
| `interfaceName` | `string` | — | TypeScript interface name for code generation. |
| `dbName` | `string` | Auto | Custom database table name. |
| `virtual` | `boolean` | `false` | Skip database storage; field exists only in API. |
| `defaultValue` | `RepeaterRowValue[] \| (data) => RepeaterRowValue[]` | — | Static default rows. |
| `admin.initCollapsed` | `boolean` | `false` | Render rows initially collapsed. |
| `admin.isSortable` | `boolean` | `true` | Enable drag-and-drop reorder. |
| `admin.components.RowLabel` | `React.ComponentType<RepeaterRowLabelProps>` | — | Custom row-label component. |

```typescript
// FAQ with custom row labels
repeater({
  name: "faq",
  labels: { singular: "Question", plural: "Questions" },
  fields: [
    text({ name: "question", required: true }),
    richText({ name: "answer", required: true }),
  ],
  admin: {
    initCollapsed: true,
    // RowLabel component must be provided as a path string when using
    // a server-rendered config; React component in client contexts.
  },
});
```

> **Note:** Use `repeater()` to define this field. The internal `type` is `"repeater"`. (Some other CMSes call this concept "array".)

**Cross-links:** [Field Groups](https://nextlyhq.com/docs/configuration/field-groups#repeatable-single-field-group) covers the alternative repeatable field-group pattern when you want a typed schema instead of inline fields.

---

### group

Organize related fields together. Named groups create nested data; groups without a `name` are presentational only.

```typescript
group({
  name: "seo",
  fields: [
    text({ name: "metaTitle", maxLength: 60 }),
    textarea({ name: "metaDescription", maxLength: 160 }),
  ],
})
// Stored data: { seo: { metaTitle: "...", metaDescription: "..." } }
```

| Option | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | If provided, fields are nested under this property. If omitted, the group is purely visual. |
| `fields` | `FieldConfig[]` | — | **Required.** Nested field definitions. |
| `interfaceName` | `string` | — | TypeScript interface name. |
| `dbName` | `string` | Auto | Custom database column/table name. |
| `virtual` | `boolean` | `false` | Skip database storage. |
| `defaultValue` | `Record<string, unknown> \| (data) => …` | — | Default values for nested fields (named groups only). |
| `admin.hideGutter` | `boolean` | `false` | Remove the left-side visual gutter. |

```typescript
// Presentational group — no data nesting; fields stored at parent level
group({
  label: "Display Settings",
  fields: [
    checkbox({ name: "showTitle", defaultValue: true }),
    checkbox({ name: "showDate", defaultValue: true }),
  ],
  admin: { hideGutter: true },
});
```

**Gotchas:** named groups create real nested objects in your data — keep that in mind for queries and migrations. Presentational groups are pure UI; their fields share the parent's data namespace.

---

## Component

### component

Embed reusable [field groups](https://nextlyhq.com/docs/configuration/field-groups) inside collections, singles, or other field groups. Three usage modes are supported.

```typescript
// Single fixed type
fieldGroup({ name: "seo", component: "seo" })

// Dynamic zone
fieldGroup({
  name: "layout",
  components: ["hero", "cta", "content-block"],
  repeatable: true,
})

// Repeatable single type
fieldGroup({
  name: "features",
  component: "feature-card",
  repeatable: true,
  minRows: 1,
  maxRows: 12,
})
```

| Option | Type | Default | Description |
|---|---|---|---|
| `component` | `string` | — | Single mode: one specific component slug. Mutually exclusive with `components`. |
| `components` | `string[]` | — | Dynamic-zone mode: array of allowed component slugs. Mutually exclusive with `component`. |
| `repeatable` | `boolean` | `false` | Allow multiple instances (array mode). |
| `minRows` | `number` | — | Min instances when `repeatable: true`. |
| `maxRows` | `number` | — | Max instances when `repeatable: true`. |
| `admin.initCollapsed` | `boolean` | `false` | Start instances collapsed. |
| `admin.isSortable` | `boolean` | `true` | Drag-and-drop reorder when `repeatable: true`. |

**Gotchas:** `component` and `components` are mutually exclusive; you'll get a startup error if both are set. Component nesting is capped at depth 3.

**Cross-links:** see [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) for the `defineFieldGroup()` reference and [the three modes](https://nextlyhq.com/docs/configuration/field-groups#using-field-groups-in-collections-and-singles) explained side-by-side.

---

## Advanced

### json

Store arbitrary JSON data with an in-browser code editor. Supports JSON Schema validation.

```typescript
json({ name: "metadata" })
```

| Option | Type | Default | Description |
|---|---|---|---|
| `jsonSchema` | `JSONSchemaDefinition` | — | Inline JSON Schema for validation and editor hints. |
| `defaultValue` | Any valid JSON value or function | — | Default value. |
| `admin.editorOptions.height` | `number \| string` | `300` | Editor height. |
| `admin.editorOptions.minHeight` | `number` | `100` | Minimum height. |
| `admin.editorOptions.maxHeight` | `number` | — | Maximum height. |
| `admin.editorOptions.lineNumbers` | `boolean` | `true` | Show line numbers. |
| `admin.editorOptions.folding` | `boolean` | `true` | Enable code folding. |
| `admin.editorOptions.wordWrap` | `boolean` | `false` | Enable word wrapping. |
| `admin.editorOptions.minimap` | `boolean` | `false` | Show code minimap. |
| `admin.editorOptions.tabSize` | `number` | `2` | Tab size in spaces. |
| `admin.editorOptions.formatOnBlur` | `boolean` | `true` | Auto-prettify on blur. |
| `admin.editorOptions.validateOnChange` | `boolean` | `true` | Real-time syntax validation. |

**Database storage:** PostgreSQL uses `JSONB`, MySQL uses `JSON`, SQLite uses `TEXT`. Schema validation happens at the application level so behavior is consistent across adapters.

```typescript
json({
  name: "settings",
  jsonSchema: {
    type: "object",
    properties: {
      theme: { type: "string", enum: ["light", "dark", "system"] },
      maxItems: { type: "number", minimum: 1 },
    },
    required: ["theme"],
  },
});
```

---

## Virtual

### join

Display reverse relationships — entries from another collection that reference the current document. Join fields are read-only and do **not** store data; they query at read time.

```typescript
{
  name: "posts",
  type: "join",
  collection: "posts",
  on: "category",
}
```

There is no helper function for `join` — declare it as a plain object with `type: "join"`.

| Option | Type | Default | Description |
|---|---|---|---|
| `type` | `"join"` | — | **Required.** Field type literal. |
| `name` | `string` | — | **Required.** Field identifier (no DB column is created). |
| `collection` | `string` | — | **Required.** Collection containing the referencing field. |
| `on` | `string` | — | **Required.** Field name in `collection` that references this document. Supports dot notation (e.g. `"metadata.author"`). |
| `where` | `Record<string, unknown>` | — | Additional filter for joined entries (Nextly Where syntax). |
| `defaultLimit` | `number` | `10` | Max entries to display. Set `0` to display all. |
| `defaultSort` | `string` | — | Sort field. Prefix with `-` for descending. |
| `maxDepth` | `number` | `1` | Population depth for relationships in joined entries. |
| `label` | `string` | Auto | Display label. |
| `admin.allowNavigation` | `boolean` | `true` | Make entries clickable links. |
| `admin.allowCreate` | `boolean` | `false` | Show a "Create New" button (pre-fills the relationship). |
| `admin.defaultColumns` | `string[]` | — | Columns to display in the list. |

```typescript
// On a Categories collection — show all posts in this category
{
  name: "posts",
  type: "join",
  label: "Posts in this Category",
  collection: "posts",
  on: "category",
  defaultSort: "-createdAt",
  admin: {
    defaultColumns: ["title", "status", "createdAt"],
  },
}
```

**Gotchas:** join fields are **read-only**; the related entries are still edited from their own collection's edit page. Only `name`, `label`, and `admin` are common with other field types — `required`, `unique`, `defaultValue`, `validate`, `access`, and `hooks` do not apply.

---

## Common options across fields

Every field type (except `join`, which is virtual) inherits the following from `BaseFieldConfig`. Where a specific field's reference table above doesn't repeat them, they still apply.

### Identity

| Option | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | **Required.** Unique identifier. Lowercase, underscores or numbers — no hyphens, no spaces, no SQL reserved words. |
| `type` | `FieldType` | Set by helper | Field type literal. The helper functions (`text`, `number`, etc.) set this for you. |
| `label` | `string` | Auto from `name` | Display label in the admin UI (e.g. `user_name` → `User Name`). |
| `required` | `boolean` | `false` | Whether the field must have a non-null, non-empty value. |
| `unique` | `boolean` | `false` | Enforce database-level uniqueness. |
| `index` | `boolean` | `false` | Create a single-field database index. |
| `localized` | `boolean` | `false` | **Reserved for a future release.** When implemented, will store separate values per locale. |
| `custom` | `Record<string, unknown>` | — | Arbitrary metadata for plugins or hooks. Not persisted. |

### `admin`

Shared UI options:

| Option | Type | Default | Description |
|---|---|---|---|
| `position` | `"sidebar"` | — | Place the field in the sidebar instead of the main content area. |
| `width` | `"25%" \| "33%" \| "50%" \| "66%" \| "75%" \| "100%"` | `"100%"` | Field width in the form layout grid. |
| `description` | `string` | — | Help text below the field label. |
| `placeholder` | `string` | — | Placeholder text when empty. |
| `readOnly` | `boolean` | `false` | Make the field read-only in the UI. |
| `disabled` | `boolean` | `false` | Disable the input. |
| `hidden` | `boolean` | `false` | Hide the field from the UI entirely (still settable via API). |
| `condition` | `FieldCondition` | — | Conditionally show/hide based on another field's value. |
| `className` | `string` | — | Custom CSS class on the wrapper. |
| `style` | `Record<string, string>` | — | Inline styles on the wrapper. |
| `components.Field` | `React.ComponentType<FieldComponentProps>` | — | Custom form-field renderer. |
| `components.Cell` | `React.ComponentType<CellComponentProps>` | — | Custom list/table cell renderer. |
| `components.Filter` | `React.ComponentType<FilterComponentProps>` | — | Custom list-view filter UI. |

#### Conditional logic

```typescript
text({
  name: "externalUrl",
  admin: {
    condition: {
      field: "linkType",
      equals: "external",
    },
  },
});
```

Available `FieldCondition` operators: `equals`, `notEquals`, `contains`, `exists`.

### `access`

Field-level access control — granular permissions per CRUD operation.

```typescript
text({
  name: "internalNotes",
  access: {
    create: ({ req }) => req.user?.role === "admin",
    read: ({ req }) => req.user?.role === "admin",
    update: ({ req }) => req.user?.role === "admin",
  },
});
```

Each function receives `{ req, id?, data? }` and returns `boolean | Promise<boolean>`. Field-level access is checked **in addition to** collection/single access.

### `hooks`

Field-level lifecycle hooks. Each hook is an array of handlers run in order.

| Hook | When it runs |
|---|---|
| `beforeValidate` | Before validation. Can transform the value. |
| `beforeChange` | Before the database write. |
| `afterChange` | After the database write. |
| `afterRead` | After reading from the database. Can transform the returned value. |

```typescript
text({
  name: "slug",
  hooks: {
    beforeValidate: [
      async ({ value, data }) => {
        if (!value && data?.title) {
          return data.title.toLowerCase().replace(/\s+/g, "-");
        }
        return value;
      },
    ],
  },
});
```

### `validate`

Custom validation function. Receives the typed field value plus `{ data, req }` and returns either `true` (valid) or an error-message string. Runs **after** the field's built-in validation.

```typescript
text({
  name: "username",
  validate: (value) => {
    if (value && !/^[a-z0-9_]+$/.test(String(value))) {
      return "Lowercase letters, numbers, and underscores only";
    }
    return true;
  },
});
```

### `defaultValue`

Static value or `(data) => value` function. The function form receives the document data being created so you can compute defaults from sibling fields. Each field type's signature accepts the value type appropriate for that field.

---

## Helper utilities

### `option(label, value?)`

Creates a `{ label, value }` option for `select` and `radio` fields. Auto-generates the value from the label by lowercasing and replacing spaces with underscores.

```typescript
import { option } from "nextly";

option("Draft");          // { label: "Draft", value: "draft" }
option("In Progress");    // { label: "In Progress", value: "in_progress" }
option("Active", "active");
```

## Next steps

- [Collections](https://nextlyhq.com/docs/configuration/collections) — define content types using fields
- [Singles](https://nextlyhq.com/docs/configuration/singles) — define single-document content using fields
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) — create reusable field groups
- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — build collections, singles, and field groups visually

---
title: Environment Variables
description: Every environment variable Nextly reads, organized by category with required vs. optional indicators.
url: https://nextlyhq.com/docs/configuration/environment
---

Nextly reads environment variables for database connections, authentication, storage, email, and other runtime settings. Most live in the central env schema (`packages/nextly/src/shared/lib/env.ts`); storage adapter env vars are per-adapter and read by the adapter packages directly.

Copy `.env.example` to `.env` and fill in values:

```bash
cp .env.example .env
```

## Canonical `.env.example`

The base template `templates/base/.env.example` ships the minimum required variables:

```bash title=".env.example"
# Nextly Configuration
# Generated by create-nextly-app

# Database Configuration
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@localhost:5432/nextly_dev

# Authentication (REQUIRED)
# Generate with: openssl rand -base64 32
NEXTLY_SECRET=change-me-generate-a-secure-secret

# Application URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Development diagnostics (opt-in — see below)
# NEXTLY_DEV_DIAGNOSTICS=1

# Storage (per-adapter — see "Storage" section below)
```

The `create-nextly-app` scaffolder fills in `DB_DIALECT`, `DATABASE_URL`, and an auto-generated 32-byte base64 `NEXTLY_SECRET` for you. For a production deployment, regenerate `NEXTLY_SECRET` with:

```bash
openssl rand -base64 32
```

---

## Database

Source: `packages/nextly/src/shared/lib/env.ts`.

| Variable | Required | Default | Description |
|---|---|---|---|
| `DB_DIALECT` | Yes | `postgresql` | Database dialect: `postgresql`, `mysql`, or `sqlite`. |
| `DATABASE_URL` | Yes (PostgreSQL/MySQL) | — | Full database connection URL. Required for `postgresql` and `mysql`; optional for `sqlite` (paired with `SQLITE_PATH`). Validated as a URL. |
| `SQLITE_PATH` | Optional (SQLite only) | `file:./data/nextly.db` (factory default) | SQLite file path; alternative to `DATABASE_URL` for the `sqlite` dialect. |
| `DB_POOL_MAX` | No | `20` | Max connections in the pool. Min: 1. |
| `DB_POOL_MIN` | No | `2` | Min connections in the pool. Min: 0. |
| `DB_POOL_IDLE_TIMEOUT` | No | `30000` | Idle connection timeout in milliseconds. Min: 1000. |
| `DB_QUERY_TIMEOUT` | No | `15000` | Query timeout in milliseconds. Min: 1000. |
| `DB_HEALTHCHECK_INTERVAL_MS` | No | `30000` | Health-check interval in milliseconds. Min: 1000. |
| `DB_SNAKE_CASE` | No | `false` | Use `snake_case` for database column names instead of `camelCase`. |

### Connection-string formats

```bash
# PostgreSQL (recommended for production)
DATABASE_URL=postgresql://user:password@localhost:5432/nextly_dev

# MySQL
DATABASE_URL=mysql://root:root@localhost:3306/nextly_dev

# SQLite (development / single-instance only)
DATABASE_URL=file:./dev.db
# or
SQLITE_PATH=./dev.db
```

---

## Runtime

| Variable | Required | Default | Description |
|---|---|---|---|
| `NODE_ENV` | No | `development` | Runtime environment: `development`, `production`, or `test`. Affects production-only checks below. |

---

## Development diagnostics

| Variable | Required | Default | Description |
|---|---|---|---|
| `NEXTLY_DEV_DIAGNOSTICS` | No | — | Set to `1` to add a `_devDiagnostics` field to error responses, carrying the error's log context and the message of its underlying cause. Ignored unless `NODE_ENV` is `development`. |

An error response is deliberately generic: it carries a code, a public message
and a request id, and withholds the log context and the underlying cause so a
response cannot disclose driver output, table names or internal paths. That is
right for a deployed app and unhelpful while you are building, where the detail
you need is exactly what was withheld.

With this set, an error in development also carries:

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred.",
    "requestId": "req_01HQ...",
    "_devDiagnostics": {
      "logContext": { "collectionName": "posts", "entryId": "abc123" },
      "cause": "duplicate key value violates unique constraint posts_slug_key",
      "flattened": [{ "code": "CONFLICT", "logContext": { "field": "slug" } }]
    }
  }
}
```

`flattened` lists errors that were rebuilt on the way to the boundary, which is
what makes an unexpected failure name itself instead of looking like every
other one.

**Why it is opt-in rather than on by default.** The gate requires two
independent signals: `NODE_ENV` must be `development` **and** this flag must be
`1`. The second exists precisely because the first can be wrong — `nextly` ships
pre-built and stays external to your build, so `NODE_ENV` is a runtime value a
deployment can carry by mistake.

A default that shipped in `.env` would be true in exactly that case, which is
the one the second signal guards against, collapsing two independent signals
back into one. So `create-nextly-app` writes the setting **commented out** with
this explanation: discoverable, and never enabled by a file that travels with
your app.

Uncomment it in your local `.env` — not in a file you deploy — and keep it out
of any environment where `NODE_ENV` might not be what you expect.

---

## Authentication

Nextly uses a custom JWT auth system (access + refresh tokens, sessions, API keys, RBAC). There is **no** OAuth.

| Variable | Required | Default | Description |
|---|---|---|---|
| `NEXTLY_SECRET` | Yes (production: ≥ 32 chars) | — | Secret used to sign JWTs and other crypto. Production startup throws if it is missing or shorter than 32 characters. Generate with `openssl rand -base64 32`. |
| `NEXTLY_SECRET_PREVIOUS` | No | — | Secrets you have RETIRED, newest first. Kept for READING only — nothing new is ever keyed with one. See "Rotating `NEXTLY_SECRET`" below. |
| `NEXTLY_ALLOWED_ORIGINS` | No | — | Comma-separated list of additional origins allowed for CSRF validation (e.g. `https://admin.example.com,https://staging.example.com`). The app's own origin is always allowed. |

### Rotating `NEXTLY_SECRET`

Rotating the secret re-keys everything derived from it, and the values already
written do not move. For most of them that fails loudly and is fine — a webhook
signing secret that no longer decrypts is one an operator re-enters.

The email delivery log is the exception, because it fails **quietly**. Each row
identifies its recipient by an HMAC of their address, so after a rotation an
erasure request computes a digest none of the older rows carry, matches nothing,
and reports success. "No rows matched" is also what a person with no mail looks
like, so nothing distinguishes the two.

List the old secret in `NEXTLY_SECRET_PREVIOUS` and those rows stay reachable —
for lookups and for erasure — without becoming writable:

```bash
NEXTLY_SECRET=the-new-one
NEXTLY_SECRET_PREVIOUS=the-old-one,an-older-one
```

**Two spellings, because one of them cannot express every legal secret.** The
comma-separated form above is the ordinary one. Use the JSON-array form when a
retired secret contains a comma, or when leading or trailing whitespace is part
of the key — splitting or trimming those produces a key that was never used,
which matches nothing and fails in the silent direction:

```bash
# Single quotes are REQUIRED. Without them the shell strips the inner double
# quotes and the value becomes `[old,with,commas,  spaced  ]`, which is not
# JSON — it falls back to comma splitting and derives four keys that were never
# used, so lookups and erasure silently miss the rows this is meant to reach.
NEXTLY_SECRET_PREVIOUS='["old,with,commas","  spaced  "]'
```

The JSON form also names two generations no string can:

- `null` is the **unkeyed** generation — what an install writes when it has no
  `NEXTLY_SECRET` at all, which is only possible outside production. Rows
  written then carry a plain SHA-256 digest that no HMAC reproduces, so
  enabling a secret later strands them unless you name that generation.
- `""` is a secret that really was the empty string, which is used as an HMAC
  key like any other.

```bash
# was unkeyed in development, now has a secret
NEXTLY_SECRET_PREVIOUS='[null]'
```

An empty entry in the **comma** form is dropped rather than rejected: a trailing
comma is the likeliest way to write the list, and nothing about `older,` says a
second key was meant. Write `'[""]'` when you mean it — with the outer single quotes, for the same
reason.

---

## Application URLs

| Variable | Required | Default | Description |
|---|---|---|---|
| `NEXT_PUBLIC_APP_URL` | Yes (production) | — | Public-facing app URL. Used in client-side code and as the fallback for email-link `baseUrl`. Production startup throws if missing. |
| `API_BASE_URL` | No | `http://localhost:3000/api` | Base URL for API routes. Validated as a URL. |

---

## Storage (per-adapter)

The default storage backend is **local disk** under `./public/uploads/`. No env vars are needed for default storage.

Cloud adapters are opt-in. The variables below are read **by the adapter packages**, not by the central env schema, so they only need to exist when you actually configure that adapter in `nextly.config.ts`. Nothing else (env-validation, etc.) checks for them.

### S3 / S3-compatible — `@nextlyhq/storage-s3`

Works with AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces. The plugin accepts these values directly; the env-var names below are the conventional ones used in our examples (and what your `nextly.config.ts` typically references with `process.env.X`).

| Variable | Required | Description |
|---|---|---|
| `S3_BUCKET` | Yes | Bucket name. |
| `AWS_REGION` | Yes | AWS region (e.g. `us-east-1`). Use `auto` for Cloudflare R2. |
| `AWS_ACCESS_KEY_ID` | Yes | Access key ID. |
| `AWS_SECRET_ACCESS_KEY` | Yes | Secret access key. |
| `S3_ENDPOINT` | Sometimes | Custom endpoint URL. Required for R2 and MinIO. |
| `S3_PUBLIC_URL` | No | Public URL prefix (e.g. `https://pub-xxxx.r2.dev` for R2 or a CDN domain). |
| `S3_FORCE_PATH_STYLE` | No | Set `true` for MinIO and other path-style providers. |

```typescript title="nextly.config.ts"
import { s3Storage } from "@nextlyhq/storage-s3";

storage: [
  s3Storage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.AWS_REGION!,
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    endpoint: process.env.S3_ENDPOINT,
    forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
    publicUrl: process.env.S3_PUBLIC_URL,
    collections: { media: true },
  }),
];
```

### Vercel Blob — `@nextlyhq/storage-vercel-blob`

Recommended for Vercel deployments.

| Variable | Required | Description |
|---|---|---|
| `BLOB_READ_WRITE_TOKEN` | Yes | Vercel Blob token from the Vercel dashboard. The adapter reads this directly when the `token` config option is omitted. |

### UploadThing — `@nextlyhq/storage-uploadthing`

| Variable | Required | Description |
|---|---|---|
| `UPLOADTHING_TOKEN` | Yes | UploadThing API token. The adapter reads this directly when the `token` config option is omitted. |

---

## Email / SMTP

Source: `packages/nextly/src/shared/lib/env.ts`. Required only if you send emails (password resets, notifications). In production, if **any** SMTP variable is set, **all four** of `SMTP_HOST`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM` must be set or the env validator throws.

| Variable | Required | Default | Description |
|---|---|---|---|
| `SMTP_HOST` | No | — | SMTP server hostname (e.g. `smtp.gmail.com`). |
| `SMTP_PORT` | No | `587` | SMTP port. 587 for TLS, 465 for SSL. Range: 1–65535. |
| `SMTP_USER` | No | — | SMTP authentication username. |
| `SMTP_PASS` | No | — | SMTP authentication password. |
| `SMTP_FROM` | No | — | From address for outgoing emails. Validated as an email. |

For local development, the repo ships a Mailpit profile (`docker compose --profile with-mailpit up -d mailpit`) on host ports 1025 (SMTP) and 8025 (web UI) — see [Email guide](https://nextlyhq.com/docs/guides/email) for details.

---

## Security

These env vars are read by middleware and security helpers. None are part of the central env schema; they are read directly by the modules that use them.

| Variable | Required | Default | Description | Read by |
|---|---|---|---|---|
| `TRUSTED_PROXY_IPS` | No | empty | Comma-separated CIDR list of trusted reverse-proxy IPs. Combined with `security.trustProxy: true`, controls which `X-Forwarded-For` values are honoured for client-IP resolution (rate limiting, refresh-token binding, audit logging). | `packages/nextly/src/utils/get-trusted-client-ip.ts` |

---

## Performance — permission cache

Nextly's RBAC layer ships a hybrid (in-memory LRU + database) permission cache. These env vars tune it; none are part of the central env schema — they are read directly by the permission service.

| Variable | Required | Default | Description | Read by |
|---|---|---|---|---|
| `PERMISSION_CACHE_ENABLED` | No | `true` | Set to `false` or `0` to disable the hybrid permission cache. | `packages/nextly/src/services/lib/permissions.ts` |
| `PERMISSION_CACHE_TTL_SECONDS` | No | `86400` | Time-to-live for database cache entries (seconds). | `packages/nextly/src/services/lib/permissions.ts` |
| `PERMISSION_CACHE_MEMORY_SIZE` | No | `10000` | In-memory LRU cache size (number of entries). | `packages/nextly/src/services/lib/permissions.ts` |

The database permission cache benefits from periodic cleanup. A typical daily cron:

```bash
0 2 * * * curl -X POST http://localhost:3000/api/auth/cache/cleanup
```

---

## Debug

| Variable | Required | Default | Description | Read by |
|---|---|---|---|---|
| `DEBUG_RBAC` | No | — | Set `1` to log detailed RBAC permission decisions. | `packages/nextly/src/services/lib/permissions.ts` |
| `DEBUG_CACHE` | No | — | Set `1` to log permission-cache hit/miss/eviction details. | `packages/nextly/src/domains/auth/services/permission-cache-service.ts` |

---

## Docker development (optional)

Used by the bundled `docker-compose.yml` for local Postgres / Redis / Adminer / Drizzle Studio / Mailpit setup. Not needed when connecting to an existing database.

| Variable | Default | Description |
|---|---|---|
| `DB_NAME` | `nextly_dev` | PostgreSQL database name. |
| `DB_USER` | `postgres` | PostgreSQL user. |
| `DB_PASSWORD` | — | PostgreSQL password. Override in production. |
| `DB_PORT` | `5432` | PostgreSQL host port. |
| `ADMINER_PORT` | `8080` | Adminer (database browser) UI port. |
| `REDIS_PORT` | `6379` | Redis cache port. |
| `DRIZZLE_STUDIO_PORT` | `4983` | Drizzle Studio port for the database GUI. |

---

## Example `.env` files

### Minimal production

```bash
# Runtime
NODE_ENV=production

# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@db.example.com:5432/nextly_prod

# Auth
NEXTLY_SECRET=your-generated-secret-at-least-32-characters-long
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Storage (Vercel Blob example)
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxxxxxxxxx
```

### Development with S3-compatible storage (MinIO)

```bash
# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextly_dev

# Auth
NEXTLY_SECRET=dev-secret-minimum-32-characters-long-replace-in-production
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Storage (MinIO)
S3_BUCKET=nextly-dev
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_FORCE_PATH_STYLE=true
```

## Next steps

- [Nextly config](https://nextlyhq.com/docs/configuration/nextly-config) — configure storage and security from `nextly.config.ts`
- [Database](https://nextlyhq.com/docs/database) — choose and configure PostgreSQL, MySQL, or SQLite
- [Authentication guide](https://nextlyhq.com/docs/guides/authentication) — auth-related env vars in depth
- [Deployment guide](https://nextlyhq.com/docs/guides/deployment) — production environment-variable checklist

---
title: Media Upload Security
description: How Nextly validates and sanitizes uploaded media — MIME allowlist, SVG sanitization, polyglot defenses, and per-adapter Content-Disposition trade-offs.
url: https://nextlyhq.com/docs/configuration/media-upload-security
---

Every file uploaded through `/api/media` or `/admin/api/collections/[slug]/uploads` passes through a unified validation pipeline at `services/upload-validation/`. This page explains what gets checked, what gets stripped, and how to tune the policy for your deployment.

## The validation pipeline

Each upload runs through six checks, in order. The first failure short-circuits the request with a `NextlyError.validation` carrying a stable machine code.

| Step | Code on failure           | Notes                                                                                         |
| ---- | ------------------------- | --------------------------------------------------------------------------------------------- |
| 1    | `FILENAME_INVALID`        | empty, > 255 chars, null byte, path separator, all-dots                                       |
| 2    | `EXTENSION_BLOCKED`       | `.html`, `.js`, `.php`, `.exe`, etc. — rejected regardless of MIME                            |
| 3    | `MIME_BLOCKED`            | `text/html`, `application/javascript` (hard-block, overrides allowlist)                       |
| 4    | `MIME_NOT_ALLOWED`        | type not in resolved allowlist                                                                |
| 5    | `SIZE_EXCEEDED` (overall) | per-file cap — `security.limits.fileSize` (default 10MB), applies to every upload             |
| 5b   | `SIZE_EXCEEDED` (SVG)     | additional 2MB cap, applied only when the upload claims `image/svg+xml` (XML parser DoS guard) |
| 6    | `MAGIC_BYTE_MISMATCH`     | sniffed bytes disagree with claimed MIME                                                      |
| 7    | `SVG_SANITIZATION_FAILED` | sanitizer threw or output was empty                                                           |

For SVG uploads, the bytes that hit storage are the **sanitized** output, never the input — the validator owns that step so call sites can't accidentally persist unsanitized content.

## Customizing the allowlist

```ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  security: {
    uploads: {
      // Replace the default allowlist entirely.
      allowedMimeTypes: ["image/png", "image/webp", "application/pdf"],

      // OR: add to the default allowlist.
      additionalMimeTypes: ["application/zip"],

      // Set Content-Disposition: attachment on SVG uploads (default: true).
      // The mitigation prevents direct-URL navigation from rendering SVG
      // inline. Browser <img src> rendering is unaffected (already sandboxed).
      svgCsp: true,
    },
    limits: {
      // Per-file cap applied to ALL upload paths (default: "10mb").
      fileSize: "20mb",
    },
  },
});
```

`text/html`, `application/javascript`, `application/xhtml+xml`, and `text/ecmascript` are **unconditionally blocked** even if explicitly listed in `allowedMimeTypes` — they get stripped at boot with a `console.warn`. The same applies to extensions: `.html`, `.js`, `.php`, `.exe`, etc. are blocked at the extension layer regardless of claimed MIME, so renaming `evil.html` to `evil.png` with `Content-Type: image/png` doesn't help an attacker.

## SVG support and what gets stripped

SVG files are allowed by default but **sanitized** via DOMPurify with an explicit policy on top of `USE_PROFILES: { svg, svgFilters }`. The sanitizer removes anything that can execute, fetch external resources, or trigger script-like behavior in a browser.

| Removed                                  | Kept                                            |
| ---------------------------------------- | ----------------------------------------------- |
| `<script>` and all event handlers        | `<path>`, `<rect>`, `<circle>`, shapes          |
| `<foreignObject>` (HTML escape)          | Gradients, filters, masks, patterns             |
| `<animate>` / `<animateMotion>` / `<set>` | Internal `<use href="#id">` references          |
| External `<use href="http…">`            | SVG filter primitives (`feGaussianBlur`, etc.)  |
| `<image href="http…">`                   | `style="…"` inline attribute styling            |
| `<style>` blocks (external CSS `@import`) | Embedded text and fonts                        |
| `data:` URIs in `href`                   | Fragment-only URIs (`#gradient-id`)             |
| `<!DOCTYPE>` declarations                | —                                               |

Output may differ from input. Designers using Adobe Illustrator's "Embed raster" option will lose embedded raster layers — link them by sanitized URL instead. The `<style>` block ban means CSS animations and `@import`-driven styling are dropped; use `style="…"` attributes on individual elements.

## Magic-byte polyglot defense

The validator sniffs the file's actual bytes via `file-type` and compares against the claimed MIME. Mismatches are rejected:

```text
Claimed: image/png    Sniffed: text/html      → MAGIC_BYTE_MISMATCH
Claimed: image/svg+xml Bytes: PNG header      → MAGIC_BYTE_MISMATCH (svg-claim-without-svg-content)
Claimed: image/png    Bytes: <svg…>           → MAGIC_BYTE_MISMATCH (xml-content-non-svg-claim)
```

The SVG case is special: `file-type` returns `application/xml` for SVG (not `image/svg+xml`), so the validator treats them as equivalent only when the buffer's first 2KB contains an actual `<svg>` root. This closes a polyglot bypass where an attacker would claim `image/svg+xml` with non-SVG bytes to skip the sanitizer.

## Per-adapter Content-Disposition support

`Content-Disposition: attachment` is the strongest mitigation against direct-navigation script execution (browser `<img>` rendering is already sandboxed; the threat is `<a href>` clicks and address-bar pastes).

| Adapter                          | Support                                                                                                                                            |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@nextlyhq/storage-s3` / R2 / MinIO | Full — passes through via `PutObjectCommand` `ContentDisposition`.                                                                                |
| `@nextlyhq/storage-vercel-blob`     | **SVG: supported** via Vercel Blob's `downloadUrl` (the file URL with `?download=1` appended). The adapter returns this URL when the upload requests `contentDisposition: "attachment"`, so top-level navigation forces download while `<img src>` still renders the SVG inline. **HTML: refused** with `NextlyError.validation` (code `UNSUPPORTED_FOR_BACKEND`) — HTML is unsafe to host on a shared blob CDN regardless of disposition. |
| `storage-local` (Next.js static `/public`) | Sanitization runs, but per-file response headers cannot be applied. Self-hosters wanting strict headers should serve through a CDN with a response-header policy. |
| `@nextlyhq/storage-uploadthing`     | Investigation pending — see adapter README.                                                                                                       |

## Telemetry

Every validation failure emits a structured log event so operators can alert on attack-pattern spikes:

```json
{
  "msg": "upload.rejected",
  "event": "nextly.upload.rejected",
  "code": "MAGIC_BYTE_MISMATCH",
  "route": "media-service.upload",
  "mimeType": "image/svg+xml",
  "filename": "logo.svg",
  "size": 12345
}
```

The event fires from every upload path that runs the validator: `upload-service.upload`, `media-service.upload`, and `actions.uploadMedia` (the published server action). The `route` field says which one, so an alert can tell a probed public form from a probed admin panel. Wire an alert on sudden bursts of `MAGIC_BYTE_MISMATCH` or `EXTENSION_BLOCKED` — those usually indicate polyglot probing.

## Error response shape

Validation failures emit the canonical `NextlyError` wire shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "data": {
      "errors": [
        {
          "path": "file",
          "code": "MAGIC_BYTE_MISMATCH",
          "message": "File contents do not match the declared type."
        }
      ]
    },
    "requestId": "req_…"
  }
}
```

Operator-only detail (sniffed type, actual size, internal reason codes) lives in `logContext` and is never serialised to the wire — per the §13.8 rubric.

---
title: Visual Schema Builder
description: Design Collections, Singles, and Field Groups visually with drag-and-drop instead of writing code.
url: https://nextlyhq.com/docs/schema-builder
---

The **Visual Schema Builder** is Nextly's drag-and-drop schema designer. It produces the same registered Collections, Singles, and Field Groups that the code-first approach produces, plus the matching TypeScript types and Drizzle migration files. You can switch between the Visual Schema Builder and code-first definitions at any time — they are interchangeable per entity.

The Schema Builder has three variants that share the same canvas, palette, and field editor:

| Variant | Route | Output |
|---|---|---|
| Collections Builder | `/admin/builder/collections` | Persists the schema row, generates a TypeScript schema file under `db.schemasDir` (default `./src/db/schemas/collections/`), and writes a Drizzle migration under `db.migrationsDir` (default `./src/db/migrations/`). |
| Singles Builder | `/admin/builder/singles` | Persists the schema in the `dynamic_singles` database table. No files written to disk. |
| Field Groups Builder | `/admin/builder/field-groups` | Persists the field group definition in the database. No files written to disk. |

Create a new entity from any of the three list pages above. Edit an existing entity by appending its slug, e.g. `/admin/builder/collections/posts`.

## Layout

Each Schema Builder uses a two-column layout:

- **Canvas** (main area) — a sortable list of the fields in your schema. Each row shows an icon, the field name, the type badge, and a "Required" indicator. Drag the grip handle to reorder. Click a row to edit it. Container types (Repeater, Group) display their child fields inline with indentation and dedicated drop zones.
- **Right panel.** The field palette and the field editor. Use the toolbar at the top of the canvas to open the Settings dialog (entity-level config like description, sidebar icon, admin group) or to preview/save changes.

### Field palette

The field palette groups field types into five categories, in this order:

| Category | Field types in the picker |
|---|---|
| Basic | Text, Long text, Editor (rich text), Email, Password, Number |
| Advanced | Code, Date, Select, Radio, Checkbox, Toggle, JSON, Tags (chips) |
| Media | Media (upload) |
| Relational | Relationship |
| Structured | Repeater, Group, Component |

This is the picker grouping inside the admin UI. The reference docs in [Fields](https://nextlyhq.com/docs/configuration/fields) group fields slightly differently (Basic / Selection / Media / Relationship / Layout / Component / Advanced / Virtual) so the prose can talk about families that don't all map to a single picker tab — for example, the `join` field is a code-first virtual field with no picker entry.

### Field editor

Click a field on the canvas to slide the field editor over the palette. The editor has four tabs:

| Tab | What you configure |
|---|---|
| **General** | Name (auto-derived slug), label, description, default value, and the field's type-specific options (e.g. Select options, Relationship target, Upload MIME pattern). |
| **Validation** | `required`, plus type-specific rules: `minLength` / `maxLength`, `min` / `max`, `minRows` / `maxRows`, `minChips` / `maxChips`, regex `pattern`, custom `message`. |
| **Display** | Layout `width` (25% / 33% / 50% / 66% / 75% / 100%), `position` (Main content or Sidebar), `readOnly`, `hidden`, conditional visibility (a per-field condition keyed off another field's value), description, placeholder. |
| **Advanced** | `unique` constraint, database `index`, and a reserved `localized` flag (not yet wired through to runtime localization). |

Conditional visibility supports type-aware operators (`equals`, `notEquals`, `contains`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty`, numeric comparisons, `between`, date `before` / `after`, and boolean `isTrue` / `isNotTrue`).

### Settings dialog

The toolbar's Settings button opens a Basics / Advanced modal that edits entity-level metadata: name, slug, description, sidebar icon, admin group (Collections) or category (Components), sort order, and an `i18n` flag. Per-collection lifecycle hooks are configured in code via the `hooks` array on `defineCollection()`; the Visual Schema Builder does not currently expose a hooks editor in the UI.

## Field types

The palette ships every field type Nextly supports through code-first definitions. The label in the picker can differ from the canonical type name (the picker shows "Long text" for `textarea`, "Editor" for `richText`, "Media" for `upload`, "Tags" for `chips`).

For the full per-type option reference, see [Fields](https://nextlyhq.com/docs/configuration/fields).

### Container fields and nesting

Repeater, Group, and Component fields can themselves contain fields. Nesting is capped at 4 levels deep — `MAX_NESTING_DEPTH = 4` in `packages/admin/src/components/features/schema-builder/types.ts`. Each level renders with a progressively darker background to make the hierarchy visible.

A Component field embeds a reusable field group definition (created via the Field Groups Builder or `defineFieldGroup()`). It can target a single field group or a list of allowed field groups, and can be marked repeatable to act as an inline content zone.

## Walkthrough: create a Blog Posts collection

1. Open `/admin/builder/collections` and click **New Collection**.
2. Fill in the singular and plural names (e.g. "Post" and "Posts"). The slug is generated from the singular name (`post`); you can override it.
3. Pick a sidebar icon (Lucide icon name) and an optional admin group, then click **Continue** to enter the canvas.
4. Drag a **Long text** (`textarea`) field from the palette and rename it `excerpt` in the editor.
5. Drag an **Editor** (`richText`) field and name it `content`.
6. Drag a **Media** (`upload`) field and name it `featuredImage`. On the General tab, restrict the MIME pattern to `image/*`.
7. Open the **Advanced** tab and toggle **Status (Draft / Published)** on. This wires Nextly's built-in lifecycle — the runtime injects a `status` system column and the entry editor surfaces Save Draft / Publish buttons. Don't drag a `Select` field for this: declaring a user-defined `status` field would conflict with the system column. (See [Draft / Published status guide](https://nextlyhq.com/docs/guides/draft-published-status).)
8. Drag a **Relationship** field and name it `author`. Set the target collection to `users`.
9. Reorder the fields by dragging the grip handles.
10. Click **Save**. For Collections, the toolbar previews the schema diff before applying it; for Singles and Components the change applies immediately.

After save, the new collection appears in the admin sidebar under Collections. The generated TypeScript schema and Drizzle migration are written to your `db.schemasDir` and `db.migrationsDir` and should be committed alongside your code.

## Persistence

| Entity | Where it is stored | What gets generated |
|---|---|---|
| Collection | `dynamic_collections` table + files on disk | TypeScript schema file (`<slug>.ts` under `db.schemasDir`) and a Drizzle migration in `db.migrationsDir`. The schema file's path is exported from a generated `index.ts` so the runtime can import it. |
| Single | `dynamic_singles` table | Runtime-only: the schema is regenerated from the database row on each request. No files are written. |
| Component | Database row | Runtime-only: stored alongside dynamic singles. No files are written. |

When you edit and re-save a collection, Nextly emits an additive migration (or, when destructive, prompts for confirmation in the toolbar). The generator avoids re-running migrations that have already been applied — see [`packages/nextly/src/services/collection-file-manager.ts`](../packages/nextly/src/services/collection-file-manager.ts) for the implementation.

## Permissions and visibility

The Visual Schema Builder is reached through the Builders top-level icon. That icon is gated by the `admin.branding.showBuilder` toggle:

- Default behaviour: visible when `process.env.NODE_ENV !== "production"`, hidden in production.
- Force visible: `admin.branding.showBuilder = true` in `nextly.config.ts`.
- Force hidden: `admin.branding.showBuilder = false`.

See [Branding > Schema Builder visibility](https://nextlyhq.com/docs/admin/branding#schema-builder-visibility) for the full toggle reference.

## Builder vs code-first

Both approaches produce the same registered entities. Pick by workflow:

| Aspect | Visual Schema Builder | Code-first |
|---|---|---|
| Speed to prototype | Drag-and-drop | Write config, run `nextly db:sync` |
| Source of truth | DB row (Singles / Components) or generated file (Collections) | Hand-written TypeScript file |
| Lifecycle hooks | Configure in code via `hooks` array | Configure in code via `hooks` array |
| Team workflow | Editors and non-developers can iterate | Developers own the schema |

You can mix both — define core collections in code and let editors prototype new ones in the Schema Builder, or vice versa.

## Next steps

- [Admin Panel Overview](https://nextlyhq.com/docs/admin) — full navigation guide
- [Branding](https://nextlyhq.com/docs/admin/branding) — control Builder visibility with `showBuilder`
- [Collections](https://nextlyhq.com/docs/configuration/collections) — code-first collection definitions
- [Singles](https://nextlyhq.com/docs/configuration/singles) — code-first Single definitions
- [Field Groups](https://nextlyhq.com/docs/configuration/field-groups) — reusable field groups
- [Fields](https://nextlyhq.com/docs/configuration/fields) — per-type option reference and validation

---
title: Dynamic Collections
description: What the Visual Schema Builder creates, and how it coexists with collections defined in code.
url: https://nextlyhq.com/docs/dynamic-collections
---

A collection defined in `nextly.config.ts` exists because you wrote it. A collection built
in the [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) exists because someone created it in
the admin, and its definition lives in the database. The second kind is a **dynamic
collection**.

Both produce the same thing downstream: real database tables, the same REST and Direct API,
the same admin screens, the same access control. The difference is where the definition is
stored and who can change it.

## Availability

| | |
|---|---|
| Built in | Created through the Visual Schema Builder at `/admin/builder/collections` |
| Permission | Creating and editing schema is an admin capability, separate from editing content |

## Which to use

| Use code-first when | Use the Schema Builder when |
|---|---|
| The shape is part of your application's logic | The shape is part of the site's content |
| You want it reviewed in a pull request | You want a non-developer to add a field without a deploy |
| It ships with your repository | It differs between environments, or is created by a client |

The two coexist. A project can define `posts` in code and let an editor add a `testimonials`
collection in the admin, and nothing about either changes because the other exists.

## Moving between them

A collection can be handed from code to the builder, so schema editing moves to the admin
without recreating anything or losing content.

## What differs from a code-first collection

- Its **runtime definition** lives in a database row. The generated migration, however,
  carries both the table DDL and a serialized copy of the field definition, so once you commit
  it the shape *is* in git and *is* reviewable in a pull request.
- A metadata-only edit — renaming a label, changing help text — emits **no SQL migration**,
  because nothing about the table changed. In development the builder also mirrors the entity
  into a committable `ui-schema.json`, so such an edit usually still leaves something to
  review. That mirror is best-effort and development-only: treat the absence of a migration as
  the reliable signal, and the manifest as a convenience rather than a guarantee.
- The trade is narrower than "no oversight": structural changes arrive as a committed
  migration you can review, and presentational ones usually arrive in the development
  manifest.
- It **does** generate a SQL migration file under your `migrationsDir`, and that file is
  what recreates the table and its registry row in another environment. **Commit it.**
  Deploying without it leaves the collection unreproducible outside the database it was
  created in.

## Related

- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — the interface that creates these
- [Collections](https://nextlyhq.com/docs/configuration/collections) — the code-first equivalent
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations)

---
title: Database
description: Choose and configure a database for your Nextly application. PostgreSQL is the recommended production database; MySQL is supported; SQLite is for local demos only.
url: https://nextlyhq.com/docs/database
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Nextly stores data through a small set of dialect-specific adapter packages built on a shared [Drizzle ORM](https://orm.drizzle.team/) core. Pick the adapter that matches your database, install it as a regular dependency, and Nextly handles dialect differences (placeholders, identifier escaping, RETURNING fallbacks, error classification) automatically.

## Supported databases

| Database | Package | Driver | Use it for |
|----------|---------|--------|------------|
| [PostgreSQL](https://nextlyhq.com/docs/database/postgres) | `@nextlyhq/adapter-postgres` | `pg` | **Recommended for production.** Full feature set: JSONB, arrays, full-text search, ILIKE, savepoints, RETURNING. |
| [MySQL](https://nextlyhq.com/docs/database/mysql) | `@nextlyhq/adapter-mysql` | `mysql2` | Supported. Use it when you already run MySQL or a MySQL-compatible cloud database. Some features are emulated -- see the page. |
| [SQLite](https://nextlyhq.com/docs/database/sqlite) | `@nextlyhq/adapter-sqlite` | `better-sqlite3` | **Local demos only.** Single-writer, file-based, no SSL. Not recommended for serious local development -- run Postgres in Docker instead. |

For minimum versions, cloud-provider compatibility, and the policy on MySQL-compatible variants (MariaDB, TiDB, Aurora MySQL, PlanetScale, Vitess), see [database support](https://nextlyhq.com/docs/database/support).

## Quick recommendation

> **Use PostgreSQL.** It is the recommended production database, the only adapter with the full feature set, and the easiest to run locally with Docker (`docker compose up -d postgres`). Pick MySQL only if you already run it. Pick SQLite only for one-off local demos.

## Installation

Each adapter is a regular npm package. Install the adapter and its peer driver in your project.

**pnpm:**

```bash
# PostgreSQL (recommended)
pnpm add @nextlyhq/adapter-postgres pg

# MySQL
pnpm add @nextlyhq/adapter-mysql mysql2

# SQLite (local demos only)
pnpm add @nextlyhq/adapter-sqlite better-sqlite3
```

**npm:**

```bash
# PostgreSQL (recommended)
npm install @nextlyhq/adapter-postgres pg

# MySQL
npm install @nextlyhq/adapter-mysql mysql2

# SQLite (local demos only)
npm install @nextlyhq/adapter-sqlite better-sqlite3
```

**yarn:**

```bash
# PostgreSQL (recommended)
yarn add @nextlyhq/adapter-postgres pg

# MySQL
yarn add @nextlyhq/adapter-mysql mysql2

# SQLite (local demos only)
yarn add @nextlyhq/adapter-sqlite better-sqlite3
```

**bun:**

```bash
# PostgreSQL (recommended)
bun add @nextlyhq/adapter-postgres pg

# MySQL
bun add @nextlyhq/adapter-mysql mysql2

# SQLite (local demos only)
bun add @nextlyhq/adapter-sqlite better-sqlite3
```

## Selecting a dialect

Nextly's runtime picks the dialect from environment variables, in this order:

1. **`DB_DIALECT`** -- explicit override. One of `postgresql`, `mysql`, `sqlite`.
2. **`DATABASE_URL`** protocol -- `postgres://` / `postgresql://` -> PostgreSQL, `mysql://` -> MySQL, `file:` (or `*.db` / `*.sqlite`) -> SQLite.
3. **Fallback** -- PostgreSQL with a warning. Always set `DB_DIALECT` explicitly to avoid the warning.

Minimal `.env` files for each dialect:

```bash title=".env (PostgreSQL)"
DB_DIALECT=postgresql
DATABASE_URL=postgres://nextly:nextly@localhost:5432/nextly_dev
```

```bash title=".env (MySQL)"
DB_DIALECT=mysql
DATABASE_URL=mysql://nextly:nextly@localhost:3306/nextly_dev
```

```bash title=".env (SQLite, local demo only)"
DB_DIALECT=sqlite
DATABASE_URL=file:./data/nextly.db
```

## Feature comparison

The adapters share a single CRUD API, but underlying dialect capabilities differ. The shared `DrizzleAdapter` base reports per-dialect capabilities at runtime; this table is a quick reference.

| Feature | PostgreSQL | MySQL | SQLite |
|---------|------------|-------|--------|
| JSONB columns | Yes | No (JSON only) | No (JSON as TEXT) |
| Array columns | Yes | No | No |
| `RETURNING` clause | Yes | No (extra `SELECT` after writes) | Yes (3.35+) |
| `ILIKE` (case-insensitive) | Native | `LOWER(...) LIKE LOWER(...)` fallback | `LOWER(...) LIKE LOWER(...)` fallback |
| Savepoints (nested transactions) | Yes | Disabled by adapter | Yes |
| Full-text search | `tsvector` | `FULLTEXT` indexes | FTS5 (extension) |
| Upsert syntax | `ON CONFLICT DO UPDATE` | `ON DUPLICATE KEY UPDATE` | `ON CONFLICT DO UPDATE` |
| Connection pooling | `pg.Pool` | `mysql2` pool | None (single file handle) |
| Generated columns | Yes | Yes | Yes |
| Max query parameters | 65,535 | 65,535 | 999 |
| SSL / TLS | Yes | Yes | N/A (local file) |
| Deadlock retry | On `40001` / `40P01` (configurable) | On error 1213 (configurable) | N/A |
| Auto-detected providers | Neon, Supabase, standard | None | None |

## Next steps

- [PostgreSQL setup](https://nextlyhq.com/docs/database/postgres) -- recommended for production
- [MySQL setup](https://nextlyhq.com/docs/database/mysql) -- supported with caveats
- [SQLite setup](https://nextlyhq.com/docs/database/sqlite) -- local demos only
- [Database support](https://nextlyhq.com/docs/database/support) -- minimum versions, cloud providers, MySQL variant policy
- [Environment variables](https://nextlyhq.com/docs/configuration/environment) -- canonical env var reference
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- how schema changes ship to production

---
title: PostgreSQL
description: Set up Nextly with PostgreSQL. Covers installation, connection strings, provider auto-detection (Neon, Supabase), pool tuning, SSL, migrations, local Docker, and production checklist.
url: https://nextlyhq.com/docs/database/postgres
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

PostgreSQL is the recommended production database for Nextly. The adapter uses the standard [`pg`](https://node-postgres.com/) driver and ships the full feature set: JSONB, arrays, `RETURNING`, `ILIKE`, savepoints, full-text search, and serialization-failure / deadlock retry. It also auto-detects [Neon](https://neon.tech) and [Supabase](https://supabase.com) connection strings and applies provider-appropriate defaults.

> **Minimum version: PostgreSQL 15.0.** Older versions hard-fail at connect with a clear upgrade pointer. See [database support](https://nextlyhq.com/docs/database/support) for cloud-provider compatibility.

## Installation

Install the adapter alongside the `pg` driver:

**pnpm:**

```bash
pnpm add @nextlyhq/adapter-postgres pg
```

**npm:**

```bash
npm install @nextlyhq/adapter-postgres pg
```

**yarn:**

```bash
yarn add @nextlyhq/adapter-postgres pg
```

**bun:**

```bash
bun add @nextlyhq/adapter-postgres pg
```

## Configuration

Set `DB_DIALECT=postgresql` and `DATABASE_URL` in your environment. Nextly's runtime factory loads the adapter for you on first request -- no explicit wiring required.

```bash title=".env"
DB_DIALECT=postgresql
DATABASE_URL=postgres://nextly:nextly@localhost:5432/nextly_dev
```

### Programmatic usage

If you need an adapter outside the request pipeline (a script, a background worker, a test harness), create one directly:

```typescript title="src/db.ts"
import { createPostgresAdapter } from "@nextlyhq/adapter-postgres";

const adapter = createPostgresAdapter({
  url: process.env.DATABASE_URL!,
});

await adapter.connect();
```

You can also pass discrete connection fields instead of a URL:

```typescript
const adapter = createPostgresAdapter({
  host: "localhost",
  port: 5432,
  database: "nextly_dev",
  user: "nextly",
  password: "nextly",
});
```

## Connection string

Vanilla PostgreSQL:

```
postgres://user:password@host:port/database
```

[Neon](https://neon.tech) -- pooled connection from the project dashboard, e.g.:

```
postgres://user:password@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require
```

[Supabase](https://supabase.com) -- the connection string from **Project Settings -> Database**, e.g.:

```
postgres://postgres.<project-ref>:password@aws-0-us-east-1.pooler.supabase.com:5432/postgres
```

### Provider auto-detection

When the adapter connects, it inspects `DATABASE_URL` and applies provider-aware defaults:

| Detected provider | Triggered by URL containing | Defaults applied |
|---|---|---|
| `neon` | `.neon.tech` or `neon.` | `ssl: true`, `poolMax: 5`, `poolMin: 0`, `idleTimeoutMs: 10000`, `connectionTimeoutMs: 20000`, `statementTimeoutMs: 30000`, `retryAttempts: 5` (cold-start tolerance) |
| `supabase` | `.supabase.` or `supabase.` | `ssl: true`, `poolMax: 5`, `poolMin: 0`, `idleTimeoutMs: 30000`, `connectionTimeoutMs: 15000`, `statementTimeoutMs: 15000`, `retryAttempts: 3` |
| `standard` | anything else | `ssl: false`, `poolMax: 10`, `poolMin: 0`, `idleTimeoutMs: 30000`, `connectionTimeoutMs: 15000`, `statementTimeoutMs: 15000`, `retryAttempts: 3` |

Override the detection with the `DB_PROVIDER` env var (`neon`, `supabase`, or `standard`). User-provided config (`pool`, `ssl`, `statementTimeout`) always wins over provider defaults.

## SSL / TLS

For Neon and Supabase, SSL is on by default with `rejectUnauthorized: true`. For self-hosted PostgreSQL the default is no SSL -- enable it explicitly:

```typescript
const adapter = createPostgresAdapter({
  url: process.env.DATABASE_URL!,
  ssl: { rejectUnauthorized: true, ca: process.env.CA_CERT },
});
```

Pass `ssl: true` for a quick default, or an `SslConfig` object for full control:

| Option | Type | Notes |
|---|---|---|
| `rejectUnauthorized` | `boolean` | Default `true`. Setting to `false` disables certificate verification and logs a warning -- unsafe on untrusted networks. Provide a trusted `ca` cert instead. |
| `ca` | `string` | PEM-encoded CA certificate. |
| `cert` | `string` | Client certificate (mTLS). |
| `key` | `string` | Client private key (mTLS). |

## Connection pool

The adapter uses `pg.Pool`. Resolution order: **user config > provider defaults > hardcoded defaults** (`min: 0`, `max: 5`, `idleTimeoutMs: 30000`, `connectionTimeoutMs: 15000`).

| Option | Hardcoded default | Description |
|---|---|---|
| `pool.min` | `0` | Minimum connections. Stays at 0 to avoid eager creation while a serverless DB (Neon) is waking. |
| `pool.max` | `5` | Maximum connections. Conservative to stay under cloud limits. Next.js can spawn up to ~7 build workers; multiply your `pool.max` by that to sanity-check against your provider's connection cap. |
| `pool.idleTimeoutMs` | `30000` | Close idle connections after 30 s. |
| `pool.connectionTimeoutMs` | `15000` | Wait at most 15 s for a free connection from the pool. |
| `pool.maxLifetimeMs` | (driver default) | Recycle connections older than this. |

```typescript
const adapter = createPostgresAdapter({
  url: process.env.DATABASE_URL!,
  pool: {
    min: 2,
    max: 20,
    idleTimeoutMs: 30000,
    connectionTimeoutMs: 10000,
  },
});
```

TCP keepalive is always enabled with a 10-second initial delay, which prevents serverless databases from silently dropping idle connections between the pool smoke-test and the first real query.

## PostgreSQL-specific options

| Option | Type | Description |
|---|---|---|
| `applicationName` | `string` | Identifies your app in `pg_stat_activity`. Useful for debugging connection issues. |
| `statementTimeout` | `number` (ms) | Per-statement timeout. Queries exceeding this are cancelled by PostgreSQL. |
| `queryTimeout` | `number` (ms) | Driver-level query timeout. |
| `preparedStatements` | `boolean` | Default `true`. Disable for poolers that block extended-protocol prepares. |
| `queryTimeoutMs` | `number` (ms) | Default `15000`. Used by the adapter's internal timeout helpers. |

```typescript
const adapter = createPostgresAdapter({
  url: process.env.DATABASE_URL!,
  applicationName: "my-nextly-app",
  statementTimeout: 30000,
});
```

## Connect-time retry

Transient connection errors retry with linear backoff (1 s, 2 s, 3 s, ...) up to the provider's `retryAttempts` (5 for Neon, 3 elsewhere). Retryable Node.js error codes: `ETIMEDOUT`, `ECONNREFUSED`, `ECONNRESET`, `ENOTFOUND`, `EAI_AGAIN`. This handles serverless cold-starts, brief network hiccups, and DNS races during build parallelism.

Per-query retries kick in on `ETIMEDOUT`, `ECONNRESET`, `ECONNREFUSED` (up to 3 attempts, 500 ms / 1 s / 1.5 s backoff). Transactions automatically retry serialization failures (`40001`) and deadlocks (`40P01`) when you opt in via `transaction(work, { retryCount: 3, retryDelayMs: 100 })`.

## Migrations

Schema changes live as `.sql` files in your repo. Nextly's runtime never auto-applies them; you ship them with the migration CLI:

```bash
pnpm nextly migrate:create --name=add-posts-table   # scaffold a new migration
pnpm nextly migrate:status                          # show applied / pending / failed
pnpm nextly migrate:check                           # CI gate: integrity + drift, no DB connection
pnpm nextly migrate                                 # apply pending migrations
pnpm nextly migrate:fresh                           # destructive: drop all tables and re-apply
```

> **Forward-only.** There is no `migrate:rollback` or `migrate:down`. To undo an applied change, write a NEW corrective migration that reverses it. See [production migrations](https://nextlyhq.com/docs/guides/production-migrations).

`migrate:fresh` is destructive and prompts for confirmation -- use `--force` to skip the prompt in scripted local-dev flows. It is CLI-only and refuses to import from runtime code; never invoke it from a deployed app.

## Local development with Docker

Nextly ships a `docker-compose.yml` at the repo root with a Postgres service. The simplest way to run Postgres locally for a Nextly app:

```yaml title="docker-compose.yml"
services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: nextly_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: dev_password_change_in_production
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
```

```bash
docker compose up -d postgres
```

```bash title=".env"
DB_DIALECT=postgresql
DATABASE_URL=postgres://postgres:dev_password_change_in_production@localhost:5432/nextly_dev
```

To stop and remove:

```bash
docker compose down
```

## Production checklist

- **Use a managed provider with SSL on by default** (Neon, Supabase, AWS RDS, Cloud SQL, Railway). For self-hosted, set `ssl: { rejectUnauthorized: true, ca: process.env.CA_CERT }` explicitly.
- **Cap `pool.max` against your provider's connection limit.** Neon free tier allows ~25-30 simultaneous connections; with 7 Next.js build workers, `pool.max: 5` already lands at 35.
- **Use a connection pooler** for serverless / edge runtimes that fan out many short-lived workers: PgBouncer for self-hosted, Neon's pooler endpoint, Supabase's Supavisor pooler. Pick the transaction-mode pooler if you don't need session features (advisory locks, prepared statements, `LISTEN`/`NOTIFY`).
- **Set `applicationName`** so you can identify your app's connections in `pg_stat_activity`.
- **Set `statementTimeout`** (e.g., 30 s) to prevent runaway queries from holding connections.
- **Run migrations from CI** before each deploy, not from the deployed app. See [production migrations](https://nextlyhq.com/docs/guides/production-migrations).
- **Back up your database.** Most managed providers do this automatically; verify retention and restore procedure in staging.

## Capabilities

The adapter reports the following capabilities at runtime:

```typescript
{
  dialect: "postgresql",
  supportsJsonb: true,
  supportsJson: true,
  supportsArrays: true,
  supportsGeneratedColumns: true,
  supportsFts: true,
  supportsIlike: true,
  supportsReturning: true,
  supportsSavepoints: true,
  supportsOnConflict: true,
  maxParamsPerQuery: 65535,
  maxIdentifierLength: 63,
}
```

## Next steps

- [Database overview](https://nextlyhq.com/docs/database) -- compare all supported databases
- [Database support](https://nextlyhq.com/docs/database/support) -- minimum versions and cloud-provider compatibility
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- forward-only deploy patterns
- [Environment variables](https://nextlyhq.com/docs/configuration/environment) -- full env var reference
- [MySQL setup](https://nextlyhq.com/docs/database/mysql) -- alternative dialect
- [SQLite setup](https://nextlyhq.com/docs/database/sqlite) -- local demo only

---
title: MySQL
description: Set up Nextly with MySQL. Covers installation, connection strings, charset and collation, pool tuning, SSL, deadlock retry, migrations, and gaps versus PostgreSQL.
url: https://nextlyhq.com/docs/database/mysql
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

MySQL is supported. Use it when you already run MySQL or a MySQL-compatible cloud database. The adapter uses [`mysql2`](https://github.com/sidorares/node-mysql2) and emulates features MySQL lacks (`RETURNING`, `ILIKE`) on top of the shared `DrizzleAdapter` core.

> **MySQL is second-class to PostgreSQL in Nextly.** Some features Nextly relies on -- savepoints, JSONB, array types, native `ILIKE`, native `RETURNING` -- either don't exist or are emulated. PostgreSQL is the recommended production database; pick MySQL only if it is already part of your stack. See the [feature comparison](https://nextlyhq.com/docs/database#feature-comparison).

> **Minimum version: MySQL 8.0.** Older real MySQL hard-fails at connect with a clear upgrade pointer. MySQL-compatible variants (MariaDB, TiDB, Aurora MySQL, PlanetScale, Vitess) warn and proceed -- see [database support](https://nextlyhq.com/docs/database/support) for the variant policy.

## Installation

Install the adapter alongside the `mysql2` driver:

**pnpm:**

```bash
pnpm add @nextlyhq/adapter-mysql mysql2
```

**npm:**

```bash
npm install @nextlyhq/adapter-mysql mysql2
```

**yarn:**

```bash
yarn add @nextlyhq/adapter-mysql mysql2
```

**bun:**

```bash
bun add @nextlyhq/adapter-mysql mysql2
```

## Configuration

Set `DB_DIALECT=mysql` and `DATABASE_URL` in your environment.

```bash title=".env"
DB_DIALECT=mysql
DATABASE_URL=mysql://nextly:nextly@localhost:3306/nextly_dev
```

### Programmatic usage

```typescript title="src/db.ts"
import { createMySqlAdapter } from "@nextlyhq/adapter-mysql";

const adapter = createMySqlAdapter({
  url: process.env.DATABASE_URL!,
});

await adapter.connect();
```

Or pass discrete fields:

```typescript
const adapter = createMySqlAdapter({
  host: "localhost",
  port: 3306,
  database: "nextly_dev",
  user: "nextly",
  password: "nextly",
});
```

## Connection string

```
mysql://user:password@host:port/database
```

For example:

```bash title=".env"
DATABASE_URL=mysql://nextly:nextly@localhost:3306/nextly_dev
```

## Charset and collation

MySQL's default `utf8` is a 3-byte subset of UTF-8 that doesn't store emoji or many CJK characters. Use `utf8mb4` for everything Nextly stores. The adapter does **not** force a charset by default -- set it on the connection:

```typescript
const adapter = createMySqlAdapter({
  url: process.env.DATABASE_URL!,
  charset: "utf8mb4",
});
```

For a freshly created database, configure the server-level defaults too:

```sql
CREATE DATABASE nextly_dev
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;
```

The Docker setup at the repo root already runs MySQL with `--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci`.

## Connection pool

The adapter uses `mysql2`'s built-in pool. Defaults:

| Option | Default | Description |
|---|---|---|
| `pool.max` | `10` | Maps to `mysql2`'s `connectionLimit`. Maximum simultaneous connections. |
| `pool.idleTimeoutMs` | `30000` | Idle connection timeout (`mysql2` `idleTimeout`). |
| `pool.connectionTimeoutMs` | `10000` | Time to establish a new connection (`mysql2` `connectTimeout`). |

```typescript
const adapter = createMySqlAdapter({
  url: process.env.DATABASE_URL!,
  pool: {
    max: 20,
    idleTimeoutMs: 30000,
    connectionTimeoutMs: 10000,
  },
});
```

The pool is configured with `waitForConnections: true` and an unlimited queue (`queueLimit: 0`) -- callers wait for a free connection rather than failing fast.

## SSL / TLS

For production, enable SSL:

```typescript
const adapter = createMySqlAdapter({
  url: process.env.DATABASE_URL!,
  ssl: { rejectUnauthorized: true, ca: process.env.CA_CERT },
});
```

`ssl: true` enables SSL with driver defaults; `ssl: false` (or omitted) disables it. The full `SslConfig` shape (`rejectUnauthorized`, `ca`, `cert`, `key`) is the same as the [PostgreSQL adapter](https://nextlyhq.com/docs/database/postgres#ssl-tls).

## MySQL-specific options

| Option | Type | Default | Description |
|---|---|---|---|
| `charset` | `string` | (driver default) | Connection charset. Set to `utf8mb4` for full Unicode. |
| `timezone` | `string` | `'local'` | Timezone for date handling, e.g. `'+00:00'`. |
| `multipleStatements` | `boolean` | `false` | Allow multiple statements per query. Off for SQL-injection safety; the adapter forces `false`. |
| `dateStrings` | `boolean` | `false` | Return dates as strings instead of `Date` objects. The adapter forces `false`. |
| `queryTimeoutMs` | `number` (ms) | `15000` | Default for the adapter's internal timeout helpers. |

```typescript
const adapter = createMySqlAdapter({
  url: process.env.DATABASE_URL!,
  charset: "utf8mb4",
  timezone: "+00:00",
});
```

## Differences from PostgreSQL

The adapter handles each of these automatically, but they are worth knowing:

- **No `RETURNING`.** After `INSERT`, the adapter issues a follow-up `SELECT` (using `insertId` for auto-increment, otherwise filtering by inserted column values) to return the row. Bulk inserts return rows by reading `result.insertId..result.insertId + affectedRows - 1`.
- **No savepoints.** The MySQL adapter sets `savepoint`, `rollbackToSavepoint`, and `releaseSavepoint` to `undefined` on the transaction context for safety. Nested transactions are not supported.
- **No native `ILIKE`.** Case-insensitive search is rewritten to `LOWER(column) LIKE LOWER(value)`.
- **No JSONB.** MySQL has a native `JSON` type but no JSONB-style binary-indexed variant.
- **No array types.** Store arrays as JSON.
- **`ON DUPLICATE KEY UPDATE`** instead of `ON CONFLICT DO UPDATE`. The adapter normalizes upserts across both syntaxes.
- **Backtick identifiers.** MySQL uses `` `name` `` instead of `"name"`.
- **`?` placeholders.** MySQL uses positional `?` instead of `$1`, `$2`.

See the full feature matrix on the [database overview](https://nextlyhq.com/docs/database#feature-comparison).

## Deadlock retry

Transaction failures with MySQL error code 1213 (`ER_LOCK_DEADLOCK`) automatically retry when you opt in via `transaction()` options:

```typescript
await adapter.transaction(
  async (tx) => {
    await tx.insert("orders", orderData);
    await tx.update("inventory", stockUpdate, where);
  },
  {
    retryCount: 3,
    retryDelayMs: 100, // exponential backoff: 100ms, 200ms, 300ms
  },
);
```

Lock-wait timeouts (error 1205) and other failures are **not** retried -- they surface immediately so callers can decide what to do.

## Migrations

MySQL uses the same forward-only migration CLI as the other dialects:

```bash
pnpm nextly migrate:create --name=add-posts-table
pnpm nextly migrate:status
pnpm nextly migrate:check
pnpm nextly migrate
pnpm nextly migrate:fresh   # destructive, local-dev only
```

> **Forward-only.** There is no `migrate:rollback` or `migrate:down`. Write a new corrective migration to reverse a change. See [production migrations](https://nextlyhq.com/docs/guides/production-migrations).

## Local development with Docker

The repo's `docker-compose.yml` includes a MySQL profile. Start it with:

```bash
docker compose --profile mysql up -d mysql
```

That uses the same image and config as below. To run MySQL standalone:

```yaml title="docker-compose.yml"
services:
  mysql:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: dev_password
      MYSQL_DATABASE: nextly_dev
      MYSQL_USER: nextly
      MYSQL_PASSWORD: dev_password
    command: >
      --default-authentication-plugin=mysql_native_password
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:
```

```bash
docker compose up -d mysql
```

```bash title=".env"
DB_DIALECT=mysql
DATABASE_URL=mysql://nextly:dev_password@localhost:3306/nextly_dev
```

## Capabilities

The adapter reports the following capabilities at runtime:

```typescript
{
  dialect: "mysql",
  supportsJsonb: false,
  supportsJson: true,
  supportsArrays: false,
  supportsGeneratedColumns: true,
  supportsFts: true,
  supportsIlike: false,
  supportsReturning: false,
  supportsSavepoints: false,
  supportsOnConflict: true,
  maxParamsPerQuery: 65535,
  maxIdentifierLength: 64,
}
```

## Next steps

- [Database overview](https://nextlyhq.com/docs/database) -- compare all supported databases
- [Database support](https://nextlyhq.com/docs/database/support) -- minimum versions and the MySQL-compatible variants policy
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- forward-only deploy patterns
- [PostgreSQL setup](https://nextlyhq.com/docs/database/postgres) -- recommended for production
- [SQLite setup](https://nextlyhq.com/docs/database/sqlite) -- local demo only

---
title: SQLite
description: Set up Nextly with SQLite. SQLite is for local demos only -- this page covers when (and when not) to use it, install instructions, file paths, WAL mode, and limitations.
url: https://nextlyhq.com/docs/database/sqlite
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

> **SQLite is for local demos only.** Concurrent writes serialize on a single file lock, the database is fragile across process crashes and shared filesystems, there is no SSL or network access, and you will likely hit issues even during serious local development. Use **PostgreSQL** for any meaningful work -- `docker compose up -d postgres` is a one-liner. Set `DB_DIALECT=postgresql` and point `DATABASE_URL` at it. See the [PostgreSQL setup page](https://nextlyhq.com/docs/database/postgres#local-development-with-docker).

The SQLite adapter wraps [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) -- a synchronous C++ binding -- behind the same async `DrizzleAdapter` interface as the other dialects. It is in the codebase so a one-off demo, a quick `npx create-nextly-app@alpha` walk-through, or a tiny in-memory test suite Just Works without any infrastructure.

> **Minimum version: SQLite 3.38.** The pinned `better-sqlite3` ships a much newer SQLite (3.45+ at time of writing), so users on this package always pass the version check. See [database support](https://nextlyhq.com/docs/database/support).

## Installation

Install the adapter alongside the `better-sqlite3` driver:

**pnpm:**

```bash
pnpm add @nextlyhq/adapter-sqlite better-sqlite3
```

**npm:**

```bash
npm install @nextlyhq/adapter-sqlite better-sqlite3
```

**yarn:**

```bash
yarn add @nextlyhq/adapter-sqlite better-sqlite3
```

**bun:**

```bash
bun add @nextlyhq/adapter-sqlite better-sqlite3
```

`better-sqlite3` is a native module that compiles on `npm install`. Make sure your platform has a working C++ toolchain (`build-essential` on Linux, Xcode CLT on macOS, Visual Studio Build Tools on Windows).

## Configuration

Set `DB_DIALECT=sqlite` and either `DATABASE_URL` (with a `file:` prefix) or leave both unset to fall back to the default file path.

```bash title=".env"
DB_DIALECT=sqlite
DATABASE_URL=file:./data/nextly.db
```

If you set neither `DATABASE_URL` nor `SQLITE_PATH`, Nextly's runtime adapter factory defaults to `file:./data/nextly.db` and logs a warning in development. The adapter creates the file automatically if it does not exist.

### Programmatic usage

```typescript title="src/db.ts"
import { createSqliteAdapter } from "@nextlyhq/adapter-sqlite";

const adapter = createSqliteAdapter({
  url: "file:./data/nextly.db",
});

await adapter.connect();
```

## File path

The `url` option accepts a path with an optional `file:` prefix. The adapter strips the prefix before opening:

```typescript
createSqliteAdapter({ url: "file:./data/nextly.db" }); // relative to CWD
createSqliteAdapter({ url: "/absolute/path/nextly.db" }); // absolute
createSqliteAdapter({ url: "file:./data/nextly.db" });    // with prefix
```

If `memory: true` is set, the adapter ignores `url` and opens an in-memory database (`:memory:`).

## In-memory databases

For tests or ephemeral demos:

```typescript
const adapter = createSqliteAdapter({ memory: true });
```

In-memory databases are extremely fast but disappear when the process exits. Each adapter instance gets its own database -- they are not shared between processes or workers.

## SQLite-specific options

| Option | Type | Default | Description |
|---|---|---|---|
| `wal` | `boolean` | `true` | Enable WAL (Write-Ahead Logging) mode for better concurrent-read performance. Auto-disabled for in-memory and read-only databases. |
| `busyTimeout` | `number` (ms) | `5000` | How long to wait when the database is locked before throwing `SQLITE_BUSY`. |
| `foreignKeys` | `boolean` | `true` | Enable `PRAGMA foreign_keys = ON`. SQLite ships with this off by default; the adapter turns it on. |
| `memory` | `boolean` | `false` | Open an in-memory database. Overrides `url`. |
| `readonly` | `boolean` | `false` | Open in read-only mode. Disables WAL because changing journal mode requires write access. |
| `queryTimeoutMs` | `number` (ms) | `15000` | Default for the adapter's internal timeout helpers. |

```typescript
const adapter = createSqliteAdapter({
  url: "file:./data/nextly.db",
  wal: true,
  foreignKeys: true,
  busyTimeout: 5000,
});
```

## WAL mode

WAL is enabled by default for file-based databases. It allows multiple concurrent readers while a writer is active, significantly reducing read-side contention. WAL is automatically skipped when:

- The database is in-memory (`:memory:` does not need WAL).
- The database is opened read-only (changing the journal mode requires write access).

WAL mode creates two sidecar files alongside the database: `<name>.db-wal` and `<name>.db-shm`. Don't delete them while the app is running.

## Environment variables

You can configure the database path two ways:

```bash title=".env"
# Option 1: with a file: prefix in DATABASE_URL
DB_DIALECT=sqlite
DATABASE_URL=file:./data/nextly.db

# Option 2: SQLITE_PATH alongside DB_DIALECT (no DATABASE_URL needed)
DB_DIALECT=sqlite
SQLITE_PATH=./data/nextly.db
```

Either is fine; pick one consistently. If both are unset, the runtime defaults to `file:./data/nextly.db`.

## Limitations

SQLite is intentionally simple, and that simplicity is the trade-off:

- **Single writer.** Only one write operation at a time -- writes are globally serialized regardless of WAL mode. Concurrent writes from different processes wait on the busy timeout, then fail. Not viable for any real workload.
- **No connection pooling.** A single file handle. `getPoolStats()` returns `null`. There is no path to scale write throughput across connections.
- **No SSL / TLS.** SQLite is a local file; remote access does not exist. If your app is in another container, the file is not.
- **Fragile across crashes and shared filesystems.** Process crashes during writes can leave WAL files in inconsistent states; running over NFS / SMB / Docker bind mounts can corrupt the database.
- **Weaker schema operations.** SQLite's `ALTER TABLE` is much more limited than PostgreSQL or MySQL -- some column changes require recreating the table. Nextly's migration model handles this where possible, but you will hit cases the other dialects handle natively.
- **Weaker types.** SQLite uses dynamic typing with type affinity; numbers, strings, and dates flow through with less validation than PostgreSQL or MySQL provide.
- **No `ILIKE`.** Case-insensitive search uses `LOWER(column) LIKE LOWER(value)`.
- **No JSONB.** JSON is stored as TEXT and queried with `json_extract()`. No JSON indexes.
- **No array types.** Store arrays as JSON text.
- **999 parameter limit per query.** PostgreSQL and MySQL allow 65,535. Bulk operations may need batching at lower thresholds for SQLite.
- **No native full-text search by default.** FTS5 ships with `better-sqlite3` but is not wired through Nextly's query builder.

## Implementation notes

- The adapter wraps `better-sqlite3`'s synchronous API in `Promise.resolve(...)` to match the async `DrizzleAdapter` contract.
- `RETURNING` is supported (SQLite 3.35+) and used automatically for `INSERT` / `UPDATE` / `DELETE`.
- Placeholders: the base adapter emits `$1`, `$2` -- the SQLite adapter rewrites them to `?` before execution.
- Transactions use `BEGIN IMMEDIATE` to acquire a write lock at the start, which avoids the upgrade-deadlock pattern where two readers try to become writers concurrently.
- Savepoints are fully supported for nested transactions.
- JavaScript values are sanitized before binding: `boolean -> 0/1`, `Date -> ISO string`, plain objects -> `JSON.stringify(...)`, `undefined -> null`.

## Migrations

The migration CLI works the same as for the other dialects:

```bash
pnpm nextly migrate:create --name=add-posts-table
pnpm nextly migrate:status
pnpm nextly migrate:check
pnpm nextly migrate
pnpm nextly migrate:fresh   # destructive
```

> **Forward-only.** No `migrate:rollback` or `migrate:down`. Write a new corrective migration to reverse a change. See [production migrations](https://nextlyhq.com/docs/guides/production-migrations).

## Capabilities

The adapter reports the following capabilities at runtime:

```typescript
{
  dialect: "sqlite",
  supportsJsonb: false,
  supportsJson: true,
  supportsArrays: false,
  supportsGeneratedColumns: true,
  supportsFts: true,
  supportsIlike: false,
  supportsReturning: true,
  supportsSavepoints: true,
  supportsOnConflict: true,
  maxParamsPerQuery: 999,
  maxIdentifierLength: 128,
}
```

## Next steps

- [PostgreSQL setup](https://nextlyhq.com/docs/database/postgres) -- the database you should use instead
- [Database overview](https://nextlyhq.com/docs/database) -- feature comparison across dialects
- [Database support](https://nextlyhq.com/docs/database/support) -- minimum versions
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- forward-only deploy patterns

---
title: Database support and version requirements
description: Minimum supported database versions, cloud-provider compatibility, and the warn-and-proceed policy for MySQL-compatible variants.
url: https://nextlyhq.com/docs/database/support
---

Nextly supports PostgreSQL, MySQL, and SQLite through dedicated adapter packages. Each `connect()` call queries the database for its version string and validates it against the minimum Nextly requires. Real PostgreSQL / MySQL / SQLite below minimum hard-fails with an upgrade pointer; recognized MySQL-compatible variants warn and proceed; completely unparseable strings hard-fail at boot rather than silently letting you hit cryptic errors mid-apply.

## Minimum versions

| Database | Minimum | Why |
|----------|---------|-----|
| PostgreSQL | **15.0** | Native `MERGE`, modern btree dedup, full transactional DDL parity. PG 15 is the oldest version still in upstream support. |
| MySQL | **8.0** | Native `RENAME COLUMN` (replaces MySQL 5.7's `CHANGE COLUMN` recreate dance). 8.0 is the only modern major in active upstream support. |
| SQLite | **3.38** | Native `unixepoch()`, strict tables, improved query planner. 3.38 ships with most distributions; the pinned `better-sqlite3` ships an even newer build. |

If your database reports a version below the minimum, the adapter's `connect()` throws `UnsupportedDialectVersionError` with a message that links back to this page.

## Cloud-provider compatibility

### PostgreSQL — supported

| Provider | Status | Notes |
|----------|--------|-------|
| Standard PostgreSQL (self-hosted, Docker, RDS, Cloud SQL) | Supported | Any 15.0+ build works without configuration. |
| [Neon](https://neon.tech) | Supported | Auto-detected from URL pattern (`*.neon.tech`). Cold-start retries built into the adapter. SSL on by default. Vercel projects also reach Postgres through Neon since the [Vercel Postgres -> Neon migration](https://neon.com/docs/guides/vercel-postgres-transition-guide) in late 2024. |
| [Supabase](https://supabase.com) | Supported | Auto-detected from URL pattern (`*.supabase.com` / `*.supabase.co`). SSL on by default. Use the connection-pooler endpoint from **Project Settings -> Database**. |
| AWS RDS / Aurora PostgreSQL (PG-flavored, not MySQL Aurora) | Supported | RDS reports as standard PostgreSQL; PG-compatible Aurora majors pass the version check. |
| Railway | Supported | Standard PostgreSQL image. |
| Cloud SQL (Postgres) | Supported | Standard PostgreSQL with SSL recommended. |

### MySQL — supported with warnings for variants

Nextly is regression-tested against **real MySQL 8.0+** only. MySQL-protocol-compatible variants are recognized at connect, log a one-time warning through the adapter's logger, and proceed:

| Variant | Behavior |
|---------|----------|
| **MariaDB** (any version) | Warning + proceed. Wire-compatible with MySQL; most operations work but feature drift is possible on advanced SQL. |
| **TiDB** | Warning + proceed. Advertises MySQL 5.7 protocol; modern TiDB versions support enough MySQL 8 features for typical CMS workloads. |
| **AWS Aurora MySQL** | Warning + proceed. Internal version reporting differs from upstream MySQL. |
| **PlanetScale / Vitess** | Warning + proceed. Vitess-based MySQL-compatible layer. Caveat: PlanetScale's serverless connection model (no foreign keys by default, branched schemas) may surface other issues. |

The warning text routes through your adapter's configured logger and looks like:

```
Detected mariadb ('10.11.5-MariaDB-...'). Nextly is regression-tested
against real MySQL 8.0+ only; this MySQL-compatible variant is not
officially supported in v1 but most operations should work. See
https://nextlyhq.com/docs/database/support.
```

If a MySQL response is **completely unparseable** -- no version number AND no variant token detected -- Nextly hard-fails at boot.

If you hit a variant-specific bug, please file an issue with your variant + version. v2 will add opt-in regression coverage for individual variants.

### SQLite — supported

| Provider | Status | Notes |
|----------|--------|-------|
| `better-sqlite3` (default) | Supported | Bundled SQLite ships with the pinned `better-sqlite3` (currently 3.45+). |
| `bun:sqlite` | Not yet supported | No adapter. |
| `libSQL` / Turso | Not yet supported | No adapter. |

## Production-migrations rules

- **Forward-only.** No `migrate:rollback` or `migrate:down` exists. To undo a deployed change, write a NEW migration that reverses it.
- **Schema lives in your repo.** `nextly migrate:create --name=...` scaffolds an empty migration; you commit it; CI applies it before deploy.
- **The deployed app never touches the schema.** `migrate:fresh` is destructive and CLI-only -- it is rejected if imported from runtime code.

For platform-specific deploy patterns (Vercel + GitHub Actions, Vercel build step, "other platforms"), see [production migrations](https://nextlyhq.com/docs/guides/production-migrations).

## Upgrade guidance

### PostgreSQL

If you are on PG 12 / 13 / 14: most managed providers offer in-place major-version upgrades. Run `SELECT version()` to confirm; consult your provider's docs for the upgrade procedure. For self-hosted, follow the standard `pg_upgrade` workflow.

### MySQL

If you are on MySQL 5.7: upstream support ended in October 2023. Your provider almost certainly offers a managed upgrade to 8.0. Test the upgrade in staging first -- some 5.7 SQL is incompatible with 8.0 reserved-word changes.

### SQLite

Bundled with `better-sqlite3`. Upgrade by bumping that package. If you maintain your own SQLite linkage, install at least 3.38 from your distribution's package manager.

## Why the policy is hybrid

Nextly draws three different lines at connect time:

1. **Real PG / MySQL / SQLite below minimum -> hard-fail.** Schema migrations rely on dialect features at the minimum-version threshold (`RENAME COLUMN`, transactional DDL, `MERGE`, strict tables). A real MySQL 5.7 user who proceeded would hit confusing mid-apply errors during their first schema change.
2. **Recognized variant (MariaDB, TiDB, Aurora MySQL, PlanetScale, Vitess) -> warn and proceed.** These are real cloud databases millions of developers run. Hard-failing them on first install would lock out legitimate users from a CMS that mostly works on their stack. The warning makes the trade-off explicit.
3. **Completely unparseable string -> hard-fail.** If we cannot find a version number AND cannot detect a variant token, we surface the issue immediately rather than silently proceeding into cryptic errors.

The error and warning paths both link to this page so users know the upgrade lever or, for variants, that they are running on best-effort support.

## When the version check runs

`checkDialectVersion()` runs inside each adapter's `connect()`, after the connection is verified alive but before the adapter marks itself ready. PostgreSQL retries transient network failures (Neon cold starts, `EAI_AGAIN`) without re-running the version query in a tight loop; only confirmed version mismatches throw `UnsupportedDialectVersionError`.

## Catching the error

The error implements adapter-drizzle's `DatabaseError` interface, so existing `isDatabaseError()` type guards continue to work. You can also branch on the `kind` field directly:

```ts
import { UnsupportedDialectVersionError } from "@nextlyhq/adapter-drizzle/version-check";

declare const adapter: import("@nextlyhq/adapter-drizzle").DrizzleAdapter;

try {
  await adapter.connect();
} catch (error) {
  if (error instanceof UnsupportedDialectVersionError) {
    console.error(
      `Detected ${error.detectedVersion}, required ${error.requiredVersion}`,
    );
    process.exit(1);
  }
  throw error;
}
```

## Next steps

- [Database overview](https://nextlyhq.com/docs/database) -- feature comparison across dialects
- [PostgreSQL setup](https://nextlyhq.com/docs/database/postgres) -- recommended for production
- [MySQL setup](https://nextlyhq.com/docs/database/mysql) -- supported with caveats
- [SQLite setup](https://nextlyhq.com/docs/database/sqlite) -- local demo only
- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- forward-only deploy patterns

---
title: Direct API
description: Server-side API for querying and mutating data directly from Next.js Server Components, server actions, and route handlers. No HTTP, no serialisation overhead.
url: https://nextlyhq.com/docs/api-reference/direct-api
---

The Direct API is the recommended way to read and write Nextly data on the server. It calls into the runtime's service layer in-process, so there is no HTTP round-trip and no JSON serialisation. Use it from Server Components, server actions, route handlers, hooks — anywhere your code already runs in a trusted Node.js context.

If you need to reach the same data from the browser, a mobile app, or a third-party service, use the [REST API](https://nextlyhq.com/docs/api-reference/rest-api) instead.

## Initialisation

Import `getNextly` (or the lazy `nextly` convenience object) from the runtime package:

```typescript title="app/posts/page.tsx"
import { getNextly } from "nextly";

import config from "../../nextly.config";

const nextly = await getNextly({ config });

const result = await nextly.find({
  collection: "posts",
  where: { status: { equals: "published" } },
  sort: "-publishedAt",
  limit: 10,
});

console.log(result.items);      // Post[]
console.log(result.meta.total); // number
```

The module-level `nextly` export resolves the singleton lazily on each call, so it is safe to import at module scope:

```typescript
import { nextly } from "nextly";

const posts = await nextly.find({ collection: "posts", limit: 10 });
```

`getNextly({ config })` and `nextly` reach the same singleton. `getNextly` takes your loaded config and can initialise the runtime itself, so it is safe to call from anywhere; `nextly` is the lighter import for code that runs after initialisation, and throws if nothing has initialised the runtime yet (this happens automatically when your Next.js route handler boots through `createDynamicHandlers`).

## TypeScript support

Run `nextly generate:types` after defining your collections to get full type inference on every Direct API call:

```typescript
const posts = await nextly.find({ collection: "posts" });
// posts.items is typed as Post[] when generated types are present.

const invalid = await nextly.find({ collection: "nonexistent" });
// Type error: collection slug not in the generated union.
```

The generator writes a `payload-types.ts` (or whatever path you set in `typescript.outputFile`) that augments the runtime's `GeneratedTypes` interface via `declare module "nextly"`. See [Configuration → typescript](https://nextlyhq.com/docs/configuration/nextly-config) for the config surface.

## Access control

By default, Direct API calls run with `overrideAccess: true` — access control is bypassed because the Direct API runs in trusted server code. If you want collection access control, field-level rules, and row-level filters to apply (for example when forwarding a user request through a server action), pass `overrideAccess: false` and supply a `user`:

```typescript
const visiblePosts = await nextly.find({
  collection: "posts",
  overrideAccess: false,
  user: { id: "user-123", role: "editor" },
});
```

`overrideAccess`, `user`, and `context` flow through every hook the operation triggers. Anything you put in `context` is accessible inside hooks via `req.context`.

## Collections

These methods hang off the `nextly` root and operate on collection entries. The shapes shown below match the canonical Phase 4 envelopes (`ListResult<T>`, `MutationResult<T>`, etc.) — verify against [`packages/nextly/src/direct-api/types/shared.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/nextly/src/direct-api/types/shared.ts) if you need the exact TypeScript definitions.

### find

Find multiple documents in a collection. Returns the canonical list envelope `{ items, meta }`.

```typescript
const result = await nextly.find({
  collection: "posts",
  where: { status: { equals: "published" } },
  sort: "-publishedAt",
  limit: 10,
  page: 1,
  depth: 2,
});

result.items;            // Post[]
result.meta.total;       // total matching rows
result.meta.page;        // current page (1-indexed)
result.meta.limit;       // page size
result.meta.totalPages;  // total pages
result.meta.hasNext;     // boolean
result.meta.hasPrev;     // boolean
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `collection` | `string` | required | Collection slug. |
| `where` | `WhereFilter` | — | Filter conditions (see [Querying](#querying)). |
| `limit` | `number` | `10` | Page size. |
| `page` | `number` | `1` | Page number, 1-indexed. |
| `sort` | `string` | — | `field` for ascending, `-field` for descending. |
| `depth` | `number` | `0` | Relationship population depth. |
| `select` | `Record<string, boolean>` | — | Whitelist or blacklist fields. |
| `populate` | `Record<string, boolean \| PopulateOptions>` | — | Per-field population control. |
| `pagination` | `boolean` | `true` | Set `false` to return all matching rows without paging. |
| `richTextFormat` | `"json" \| "html" \| "both"` | `"json"` | Output format for rich text fields. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |
| `context` | `Record<string, unknown>` | — | Custom data forwarded to hooks via `req.context`. |
| `disableErrors` | `boolean` | `false` | Return an empty result instead of throwing. |

### findByID

Find a single document by ID. Returns the bare document, or throws `NextlyError` (`NOT_FOUND`) when no match is found.

```typescript
const post = await nextly.findByID({
  collection: "posts",
  id: "abc-123",
  depth: 2,
});
```

Pass `disableErrors: true` to get `null` instead of an exception:

```typescript
const post = await nextly.findByID({
  collection: "posts",
  id: "maybe-exists",
  disableErrors: true,
});

if (post) {
  console.log(post.title);
}
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `collection` | `string` | required | Collection slug. |
| `id` | `string` | required | Document ID. |
| `depth` | `number` | `0` | Relationship population depth. |
| `select` | `Record<string, boolean>` | — | Whitelist or blacklist fields. |
| `populate` | `Record<string, boolean \| PopulateOptions>` | — | Per-field population control. |
| `richTextFormat` | `"json" \| "html" \| "both"` | `"json"` | Output format for rich text fields. |
| `disableErrors` | `boolean` | `false` | Return `null` instead of throwing. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |

**Returns:** `T | null`.

### create

Create a new document. Returns the canonical mutation envelope `{ message, item }`.

```typescript
const created = await nextly.create({
  collection: "posts",
  data: {
    title: "Hello world",
    content: "My first post",
    status: "draft",
  },
});

created.message;  // e.g. "Posts created."
created.item;     // the created Post
created.item.id;
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `collection` | `string` | required | Collection slug. |
| `data` | `Record<string, unknown>` | required | Document data. |
| `draft` | `boolean` | `false` | Save as draft. |
| `disableVerificationEmail` | `boolean` | `false` | Skip the verification email when creating users. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |
| `context` | `Record<string, unknown>` | — | Forwarded to hooks. |

**Returns:** `MutationResult<T>` (`{ message, item }`). Throws `NextlyError` (`VALIDATION_ERROR`) when the payload fails validation; the thrown error carries field-level details on `error.publicData.errors`.

### update

Update by ID, or update the first match of a `where` clause. Either `id` or `where` is required.

```typescript
// By ID
const updated = await nextly.update({
  collection: "posts",
  id: "abc-123",
  data: { status: "published", publishedAt: new Date() },
});

updated.item;     // the updated Post
updated.message;  // "Posts updated."

// By where (single match path — use bulk endpoints for true bulk semantics)
const archived = await nextly.update({
  collection: "posts",
  where: { status: { equals: "draft" } },
  data: { status: "archived" },
});
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `collection` | `string` | required | Collection slug. |
| `id` | `string` | — | Document ID. Either `id` or `where` is required. |
| `where` | `WhereFilter` | — | Where clause for the by-query path. |
| `data` | `Record<string, unknown>` | required | Update payload. |
| `draft` | `boolean` | `false` | Autosave as draft. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |

**Returns:** `MutationResult<T>` (`{ message, item }`). Throws `NextlyError` (`NOT_FOUND`) when the where clause matches nothing.

### delete

Delete by ID or by `where`. The two paths return different shapes because a multi-row delete cannot collapse into a single mutation envelope, and the return type is the union either way — narrow it before reading a path-specific field:

```typescript
// By ID — returns MutationResult<{ id }>
const deleted = await nextly.delete({
  collection: "posts",
  id: "abc-123",
});

if ("item" in deleted) {
  deleted.message; // "Posts deleted."
  deleted.item.id; // "abc-123"
}

// By where — returns DeleteResult ({ deleted: boolean, ids: string[] })
const archived = await nextly.delete({
  collection: "posts",
  where: { status: { equals: "archived" } },
});

if ("ids" in archived) {
  console.log("Deleted IDs:", archived.ids);
}
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `collection` | `string` | required | Collection slug. |
| `id` | `string` | — | Document ID. Either `id` or `where` is required. |
| `where` | `WhereFilter` | — | Where clause for the bulk-by-query path. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |

**Returns:** `MutationResult<{ id: string }> | DeleteResult`.

### count

Count documents matching a query. Returns `{ total }`.

```typescript
const { total } = await nextly.count({
  collection: "posts",
  where: { status: { equals: "published" } },
});

console.log("Published posts:", total);
```

**Returns:** `CountResult` (`{ total: number }`).

### bulkDelete

Delete many documents by IDs with first-class partial-success semantics. Use this when you need the per-item failure detail that `delete({ where })` cannot give you.

```typescript
const result = await nextly.bulkDelete({
  collection: "posts",
  ids: ["post-1", "post-2", "post-3"],
});

result.successes;    // [{ id: "post-1" }, { id: "post-2" }]
result.failures;     // [{ id: "post-3", code: "NOT_FOUND", message: "..." }]
result.total;        // 3
result.successCount; // 2
result.failedCount;  // 1
```

**Returns:** `BulkOperationResult<T>` — `{ successes, failures, total, successCount, failedCount }`. The HTTP request always returns 200 unless the input itself is malformed; per-item errors live in the body's `failures` array.

### duplicate

Duplicate a document. Optionally pass field overrides — overridden fields replace the copied values.

```typescript
const copy = await nextly.duplicate({
  collection: "posts",
  id: "abc-123",
  overrides: { title: "Copy of Original Post" },
});

copy.message;  // "Posts duplicated."
copy.item.id;  // new id
```

**Returns:** `MutationResult<T>` (`{ message, item }`).

## Singles

Singles are single-document entities for site-wide settings (navigation, footer, theme, etc.). The Direct API method names still use the legacy "global" naming.

### findSingle

Get a single's content by slug. Returns the bare document.

```typescript
const settings = await nextly.findSingle({
  slug: "site-settings",
  depth: 1,
});

console.log(settings.siteName);
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `slug` | `string` | required | Single slug. |
| `depth` | `number` | `0` | Relationship population depth. |
| `select` | `Record<string, boolean>` | — | Whitelist or blacklist fields. |
| `populate` | `Record<string, boolean \| PopulateOptions>` | — | Per-field population control. |
| `richTextFormat` | `"json" \| "html" \| "both"` | `"json"` | Rich text output format. |
| `overrideAccess` | `boolean` | `true` | Bypass access control. |
| `user` | `{ id, role? }` | — | Required when `overrideAccess: false`. |

**Returns:** the bare single document (`T`).

### updateSingle

Update a single's content by slug. Returns the same `{ message, item }` envelope
the collection mutations return, so every mutation reports its outcome the same
way.

```typescript
const { item, warnings } = await nextly.updateSingle({
  slug: "site-settings",
  data: {
    siteName: "My Awesome Site",
    maintenanceMode: false,
  },
});

item.siteName; // "My Awesome Site"

if (warnings) {
  // The document was saved. A hook that runs after the write committed threw,
  // so a side effect did not happen — each warning names the phase, the single
  // and the error code.
}
```

**Returns:** `MutationResult<T>` — `{ message, item, warnings? }`.

`warnings` is present only when a post-commit hook failed. The write itself
succeeded: an `afterChange` hook cannot un-save the document, so the operation
reports success and the failed side effect is reported beside it rather than
being turned into an error that would invite a retry.

### findSingles

List the actual content for every registered single. Returns the legacy list shape `{ docs, totalDocs, limit, offset }` (this method has not yet been migrated to the canonical `{ items, meta }` envelope).

```typescript
const result = await nextly.findSingles();

result.docs.forEach(({ slug, label, data }) => {
  console.log(`${label} (${slug}):`, data);
});

// Filter by source
const codeSingles = await nextly.findSingles({ source: "code" });

// Search by name or slug
const settingsLike = await nextly.findSingles({ search: "settings" });
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `source` | `"code" \| "ui" \| "built-in"` | — | Filter by definition source. |
| `migrationStatus` | `"synced" \| "pending" \| "generated" \| "applied" \| "failed"` | — | Filter by current schema state. |
| `locked` | `boolean` | — | Return only locked or only unlocked singles. |
| `search` | `string` | — | Substring match on slug or label. |
| `limit` | `number` | — | Max results. |
| `offset` | `number` | `0` | Skip count. |

**Returns:** `SingleListResult` — `{ docs: SingleEntry[], totalDocs, limit, offset }`. Each `SingleEntry` is `{ slug, label, data }`.

## Email

The `nextly.email.*` namespace sends transactional email through whichever provider is configured (database-default first, code-config fallback second).

### email.send

Send a raw HTML email.

```typescript
const result = await nextly.email.send({
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Welcome to Nextly</p>",
  text: "Welcome to Nextly",
});

result.success;    // boolean
result.messageId;  // provider-assigned ID (when successful)
result.error;      // error string (when failed)
```

| Argument | Type | Description |
|---|---|---|
| `to` | `string \| string[]` | Recipient(s). |
| `subject` | `string` | Subject line. |
| `html` | `string` | HTML body. |
| `text` | `string` | Plain-text fallback. |
| `from` | `string` | Override the sender. |
| `providerId` | `string` | Use a specific provider instead of the default. |
| `attachments` | `EmailAttachmentInput[]` | Media-library attachments. |

**Returns:** `SendEmailResult` — `{ success, messageId?, error? }`.

### email.sendWithTemplate

Send an email rendered from a database template.

```typescript
const result = await nextly.email.sendWithTemplate({
  to: "user@example.com",
  template: "welcome-email",
  variables: { name: "Alice", productName: "Nextly" },
});
```

| Argument | Type | Description |
|---|---|---|
| `to` | `string \| string[]` | Recipient(s). |
| `template` | `string` | Template slug. |
| `variables` | `Record<string, string>` | Substituted into the template. |
| `from` | `string` | Override the sender. |
| `providerId` | `string` | Use a specific provider. |
| `attachments` | `EmailAttachmentInput[]` | Merged with the template's defaults at send time. |

**Returns:** `SendEmailResult` — `{ success, messageId?, error? }`.

## Auth

The Direct API exposes auth operations as methods on the root `nextly` object. They speak directly to the auth service and are useful in server actions and admin scripts.

### login

Verify credentials and issue a signed JWT. The token expiry is 30 days. The Direct API does **not** set cookies — that responsibility belongs to your route handler / server action wrapper.

```typescript
const result = await nextly.login({
  email: "user@example.com",
  password: "secure-password",
});

result.user;   // { id, email, name, image, ... }
result.token;  // string (JWT)
result.exp;    // unix timestamp
```

**Returns:** `LoginResult` — `{ user, token, exp }`. Throws `NextlyError` (`AUTH_INVALID_CREDENTIALS`) on bad credentials.

### logout

No-op for the Direct API — there is no session state to clear at this layer. Clear your auth cookies in the route handler that wraps the call.

```typescript
await nextly.logout();
```

### register

Register a new user with email + password.

```typescript
const result = await nextly.register({
  email: "newuser@example.com",
  password: "secure-password",
  name: "New User",
});

result.user; // { id, email, name }
```

**Returns:** `{ user }`. Throws `NextlyError` (`VALIDATION_ERROR`, `CONFLICT`) on validation failure or duplicate email.

### me / updateMe

Both require an explicit `user.id` because the Direct API has no implicit session.

```typescript
const profile = await nextly.me({ user: { id: "user-123" } });
profile.user; // current user record (or null)

const updated = await nextly.updateMe({
  user: { id: "user-123" },
  data: { name: "New Display Name" },
});
```

**Returns:** `AuthResult` — `{ user, permissions? }`. Throws `NextlyError` (`NOT_FOUND`) if the user does not exist.

### changePassword

```typescript
await nextly.changePassword({
  user: { id: "user-123" },
  currentPassword: "old",
  newPassword: "new-secure-password",
});
```

**Returns:** `{ success: true }`. Throws `NextlyError` (`AUTH_INVALID_CREDENTIALS`) when the current password is wrong.

### forgotPassword

Initiate a password reset. Always returns `success: true` — even when the email is unknown — to avoid user enumeration. Pass `disableEmail: true` to receive the raw token instead of the runtime mailing it for you.

```typescript
const result = await nextly.forgotPassword({
  email: "user@example.com",
});

// With disableEmail
const tokenResult = await nextly.forgotPassword({
  email: "user@example.com",
  disableEmail: true,
});
console.log(tokenResult.token); // raw token, you mail it yourself
```

**Returns:** `{ success: true, token? }`.

### resetPassword

Consume a reset token and set a new password.

```typescript
const result = await nextly.resetPassword({
  token: "reset-token-from-email",
  password: "new-password",
});

result.email; // address whose password was reset
```

**Returns:** `{ success: true, email? }`. Throws `NextlyError` (`VALIDATION_ERROR` / `NOT_FOUND`) when the token is invalid or expired.

### verifyEmail

```typescript
await nextly.verifyEmail({ token: "verification-token" });
```

**Returns:** `{ success: true, email? }`.

## Other namespaces

The Direct API also exposes typed namespaces for users, media, forms, field groups, email providers + templates, RBAC, API keys, and access checks. They follow the same `find` / `findByID` / `create` / `update` / `delete` shape and use the canonical `ListResult<T>` and `MutationResult<T>` envelopes:

| Namespace | Purpose | Key methods |
|---|---|---|
| `nextly.users` | User records | `find`, `findOne`, `findByID`, `create`, `update`, `delete` |
| `nextly.media` | Media library | `upload`, `find`, `findByID`, `update`, `delete`, `bulkDelete`, `folders.list`, `folders.create` |
| `nextly.forms` | Form-builder forms | `find`, `findBySlug`, `submit`, `submissions` |
| `nextly.fieldGroups` | Reusable field group definitions | `find`, `findBySlug`, `create`, `update`, `delete` |
| `nextly.emailProviders` | Provider CRUD | `find`, `findByID`, `create`, `update`, `delete`, `setDefault`, `test` |
| `nextly.emailTemplates` | Template CRUD + preview + layout | `find`, `findByID`, `findBySlug`, `create`, `update`, `delete`, `preview`, `getLayout`, `updateLayout` |
| `nextly.userFields` | Custom user field definitions | `find`, `findByID`, `create`, `update`, `delete`, `reorder` |
| `nextly.roles` | RBAC roles | `find`, `findByID`, `create`, `update`, `delete`, `getPermissions`, `setPermissions` |
| `nextly.permissions` | RBAC permissions | `find`, `findByID`, `create`, `delete` |
| `nextly.access` | Permission checks | `check`, `checkApiKey` |
| `nextly.apiKeys` | API keys | `list`, `findByID`, `create`, `update`, `revoke` |

The full TypeScript surface is generated from [`packages/nextly/src/direct-api/namespaces/`](https://github.com/nextlyhq/nextly/tree/main/packages/nextly/src/direct-api/namespaces).

## Querying

`where` accepts a structured filter object. Conditions on the same level are AND-ed; use `and` and `or` for explicit groupings.

### Operators

| Operator | Description | Example |
|---|---|---|
| `equals` | Exact match | `{ status: { equals: "published" } }` |
| `not_equals` | Not equal | `{ status: { not_equals: "draft" } }` |
| `greater_than` | `>` | `{ price: { greater_than: 100 } }` |
| `greater_than_equal` | `>=` | `{ price: { greater_than_equal: 100 } }` |
| `less_than` | `<` | `{ price: { less_than: 50 } }` |
| `less_than_equal` | `<=` | `{ price: { less_than_equal: 50 } }` |
| `like` | SQL `LIKE` (case-sensitive) | `{ title: { like: "%hello%" } }` |
| `contains` | Case-insensitive substring (`ILIKE`) | `{ title: { contains: "hello" } }` |
| `search` | Alias for `contains` | `{ title: { search: "hello" } }` |
| `in` | Value in array | `{ status: { in: ["draft", "published"] } }` |
| `not_in` | Value not in array | `{ status: { not_in: ["archived"] } }` |
| `exists` | Field is non-null when `true`, null when `false` | `{ image: { exists: true } }` |

Point fields also support `near` and `within` geo operators; these are evaluated in the application layer rather than pushed to the database.

### Combining conditions

Same-level keys are implicitly AND-ed:

```typescript
where: {
  status: { equals: "published" },
  category: { equals: "news" },
}
```

Use `and` or `or` to express more complex shapes:

```typescript
const posts = await nextly.find({
  collection: "posts",
  where: {
    and: [
      { status: { equals: "published" } },
      {
        or: [
          { category: { equals: "news" } },
          { category: { equals: "featured" } },
        ],
      },
      { publishedAt: { less_than: new Date().toISOString() } },
    ],
  },
});
```

## Sorting

Pass a single field name. Prefix with `-` for descending:

```typescript
await nextly.find({ collection: "posts", sort: "-publishedAt" });
await nextly.find({ collection: "posts", sort: "title" });
```

## Selecting fields

Use `select` to whitelist or blacklist fields on the response. `true` includes, `false` excludes:

```typescript
await nextly.find({
  collection: "posts",
  select: { title: true, slug: true, publishedAt: true },
});
```

## Depth

`depth` controls how many levels of relationship and upload fields to populate:

- `0` (default): return relationship IDs as strings.
- `1`: populate direct relationships with their full document.
- `2+`: populate nested relationships up to the requested depth.

```typescript
const posts = await nextly.find({ collection: "posts", depth: 0 });
posts.items[0].author; // "user-abc"

const populated = await nextly.find({ collection: "posts", depth: 1 });
populated.items[0].author; // { id: "user-abc", name: "John", ... }
```

For per-field control, use `populate`:

```typescript
await nextly.find({
  collection: "posts",
  depth: 1,
  populate: {
    author: { select: { name: true, email: true } },
    category: false, // skip population for this field
  },
});
```

## Rich text format

Rich text fields are stored as Lexical JSON. Pick the output shape with `richTextFormat`:

```typescript
// JSON (default) — Lexical editor state
const a = await nextly.find({ collection: "posts", richTextFormat: "json" });

// HTML — rendered string
const b = await nextly.find({ collection: "posts", richTextFormat: "html" });
b.items[0].content; // "<p>Hello world</p>"

// Both — { json, html }
const c = await nextly.find({ collection: "posts", richTextFormat: "both" });
c.items[0].content; // { json: {...}, html: "<p>Hello world</p>" }
```

## Errors

Every Direct API failure throws a single `NextlyError` class. The error carries a public payload (safe to surface) and a log payload (for the server logger). Type guards let you narrow without `instanceof` (which can fail at package boundaries):

```typescript
import { NextlyError } from "nextly";

async function getPost() {
  try {
    const post = await nextly.findByID({ collection: "posts", id: "missing" });
    return post;
  } catch (err) {
    if (NextlyError.isNotFound(err)) {
      // 404
      return null;
    }
    if (NextlyError.isValidation(err)) {
      // 400 — err.publicData.errors carries [{ path, code, message }]
      console.log(err.publicData);
      throw err;
    }
    if (NextlyError.isAuthRequired(err)) {
      // 401
    }
    if (NextlyError.isForbidden(err)) {
      // 403
    }
    throw err;
  }
}
```

Available type guards: `NextlyError.is`, `NextlyError.isCode`, `NextlyError.isNotFound`, `NextlyError.isValidation`, `NextlyError.isAuthRequired`, `NextlyError.isForbidden`, `NextlyError.isConflict`, `NextlyError.isRateLimited`.

Common `code` values you will see: `VALIDATION_ERROR` (400), `INVALID_INPUT` (422), `AUTH_REQUIRED` (401), `AUTH_INVALID_CREDENTIALS` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `CONFLICT` (409), `DUPLICATE` (409), `PAYLOAD_TOO_LARGE` (413), `RATE_LIMITED` (429), `DATABASE_ERROR` (500), `INTERNAL_ERROR` (500), `SERVICE_UNAVAILABLE` (503).

The same `NextlyError` is what the route handler serialises into the HTTP error envelope (`{ error: { code, message, requestId, ... } }`) — see the [REST API error response section](https://nextlyhq.com/docs/api-reference/rest-api#errors) for the wire format.

## Example: blog page

```typescript title="app/blog/page.tsx"
import { getNextly } from "nextly";

import config from "../../nextly.config";

export default async function BlogPage({
  searchParams,
}: {
  searchParams: Promise<{ page?: string }>;
}) {
  const { page } = await searchParams;
  const nextly = await getNextly({ config });

  const result = await nextly.find({
    collection: "posts",
    where: { status: { equals: "published" } },
    sort: "-publishedAt",
    limit: 12,
    page: Number(page) || 1,
    depth: 1,
    richTextFormat: "html",
  });

  return (
    <main>
      <h1>Blog</h1>
      <div className="grid grid-cols-3 gap-6">
        {result.items.map((post) => (
          <article key={post.id}>
            <h2>{post.title}</h2>
            <div dangerouslySetInnerHTML={{ __html: post.content }} />
          </article>
        ))}
      </div>

      {result.meta.hasNext && (
        <a href={`/blog?page=${result.meta.page + 1}`}>Next page</a>
      )}
    </main>
  );
}
```

## Next steps

- [REST API](https://nextlyhq.com/docs/api-reference/rest-api) — HTTP endpoints for browser code, mobile clients, and third-party integrations.
- [Collections](https://nextlyhq.com/docs/configuration/collections) — define the content types the Direct API operates on.
- [Authentication](https://nextlyhq.com/docs/guides/authentication) — RBAC and access control for API operations.
- [Configuration → typescript.outputFile](https://nextlyhq.com/docs/configuration/nextly-config) — set up generated types for full inference.

---
title: REST API
description: HTTP REST API for browser code, mobile apps, and third-party integrations. Mounted under /api/ via a single Next.js catch-all route handler.
url: https://nextlyhq.com/docs/api-reference/rest-api
---

The REST API exposes the same operations as the [Direct API](https://nextlyhq.com/docs/api-reference/direct-api) over HTTP. Every collection, single, user, role, permission, media file, email template, API key, and more is reachable through standard HTTP methods. Use it whenever your code does **not** run in a trusted Node.js context — browser apps, mobile clients, third-party services.

## Setup

Create a single Next.js catch-all route handler that delegates to Nextly. The dynamic handlers cover collections, singles, auth, dashboard, schema, email, RBAC, media, API keys, and the rest of the surface:

```typescript title="app/api/[[...params]]/route.ts"
import { createDynamicHandlers } from "nextly/runtime";
import nextlyConfig from "../../../nextly.config";

const handlers = createDynamicHandlers({ config: nextlyConfig });

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = handlers;
```

The health endpoint and media-streaming endpoint can be exported at their own routes if you want to opt out of catch-all coverage:

```typescript title="app/api/health/route.ts"
export { GET, HEAD } from "nextly/api/health";
```

All API endpoints are served under `/api/`.

## Authentication

Two authentication mechanisms are supported.

### Cookie auth (browser sessions)

When a user logs in through `/api/auth/login` (or completes the `/admin/setup` wizard), the runtime sets two HTTP-only cookies:

- `__nextly_access_token` — short-lived JWT used for every authenticated request.
- `__nextly_refresh_token` — long-lived token consumed only by `/api/auth/refresh`.

Browsers send these automatically. There is no header for you to set; just call `fetch` with `credentials: "include"` if your frontend lives on a different origin.

### API key (server-to-server)

Send the API key as a Bearer token:

```bash
curl https://example.com/api/collections/posts/entries \
  -H "Authorization: Bearer nx_live_<random>..."
```

API keys are managed via `POST /api/api-keys` (admin UI). There is **no** `X-API-Key` header — `Authorization: Bearer <key>` is the only supported form.

## Response envelopes

All responses follow the canonical Phase 4 shapes documented in [`packages/nextly/src/api/response-shapes.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/nextly/src/api/response-shapes.ts). Content-Type is always `application/json` for success responses and `application/problem+json` for errors. Every response carries an `X-Request-Id` header you can quote when filing bugs.

### List

Paginated reads return `{ items, meta }`:

```json
{
  "items": [ /* T[] */ ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
```

### Read

Single-document reads return the bare document:

```json
{
  "id": "abc-123",
  "title": "Hello world",
  "status": "published",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
```

### Mutation

Create / update / delete-by-id return `{ message, item }`:

```json
{
  "message": "Posts updated.",
  "item": {
    "id": "abc-123",
    "title": "Hello world",
    "status": "published"
  }
}
```

### Action

Non-CRUD writes (login, forgot-password, verify-email, ...) return `{ message, ...result }` — a server-authored toast plus any operation-specific fields:

```json
{
  "message": "Logged in.",
  "user": { "id": "user-1", "email": "user@example.com" },
  "token": "eyJ..."
}
```

### Bulk

Bulk-by-id and bulk-upload responses return `{ message, items, errors }`. The HTTP status is always 200 unless the request itself is malformed; per-item failures are first-class data in `errors`:

```json
{
  "message": "Bulk delete completed.",
  "items": [ { "id": "post-1" }, { "id": "post-2" } ],
  "errors": [
    { "id": "post-3", "code": "NOT_FOUND", "message": "Resource not found." }
  ]
}
```

### Errors

Failures emit `application/problem+json` with status from `NextlyError.statusCode` and a single envelope:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "requestId": "req_nlwxzwtnlvqsu3lc"
  }
}
```

When the failure is a validation error, `error.data` carries field-level details:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "requestId": "req_xxx",
    "data": {
      "errors": [
        { "path": "email", "code": "INVALID_EMAIL", "message": "Email is invalid." }
      ]
    }
  }
}
```

For rate-limited responses (`code: "RATE_LIMITED"`, status 429) the runtime also sets `Retry-After` from `error.data.retryAfterSeconds`.

| Status | Common codes | When |
|---|---|---|
| `400` | `VALIDATION_ERROR` | Body or query failed validation. |
| `401` | `AUTH_REQUIRED`, `AUTH_INVALID_CREDENTIALS` | Missing or bad credentials. |
| `403` | `FORBIDDEN` | Authenticated but lacks permission. |
| `404` | `NOT_FOUND` | Resource does not exist. |
| `409` | `CONFLICT`, `DUPLICATE` | Concurrent edit, duplicate email, etc. |
| `413` | `PAYLOAD_TOO_LARGE` | Upload bigger than configured cap. |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | Wrong `Content-Type`. |
| `422` | `INVALID_INPUT` | Semantic validation failed. |
| `429` | `RATE_LIMITED` | Per-IP or per-key rate limit. `Retry-After` is set. |
| `500` | `INTERNAL_ERROR`, `DATABASE_ERROR` | Server-side failure. |
| `503` | `SERVICE_UNAVAILABLE` | Health probe / dependency outage. |

## Endpoint inventory

The catch-all dispatches every URL under `/api/` to one of these endpoint groups. Auth column shows whether a session cookie or API key is required.

| Method | Path | Description | Auth |
|---|---|---|---|
| `GET` / `HEAD` | `/api/health` | Liveness + DB probe. | Public |
| `GET` | `/api/auth/setup-status` | Whether the setup wizard has run. | Public |
| `POST` | `/api/auth/setup` | Run the first-boot setup wizard (creates super admin). | Public, one-shot |
| `GET` | `/api/auth/session` | Current session info from the cookie. | Cookie |
| `GET` | `/api/auth/csrf` | CSRF token (when applicable). | Public |
| `POST` | `/api/auth/login` | Email + password login. Sets cookies. | Public |
| `POST` | `/api/auth/logout` | Clear cookies. | Cookie |
| `POST` | `/api/auth/refresh` | Rotate the access token. | Cookie |
| `POST` | `/api/auth/register` | Public registration. | Public |
| `POST` | `/api/auth/forgot-password` | Send password-reset email. | Public |
| `POST` | `/api/auth/reset-password` | Consume reset token and set new password. | Public |
| `POST` | `/api/auth/verify-email` | Consume email-verification token. | Public |
| `POST` | `/api/auth/verify-email/resend` | Resend the verification email. | Public |
| `PATCH` | `/api/auth/change-password` | Change current user's password. | Cookie |
| `GET` | `/api/me` | Current user profile. | Cookie / Bearer |
| `PATCH` | `/api/me` | Update current user profile. | Cookie / Bearer |
| `GET` | `/api/me/permissions` | Resolved permissions for current user. | Cookie / Bearer |
| `GET` | `/api/users` | List users. | `read-users` |
| `POST` | `/api/users` | Create user. | `create-users` |
| `GET` | `/api/users/{id}` | Get user. | `read-users` |
| `PATCH` | `/api/users/{id}` | Update user. | `update-users` |
| `DELETE` | `/api/users/{id}` | Delete user. | `delete-users` |
| `PATCH` | `/api/users/{id}/password` | Set password hash directly. | `update-users` |
| `GET` | `/api/users/{id}/accounts` | List linked accounts. | `read-users` |
| `DELETE` | `/api/users/{id}/accounts/{provider}/{providerAccountId}` | Unlink account. | `update-users` |
| `GET` | `/api/users/{id}/roles` | List user roles. | `read-roles` |
| `POST` | `/api/users/{id}/roles` | Assign role to user. | `update-users` |
| `DELETE` | `/api/users/{id}/roles/{roleId}` | Unassign role. | `update-users` |
| `GET` | `/api/roles` | List roles. | `read-roles` |
| `POST` | `/api/roles` | Create role. | `create-roles` |
| `GET` | `/api/roles/{id}` | Get role. | `read-roles` |
| `PATCH` | `/api/roles/{id}` | Update role. | `update-roles` |
| `DELETE` | `/api/roles/{id}` | Delete role. | `delete-roles` |
| `GET` | `/api/roles/{id}/permissions` | List role permissions. | `read-roles` or `read-permissions` |
| `POST` | `/api/roles/{id}/permissions` | Add permission to role. | `update-roles` |
| `PATCH` | `/api/roles/{id}/permissions` | Replace all role permissions. | `update-roles` |
| `DELETE` | `/api/roles/{id}/permissions/{permissionId}` | Remove permission from role. | `update-roles` |
| `GET` | `/api/roles/{id}/children` | List child roles (inheritance). | `read-roles` |
| `POST` | `/api/roles/{id}/children` | Add child role. | `update-roles` |
| `DELETE` | `/api/roles/{id}/children/{childId}` | Remove child role. | `update-roles` |
| `GET` | `/api/roles/{id}/parents` | List ancestor roles. | `read-roles` |
| `GET` | `/api/permissions` | List permissions. | `read-permissions` (or `read-roles`) |
| `POST` | `/api/permissions` | Create permission. | `create-permissions` |
| `GET` | `/api/permissions/{id}` | Get permission. | `read-permissions` (or `read-roles`) |
| `PATCH` | `/api/permissions/{id}` | Update permission. | `update-permissions` |
| `DELETE` | `/api/permissions/{id}` | Delete permission. | `delete-permissions` |
| `GET` | `/api/collections` | List collection definitions. | Authenticated |
| `POST` | `/api/collections` | Create collection (Schema Builder). | `manage-settings` |
| `GET` | `/api/collections/{slug}` | Get collection definition. | `read-{slug}` |
| `PATCH` | `/api/collections/{slug}` | Update collection definition. | `manage-settings` |
| `DELETE` | `/api/collections/{slug}` | Delete collection. | `manage-settings` |
| `GET` | `/api/collections/schema/{slug}` | Get enriched schema (with component fields). | `read-{slug}` |
| `POST` | `/api/collections/schema/{slug}/preview` | Dry-run schema diff. | `manage-settings` |
| `POST` | `/api/collections/schema/{slug}/apply` | Apply confirmed schema changes. | `manage-settings` |
| `GET` | `/api/collections/{slug}/entries` | List entries. | `read-{slug}` |
| `POST` | `/api/collections/{slug}/entries` | Create entry. | `create-{slug}` |
| `GET` | `/api/collections/{slug}/entries/{id}` | Get entry by ID. | `read-{slug}` |
| `PATCH` | `/api/collections/{slug}/entries/{id}` | Update entry. | `update-{slug}` |
| `DELETE` | `/api/collections/{slug}/entries/{id}` | Delete entry. | `delete-{slug}` |
| `GET` | `/api/collections/{slug}/entries/count` | Count entries matching a query. | `read-{slug}` |
| `POST` | `/api/collections/{slug}/entries/{id}/duplicate` | Duplicate entry. | `create-{slug}` |
| `POST` | `/api/collections/{slug}/entries/bulk-delete` | Bulk delete by IDs. | `delete-{slug}` |
| `POST` | `/api/collections/{slug}/entries/bulk-update` | Bulk update by IDs. | `update-{slug}` |
| `PATCH` | `/api/collections/{slug}/entries` | Bulk update by query. | `update-{slug}` |
| `GET` | `/api/singles` | List singles. | Authenticated |
| `POST` | `/api/singles` | Create single (Schema Builder). | `manage-settings` |
| `GET` | `/api/singles/{slug}` | Get single content. | `read-{slug}` |
| `PATCH` | `/api/singles/{slug}` | Update single content. | `update-{slug}` |
| `DELETE` | `/api/singles/{slug}` | Delete UI-created single. | `manage-settings` |
| `GET` | `/api/singles/{slug}/schema` | Get single schema. | `read-{slug}` |
| `PATCH` | `/api/singles/{slug}/schema` | Update single schema (Schema Builder). | `manage-settings` |
| `POST` | `/api/singles/schema/{slug}/preview` | Dry-run single schema diff. | `manage-settings` |
| `POST` | `/api/singles/schema/{slug}/apply` | Apply single schema changes. | `manage-settings` |
| `GET` | `/api/field-groups` | List field group definitions. | Authenticated |
| `POST` | `/api/field-groups` | Create field group. | `manage-settings` |
| `GET` | `/api/field-groups/{slug}` | Get field group. | Authenticated |
| `PATCH` | `/api/field-groups/{slug}` | Update field group. | `manage-settings` |
| `DELETE` | `/api/field-groups/{slug}` | Delete field group. | `manage-settings` |
| `POST` | `/api/field-groups/schema/{slug}/preview` | Dry-run field group schema diff. | `manage-settings` |
| `POST` | `/api/field-groups/schema/{slug}/apply` | Apply field group schema changes. | `manage-settings` |
| `GET` | `/api/forms` | List published forms. | Public |
| `GET` | `/api/forms/{slug}` | Get form by slug. | Public |
| `POST` | `/api/forms/{slug}/submit` | Submit a form. | Public |
| `POST` | `/api/email/send` | Send a raw email. | Authenticated |
| `POST` | `/api/email/send-with-template` | Send a templated email. | Authenticated |
| `GET` | `/api/email-providers` | List providers. | `read-email-providers` |
| `POST` | `/api/email-providers` | Create provider. | `create-email-providers` |
| `GET` | `/api/email-providers/{id}` | Get provider. | `read-email-providers` |
| `PATCH` | `/api/email-providers/{id}` | Update provider. | `update-email-providers` |
| `DELETE` | `/api/email-providers/{id}` | Delete provider. | `delete-email-providers` |
| `PATCH` | `/api/email-providers/{id}/default` | Set default provider. | `update-email-providers` |
| `POST` | `/api/email-providers/{id}/test` | Send a test email. | `read-email-providers` |
| `GET` | `/api/email-templates` | List templates. | `read-email-templates` |
| `POST` | `/api/email-templates` | Create template. | `create-email-templates` |
| `GET` | `/api/email-templates/layout` | Get shared header/footer. | `read-email-templates` |
| `PATCH` | `/api/email-templates/layout` | Update shared header/footer. | `update-email-templates` |
| `GET` | `/api/email-templates/{id}` | Get template. | `read-email-templates` |
| `PATCH` | `/api/email-templates/{id}` | Update template. | `update-email-templates` |
| `DELETE` | `/api/email-templates/{id}` | Delete template. | `delete-email-templates` |
| `POST` | `/api/email-templates/{id}/preview` | Render template with sample data. | `read-email-templates` |
| `GET` | `/api/user-fields` | List user field definitions. | `read-settings` |
| `POST` | `/api/user-fields` | Create user field. | `create-settings` |
| `PATCH` | `/api/user-fields/reorder` | Reorder user fields. | `update-settings` |
| `GET` | `/api/user-fields/{id}` | Get user field. | `read-settings` |
| `PATCH` | `/api/user-fields/{id}` | Update user field. | `update-settings` |
| `DELETE` | `/api/user-fields/{id}` | Delete user field. | `delete-settings` |
| `GET` | `/api/api-keys` | List API keys for current user. | Cookie (session-only) |
| `POST` | `/api/api-keys` | Create API key. | Cookie (session-only) |
| `GET` | `/api/api-keys/{id}` | Get API key metadata. | Cookie (session-only) |
| `PATCH` | `/api/api-keys/{id}` | Update name/description. | Cookie (session-only) |
| `DELETE` | `/api/api-keys/{id}` | Revoke API key. | Cookie (session-only) |
| `GET` | `/api/dashboard/stats` | Admin dashboard stats. | Cookie |
| `GET` | `/api/dashboard/recent-entries` | Recent activity. | Cookie |
| `GET` | `/api/dashboard/activity` | Activity feed. | Cookie |
| `GET` | `/api/schema/journal` | Schema migration journal (super-admin only). | Cookie + super admin |
| `GET` / `PATCH` | `/api/general-settings` | Project-wide settings. | `manage-settings` |
| `GET` | `/api/image-sizes` | List image-size presets. | Cookie |
| `POST` | `/api/image-sizes` | Create image-size preset. | `manage-settings` |
| `PATCH` | `/api/image-sizes/{id}` | Update preset. | `manage-settings` |
| `DELETE` | `/api/image-sizes/{id}` | Delete preset. | `manage-settings` |

The slug-based permissions use the pattern `{action}-{slug}` so a `posts` collection requires `read-posts`, `create-posts`, etc.

## Per-section detail

The endpoint inventory above is the complete list. The sections below cover the request/response specifics for the groups with non-trivial body shapes.

### Health

```bash
curl -i http://localhost:3000/api/health
```

```http
HTTP/1.1 200 OK
content-type: application/json
cache-control: public, max-age=60, stale-while-revalidate=30
x-request-id: req_xxx

{
  "ok": true,
  "version": "0.0.142",
  "uptime": 123,
  "timestamp": "2026-05-05T09:00:00.000Z",
  "database": { "ok": true, "dialect": "postgresql", "latency": 4 }
}
```

When the database probe fails the runtime emits the canonical error envelope at status 503:

```json
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service unavailable. Please try again later.",
    "requestId": "req_xxx"
  }
}
```

`HEAD /api/health` returns the same status, headers, and `X-Request-Id` with no body — useful for monitors that only need the status code.

### Auth

```bash
# Login
curl -i -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secure-password"}'
```

A successful login responds 200 with the action envelope `{ message, user, token, exp }` and sets `__nextly_access_token` + `__nextly_refresh_token` cookies on the response. Browsers handle these automatically; for API clients you can ignore them and use the returned `token` as a Bearer token instead.

```bash
# Register
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","password":"secure-password","name":"New User"}'
```

```bash
# Forgot password
curl -X POST http://localhost:3000/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

The `forgot-password` endpoint always returns 200 to avoid leaking which addresses exist. The reset email contains the token; consume it with `POST /api/auth/reset-password`.

```bash
# Reset password
curl -X POST http://localhost:3000/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"<token-from-email>","password":"new-secure-password"}'
```

```bash
# Change password (authenticated)
curl -X PATCH http://localhost:3000/api/auth/change-password \
  -H "Content-Type: application/json" \
  -b "__nextly_access_token=..." \
  -d '{"currentPassword":"old","newPassword":"new-secure"}'
```

```bash
# Verify email
curl -X POST http://localhost:3000/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"<token-from-email>"}'
```

The setup wizard is a one-shot path that runs only when no super admin exists:

```bash
curl http://localhost:3000/api/auth/setup-status
# {"ok":true,"completed":false}

curl -X POST http://localhost:3000/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","name":"Admin","password":"strong-password"}'
```

Re-running setup after the first super admin exists returns a 409.

### Collection entries

List:

```bash
curl "http://localhost:3000/api/collections/posts/entries?limit=10&page=1&sort=-createdAt&where[status][equals]=published"
```

```json
{
  "items": [
    { "id": "abc-123", "title": "Hello world", "status": "published" }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
```

Get by ID:

```bash
curl "http://localhost:3000/api/collections/posts/entries/abc-123?depth=2"
```

```json
{
  "id": "abc-123",
  "title": "Hello world",
  "author": { "id": "user-1", "name": "John Doe" },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
```

Create:

```bash
curl -X POST "http://localhost:3000/api/collections/posts/entries" \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"New Post","content":"Hello!","status":"draft"}'
```

```json
{
  "message": "Posts created.",
  "item": { "id": "...", "title": "New Post", "status": "draft" }
}
```

Update (PATCH a single field set; everything not in the body is left alone):

```bash
curl -X PATCH "http://localhost:3000/api/collections/posts/entries/abc-123" \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"published"}'
```

Delete:

```bash
curl -X DELETE "http://localhost:3000/api/collections/posts/entries/abc-123" \
  -H "Authorization: Bearer nx_live_..."
```

Count:

```bash
curl "http://localhost:3000/api/collections/posts/entries/count?where[status][equals]=published"
# {"total": 42}
```

Duplicate:

```bash
curl -X POST "http://localhost:3000/api/collections/posts/entries/abc-123/duplicate" \
  -H "Authorization: Bearer nx_live_..."
```

Bulk delete (status 200, partial success in body):

```bash
curl -X POST "http://localhost:3000/api/collections/posts/entries/bulk-delete" \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["post-1","post-2","post-3"]}'
```

```json
{
  "message": "Bulk delete completed.",
  "items": [{ "id": "post-1" }, { "id": "post-2" }],
  "errors": [
    { "id": "post-3", "code": "NOT_FOUND", "message": "Resource not found." }
  ]
}
```

Bulk update by IDs:

```bash
curl -X POST "http://localhost:3000/api/collections/posts/entries/bulk-update" \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["post-1","post-2"],"data":{"status":"archived"}}'
```

Bulk update by query (PATCH on the collection root with a `where` clause in the body):

```bash
curl -X PATCH "http://localhost:3000/api/collections/posts/entries" \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"where":{"status":{"equals":"draft"}},"data":{"status":"archived"}}'
```

### Singles

List metadata for every registered single:

```bash
curl http://localhost:3000/api/singles
```

Get the actual content:

```bash
curl http://localhost:3000/api/singles/site-settings
```

Update content:

```bash
curl -X PATCH http://localhost:3000/api/singles/site-settings \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"siteName":"My New Site","maintenanceMode":false}'
```

### Email send

Both endpoints accept an authenticated request (cookie or API key). The body matches the Direct API arguments documented in [Direct API → Email](https://nextlyhq.com/docs/api-reference/direct-api#email).

```bash
curl -X POST http://localhost:3000/api/email/send \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>Welcome to Nextly</p>"
  }'

curl -X POST http://localhost:3000/api/email/send-with-template \
  -H "Authorization: Bearer nx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "template": "welcome-email",
    "variables": { "name": "Alice" }
  }'
```

### Media

The media collection is just a normal collection (`/api/collections/media/entries`) with extra plumbing for binary uploads. The `POST /api/collections/media/entries` endpoint accepts `multipart/form-data` with the file under `file` and any other fields alongside.

Image-size presets are managed under `/api/image-sizes`. The `regeneration-status` and `regenerate` sub-routes return a "coming soon" placeholder today (see [`packages/nextly/src/routeHandler.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/nextly/src/routeHandler.ts)).

### API keys

`/api/api-keys/*` is session-only — these endpoints **do not** accept Bearer authentication, so an attacker with a stolen key cannot mint new keys with it. Manage keys from the admin UI or via cookie-authenticated requests.

```bash
curl http://localhost:3000/api/api-keys -b "__nextly_access_token=..."
```

`POST /api/api-keys` returns the new key value once at creation; it is hashed on the server and never displayed again.

## Query parameters

These parameters are accepted by every list endpoint that delegates to the collection / single dispatcher.

### status

For Draft/Published collections and singles, `?status=` controls which lifecycle states a read returns.

| Value | Returns |
|---|---|
| _(omitted)_ | Published only — the safe default. Drafts are never returned unless you ask. |
| `published` | Published only (explicit). |
| `draft` | Drafts only. |
| `all` | Every entry regardless of status. |

```
?status=all
?status=draft
```

An **unrecognized** value (a typo like `?status=pubished`) is rejected with `400 VALIDATION_ERROR` rather than silently returning everything, so a bad filter can never widen a read. Trusted server-side calls through the Direct API (which bypass access checks) see every status by default; over HTTP the default is always published-only. The admin panel requests `?status=all` explicitly so editors still see their drafts.

### where

Filter rows using bracket notation:

```
?where[status][equals]=published
?where[price][greater_than]=100
?where[title][contains]=hello
?where[category][in]=news,featured
```

Operators (verified against `packages/nextly/src/domains/collections/query/query-operators.ts`):

| Operator | Description | Query string example |
|---|---|---|
| `equals` | Exact match. | `where[status][equals]=published` |
| `not_equals` | Not equal. | `where[status][not_equals]=draft` |
| `greater_than` | `>` | `where[price][greater_than]=100` |
| `greater_than_equal` | `>=` | `where[price][greater_than_equal]=100` |
| `less_than` | `<` | `where[price][less_than]=50` |
| `less_than_equal` | `<=` | `where[price][less_than_equal]=50` |
| `like` | SQL `LIKE` (case-sensitive). | `where[title][like]=%hello%` |
| `contains` | Case-insensitive substring (`ILIKE`). | `where[title][contains]=hello` |
| `search` | Alias for `contains`. | `where[title][search]=hello` |
| `in` | Value in comma-separated list. | `where[status][in]=draft,published` |
| `not_in` | Value not in comma-separated list. | `where[status][not_in]=archived` |
| `exists` | Field is non-null when `true`, null when `false`. | `where[image][exists]=true` |

For nested AND / OR you can either pass URL-encoded JSON via `where=...`, or use the index syntax:

```
?where[and][0][status][equals]=published&where[and][1][category][equals]=news
```

### sort

Field name; prefix with `-` for descending.

```
?sort=-createdAt
?sort=title
```

### Pagination

```
?limit=20&page=2
```

Maximum `limit` is 500 (anything higher is clamped). The response always includes the `meta` envelope with `total`, `page`, `limit`, `totalPages`, `hasNext`, and `hasPrev`.

### depth

Relationship population depth. `0` returns only IDs; `1+` populates referenced documents.

```
?depth=0   # IDs only
?depth=1   # populate direct relationships
?depth=2   # populate one level deeper
```

### select

Whitelist of fields to include. Two spellings, both accepted:

```
?select=id,title,publishedAt          # comma-separated
?select={"id":true,"title":true}      # JSON object (URL-encode it)
```

The `id` and the system timestamps come back whether or not they are named.

A `select` the API cannot read is a `400`, rather than a response carrying every
field — a projection that is silently discarded looks exactly like one that was
never asked for. Naming no fields at all is unreadable for the same reason; omit
the parameter to get every field.

### richTextFormat

```
?richTextFormat=html       # rendered HTML
?richTextFormat=json       # Lexical JSON (default)
?richTextFormat=both       # { json, html }
```

## Pagination

Page-based with the `meta` envelope. Use `meta.hasNext` to drive a "Next page" UI; do not assume a fixed `totalPages` because the underlying count can change between requests.

```typescript
async function fetchPosts(page = 1) {
  const params = new URLSearchParams({
    limit: "10",
    page: String(page),
    sort: "-createdAt",
    "where[status][equals]": "published",
    depth: "1",
  });

  const response = await fetch(`/api/collections/posts/entries?${params}`, {
    credentials: "include",
  });
  const json = await response.json();
  return json; // { items, meta }
}
```

## Security

The route handler ships with built-in defences:

- **Rate limiting** on auth write endpoints (per IP) and global per-IP / per-key limits configured in `nextly.config.ts`.
- **CORS** controlled by `NEXTLY_ALLOWED_ORIGINS` and the `security` config.
- **Cache headers** (`no-store`) on every `/api/auth/*` response to keep tokens out of caches.
- **Super-admin protection** so non-super-admins cannot grant the super-admin role.
- **Trusted proxy / forwarded-for** filtering when `trustProxy` is on.

See [Configuration](https://nextlyhq.com/docs/configuration/nextly-config) and [Authentication](https://nextlyhq.com/docs/guides/authentication) for the configurable surface.

## Next steps

- [Direct API](https://nextlyhq.com/docs/api-reference/direct-api) — server-side equivalent with no HTTP overhead.
- [Authentication](https://nextlyhq.com/docs/guides/authentication) — RBAC, API keys, and cookie configuration.
- [Collections](https://nextlyhq.com/docs/configuration/collections) — define the content types this API serves.
- [Configuration](https://nextlyhq.com/docs/configuration/nextly-config) — security, rate-limit, and storage configuration.

---
title: Block document format
description: The stored shape of a page built with blocks, and what is frozen about it.
url: https://nextlyhq.com/docs/api-reference/block-document-format
---

A page built with blocks is stored as one JSON document. This page is the
format's specification: what a document contains, which parts are fixed, and
which parts are expected to grow.

It is written for anything that produces or consumes a document without going
through an editor — a migration script, a content generator, an AI agent
writing a page, or a build step reading one.

## What this format covers

This is the document format of `@nextlyhq/blocks-engine`. It is what the
`blocks` field stores and what `@nextlyhq/blocks-react` renders.

**The `@nextlyhq/plugin-page-builder` editor does not currently write this
format.** Its canvas stores a different, internal shape — a single `root`
container under a `version` key — and there is no adapter between the two. That
editor is a proof of concept being replaced, and the replacement writes this
format; until then, a document saved by that canvas will not validate here, and
that is expected rather than a defect in either.

So: use this specification for the `blocks` field, for the engine, for the
renderer, and for anything you generate yourself. Do not use it to read what the
legacy page-builder canvas has already saved.

## Checking a document

```ts
import { parseBlockDocument } from "nextly";

declare const value: unknown; // the document you did not write

const result = parseBlockDocument(value);
if (!result.success) {
  console.error(result.issues);
}
```

`parseBlockDocument` is the entry point to use on a document you did not write.
It bounds both nesting **depth** and node **count** before parsing, so a hostile
or merely broken input comes back as invalid rather than consuming the process
doing the checking. Depth matters because the schema is self-referential, and a
long enough chain of nested slots exhausts the call stack; count matters because
a document can be shallow and still enormous, and parsing walks and copies the
whole forest before it can report anything.

The underlying schema is deliberately not exported, because those bounds are a
precondition rather than an option.

For a consumer with neither TypeScript nor zod, the format is also published as
plain JSON Schema:

```ts
import { blockDocumentJsonSchema } from "nextly";
```

It is derived from the same definition this package checks against, so what is
published cannot describe a different format from what Nextly accepts.

### What it does not repair

Anything it accepts, it returns **unchanged**. A checker that quietly tidied its
input would hand you a document the engine still rejects, with the diagnostic
already discarded — so unknown fields survive, and a malformed token reference
stays malformed for the engine to report.

> **Known limitation: the caps assume an ordinary object.** `parseBlockDocument`
> establishes its size, depth and node bounds by reading property descriptors,
> and then hands the same value to the schema, which reads it by ordinary
> property access. For anything `JSON.parse` produces, or any object you built
> yourself, those two readings are identical.
>
> A `Proxy` can make them differ. One whose descriptors report an empty array
> while its `get` returns thousands of nodes passes every bound and is then
> walked in full, so the bounds do not hold for it. A non-enumerable named
> property on an array is invisible in the same way, and survives on the value
> you get back although storage drops it.
>
> Both have the same cause — two readers of one untrusted value — and the fix is
> to have the bounded walk produce the value everything downstream uses, which
> changes what this function RETURNS and so is being done as its own change
> rather than folded in here. **Pass a value you own, or one from
> `JSON.parse`, and neither case arises.**

**It answers a narrower question than the engine does.** The schema asks _is
this the block document format at all_; `validate(doc, ctx)` asks _is this a
legal document for this app_, against the blocks that are actually registered
and the breakpoints that are actually configured. A document can satisfy the
schema and still be rejected — an unregistered block type, for example, is
invisible to a static schema.

Where the schema cannot be exact it stays permissive, because refusing a
document Nextly would have accepted is worse than accepting one the engine
rejects a moment later with a better message.

## The envelope

```json
{
  "formatVersion": 1,
  "kind": "page",
  "nodes": [],
  "settings": { "styles": {}, "customCss": "" },
  "assets": { "mediaIds": [] }
}
```

`nodes` is a plain array: a page **is** a list of sections. There is no
synthetic root block, so nothing has to special-case an undeletable, unmovable
pseudo-node. Document-level concerns live on the envelope instead.

`kind` is closed:

| kind        | what it is                                                           |
| ----------- | -------------------------------------------------------------------- |
| `page`      | an entry's blocks-field content                                      |
| `pattern`   | a copy-on-insert saved subtree, including full-page patterns         |
| `component` | a linked, reusable definition with exposed props, slots and variants |
| `region`    | a layout region such as a header or footer                           |
| `template`  | a collection template                                                |

A layout is a named bundle _referencing_ region documents, so it is not a kind of
its own.

## A node

```json
{
  "id": "01J...",
  "type": "core/heading",
  "version": 1,
  "props": { "text": "Hello", "level": 2 }
}
```

`id` is the only way anything addresses a node. Editor operations, locale
overlays, scoped-CSS class derivation and selection all key on it. **Positional
addressing is never part of any stored or public contract** — an operation that
said "the third child" would break the moment anything moved.

`version` is required on every node, not defaulted. It records which schema
version of its block the node was written against, and both forgiving rendering
and migration read it unconditionally. A node without one cannot be migrated,
only guessed at.

Optional fields: `bindings`, `slots`, `styles`, `classes`, `visibility`,
`locked`, `name`, `customCss`, `cssId`, `attributes`, `migrationFailed`.

### Bindings

A binding is a typed field path, never an expression:

```json
{ "$bind": "title", "source": "entry", "fallback": "Untitled" }
```

`source` is one of `entry`, `item`, `single` or `site`. **`single` requires
`sourceKey`**, the slug of the document to read from; the other sources are
implied by the render context. A binding naming `single` without a key resolves
to nothing at read time, so the format rejects it at the point where the slug
can still be supplied.

`fallback` is what renders when the path resolves to nothing, and it stays in
`props` as the literal shown if the binding is removed.

> **Bindings are reserved, not yet resolved.** The format accepts and validates
> them, and the shape above is frozen. Nothing resolves them today: the renderer
> passes `props` through unchanged, so a bound prop renders its literal `props`
> value for every entry rather than the bound field.
>
> That is safe in itself — the literal is the documented fallback, so a page
> shows stale content rather than nothing — but a generator that writes `$bind`
> expecting it to take effect will produce pages that never update. Write the
> value you want into `props` until resolution ships.

### Visibility

```json
{
  "conditions": [[{ "field": "status", "op": "eq", "value": "vip" }]],
  "devices": { "mobile": false }
}
```

The two mechanisms are deliberately separate and must not be conflated:

- **`conditions`** decides whether a node is _served_. A hidden node is omitted
  from server output entirely, not CSS-hidden. Stored as OR-of-AND (outer array
  ORs, inner arrays AND) from the start, so a richer editing UI never needs a
  storage migration.
- **`devices`** decides whether a _served_ node is shown at a breakpoint. This
  is presentation, and it is CSS-based.

Conflating them would either leak a conditioned node into the payload or stop a
hidden-on-mobile node being indexed.

> **`conditions` is reserved, and it currently fails CLOSED.** No evaluator
> exists — `op` is an open string and nothing decides whether a predicate holds
> — so the renderer omits any node carrying `conditions` **for every visitor**,
> rather than serving it to those who match.
>
> This is deliberate: conditions gate personalised and status-restricted
> content, and showing everyone what was meant for some of them cannot be taken
> back, while content missing from a page is visible and reportable. The
> consequence is still worth stating plainly: **a node you condition today
> disappears from the page entirely.** Leave `conditions` unset until the
> evaluator ships.
>
> `devices` is unaffected and works as described.

### Styles

```json
{
  "base": {
    "desktop": { "padding": "16px", "color": { "$token": "brand.primary" } }
  }
}
```

Two axes: state, then breakpoint. The **state** axis is closed — `base`,
`hover`, `focus`, `active`. The breakpoint axis is not, because breakpoint ids
are site configuration.

A value of `{ "$token": "..." }` is a design-token reference rather than a
literal.

## What is frozen, and what may still change

The format follows one rule: **additive-open, semantically-closed.**

| change                                             | cost                   |
| -------------------------------------------------- | ---------------------- |
| a new style property                               | free; no format change |
| a new optional field                               | free                   |
| removing a field                                   | a format migration     |
| changing what an existing field means              | a format migration     |
| widening a closed vocabulary (`kind`, style state) | a format migration     |

So the format can grow without breaking stored documents. What it cannot do is
change its mind about something already written.

The frozen surface is:

1. **The document and node shapes** above, including `Binding`, `NodeVisibility`,
   locale overlays, the component-instance node shape, and the document limits.

   The freeze is over the **stored shape**, not over runtime behaviour. `Binding`
   and `NodeVisibility.conditions` are frozen and reserved while the code that
   acts on them is not written yet (see the notes in those sections). That is the
   intended order: a document written against a frozen shape stays valid when
   resolution arrives, whereas shipping a shape that later has to change would
   invalidate everything already stored.

2. **The typed-style envelope** — the states × breakpoints structure and the
   token-reference convention. The style _property catalog_ inside it is
   additive-open and is not frozen.
3. **The validation API** — `validate(doc, ctx) → ValidationIssue[]`, where an
   issue is `{ path, code, message, suggestion?, severity }` and `path` is an
   RFC 6901 JSON Pointer.

   > **`customCss` is stored, and nothing reads it yet.** The field is part of
   > the frozen shape on both a node and the document settings, and no validator
   > inspects it and no compiler emits it. Custom CSS has to be sanitized before
   > it can be written into a page at all, and that sanitizer does not exist, so
   > the value round-trips through storage and reaches no stylesheet. Do not
   > rely on it to style anything yet.

4. **The tree primitives and the reserved operation vocabulary.** The primitives
   are pure, id-addressed functions over a forest: insert, remove, move, reid,
   update.

   The editor's operation layer **builds on** these; it does not mirror them.
   The primitives are permissive by design — `removeNode` removes every node
   matching an id — while the operation layer refuses cases a stored, replayable
   edit cannot express safely, such as an id that appears twice, where an
   inverse could only ever restore one of them. That difference is deliberate,
   and closing it would reintroduce silent data loss.

5. **The manifest artifact format**, whose block entries carry name, version,
   description, example, prop schemas, serialized `supports`, and slot rules.
6. **The bindability rule** — whether a prop can be bound is derived from its
   field type, never opted into per block. The predicate is `isBindablePropType`.
7. **The registry read API.** A plugin contributing blocks does so through the
   page builder's block-registration service rather than a core `contributes`
   key — blocks belong to the page builder, not to Nextly — so the shape frozen
   here is the read side (`getBlock`, `allBlocks`, `getBlockSource`,
   `getSupport`, `allSupports`), not a contribution field.

### Reserved operation names

⚠️ **These names are reserved, not yet callable.** None of them is implemented
today. They are listed here so that nothing else claims one before the
composition features ship, and so an implementer can see the intended shape.

| name                 | what it will do                                         |
| -------------------- | ------------------------------------------------------- |
| `saveAsPattern`      | save a subtree as a copy-on-insert pattern              |
| `saveAsComponent`    | save a subtree as a linked, reusable component          |
| `convertToComponent` | replace a subtree in place with a component instance    |
| `detachComponent`    | replace a component instance with a copy of its content |

The reservation is a value rather than a sentence, because a list that exists
only in prose cannot be consulted by the code that would have to honour it:

```ts
import {
  RESERVED_OPERATION_NAMES,
  isReservedOperationName,
} from "@nextlyhq/blocks-engine";
```

An operation layer should refuse a reserved name it does not implement, rather
than reporting it as unknown. "Unknown operation" invites a caller to define
their own `saveAsPattern`, which is the collision the reservation exists to
prevent, and it would surface only once the real one shipped.

When these are built they will be operations and API actions rather than editor
gestures, so a script or an agent can perform them without driving a UI.

## What documents never contain

**Custom JavaScript.** There is no mechanism for custom JS anywhere in the
format, and this is a deliberate limit rather than an unbuilt feature — unlike
the reserved fields above, it is not waiting on an implementation.

A block may carry custom CSS at the document level and per node. That CSS is
**not** sanitized today, because the sanitizer does not exist; the field is
stored and nothing reads it (see the note on `customCss` above). Sanitization is
a precondition of ever emitting it, not a property it already has.

---
title: Page Builder
description: Let your team compose pages from blocks you define, rendered on the server with no client JavaScript by default.
url: https://nextlyhq.com/docs/page-builder
---

The Page Builder gives non-developers a canvas. They drag blocks onto a page, arrange
them, set text and images, and publish. You decide which blocks exist.

That split is the point. Your developers decide what is possible; your team decides what
goes on the page. Someone editing a page cannot invent a new kind of section, so a site
cannot drift away from its design system by accident.

It ships as a plugin, `@nextlyhq/plugin-page-builder`, built on the same public API any
plugin uses.

## What you get

- **20 blocks out of the box.** Layout (section, box, columns, column, card, accordion,
  accordion item, spacer, divider), content (heading, paragraph, rich text, list, quote,
  image, gallery, button, embed, form), and one that reads from your content
  ([collection loop](#reading-content-into-a-page)).
- **Your own blocks**, defined in code, sitting beside the built-in ones.
- **Responsive control** per block, against breakpoints you declare.
- **Server-first rendering.** A page ships no client JavaScript unless a block on it
  needs some.

## Availability

| | |
|---|---|
| Package | `@nextlyhq/plugin-page-builder`, plus `@nextlyhq/blocks-react` in your app |
| Status | Alpha. The block model, registries and render pipeline are stable; editor interactions are still evolving |
| Permission | Editing a page requires update access to the collection holding it |

## Install

```bash
pnpm add @nextlyhq/plugin-page-builder @nextlyhq/blocks-react \
  @nextlyhq/builder @nextlyhq/plugin-sdk react-hook-form
```

Add the plugin to your config. It contributes a `pages` collection whose edit screen is
the builder:

```ts
import { pageBuilder } from "@nextlyhq/plugin-page-builder";
import { defineConfig } from "nextly";

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

## Render the pages

A plugin cannot add routes to your Next.js app, so you declare one catch-all route and
let `createBlocksPage` fill it. It resolves the incoming path against your collections,
404s on a miss, and renders the stored document.

```tsx
// app/(frontend)/[...slug]/page.tsx
import { createBlockResolver } from "@nextlyhq/blocks-react";
import { coreBlocks } from "@nextlyhq/blocks-react/blocks";
import { createBlocksPage } from "@nextlyhq/blocks-react/next";
import { getNextly } from "nextly";
import type { NextlyContentReader } from "nextly/runtime";

import nextlyConfig from "../../../nextly.config";

type NextlyInstance = Awaited<ReturnType<typeof getNextly>>;

const instance = () => getNextly({ config: nextlyConfig });

// Annotated rather than inferred: without a contextual type these `args`
// parameters are implicitly `any`, which fails `next build` under strict mode.
const reader: NextlyContentReader & {
  media: Pick<NextlyInstance["media"], "findByID">;
} = {
  find: async args => (await instance()).find(args),
  findByID: async args => (await instance()).findByID(args),
  // Images that store a media id resolve through this. Omit it and those images
  // render nothing, while images holding a literal URL keep working.
  media: {
    findByID: async args => (await instance()).media.findByID(args),
  },
};

const { ContentPage, generateMetadata } = createBlocksPage({
  collections: ["pages"],
  field: "content",
  nextly: reader,
  blocks: createBlockResolver(coreBlocks),
  styleContext: {
    breakpoints: {
      viewport: [
        { id: "base", label: "Base" },
        { id: "tablet", label: "Tablet", maxWidth: 1024 },
        { id: "mobile", label: "Mobile", maxWidth: 640 },
      ],
      container: [],
    },
  },
});

export { generateMetadata };
export default ContentPage;
```

<Callout type="warn">
Without a breakpoint set the renderer emits class names with no CSS behind them, and
pages come out structurally correct and visually bare. Declare at least a `base`
breakpoint.
</Callout>

### Public sites read differently

`createBlocksPage` reads **access-enforced** content, so it needs no database during
`next build`. A wholly public site calls `createPublicBlocksPage` instead: it reads
trusted, pre-renders, and returns a `generateStaticParams` to export alongside the other
two. Which one you call *is* the security posture — there is no option to flip.

## Use it as a field instead

You do not have to accept the `pages` collection. The builder is also a field, usable in
any collection or single next to ordinary fields:

```ts
import { blocks } from "@nextlyhq/plugin-page-builder";
import { defineSingle, text } from "nextly/config";

export const Homepage = defineSingle({
  slug: "homepage",
  fields: [text({ name: "title" }), blocks({ name: "content" })],
});
```

## Reading content into a page

The **collection loop** block queries one of your collections and repeats its child
blocks once per entry — a post list, a team grid, a product row — without anyone writing
a query. The developer decides which collections are available to it; the editor decides
what each repeated item looks like.

## Related

- [Block document format](https://nextlyhq.com/docs/api-reference/block-document-format) — how a page is stored
- [Plugins](https://nextlyhq.com/docs/plugins) — the SDK this plugin is built on
- [Preview](https://nextlyhq.com/docs/preview) — see a page before it is published
- [Routing and SEO](https://nextlyhq.com/docs/guides/routing-and-seo) — how paths resolve

---
title: Localization
description: Run the same site in several languages, with a fallback when a translation is missing, and publish each language separately.
url: https://nextlyhq.com/docs/localization
---

Localization lets one document exist in several languages. An editor switches language at
the top of the edit screen and writes the Spanish version of the same post, without
creating a second post.

## Availability

| | |
|---|---|
| Built in | No plugin required |
| Admin | Language switcher on edit screens, plus a translations overview |
| Permission | The same access as editing the document |

## Turn it on

Declare your languages once, in `nextly.config.ts`:

```ts
import { defineConfig } from "nextly";

export default defineConfig({
  localization: {
    locales: [
      "en",
      { code: "es", label: "Español" },
      { code: "ar", label: "العربية", rtl: true },
      { code: "fr", label: "Français", fallbackLocale: "en" },
    ],
    defaultLocale: "en",
    fallback: true,
  },
});
```

A locale is either a bare code or an object. The object form carries:

| Key | Meaning |
|---|---|
| `code` | The locale code, e.g. `es` |
| `label` | What the admin shows in the language switcher |
| `rtl` | Renders that language right-to-left |
| `fallbackLocale` | Which language (or ordered list) to fall back to |

## Choose what gets translated

Mark a whole collection localized, then opt individual fields out:

```ts
import { defineCollection, text } from "nextly/config";

export const Posts = defineCollection({
  slug: "posts",
  localized: true,
  fields: [
    text({ name: "title" }),
    // Not worth translating: the same value in every language.
    text({ name: "externalId", localized: false }),
  ],
});
```

Fields inherit the collection's setting, so the common case is one flag.

## Fallback chains

`fallback: true` means a missing translation falls back rather than rendering empty. A
locale can name its own chain — `fallbackLocale: ["es", "en"]` tries Spanish, then
English. Without a chain, the default locale is used.

## Publishing one language at a time

Per-locale publishing needs **two** flags, not one. `localized` gives you translations;
`status` gives you the draft/published lifecycle. Only with both does each language get its
own state:

```ts
import { defineCollection, text } from "nextly/config";

export const Posts = defineCollection({
  slug: "posts",
  localized: true,
  status: true,
  fields: [text({ name: "title" })],
});
```

With both set, publishing the Spanish version does not publish the French one, and a language
still being translated stays invisible while the others are live.

<Callout type="warn">
With `localized: true` alone you get translations and no lifecycle — there is nothing to
publish per language, because the entity has no draft/published state at all.
</Callout>

<Callout type="warn">
This is per-locale **publishing**, not per-locale scheduling. A
[content release](https://nextlyhq.com/docs/releases) schedules the whole document across every language;
it cannot schedule one language on its own.
</Callout>

## Related

- [Draft and published status](https://nextlyhq.com/docs/guides/draft-published-status)
- [Content releases](https://nextlyhq.com/docs/releases) — publishing a set of documents together
- [Versions](https://nextlyhq.com/docs/versions) — history per document

---
title: Version History
description: Every save is recorded, so you can see what changed, compare any two versions, and put an earlier one back.
url: https://nextlyhq.com/docs/versions
---

Version history is **opt-in per collection or single**. Turn it on and every create and
update records a version, so nothing is lost when someone overwrites a paragraph and "who
changed this, and when" has an answer.

```ts
import { defineCollection, text } from "nextly/config";

export const Posts = defineCollection({
  slug: "posts",
  versions: true,
  fields: [text({ name: "title" })],
});
```

`status: true` also switches history on by itself: an entity with the draft/publish lifecycle
captures history even when `versions` is omitted.

Working drafts need **both** halves — drafts-enabled versioning *and* the lifecycle. Either
one alone gives you history and edits that write the live row:

| `versions` | `status` | History | Working drafts |
|---|---|---|---|
| omitted | `false` | No | No |
| omitted | `true` | **Yes** | No |
| `true` | `false` | Yes | **No** — the lifecycle is disabled |
| `true` | `true` | Yes | **Yes** |
| `{ drafts: false }` | either | Yes | No |

One further gate: a collection with a reachable password field never gets working drafts,
whatever the flags say. A snapshot strips passwords, so a draft could neither carry a password
change nor preserve one made while it was open.

<Callout type="warn">
An entity with neither flag is unversioned and captures nothing — and turning versioning on
later does not recover saves made before. Decide before you need it, not after.
</Callout>

## Availability

| | |
|---|---|
| Built in | No plugin required |
| Admin | A **Versions** panel on the edit screen |
| Permission | Reading history requires read access to the document; restoring requires update access |

## How a version is recorded

A version is written **inside the same database transaction as the content change**, using
the caller's transaction handle. So a version and the content it describes commit together
or not at all — there is no window where a document is saved and its history is not.

The stored snapshot has the same shape the read path returns, which is what makes a
restored version equal to a normal read rather than an approximation of one.

## Comparing two versions

The diff compares two snapshots **against the current field definitions**, not against the
schema as it was. That matters in practice: a field deleted since a snapshot was taken is
reported as no longer part of the document, rather than silently reappearing in the
comparison.

The comparison understands the shapes your content actually uses, including rich text and
block documents, so a diff of a page shows which blocks moved rather than one opaque
change.

Secret fields are masked in diffs. A password field's history never shows its values.

## Restoring

Restore writes **through the same update path a human edit uses**. Validation runs, hooks
run, component and relationship writes happen, events fire and the outbox is written —
exactly as if a person had made the change.

Two consequences worth knowing:

1. **Restoring destroys nothing.** Because a restore is an ordinary update, the state you
   are restoring over is itself captured as a version first. You can undo an undo.
2. **A restore cannot resurrect a field the schema no longer has.** The payload is filtered
   by the current schema, so restoring an old snapshot into a changed collection puts back
   what still exists and reports the rest.

System columns — creation timestamps, the creating user — are never carried back by a
restore, so history cannot be used to forge them.

## Working drafts

A working draft holds edits in progress separately from the published document, so someone
can work on a change over several days without it going live and without blocking anyone
else from seeing the current published version.

## Retention

History grows. Retention policies trim old versions on a schedule so the table does not
grow without limit. Published versions are governed separately from drafts, because the
two have different value: a superseded draft is usually noise, and a previously published
version is usually evidence.

## Related

- [Draft and published status](https://nextlyhq.com/docs/guides/draft-published-status)
- [Content releases](https://nextlyhq.com/docs/releases)
- [Audit log](https://nextlyhq.com/docs/audit-log) — who did what, across the system

---
title: Content Releases
description: Group documents into a release and publish or unpublish them together, at a time you choose.
url: https://nextlyhq.com/docs/releases
---

A release is a set of documents that go live at the same instant. A product launch touching
a landing page, three blog posts and a pricing single becomes one thing you schedule, rather
than five things someone has to publish in the right order at 9am.

Each member of a release is set to either **publish** or **unpublish**, so the same release
can put new pages live and retire old ones in the same moment.

## Availability

| | |
|---|---|
| Built in | No plugin required |
| Admin | A **Releases** section with a calendar view, and an "Add to release" action on documents |
| Permission | Scheduling requires publish access. A key scoped only to publishing releases can schedule without holding a general read grant |

## What it is not

<Callout type="warn">
This is **scheduled publishing**, not an approval workflow. There are no review stages,
transitions or assignees. If you need "editor submits, manager approves, then it goes
live", that is not what a release does.
</Callout>

## The shape of a release

| Step | What happens |
|---|---|
| Create | An empty release with a name |
| Add members | Each member names a document and an action, `publish` or `unpublish` |
| Schedule | The release is given a time. Blocking problems are checked first |
| Apply | On a background-jobs pass after that time, every member's action is applied |
| Cancel | An unapplied release can be cancelled |

## Scheduling stores a time; a job runner applies it

Scheduling records when a release is due. The work is done by a `releases:drain` sweep that
runs as part of the [background jobs](https://nextlyhq.com/docs/jobs) pass, triggered by calling the jobs route
from a cron job, a platform scheduler, or an operator.

The scaffolded apps mount Nextly's handlers at `src/app/admin/api/[[...params]]/route.ts`, so
the URL is:

```
POST /admin/api/jobs/run
```

<Callout type="warn">
There is no general `/api` handler in a scaffolded app, so a scheduler pointed at
`/api/jobs/run` gets a 404 and your releases never publish. If you mounted the handlers
somewhere else, use that path instead.
</Callout>

<Callout type="warn">
**With no scheduler configured, a release stays scheduled forever.** Its due time passes and
nothing happens, because nothing ran the sweep. Set up an authenticated periodic call to
`/api/jobs/run` before you rely on scheduling.
</Callout>

A pass is bounded: it claims at most 10 queued jobs, and it stops **starting** new ones after
20 seconds. That 20 seconds is a budget for starting work, not a hard ceiling on the request —
the check happens before each claim, so a handler already running is awaited to completion and
the call can overrun. Size any serverless timeout for the slowest handler, not for 20 seconds.

The sweep can also defer work past its deadline while still reporting success. So a release is
applied on the first pass that actually **reaches and completes** it, which is not always the
first pass after its due time. With a backlog, or several expensive releases due together,
expect it a pass or two later. Treat the scheduled time as "not before", not as "at".

## Blocking reasons

Before a release can be scheduled, it is checked for problems that would make it fail
half-way — a member pointing at a document that no longer exists, for example. Those are
reported as **blocking reasons** so they can be fixed while there is still time, rather
than surfacing as a partial publish at 9am.

An empty release has no blockers; there is nothing to go wrong.

## One release covers every language

A member is the whole document. Adding a post to a release schedules that post in every
language it has.

<Callout type="warn">
Per-locale scheduling is **not** supported: adding a member that names a single locale is
refused, and the admin only offers the action from a document's default locale. Each
language does have its own published state — see [Localization](https://nextlyhq.com/docs/localization) — but
that is publishing, not scheduling.
</Callout>

## Related

- [Localization](https://nextlyhq.com/docs/localization) — per-language publishing
- [Draft and published status](https://nextlyhq.com/docs/guides/draft-published-status)
- [Versions](https://nextlyhq.com/docs/versions) — what a publish changed

---
title: Roles and Permissions
description: Control who can do what, down to individual fields.
url: https://nextlyhq.com/docs/permissions
---

Access control answers three questions, at three levels of detail: what a role may do,
which documents it may do it to, and which fields inside those documents it may see or
change.

## Availability

| | |
|---|---|
| Built in | No plugin required, and not gated behind a paid tier |
| Admin | A **Roles** screen for managing roles and their grants |
| Applies to | The REST API and the admin. The Direct API runs as trusted server code and **bypasses collection and document rules by default** — see below |

## Roles and grants

A role holds grants named `<action>-<resource>`: `create-posts`, `delete-media`,
`publish-content-releases`, `update-users`. A user's roles are the union of their grants.

Because grants are per-resource, a role can be narrow in a way that is actually useful — a
release manager who may schedule releases without holding a general read grant over
everything.

## Collection access

Grants say what a role may do. Collection access says which documents:

```ts
import { defineCollection, relationship, text } from "nextly/config";

export const Posts = defineCollection({
  slug: "posts",
  fields: [
    text({ name: "title" }),
    relationship({ name: "author", relationTo: "users" }),
  ],
  access: {
    read: true,
    create: ({ roles }) => roles.includes("editor") || roles.includes("admin"),
  },
});
```

`true` means anyone, including unauthenticated readers. A function receives the request
context and decides.

## Field-level access

Any field takes its own `access`, with separate `create`, `read` and `update` rules:

```ts
import { defineCollection, text } from "nextly/config";

export const Users = defineCollection({
  slug: "users",
  fields: [
    text({ name: "name" }),
    text({
      name: "internalNotes",
      access: {
        read: ({ req }) => req.user?.role === "admin",
        update: ({ req }) => req.user?.role === "admin",
      },
    }),
  ],
});
```

A field the reader may not see is removed from the response rather than blanked, and a
field they may not change is rejected on write rather than silently dropped.

This is the level most systems either do not have or sell separately. It is what lets one
collection serve two audiences — an editor who sees the article, and a finance user who
also sees the fields describing what it cost.

## The Direct API bypasses these rules by default

The Direct API is trusted server code, so `overrideAccess` defaults to `true` and collection
and document rules are **skipped**. This is deliberate — server code fetching content for a
page should not be filtered as though it were an anonymous visitor — but it means a query
written on behalf of a request does not enforce anything unless you say so:

```ts
const posts = await nextly.find({
  collection: "posts",
  // Both are required. Without a user, an owner rule has nobody to compare
  // against, so it is skipped rather than failed.
  overrideAccess: false,
  user: requestUser,
});
```

<Callout type="warn">
**Leaving `overrideAccess` at its default is the case that leaks.** Reading on behalf of a
visitor without setting `overrideAccess: false` returns rows that visitor was not allowed to
see. This is the easiest way to expose data with Nextly.
</Callout>

Forgetting the `user` is a different and much less dangerous mistake. An owner-based rule has
nobody to compare against, so the request is refused rather than answered loosely — you get
an authorization error, not somebody else's rows. If a query that should return data returns
"authentication required", a missing `user` alongside `overrideAccess: false` is the first
thing to check.

Field-level rules behave differently: they run whenever `overrideAccess` is `false`, user or
not, because "which fields may this writer set" has a sensible answer for nobody. Internal
code that genuinely needs to write a protected field says so with `overrideAccess: true`.

## Related

- [Authentication](https://nextlyhq.com/docs/guides/authentication) — how a user proves who they are
- [Audit log](https://nextlyhq.com/docs/audit-log) — what they did

---
title: Audit Log
description: A durable record of who changed what, and when.
url: https://nextlyhq.com/docs/audit-log
---

The audit log records mutations as they happen: which user, which action, which document,
and which fields changed.

## Availability

| | |
|---|---|
| Built in | No plugin required, and not gated behind a paid tier |
| Admin | Activity is surfaced on the dashboard |
| Permission | Reading activity is an admin capability |

## What a record holds

| Field | Meaning |
|---|---|
| Actor | The signed-in user responsible |
| Action | What happened — a create, an update, a delete |
| Target | The collection and document |
| Changed fields | Which fields differed, computed from the write itself |

<Callout type="warn">
**Only writes by a signed-in user are recorded.** A mutation made through an API key, or by
internal or system context such as a seed or a migration, produces no activity entry. If you
rely on this log for compliance, that gap is the thing to know: the absence of an entry does
not mean nothing happened.
</Callout>

Recording the changed field list — rather than the whole document — keeps the log useful
without turning it into a second copy of your content. [Version
history](https://nextlyhq.com/docs/versions) is where the full before-and-after lives.

## Erasing a person without erasing the record

A deletion request under privacy law asks you to remove a person's data. An audit log
exists precisely so records cannot quietly disappear. Those pull in opposite directions.

Nextly resolves it by separating the actor from the act: a person's identifying details can
be erased while the entries they produced remain, still counted, still ordered, still
showing that a change happened and what it touched. You keep the record and lose the
person, which is what both obligations actually require.

## Retention

Audit entries are pruned on a schedule, so the log holds a useful window rather than
growing forever.

## Related

- [Version history](https://nextlyhq.com/docs/versions) — the full before-and-after of one document
- [Roles and permissions](https://nextlyhq.com/docs/permissions)
- [Webhooks](https://nextlyhq.com/docs/webhooks) — the same events, delivered to another system

---
title: Draft Preview Links
description: Share an unpublished draft with someone who has no account. A preview link is a signed, expiring, per-entry credential — mount one route, add one draft gate, and declare where each collection is served.
url: https://nextlyhq.com/docs/preview
---

A preview link lets an editor show an unpublished draft to someone with **no
Nextly account at all** — a client, a reviewer, a colleague in another
department. The link carries its own signed authorization, so the recipient
never signs in and never sees anything beyond the one entry it names.

This is the part worth knowing before anything else: the link is scoped to a
**single entry**, it **expires**, and it can be **revoked**. It is not a
password to your drafts.

## The three pieces

Draft preview needs three things wired, and it is not obvious when one is
missing, because the symptom is always the same: a link that answers `404`.

| Piece | Where it goes | What happens without it |
| --- | --- | --- |
| The preview **route** | `app/api/preview/route.ts` | The link 404s immediately |
| The **draft gate** | On the route that renders your content | The link redirects, then 404s on a page that looks correct |
| The collection's **preview URL** | `admin.preview` in the collection | The admin refuses to mint a link, and says why |

### 1. Mount the route

One file, three lines:

```ts
// src/app/api/preview/route.ts
import { createPreviewRoute } from "nextly/runtime";

export const { GET } = createPreviewRoute();
```

It needs no configuration. The signing key, the revocation counter, Next's
draft mode and the request's cookies are all read from the running instance.

**Why this lives in your app and not in the package:** the draft cookie is set
by whichever *origin* serves the route. If your admin is deployed on a
different host from your site, a route inside the package would set the cookie
on the admin's host and then send the reviewer to a site that never receives
it — and they would silently see the **published** page instead of the draft.
Mounting it in your app puts it on the site's own origin, where it belongs.

If you mount it somewhere else, say so, or the admin will build links pointing
at the default:

```ts
// nextly.config.ts
import { defineConfig } from "nextly";

export default defineConfig({
  preview: { route: "/next/preview" },
});
```

It is a mount path and nothing else — site-relative, with no host, no query and
no fragment. A value carrying any of those is refused when the configuration is
read, rather than at the moment an editor clicks copy: the link's own `token`
parameter is appended to this path, so a path already carrying a `?` has nowhere
to put it.

### 2. Add the draft gate to your content route

This is the step most easily missed, and its failure is the most confusing.

```ts
import { createBlocksPage } from "@nextlyhq/blocks-react/next";
import { previewDraftGate } from "nextly/runtime";

const { ContentPage, generateMetadata } = createBlocksPage({
  collections: ["pages"],
  field: "content",
  // State the locale on a localized site, even for the default language.
  locale: "en",
  draft: previewDraftGate(),
});
```

<Callout type="warn">
**On a localized site, `locale` is required for preview to work** — and omitting
it fails in the confusing direction. The admin mints a token naming a resolved
locale even for the default language, and the gate compares that against the
route's own. A route that states none compares against `undefined`, so every
localized token is refused *after* the redirect — the visitor lands on the page
and gets the 404 this guide exists to prevent.

Nothing infers the default for you, deliberately: inferring it means reading
configuration per request, and a route's reader may defer booting until its
first query — so the inferred value would differ between the first request of a
cold process and every one after, authorizing previews intermittently.
</Callout>

Without it your route serves **published entries only**. A preview link then
verifies correctly, redirects correctly, and answers `404` from a page that
looks entirely right — indistinguishable, to the person who opened it, from a
link that had expired.

`previewDraftGate()` grants exactly the one entry the visitor's token names.
That distinction matters more than it looks: Next's own draft mode is a single
boolean for the whole host, so enabling it alone would turn a link meant for
one unpublished page into a key to **every** unpublished page on the site.

<Callout type="warn">
`createPublicContentRoute` and `createPublicBlocksPage` refuse a `draft` hook,
deliberately. A draft read cannot be cached, so accepting one would quietly
turn a statically-rendered route dynamic. Mount previewable paths on
`createContentRoute` / `createBlocksPage` instead.
</Callout>

### 3. Tell Nextly where the collection is served

Nextly cannot work out a URL on its own. If a post has the slug
`hello-world`, only your app knows whether that is `/hello-world`,
`/blog/hello-world`, or `/en/blog/hello-world` — you wrote the routing.

**Code-first**, a function of the entry:

```ts
import { defineCollection } from "nextly";

export const Posts = defineCollection({
  slug: "posts",
  status: true,
  admin: {
    preview: {
      // `null` means "not previewable yet" — a post with no slug becomes
      // previewable once it has one.
      url: entry =>
        typeof entry.slug === "string" && entry.slug !== ""
          ? `/blog/${encodeURIComponent(entry.slug)}`
          : null,
    },
  },
  fields: [/* ... */],
});
```

**In the Visual Schema Builder**, a path with `{field}` placeholders, because
no database column can hold a function:

```
/blog/{slug}
```

Both answer the same question and are resolved by the same code.

If a collection declares neither, **the admin refuses to mint a link** and
tells the editor that a developer needs to add a preview URL. That refusal is
deliberate: the alternative was reporting success and handing over a link with
nowhere to open.

#### Pages built in the page builder

The `pages` collection comes from the page-builder plugin, so you do not declare
it — you tell the plugin where you serve it:

```ts
// nextly.config.ts
plugins: [pageBuilder({ pagePreviewPath: "/{slug}" })];
```

Use `"/blocks/{slug}"`, or whatever prefix your blocks route is mounted under.
There is no default, for the reason above: the plugin cannot see your routing,
and a guessed path would trade the refusal that names the remedy for a 404 that
names nothing.

## Using it

An editor opens an entry, clicks **Copy shareable link**, and pastes it to
whoever needs to see the draft. Opening it starts a preview session scoped to
that entry and forwards to the page.

The link is a **bearer credential** — anyone holding it can read that one
draft. It is minted fresh on every click rather than cached, because it carries
an expiry and a stale one would be handed out after it stopped working.

### Expiry and revocation

Links last **one hour** by default and at most **seven days**. Asking for
longer is refused rather than quietly shortened, because an editor who believes
a link lasts a week and finds it dead is worse off than one who was told no.

To invalidate **every** outstanding link at once — including sessions already
open — raise the site's preview generation by revoking. That requires
`manage settings`, because the effect is site-wide: one editor revoking would
otherwise break every other editor's links.

### What a reviewer can and cannot see

They can read the one entry the link names, in the locale it names, as it
stands right now — including unpublished edits to an already-published page.

They cannot browse to other drafts. Every refusal — an expired token, a revoked
one, a forged one, an entry since deleted — answers with the same bare `404`,
with no cookie and no draft mode. That uniformity is intentional: a different
answer for "no such entry" would let a stranger discover which entries have
drafts.

## Requirements

- **`NEXTLY_SECRET` must be set.** Preview tokens are signed with a key derived
  from it; without one, a link would be forgeable by anyone who could guess an
  entry id.
- The collection needs a Draft / Published lifecycle to have a draft worth
  previewing — see [Draft / Published Status](https://nextlyhq.com/docs/guides/draft-published-status).

## Troubleshooting

**The link 404s straight away.** The route is not mounted, or is mounted
somewhere other than where the admin thinks. Check `app/api/preview/route.ts`
exists, and that `preview.route` in `nextly.config.ts` matches it.

**The link redirects, then 404s.** The destination route has no
`draft: previewDraftGate()`. This is the common one — in development the server
logs a warning naming the route when a valid preview cookie reaches a route
that cannot honour it.

**The admin says a preview URL is not configured.** The collection declares no
`admin.preview`. Add one, as in step 3.

**The admin says this site has no address configured.** The link has to name a
host, because it travels by email and chat to someone with no session. Nextly
takes that host from the **Site URL** setting, and falls back to
`NEXT_PUBLIC_APP_URL` when it is empty — so this means neither is set, or one of
them holds something that is not an `http(s)` address. Set either; the setting
is what you want when the admin and the site are on different origins, since it
is the only one that can name the site rather than the app the admin runs in.

**The reviewer sees the published page, not the draft.** The draft cookie was
set on a different origin from the one serving the page — usually an admin and
site on separate hosts with the preview route mounted on the admin. It belongs
on the site.

**Everything is wired and a localized entry still 404s.** The content route
states no `locale`. See the callout in step 2: the token names a locale and the
gate compares it against the route's, so a route that states none refuses every
localized token.

**The admin says this entry has no preview address yet.** The collection's
declaration returned nothing for this document — a `url` function answering
`null`, or a `urlTemplate` whose placeholder field is still empty. Filling in
the field the address is built from, usually the slug, makes it shareable. This
is distinct from a collection that declares no preview at all, which is a
developer's job rather than an editor's.

## See also

- [Draft / Published Status](https://nextlyhq.com/docs/guides/draft-published-status) — the lifecycle a preview shows
- [Routing and SEO](https://nextlyhq.com/docs/guides/routing-and-seo) — the content routes a preview lands on
- [ISR and Caching](https://nextlyhq.com/docs/guides/isr-caching) — why a draft read is never cached

---
title: Deployment
description: Deploy a Nextly application to Vercel (recommended) or self-host on Node.js. Production checklist, environment variables, and database migrations.
url: https://nextlyhq.com/docs/guides/deployment
---

A Nextly application is a standard Next.js app, so anywhere Next.js runs is fair game. This guide covers the two paths Nextly is built around:

- **Vercel** (recommended) -- the default target. Zero-config Next.js, first-class Vercel Blob storage, build-step migrations.
- **Self-host** -- Node.js 20+ behind a process manager and reverse proxy. Linked out for the operator-side details rather than reproduced here.

Whichever you choose, run database migrations on a CI/CD step (or your laptop) **before** the new app code takes traffic. The deployed app never touches schema -- see [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) for why.

## Production checklist (the short list)

Before you ship, set the following:

| Variable | Required | Purpose |
|---|---|---|
| `NODE_ENV` | yes | Set to `production`. |
| `DB_DIALECT` | yes | `postgresql`, `mysql`, or `sqlite`. PostgreSQL recommended. |
| `DATABASE_URL` | yes (Postgres / MySQL) | Database connection string. |
| `NEXTLY_SECRET` | yes | JWT signing secret, **at least 32 characters**. Generate with `openssl rand -base64 32`. |
| `NEXT_PUBLIC_APP_URL` | yes | The public URL of your deployment (used in client code and email links). |
| `NEXTLY_ALLOWED_ORIGINS` | optional | Comma-separated additional CSRF origins (e.g. a separate frontend domain). |

Plus storage env vars if you're using cloud storage (see [Media & Storage](https://nextlyhq.com/docs/guides/media-storage)) and email env vars if you're using a real provider (see [Email](https://nextlyhq.com/docs/guides/email)).

> **Note:** Boot-time validation refuses to start in production unless `NEXTLY_SECRET` is at least 32 characters and `NEXT_PUBLIC_APP_URL` is set.

## Deploy to Vercel

Vercel is the recommended platform for Nextly. Next.js detection is automatic, the Vercel Blob adapter is the easiest storage option, and the build step doubles as a migration runner.

### 1. Push to GitHub and import

1. Push the project to GitHub, GitLab, or Bitbucket.
2. Open the [Vercel Dashboard](https://vercel.com/new), import the repository.
3. Vercel detects Next.js and configures the build pipeline. Override only if you've customised the build script (see step 3 below).

### 2. Configure environment variables

In **Project Settings -> Environment Variables**, add everything from the production checklist above, plus storage and email variables you intend to use.

Set them for **Production** and **Preview** environments separately if you want preview deployments to talk to a staging database.

### 3. Build command

A scaffolded Nextly project ships this `build` script in `package.json`:

```json
{
  "scripts": {
    "build": "nextly migrate && next build"
  }
}
```

The `nextly migrate` step runs against the database referenced by `DATABASE_URL` during the Vercel build, so pending migrations are applied as part of every deploy. Migrations are forward-only -- to undo, write a new corrective migration. See [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) for the deeper trade-offs (build-time vs. CI-step migrations) and recovery patterns.

If you'd rather run migrations in a separate CI job before the Vercel deploy promotes (recommended once you have multiple developers / preview deploys), wire it into a GitHub Actions workflow as described in the migrations guide and remove `nextly migrate` from `build`.

### 4. Storage on Vercel

The default zero-config local-disk adapter does **not** work on Vercel -- serverless function instances are ephemeral, so `./public/uploads/` is wiped on cold start. Pick one of:

- **Vercel Blob** (easiest) -- install `@nextlyhq/storage-vercel-blob`, set `BLOB_READ_WRITE_TOKEN`. The auto-detection picks it up:

  ```typescript
  // nextly.config.ts
  import { defineConfig } from "nextly/config";
  import { getStorageFromEnv } from "nextly/storage";

  export default defineConfig({
    storage: await getStorageFromEnv(),
  });
  ```

- **S3 / R2 / DigitalOcean Spaces / etc.** -- install `@nextlyhq/storage-s3`, set `S3_BUCKET` + `S3_REGION` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (and `S3_ENDPOINT` + `S3_FORCE_PATH_STYLE` for non-AWS providers).

Vercel's serverless functions also have a 4.5MB request-body limit. Enable client-side direct uploads on storage collections that need to accept larger files:

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { vercelBlobStorage } from "@nextlyhq/storage-vercel-blob";

export default defineConfig({
  storage: [
    vercelBlobStorage({
      token: process.env.BLOB_READ_WRITE_TOKEN,
      collections: {
        media: {
          clientUploads: true,
        },
      },
    }),
  ],
});
```

See [Media & Storage](https://nextlyhq.com/docs/guides/media-storage) for the full storage reference.

### 5. Database

Use a managed PostgreSQL service that's reachable from Vercel's IP ranges:

- [Vercel Postgres](https://vercel.com/storage/postgres)
- [Neon](https://neon.tech)
- [Supabase](https://supabase.com)
- [PlanetScale](https://planetscale.com) (MySQL)

SQLite is **not** suitable for Vercel deployments -- the file would be wiped on every cold start. See [Database](https://nextlyhq.com/docs/database) for adapter-specific guidance.

## Self-host with Node.js

Run Nextly on any host that supports Node.js 20+. The deployment shape is intentionally boring: build the app, run it under a process manager, put a reverse proxy in front for SSL.

### Requirements

- **Node.js 20+** (matches the `serverExternalPackages` and `sharp` ABI requirements).
- **A process manager** -- pm2, systemd, Docker, or similar. Keep the Node process supervised so crashes auto-restart.
- **A reverse proxy** -- nginx or Caddy in front for TLS termination, HTTP/2, and access logging.

### Build and start

```bash
pnpm install --frozen-lockfile
pnpm build
pnpm start
```

The scaffolded `build` script runs `nextly migrate && next build`, and `pnpm start` is `next start`. If you'd rather run migrations as a separate step (recommended for production with zero-downtime deploys), drop `nextly migrate` from `build` and run it via your CI pipeline before promoting the new release.

### Environment variables

Configure the same variables listed in the production checklist above. On most hosts that means a `.env` file outside the repo (loaded by your process manager) or a secrets manager.

### Process manager and reverse proxy

Use a process manager (pm2, systemd, Docker, etc.) and a reverse proxy (nginx, Caddy, etc.) -- consult their documentation for setup specific to your distribution. The Nextly process is a plain Next.js server; nothing about it requires special configuration beyond ensuring the proxy forwards `Host` and `X-Forwarded-Proto` so callbacks resolve correctly.

If your reverse proxy is on a separate IP and you rely on rate-limiting / refresh-token IP binding, set `security.trustProxy: true` in `nextly.config.ts` and populate the `TRUSTED_PROXY_IPS` env var with the proxy's CIDR ranges. Otherwise Nextly ignores `X-Forwarded-For` and treats every request as coming from a single bucket, which is the safe default for direct-internet deployments.

### Migrations on deploy

For self-hosted deploys, the same forward-only model applies. Run `nextly migrate` against the production database **before** the new app binary takes traffic. See [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) for GitHub Actions, Railway, Render, Fly.io, and AWS examples.

## Final checklist

Before going live, verify:

- [ ] `NODE_ENV=production`.
- [ ] `NEXTLY_SECRET` is at least 32 characters (generated with `openssl rand -base64 32`).
- [ ] `DATABASE_URL` points to a production database (not localhost / SQLite).
- [ ] `NEXT_PUBLIC_APP_URL` is the public URL of your deployment.
- [ ] `NEXTLY_ALLOWED_ORIGINS` lists any additional CSRF origins (separate frontend domain, mobile bundle, etc.).
- [ ] Storage adapter is configured for non-ephemeral filesystems (no local disk on serverless).
- [ ] An email provider is configured (Resend, SMTP, or SendLayer) -- without one, password-reset and verification tokens are returned in the API response as a development fallback.
- [ ] All pending migrations have been applied (`nextly migrate:status` reports zero pending).
- [ ] The reverse proxy / load balancer terminates TLS and forwards real client headers.
- [ ] Database backups are configured (your hosting provider's snapshots, point-in-time recovery, etc.).
- [ ] Monitoring / error reporting is wired up (Sentry, Datadog, etc.).
- [ ] `.env*` files are not committed to version control.

## Next steps

- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) -- forward-only migration model, GitHub Actions and other CI examples.
- [Authentication](https://nextlyhq.com/docs/guides/authentication) -- session, RBAC, and API key configuration.
- [Media & Storage](https://nextlyhq.com/docs/guides/media-storage) -- adapter-specific configuration for S3, Vercel Blob, Uploadthing, local disk.
- [Email](https://nextlyhq.com/docs/guides/email) -- provider setup and local Mailpit testing.
- [Environment Variables](https://nextlyhq.com/docs/configuration/environment) -- full environment variable reference.
- [Database](https://nextlyhq.com/docs/database) -- adapter setup and connection options.

---
title: Production migrations
description: Ship database schema changes to production safely with the Nextly migration CLI. Forward-only model, GitHub Actions, Vercel build step, and other-platform patterns.
url: https://nextlyhq.com/docs/guides/production-migrations
---

Nextly's schema-evolution model splits responsibilities cleanly between development and production:

- **Local development:** `next dev` + Nextly's HMR pipeline auto-applies schema changes as you edit `nextly.config.ts`.
- **Production:** schema changes are committed as `.sql` files in your repo. A CI/CD step (or your laptop) runs `nextly migrate` against the production database **before** the new app code is deployed.

**By default the deployed Next.js app does not touch the schema** — you apply migrations in CI/build, before deploy (Patterns 1–3). Two production-grade options make this safe and flexible:

- **A migrate lock** guards every `nextly migrate`, so two runs never apply schema at once. It's a pooler-safe lock row (works through Neon/Supabase PgBouncer) with a TTL, plus a `--force-unlock` escape hatch.
- **Optional run-on-boot** (`db.runMigrationsOnBoot`, opt-in) applies pending migrations during app startup in production — safe across multiple instances thanks to the lock. See [Pattern 4](#pattern-4-run-migrations-on-boot-opt-in).

This page covers the common deploy patterns. Pick whichever fits your stack.

## The CLI commands you'll use

| Command | Purpose |
|---|---|
| `nextly migrate:baseline` | Run **once**, when a project developed with `db:sync` starts using migrations. Records the schema the database already has as the starting point. See [Graduating from `db:sync`](#graduating-from-dbsync-to-migrations). |
| `nextly migrate:create [name]` | After you edit `nextly.config.ts`, generate a `.sql` file capturing the change. Commit it to git. |
| `nextly migrate:check` | CI gate. Verifies migration file integrity and config drift. Does NOT connect to a database. |
| `nextly migrate` | Applies pending `.sql` files to the target database. Run from CI or your laptop. |
| `nextly migrate:status` | Shows applied / pending / failed migrations with their checksums and durations. |
| `nextly migrate:resolve` | Recovery: mark a file applied/rolled-back or clean up a failed attempt without running SQL. See [Recovering from a failed migration](#recovering-from-a-failed-migration). |
| `nextly migrate:fresh` | Wipes all tables and re-applies every migration. Local-dev only. Confirmation required. |
| `nextly migrate:down` | Rolls back the most-recently-applied migration(s) using their `-- DOWN` section. CLI-only; never runs on boot. See [Rolling back a migration](#rolling-back-a-migration). |

Global flags inherited from the root `nextly` command: `--config <path>` (custom `nextly.config.ts` path), `--cwd <path>`, `--verbose`, `-q/--quiet`.

`nextly migrate:down` reverts a single migration at a time (or the last N via `--step`). It is a manual, CLI-only tool — it never runs on boot. **In production, prefer rolling forward** with a new corrective migration, or restore from a backup; rollback restores schema *shape*, not row *data*. See [Rolling back a migration](#rolling-back-a-migration).

### Per-command flags

- `nextly migrate` -- `--dry-run` (preview without executing), `--step <n>` (apply only N pending migrations), `--force-unlock` (clear a stale migrate lock left by a crashed run, then migrate).
- `nextly migrate:baseline` -- `--name <name>` (the migration's name; defaults to `baseline`), `--force-unlock`.
- `nextly migrate:create` -- `[name]` positional or `--name <name>` flag, `--blank` (empty file for custom SQL), `--non-interactive`, `--accept-renames`.
- `nextly migrate:status` -- `--json` (machine-readable output for CI scripting).
- `nextly migrate:resolve` -- exactly one of `--applied <file>`, `--rolled-back <file>`, `--failed-cleanup <file>`; `--skip-verify` (with `--applied`, skip the live-vs-snapshot check).
- `nextly migrate:fresh` -- `-f, --force` (skip confirmation), `--seed` (run seeders after migrations).
- `nextly migrate:down` -- `--step <n>` (roll back the last N migrations), `--allow-data-loss` (required when the DOWN drops a table or column), `--yes` (required in production), `--dry-run` (show targets + DOWN SQL without executing), `--force-unlock`.

---

## Graduating from `db:sync` to migrations

`nextly db:sync` is the development loop: it pushes your config straight at the
database, with no migration files in between. Production wants the opposite —
reviewable files applied in a known order. Moving from one to the other takes
one command.

The problem it solves is that your database already has tables and your
migration history has nothing in it. Without a starting point, the first
`nextly migrate:create` compares your config to an empty schema and writes
`CREATE TABLE` for every table that already exists. That file cannot be applied
to the database it came from.

Run this once, from a machine that can reach the database you developed against:

```bash
nextly migrate:baseline
```

It records the schema the database already has as the point the history begins,
writing two files:

- `migrations/<timestamp>_baseline.sql` — the statements that would build that
  schema from nothing. It is **not** run against your database; it is recorded
  as already applied. It exists so a new environment, a CI job, or
  `nextly migrate:fresh` can build the same schema from the history alone.
- `migrations/meta/<timestamp>_baseline.snapshot.json` — the starting point
  every later `migrate:create` measures its diff from.

Commit both. From then on the normal loop applies: edit `nextly.config.ts`, run
`nextly migrate:create`, and get a file containing only what changed.

<Callout type="warn">
**Do not keep using `db:sync` against a database that holds content.** It compares your
config to the database, and when a column disappears and another appears on the same table
it has to guess whether that is a rename. It guesses rename.

On one real database, `db:sync` proposed **10 rename candidates**, including:

```
seo -> created_by          on dc_comparisons
seo -> first_published_at  on dc_comparisons
```

Every pair was an embedded field-group column being read as an unrelated system column.
Accepting them would have written content into `created_by` and `first_published_at`.
`migrate:create` proposed **zero** renames on the same database, because it diffs against
the recorded snapshot rather than guessing from shape.

`db:sync` is for a development database you are willing to throw away.
</Callout>

```bash
# One time, on the existing database
nextly migrate:baseline

# From now on, the ordinary loop
nextly migrate:create add_subtitle
nextly migrate
```

Two things it deliberately refuses:

- **A project that already has a migration history.** Baselining again would
  give it two starting points, and every later diff would depend on which one
  was read. It reports the snapshot it found and writes nothing.
- **An empty database.** There is nothing to adopt; your first migration is an
  ordinary `nextly migrate:create`.

If you reach this the other way round — you ran `nextly migrate` on a
`db:sync` project and it refused with schema drift where every difference reads
`+ table '...' present in DB` — that is this same situation, and the error
points here.

---

## Pattern 1: GitHub Actions runs migration before Vercel deploys (recommended)

Most teams should use this. The migration runs on a CI machine that explicitly has your prod DB credentials; if it fails, the Vercel deploy never happens. Old code keeps serving traffic on the old schema.

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  migrate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: Verify migration integrity
        run: pnpm exec nextly migrate:check

      - name: Apply pending migrations
        env:
          DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
          NEXTLY_APPLIED_BY: github-actions-${{ github.run_id }}
        run: pnpm exec nextly migrate

      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'
```

**Order of operations:**

1. CI VM checks out the code.
2. `nextly migrate:check` verifies file integrity + no uncommitted schema changes.
3. `nextly migrate` applies pending `.sql` files against the prod DB.
4. Vercel deploys the new app code.

If step 2 or 3 fails, step 4 doesn't run.

**Setting `NEXTLY_APPLIED_BY`** is optional but recommended. It populates the `applied_by` column in `nextly_migrations` so post-incident debugging can answer "which CI job applied this row?" When unset, the runtime falls back to `GITHUB_ACTOR` -> `USER` -> hostname.

## Pattern 2: Migration in Vercel's build step (simplest)

The default scaffold ships this `build` script in `package.json`:

```json
{
  "scripts": {
    "build": "nextly migrate && next build"
  }
}
```

Configure `DATABASE_URL` as a Vercel environment variable (available at build time). Every Vercel deploy applies pending migrations before compiling Next.js.

**Trade-offs:**

- Zero CI setup. Push to GitHub, Vercel does everything.
- Multiple Vercel deploys can race if you push twice in rapid succession (e.g. preview + production, or two PRs merging close together). Nextly's `filename` UNIQUE constraint catches double-insert; the second build will exit non-zero.
- The Vercel build machine needs prod DB access from its IP range (check with your DB host).

## Pattern 3: Manual deploys (laptop)

Run from your laptop:

```bash
DATABASE_URL=$PROD_URL pnpm exec nextly migrate
vercel --prod
```

For non-Vercel hosts, replace `vercel --prod` with whatever your deploy command is.

## Pattern 4: Run migrations on boot (opt-in)

For long-running servers/containers you can have the app apply pending migrations
during startup instead of (or in addition to) a CI step. Opt in via config:

```ts
// nextly.config.ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  db: {
    runMigrationsOnBoot: true, // default: false
  },
});
```

- **Production only** (`NODE_ENV === "production"`) — a no-op in development.
- Pending migrations apply during initialization, **under the migrate lock**, so
  multiple instances starting together are safe: one applies while the others
  wait, then all serve with the schema ready.
- **Failure-safe:** a failed boot migration is logged and the app continues (it
  does not crash the process); resolve with `nextly migrate`.
- Tune lock takeover with `db.migrateLockTtlSeconds` (default **900s**).

> **Serverless caveat.** Running migrations on boot adds work to cold starts. On
> platforms with many short-lived instances (e.g. Vercel), prefer the CI patterns
> above. Boot-time migrations suit long-running servers/containers.

## Environment-specific configurations

If your `nextly.config.ts` differs by environment (e.g. a plugin enabled only in
production), a migration generated in one environment can miss the other's
schema. Three ways to handle it:

1. **Edit the generated migration** after `migrate:create` to include the
   environment-specific changes.
2. **Temporarily enable the production env vars locally** when generating, so the
   migration captures the production shape.
3. **Use separate migration files per environment**, applied in the matching
   environment.

## Other platforms

Nextly's CLI is platform-agnostic. The pattern is the same on Railway, Render, Fly.io, or AWS:

1. Configure your deploy pipeline to run `nextly migrate` against the production DB.
2. Ensure that step runs **before** the new code is promoted.
3. If the migration fails, the deploy should abort.

Specific examples:

- **Railway:** Use `deploy.preDeployCommand` in `railway.json`. This runs once before the new revision takes traffic, so it does not race across replicas:
  ```json
  {
    "deploy": {
      "preDeployCommand": ["nextly migrate"]
    }
  }
  ```
  Do NOT put `nextly migrate` in `startCommand`. `startCommand` runs on every container start and would race across replicas, which is precisely the failure mode this guide is designed to avoid.
- **Render:** Use a [pre-deploy command](https://render.com/docs/deploys#pre-deploy-commands).
- **Fly.io:** Use a `release_command` in `fly.toml`. The `[deploy]` is a TOML section header:
  ```toml
  [deploy]
  release_command = "nextly migrate"
  ```
- **AWS (ECS, etc.):** Add a one-shot task in your pipeline that runs `nextly migrate` before updating the service.

---

## What `nextly migrate` does

1. Connects to the database via `DATABASE_URL`.
2. Reads the `nextly_migrations` table to see which `.sql` files have been applied.
3. Verifies SHA-256 hashes of already-applied files. **Hash mismatch = abort with `MIGRATION_TAMPERED` (exit 2).** No partial state, nothing else runs.
4. Discovers pending `.sql` files in your `migrations/` directory (sorted by filename timestamp).
5. Applies each pending file in a transaction (PostgreSQL/SQLite) or statement-by-statement (MySQL; see [database support](https://nextlyhq.com/docs/database/support) for MySQL caveats).
6. Records each applied file in `nextly_migrations` with `applied_at`, `applied_by`, `duration_ms`, `sha256`.

| Exit code | Meaning |
|---|---|
| 0 | All pending applied OR no pending |
| 1 | A migration failed during execution |
| 2 | `MIGRATION_TAMPERED`. Abort before running any. |
| 3 | `MIGRATION_MISSING`. Abort; file referenced in DB but missing from disk. |

## What `nextly migrate:check` does (CI-friendly, no DB)

Runs five integrity checks; first failure exits non-zero with a specific code:

| Check | What it catches |
|---|---|
| `CHECKSUM_MISMATCH` | A `.sql` file's content differs from its paired `.snapshot.json`'s recorded hash. Someone edited the file after it was generated. |
| `MISSING_SNAPSHOT` | A `.sql` file has no paired `.snapshot.json` (operator deleted the snapshot or the file was hand-added). |
| `INVALID_SNAPSHOT` | A `.snapshot.json` exists but is corrupt, hand-edited, or version-incompatible. |
| `MISSING_MIGRATION` | A `.snapshot.json` has no paired `.sql` (someone deleted the SQL but kept the snapshot). |
| `SCHEMA_DRIFT` | Your current `nextly.config.ts` doesn't match the latest snapshot. You forgot to run `migrate:create` after editing config. |

Run it in your PR CI to catch mistakes before they reach production.

## Environment variables

| Variable                     | Where used | Purpose                                                                 |
|------------------------------|------------|-------------------------------------------------------------------------|
| `DATABASE_URL`               | All commands | Target database. Required (except SQLite, which falls back to `file:./data/nextly.db`). |
| `NEXTLY_APPLIED_BY`          | `migrate`  | Recorded in `nextly_migrations.applied_by`. Falls back to `GITHUB_ACTOR` -> `USER` -> hostname. |
| `NEXTLY_ACCEPT_DATA_LOSS=1`  | `migrate`, `db:sync` | Acknowledge destructive changes (drops, type narrowings) without an interactive prompt. Required for CI runs of destructive migrations. |
| `NEXTLY_ALLOW_CORE_DESTRUCTIVE=1` | `migrate` | Allow a destructive change to Nextly's **own** core tables, which `migrate` otherwise refuses with `NEXTLY_CORE_DESTRUCTIVE_REFUSED`. Applies to every operation in the run — see below before setting it. |

## When `migrate` refuses a destructive core change

`nextly migrate` stops rather than run an operation that could lose data from Nextly's own
tables, reporting `NEXTLY_CORE_DESTRUCTIVE_REFUSED`. The refusal **names every operation it
refused** — the list you see is the whole list, not a sample — so you can judge them one at
a time.

| Operation | Verdict |
|---|---|
| A widening, e.g. `varchar(20)` → `varchar(255)` | **Safe.** Nothing that fits today stops fitting |
| A narrowing, e.g. `varchar(255)` → `varchar(20)` | **Safe only if you have measured the longest stored value** and it fits |
| A dropped column, or any other type change | **Stop.** Work out what happens to the existing values first |

Two independent facts make a widening safe: the direction, and knowing what the column
holds. A narrowing gives you the first only, so go and look:

```sql
SELECT max(length(your_column)) FROM your_table;
```

Then, and only then:

```bash
NEXTLY_ALLOW_CORE_DESTRUCTIVE=1 nextly migrate
```

<Callout type="warn">
The flag disables the refusal for **every** operation in that run, not just the one you
judged safe. Read the whole list before setting it.
</Callout>

## What you should never do

- **Don't call `nextly migrate` from your deployed app's runtime.** It's a CLI tool, not a runtime API. Nextly enforces this with an ESLint rule for code in `init/`, `route-handler/`, `dispatcher/`, `api/`, `actions/`, `direct-api/`, `routeHandler.ts`, and `next.ts`.
- **Don't edit applied migration files.** The hash check catches this and aborts with `MIGRATION_TAMPERED`. To change something already applied, write a new corrective migration.
- **Concurrent `nextly migrate` runs are guarded by the migrate lock.** A second concurrent run won't apply schema at the same time — it either errors with `NEXTLY_MIGRATE_LOCK_BUSY` (CLI) or waits (boot run). If a crashed run leaves a stale lock, clear it with `nextly migrate --force-unlock`. (The lock is a pooler-safe row with a TTL; the `filename` UNIQUE constraint remains a second line of defense.)

## Recovering from a failed migration

`nextly migrate` is forward-only. When a file partially applies or the live
schema drifts, use `nextly migrate:resolve` to fix the bookkeeping in
`nextly_schema_events` — it never runs migration SQL itself. All three modes
are idempotent (re-running a no-op exits 0) and take the same lock as `migrate`.

If `nextly migrate` fails partway through:

1. The failure is recorded as a `file_apply` event with `status='failed'` and structured `error_json` containing the SQL state and message.
2. Inspect with `nextly migrate:status --verbose`. The error JSON tells you what broke.
3. Pick the recovery that matches what actually happened:
   - **The file actually applied but wasn't recorded** (e.g. the process died after the DDL committed): `nextly migrate:resolve --applied <file>`. This verifies the live schema matches the file's target snapshot before recording it. Pass `--skip-verify` only if you have manually confirmed the state.
   - **A failed attempt is blocking retries and the `.sql` needs editing first:** `nextly migrate:resolve --failed-cleanup <file>` flips the stuck failed row to `rolled_back`. Edit the file, then run `nextly migrate` again.
   - **You need to re-run a file** that was recorded as applied: `nextly migrate:resolve --rolled-back <file>` — the next `nextly migrate` treats it as pending again.
4. Otherwise, fix the SQL (revert + regenerate via `migrate:create`) or the underlying database state, then re-run `nextly migrate`.

For MySQL specifically, partial state is possible because MySQL DDL auto-commits per statement. Manual cleanup may be needed; see [MySQL caveats](https://nextlyhq.com/docs/database/support) for the recovery playbook.

### Core schema drift after `nextly upgrade`

User migration files contain **user-schema only** — core system tables are owned by the Nextly package version and reconciled by `nextly migrate` Phase 1. If `nextly migrate` reports core schema drift after upgrading from a very early alpha (e.g. a hand-edited bundled file), run `nextly upgrade --reconcile-core`. It reconciles core in dev-loose mode and prompts for confirmation on each destructive operation. Use it only when migrate reports core drift.

## Rolling back a migration

`nextly migrate:create` writes a `-- DOWN` section into each generated migration
(the inverse of its `-- UP`). `nextly migrate:down` reverts the most-recently
applied migration using that section:

```bash
# Roll back the last migration
nextly migrate:down

# Roll back the last 3
nextly migrate:down --step 3

# Preview without executing
nextly migrate:down --dry-run
```

**Rollback restores schema *shape*, not *data*.** Reverting an added column drops
it (and its data); reverting a dropped column re-adds an empty column — the old
rows are gone. For this reason:

- A migration whose DOWN drops a table or column requires `--allow-data-loss`.
- In production (`NODE_ENV=production`), `migrate:down` requires `--yes`.
- A migration with an empty `-- DOWN` (data-only or blank) is **irreversible** —
  `migrate:down` refuses it. Roll forward with a corrective migration instead.

After a successful rollback, the migration is recorded as `rolled_back` in
`nextly_schema_events` and becomes pending again, so the next `nextly migrate`
re-applies it.

**In production, prefer rolling forward** (a new corrective migration) or
restoring from a backup. `migrate:down` is a manual, CLI-only break-glass tool;
it never runs on boot.

## Recovery via corrective migrations

`migrate:down` handles single-step rollback, but for production incidents the
safer path is usually to **roll forward** -- write a new migration that fixes the
previous one. Examples:

- Accidentally added a `NOT NULL` column without a default and the deploy failed -> write a new migration that backfills the column then re-applies the constraint.
- Renamed a column too aggressively and broke a downstream service -> write a new migration that adds the old column name back as a copy until consumers are updated.
- Need to drop a table you added in a recent migration -> write a new migration with `DROP TABLE`.

The audit trail in `nextly_schema_events` keeps both rows, so post-incident review can see exactly what was applied when, and by which CI job.

---
title: Authentication
description: Custom email + password authentication with JWT sessions, API keys, RBAC, and the super-admin bootstrap flow.
url: https://nextlyhq.com/docs/guides/authentication
---

Nextly ships a complete custom authentication system. It is **not** built on NextAuth, Auth.js, or any OAuth library. The runtime owns:

- Email + password sign-up and login (bcrypt hashing, password-strength validation, email verification).
- Stateless JWT access tokens (jose, HS256) plus opaque refresh tokens stored hashed in the database.
- API key authentication (`Authorization: Bearer nx_live_...`) with read-only / full-access / role-based scopes.
- Role-Based Access Control (RBAC) with code-defined and database-managed permissions.
- A super-admin bootstrap flow at `/admin/setup` that creates the first user.

There is no OAuth provider integration in the runtime. Authentication is local to your database.

## How sessions work

Sessions use a two-token architecture:

- **Access token** -- JWT signed with HS256 (jose), 15-minute TTL, stateless verification (no database hit). Sent as the HTTP-only `__nextly_access_token` cookie.
- **Refresh token** -- opaque random string, 7-day TTL, SHA-256 hashed in the database for revocation support. Sent as the HTTP-only refresh-token cookie.

When the access token expires, the admin UI silently refreshes it using the refresh token. Users only see a re-login prompt once the refresh token itself expires (7 days of inactivity by default). Every refresh consumes the old refresh token and issues a new one -- if a previously-consumed token is replayed, that's a signal of theft.

Cookies are scoped to `/admin/*` so Nextly auth never collides with frontend application cookies.

### Reading the session in code

```typescript
// app/api/my-route/route.ts
import { getSession } from "nextly/auth";

export async function GET(req: Request) {
  const result = await getSession(req, process.env.NEXTLY_SECRET ?? "");

  if (!result.authenticated) {
    return Response.json({ error: "Not authenticated" }, { status: 401 });
  }

  // result.user is the SessionUser
  return Response.json({
    userId: result.user.id,
    email: result.user.email,
    roleIds: result.user.roleIds,
  });
}
```

The `SessionUser` shape:

| Field      | Type       | Description                            |
|------------|------------|----------------------------------------|
| `id`       | `string`   | User's unique ID                       |
| `email`    | `string`   | User's email address                   |
| `name`     | `string`   | Display name                           |
| `image`    | `string?`  | Profile image URL                      |
| `roleIds`  | `string[]` | Array of role IDs from the JWT claims  |

Custom user fields defined via `defineConfig({ users: { fields } })` are also surfaced on the session user object.

### Requiring authentication

```typescript
import { requireAuth } from "nextly/auth";

export async function GET(req: Request) {
  // Throws AuthenticationError if no valid session.
  const user = await requireAuth(req, process.env.NEXTLY_SECRET ?? "");
  return Response.json({ email: user.email });
}
```

## Super-admin setup

The first time someone visits `/admin`, the panel redirects them to `/admin/setup` (driven by `GET /api/auth/setup-status`). The form creates the first user, assigns the built-in `Super Admin` role, seeds the core permission rows, and logs the new admin in -- all in a single CSRF-protected request.

A few things to note:

- Setup is a one-shot. Once any user exists, `POST /api/auth/setup` returns `403 SETUP_COMPLETE`.
- Passwords are validated for strength (length, character classes) before hashing -- see `validatePasswordStrength` for the exact rules.
- `Super Admin` is a system role that bypasses every permission check. Hand it out sparingly.
- For programmatic / test seeding, `seedSuperAdmin(adapter, { email, password, name? })` exists, but the recommended path is the setup wizard. It ships **no** default credentials -- `email` and `password` are required, and it throws a `VALIDATION_ERROR` if either is missing, so a known-weak default admin can never be created by accident. Pass throwaway values in tests and real, secret values anywhere else.

## Roles

Roles are managed in the admin UI at **Settings -> Roles** (`/admin/security/roles`) or programmatically via `RoleService`. Each role has a `name`, `slug`, `level`, and optional `description`.

The seeded `Super Admin` role bypasses every check. Other roles you create are gated by their assigned permissions.

### Checking roles in code

```typescript
import {
  getSession,
  hasRole,
  hasAnyRole,
  hasAllRoles,
} from "nextly/auth";

export async function GET(req: Request) {
  const result = await getSession(req, process.env.NEXTLY_SECRET ?? "");
  if (!result.authenticated) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = result.user;

  if (hasRole(user, "admin")) {
    // user has the "admin" role
  }

  if (hasAnyRole(user, ["admin", "editor"])) {
    // user has at least one of these roles
  }

  if (hasAllRoles(user, ["editor", "reviewer"])) {
    // user has both roles
  }
}
```

## Permissions

Permissions follow the slug format `<action>-<resource>` -- e.g. `read-users`, `create-roles`, `update-api-keys`, `manage-settings`. The four standard actions are `create`, `read`, `update`, `delete`; some resources also use `manage` as a coarse-grained shortcut.

Permissions for the core resources (`users`, `roles`, `permissions`) are seeded the first time the database is set up. Permissions for collections and singles you define in `nextly.config.ts` are wired up by the collection / single registration path -- you don't need to add them to a seeder.

For the full RBAC reference (role hierarchy, the seeded permission inventory, sidebar gating), see the [Admin overview](https://nextlyhq.com/docs/admin#permissions).

## Code-defined access control

You can attach access rules directly to collections and singles via `defineCollection({ access })`. Rules can be a boolean or a function that receives the request context -- they take precedence over database permissions, but Super Admin always bypasses everything.

```typescript
// src/collections/posts.ts
import { defineCollection } from "nextly/config";

export default defineCollection({
  slug: "posts",
  access: {
    // Boolean: any authenticated user can read
    read: true,

    // Function: only admins and editors can create / update
    create: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
    update: ({ roles }) => roles.includes("admin") || roles.includes("editor"),

    // Function: only admins can delete
    delete: ({ roles }) => roles.includes("admin"),
  },
  fields: [
    // ...
  ],
});
```

## API key authentication

Nextly supports API keys via the `Authorization: Bearer nx_live_...` header (no `X-API-Key` header). Keys are created and managed in the admin UI at **Settings -> API Keys**.

### Token types

| Type          | Permissions                                             |
|---------------|---------------------------------------------------------|
| `read-only`   | Only the `read-*` slugs from the creator's roles.       |
| `full-access` | All permissions of the creator's roles.                 |
| `role-based`  | Permissions of an explicitly chosen role (independent of the creator). |

Keys can be time-bound (set an expiry date) and revoked at any time. The full key value is shown to the operator **once** at creation; the database only stores the SHA-256 hash.

### How verification works

When a request includes a `Bearer` token, the auth middleware:

1. Hashes the key with SHA-256 and looks it up in the `api_keys` table.
2. Rejects expired or revoked keys.
3. Enforces per-key rate limiting (default: 1,000 requests/hour, configurable via `apiKeys.rateLimit` in `defineConfig()`).
4. Resolves the effective permission set based on the token type and creator's roles.
5. Attaches an `AuthContext` with `authMethod: "api-key"` to the request.

```typescript
// Client-side usage
const response = await fetch(
  "https://example.com/api/nextly/collections/posts/entries",
  {
    headers: {
      Authorization: "Bearer nx_live_<random>...",
    },
  }
);
```

## Security features

### Brute-force protection

Failed logins are tracked per-user. After 5 consecutive failures, the account is locked for 15 minutes. Counters reset on successful login.

### Login stall time

Every login response is held for at least 500ms regardless of whether the account exists. This prevents email enumeration via response timing.

### Per-IP auth-rate-limit

A separate per-IP envelope rate-limits `/auth/login`, `/auth/register`, `/auth/forgot-password`, and `/auth/reset-password` (default: 30 requests/hour, configurable via `security.authRateLimit`). This stops credential-stuffing attacks from a single source even before per-user lockout kicks in.

### CSRF protection

All state-changing auth endpoints (login, logout, register, setup, password operations) use double-submit CSRF tokens plus Origin/Referer validation. Add additional allowed origins via the `NEXTLY_ALLOWED_ORIGINS` env var (comma-separated).

### Refresh-token rotation

Every successful refresh consumes the old refresh token and issues a new one. Replays of a consumed token are detectable -- if you wire up monitoring on the refresh handler, you can flag these as potential theft.

### Session revocation on password change

When a user changes their password, all of their refresh tokens are deleted, forcing re-login on every device.

## Password management

Passwords are hashed with bcryptjs (12 salt rounds). The `AuthService` and password handlers cover the full lifecycle:

- `registerUser()` -- creates a new user with strength-validated password.
- `verifyCredentials()` -- validates email + password for login.
- `changePassword()` -- updates the password after verifying the current one; revokes all sessions.
- `generatePasswordResetToken()` -- issues a single-use SHA-256-hashed token (24-hour expiry) and sends the reset email.
- `resetPasswordWithToken()` -- consumes the token and updates the password.
- `generateEmailVerificationToken()` / `verifyEmail()` -- email verification flow.

Raw tokens are returned to the user once (in the email link); only the hashes are stored.

## Auth configuration

The `auth` block in `defineConfig()` currently exposes a single opt-in flag. The TTLs and brute-force settings listed below as defaults are wired in the runtime today; they are not yet exposed as user-tunable config keys.

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  auth: {
    // When false (default), /auth/register returns the same "we've sent a
    // confirmation link" response whether or not the email exists. Set to
    // true only if you don't care about email enumeration (e.g. closed
    // admin tool with controlled signup).
    revealRegistrationConflict: false,
  },
});
```

Built-in defaults you can rely on (not configurable yet):

| Setting                | Default     |
|------------------------|-------------|
| Access-token TTL       | 15 minutes  |
| Refresh-token TTL      | 7 days      |
| Max login attempts     | 5           |
| Lockout duration       | 15 minutes  |
| Login stall time       | 500ms       |
| Bcrypt salt rounds     | 12          |
| Require email verification | true    |

## Environment variables

| Variable                 | Required   | Description                                     |
|--------------------------|------------|-------------------------------------------------|
| `NEXTLY_SECRET`          | yes (prod) | JWT signing secret. **Min 32 characters in production.** |
| `NEXTLY_ALLOWED_ORIGINS` | optional   | Comma-separated additional CSRF origins.        |
| `NEXT_PUBLIC_APP_URL`    | yes (prod) | Public URL of the deployment, used in email links. |

Generate `NEXTLY_SECRET` with:

```bash
openssl rand -base64 32
```

## Auth endpoints

| Method | Path                           | Description                                  |
|--------|--------------------------------|----------------------------------------------|
| GET    | `/api/auth/setup-status`       | Has the first user been created?             |
| GET    | `/api/auth/session`            | Get the current session.                     |
| GET    | `/api/auth/csrf`               | Mint a CSRF token.                           |
| POST   | `/api/auth/setup`              | Create the first super-admin (auto-logs in). |
| POST   | `/api/auth/login`              | Email + password login.                      |
| POST   | `/api/auth/logout`             | Revoke the current session.                  |
| POST   | `/api/auth/refresh`            | Rotate access + refresh tokens.              |
| POST   | `/api/auth/register`           | User registration.                           |
| PATCH  | `/api/auth/change-password`    | Change password (auth required).             |
| POST   | `/api/auth/forgot-password`    | Request a password-reset email.              |
| POST   | `/api/auth/reset-password`     | Reset password with the email token.         |
| POST   | `/api/auth/verify-email`       | Verify email with the email token.           |
| POST   | `/api/auth/verify-email/resend`| Resend the verification email.               |

## Next steps

- [Email](https://nextlyhq.com/docs/guides/email) -- configure the provider that sends password-reset and verification emails.
- [Admin overview](https://nextlyhq.com/docs/admin#permissions) -- the seeded permissions, sidebar gating, and per-route checks.
- [Collections](https://nextlyhq.com/docs/configuration/collections) -- attach access rules to your collections.
- [Configuration reference](https://nextlyhq.com/docs/configuration/nextly-config) -- the full `defineConfig()` shape.
- [REST API](https://nextlyhq.com/docs/api-reference/rest-api) -- request / response shapes for the auth endpoints.

---
title: Media & Storage
description: Configure storage adapters (local disk, S3, Vercel Blob, Uploadthing) and named image sizes for uploaded media.
url: https://nextlyhq.com/docs/guides/media-storage
---

Nextly's media system is plugin-based. The default is local disk storage -- zero configuration, files written to `./public/uploads/` and served by Next.js as static assets. For production deployments where the filesystem isn't durable (Vercel, container runtimes), opt into S3, Vercel Blob, or Uploadthing.

## Storage adapters at a glance

| Adapter                          | Services                                                           | When to use                          |
|----------------------------------|--------------------------------------------------------------------|--------------------------------------|
| Built-in (local disk)            | Local filesystem under `./public/uploads/`                          | Development, single-server self-host |
| `@nextlyhq/storage-s3`           | AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Supabase Storage | Most production deployments          |
| `@nextlyhq/storage-vercel-blob`  | Vercel Blob                                                         | Vercel deployments                    |
| `@nextlyhq/storage-uploadthing`  | Uploadthing                                                         | Uploadthing users                     |

Storage adapters are plugins added to the `storage` array in `defineConfig()`. Each plugin declares which collections it handles, and the `MediaStorage` manager routes uploads accordingly:

```
Upload Request -> MediaStorage -> resolve collection -> plugin adapter -> storage backend
```

## Default: local disk

When no `storage` plugin is configured, Nextly uses the built-in local-disk adapter. Files are stored under `./public/uploads/{year}/{month}/` and served by Next.js at `/uploads/...` as static assets. On first upload, Nextly auto-adds `public/uploads/` to your `.gitignore`.

This is what makes local development work without setting up any cloud credentials.

> **Warning:** Local disk storage doesn't survive serverless restarts. If you deploy to Vercel, AWS Lambda, Cloudflare Workers, or any platform with ephemeral filesystems, switch to a cloud adapter before going to production.

### Explicit configuration

If you want to customise the local paths (e.g. write to `./public/media/` instead), import `localStorage` and add it explicitly:

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { localStorage } from "nextly/storage";

export default defineConfig({
  storage: [
    localStorage({
      basePath: "./public/media", // default: "./public/uploads"
      baseUrl: "/media",          // default: "/uploads"
      collections: { media: true },
    }),
  ],
});
```

## Auto-detection (zero config)

Use `getStorageFromEnv()` to let Nextly pick a storage adapter based on environment variables. Useful for moving between dev (no env vars -> local disk) and production (set the env vars and the right adapter is loaded automatically).

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { getStorageFromEnv } from "nextly/storage";

export default defineConfig({
  storage: await getStorageFromEnv(),
});
```

Detection cascade (first match wins):

1. `BLOB_READ_WRITE_TOKEN` set -> **Vercel Blob**.
2. `S3_BUCKET` (+ `S3_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) set -> **S3** (also covers R2, MinIO, Supabase Storage, DigitalOcean Spaces).
3. `UPLOADTHING_TOKEN` set -> **Uploadthing**.
4. None of the above -> **Local disk** (`./public/uploads/`).

If an env var is set but the matching adapter package isn't installed, Nextly logs a warning and falls back to the next cascade tier.

## S3 adapter

Works with any S3-compatible service. Install:

**pnpm:**

```bash
pnpm add @nextlyhq/storage-s3
```

**npm:**

```bash
npm install @nextlyhq/storage-s3
```

**yarn:**

```bash
yarn add @nextlyhq/storage-s3
```

**bun:**

```bash
bun add @nextlyhq/storage-s3
```

### AWS S3

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { s3Storage } from "@nextlyhq/storage-s3";

export default defineConfig({
  storage: [
    s3Storage({
      bucket: process.env.S3_BUCKET!,
      region: process.env.S3_REGION!,
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
      collections: { media: true },
    }),
  ],
});
```

### Cloudflare R2

R2 needs a custom endpoint and a public URL (R2 buckets don't have default public URLs):

```typescript
s3Storage({
  bucket: process.env.R2_BUCKET!,
  region: "auto",
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  publicUrl: process.env.R2_PUBLIC_URL,
  collections: { media: true },
})
```

### MinIO (self-hosted)

MinIO requires path-style URLs:

```typescript
s3Storage({
  bucket: "my-bucket",
  region: "us-east-1",
  accessKeyId: process.env.MINIO_ACCESS_KEY!,
  secretAccessKey: process.env.MINIO_SECRET_KEY!,
  endpoint: "http://localhost:9000",
  forcePathStyle: true,
  collections: { media: true },
})
```

### DigitalOcean Spaces

Spaces is S3-compatible. Use the regional endpoint:

```typescript
s3Storage({
  bucket: process.env.SPACES_BUCKET!,
  region: process.env.SPACES_REGION!,
  accessKeyId: process.env.SPACES_KEY!,
  secretAccessKey: process.env.SPACES_SECRET!,
  endpoint: `https://${process.env.SPACES_REGION}.digitaloceanspaces.com`,
  collections: { media: true },
})
```

### Supabase Storage

Supabase Storage exposes an S3-compatible endpoint. No separate adapter needed:

```typescript
s3Storage({
  bucket: "my-bucket",
  region: "us-east-1",
  accessKeyId: process.env.SUPABASE_S3_ACCESS_KEY!,
  secretAccessKey: process.env.SUPABASE_S3_SECRET_KEY!,
  endpoint: `https://${process.env.SUPABASE_PROJECT_ID}.supabase.co/storage/v1/s3`,
  forcePathStyle: true,
  collections: { media: true },
})
```

### S3 configuration reference

| Option              | Type      | Default                          | Description                                                            |
|---------------------|-----------|----------------------------------|------------------------------------------------------------------------|
| `bucket`            | `string`  | required                         | S3 bucket name.                                                        |
| `region`            | `string`  | required                         | AWS region (use `"auto"` for R2).                                      |
| `accessKeyId`       | `string`  | optional                         | Access key. Falls back to `AWS_ACCESS_KEY_ID` env var.                 |
| `secretAccessKey`   | `string`  | optional                         | Secret key. Falls back to `AWS_SECRET_ACCESS_KEY` env var.             |
| `endpoint`          | `string`  | --                               | Custom endpoint for S3-compatible services (R2, MinIO, Spaces, etc.).  |
| `publicUrl`         | `string`  | --                               | Public CDN / custom domain URL for serving files.                      |
| `forcePathStyle`    | `boolean` | `false`                          | Use path-style URLs (`https://endpoint/bucket/key`). Required for MinIO and Supabase. |
| `acl`               | `string`  | `"private"`                      | Object ACL: `"private"`, `"public-read"`, `"bucket-owner-full-control"`, etc. |
| `signedDownloads`   | `boolean` | `false`                          | Issue signed URLs for downloads of private objects.                     |
| `signedUrlExpiresIn`| `number`  | `3600`                           | Signed URL expiry in seconds.                                          |
| `cacheControl`      | `string`  | `"public, max-age=31536000"`     | Cache-Control header on uploaded objects.                              |
| `contentDisposition`| `string`  | --                               | `"inline"` or `"attachment"`. Sets the Content-Disposition header.     |

> **Note:** Default ACL is `"private"`. If you want objects to be world-readable directly from S3 (rather than via signed URLs), set `acl: "public-read"` and verify your bucket policy permits it. R2 ignores ACL settings -- configure public access in the R2 dashboard instead.

## Vercel Blob adapter

Optimised for Vercel deployments with built-in CDN. Install:

**pnpm:**

```bash
pnpm add @nextlyhq/storage-vercel-blob
```

**npm:**

```bash
npm install @nextlyhq/storage-vercel-blob
```

**yarn:**

```bash
yarn add @nextlyhq/storage-vercel-blob
```

**bun:**

```bash
bun add @nextlyhq/storage-vercel-blob
```

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { vercelBlobStorage } from "@nextlyhq/storage-vercel-blob";

export default defineConfig({
  storage: [
    vercelBlobStorage({
      token: process.env.BLOB_READ_WRITE_TOKEN,
      collections: { media: true },
    }),
  ],
});
```

If `token` is omitted, the adapter reads `BLOB_READ_WRITE_TOKEN` from the environment automatically.

## Uploadthing adapter

Install:

**pnpm:**

```bash
pnpm add @nextlyhq/storage-uploadthing
```

**npm:**

```bash
npm install @nextlyhq/storage-uploadthing
```

**yarn:**

```bash
yarn add @nextlyhq/storage-uploadthing
```

**bun:**

```bash
bun add @nextlyhq/storage-uploadthing
```

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { uploadthingStorage } from "@nextlyhq/storage-uploadthing";

export default defineConfig({
  storage: [
    uploadthingStorage({
      token: process.env.UPLOADTHING_TOKEN,
      collections: { media: true },
    }),
  ],
});
```

Files are served via Uploadthing's CDN (`utfs.io`).

## Per-collection routing and overrides

Each plugin's `collections` map controls which collection slugs it handles. Pass `true` to enable with defaults, or an object to customise per-collection behaviour:

```typescript
s3Storage({
  bucket: process.env.S3_BUCKET!,
  region: process.env.S3_REGION!,
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  collections: {
    // Public media -- defaults
    media: true,

    // Private docs -- signed downloads, custom prefix, client-side uploads
    "private-docs": {
      prefix: "private/",
      signedDownloads: true,
      signedUrlExpiresIn: 900,
      clientUploads: true,
    },
  },
})
```

| Option               | Type      | Default | Description                                              |
|----------------------|-----------|---------|----------------------------------------------------------|
| `prefix`             | `string`  | --      | Folder prefix for this collection's uploads.             |
| `clientUploads`      | `boolean` | `false` | Enable client-side direct uploads (bypasses serverless body limits). |
| `signedDownloads`    | `boolean` | `false` | Issue signed URLs for download.                          |
| `signedUrlExpiresIn` | `number`  | `3600`  | Signed-URL expiry in seconds.                            |

You can also register **multiple plugins** in the `storage` array if different collections need different backends -- for instance, public media on Vercel Blob and private documents on S3.

## Named image sizes

Nextly can automatically generate resized image variants for every uploaded image, using `sharp`. Configure them in `nextly.config.ts` (code-first), through the admin Settings page (UI), or both -- the runtime de-dupes by `name` and keeps both sets queryable.

### Code-first configuration

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  media: {
    imageSizes: [
      { name: "thumbnail", width: 150, height: 150, fit: "cover", format: "webp", quality: 80 },
      { name: "small", width: 480, fit: "inside", format: "auto", quality: 80 },
      { name: "medium", width: 768, fit: "inside", format: "auto", quality: 80 },
      { name: "large", width: 1200, fit: "inside", format: "auto", quality: 80 },
      { name: "og", width: 1200, height: 630, fit: "cover", format: "jpeg", quality: 90 },
    ],
  },
  storage: [
    // ... your storage config
  ],
});
```

### Size options

| Option    | Type     | Default     | Description                                                                                  |
|-----------|----------|-------------|----------------------------------------------------------------------------------------------|
| `name`    | `string` | required    | Unique key. Used in the API response and as part of the variant filename.                    |
| `width`   | `number` | --          | Target width in pixels (omit to auto-calculate from height).                                 |
| `height`  | `number` | --          | Target height in pixels (omit to auto-calculate from width).                                 |
| `fit`     | `string` | `"inside"`  | `"inside"` (shrink to fit), `"cover"` (crop to fill), `"contain"`, or `"fill"`.              |
| `quality` | `number` | `80`        | Image quality (1-100).                                                                       |
| `format`  | `string` | `"auto"`    | `"auto"` (WebP when possible), `"webp"`, `"jpeg"`, `"png"`, or `"avif"`.                     |

### Visual configuration

Go to **Settings -> Image Sizes** in the admin panel to manage sizes through the UI. Code-defined sizes appear as read-only; UI-created sizes are fully editable.

### REST endpoints

| Method | Path                                | Description                                  |
|--------|-------------------------------------|----------------------------------------------|
| GET    | `/api/image-sizes`                  | List configured sizes (read).                |
| POST   | `/api/image-sizes`                  | Create a new size (UI-managed).              |
| GET    | `/api/image-sizes/:id`              | Get a single size.                           |
| PATCH  | `/api/image-sizes/:id`              | Update a size.                               |
| DELETE | `/api/image-sizes/:id`              | Delete a size.                               |
| GET    | `/api/image-sizes/regeneration-status` | Status of an in-progress regeneration job. |
| POST   | `/api/image-sizes/regenerate`       | Re-generate variants for existing media.     |

The list endpoint is permission-gated by `read-settings`; mutation endpoints require `manage-settings`.

### Using sizes from your frontend

Where the variants reach you depends on how you read the media file, so it is worth
being exact about it.

A media file **populated as a relationship** on an entry or a single carries its
variants under `sizes`, keyed by the name you configured:

```json
{
  "id": "abc-123",
  "url": "/uploads/2026/04/photo.jpg",
  "width": 3000,
  "height": 2000,
  "sizes": {
    "thumbnail": { "url": "...", "width": 150, "height": 150 },
    "medium": { "url": "...", "width": 768, "height": 512 },
    "large": { "url": "...", "width": 1200, "height": 800 }
  }
}
```

`media.findByID()` does not. It returns a `MediaFile`, which declares no `sizes`
field, so a variant read straight off that result does not exist at runtime and does
not compile either.

So a variant can only be selected from a value that carries one. Give that value to
`getMediaVariant`, which asks for a name, tries your fallback name next, then
`thumbnailUrl`, then the original:

```tsx
// app/(site)/media-image.tsx
import Image from "next/image";
import { getMediaVariant, type MediaLike } from "nextly";

export function MediaImage({ media, alt }: { media: MediaLike; alt: string }) {
  return (
    <Image
      src={getMediaVariant(media, "large", { fallback: "medium" }) ?? media.url}
      alt={alt}
      width={1200}
      height={800}
    />
  );
}
```

Hand it the media value off a populated relationship, not a `findByID` result. Called on
a `MediaFile` the helper still returns a URL, but it can only ever be the thumbnail or the
original, because the variants are not on that object to choose from.

Reading a media record on its own is still a `findByID`, and it still needs a runtime:

```tsx
// app/(site)/photo/page.tsx
import Image from "next/image";
import { getNextly } from "nextly";

import config from "../../../nextly.config";

export default async function Photo() {
  const nextly = await getNextly({ config });
  const media = await nextly.media.findByID({ id: "abc-123" });
  if (!media) return null;

  return (
    <Image
      src={media.url}
      width={media.width ?? 1200}
      height={media.height ?? 800}
      alt={media.altText ?? ""}
    />
  );
}
```

`getNextly({ config })` initialises the runtime if nothing has yet, so this page works
wherever it renders. The synchronous proxy from `nextly/runtime` assumes an already
initialised process and throws `Nextly services not initialized` when it is the first
Nextly code a worker runs, which a blank scaffold makes likely because it ships no
`instrumentation.ts`.

## Crop point (focal point)

Each media record can carry a focal point that controls how `"cover"` crops behave. Set it from the admin media library by clicking the image in the edit dialog. The values are stored as `focalX` (0-100, left to right) and `focalY` (0-100, top to bottom).

Use them with CSS `object-position` for responsive cropping:

```tsx
// app/(site)/cover.tsx
import Image from "next/image";

export function Cover({
  url,
  focalX,
  focalY,
  alt,
}: {
  url: string;
  focalX: number;
  focalY: number;
  alt: string;
}) {
  return (
    <Image
      src={url}
      alt={alt}
      fill
      style={{
        objectFit: "cover",
        objectPosition: `${focalX}% ${focalY}%`,
      }}
    />
  );
}
```

The component takes the two values rather than a whole media record, because
`media.findByID()` does not return them today: `MediaFile` has no `focalX` or `focalY`,
so read the crop point from the media row until it does.

## Environment variables

### Auto-detection cascade

| Variable                | Triggers           |
|-------------------------|--------------------|
| `BLOB_READ_WRITE_TOKEN` | Vercel Blob       |
| `S3_BUCKET`             | S3 adapter        |
| `UPLOADTHING_TOKEN`     | Uploadthing       |
| (none of the above)     | Local disk         |

### S3 / R2 / MinIO / Spaces / Supabase

| Variable                | Description                                              |
|-------------------------|----------------------------------------------------------|
| `S3_BUCKET`             | Bucket name.                                              |
| `S3_REGION`             | Region (`"auto"` for R2).                                |
| `AWS_ACCESS_KEY_ID`     | Access key ID.                                           |
| `AWS_SECRET_ACCESS_KEY` | Secret access key.                                       |
| `S3_ENDPOINT`           | Custom endpoint (R2, MinIO, Supabase, Spaces).            |
| `S3_PUBLIC_URL`         | Public URL for serving files.                             |
| `S3_FORCE_PATH_STYLE`   | Set to `"true"` for MinIO and Supabase.                   |

### Vercel Blob

| Variable                  | Description                       |
|---------------------------|-----------------------------------|
| `BLOB_READ_WRITE_TOKEN`   | Vercel Blob read-write token.     |

### Uploadthing

| Variable             | Description                       |
|----------------------|-----------------------------------|
| `UPLOADTHING_TOKEN`  | Uploadthing v7+ API token.        |

## Migrating between adapters

When switching adapters (e.g. local disk -> S3 for production):

1. Existing files stay in the old storage. New uploads go to the new adapter.
2. URLs stored in the database still point to the old storage.
3. For a full migration you'll need to copy the files and rewrite the URLs in the `media` table.

A common pattern is to switch automatically based on env vars:

- Development -> no cloud env vars -> local disk.
- Staging / Production -> set `S3_BUCKET` etc. -> S3.

`getStorageFromEnv()` makes this a one-liner in `nextly.config.ts`.

## Next steps

- [Deployment](https://nextlyhq.com/docs/guides/deployment) -- deploy to Vercel or self-host with the right storage choice.
- [Configuration reference](https://nextlyhq.com/docs/configuration/nextly-config) -- full `defineConfig()` options.
- [Collections](https://nextlyhq.com/docs/configuration/collections) -- define collections with upload fields.

---
title: Email
description: Configure email providers (Resend, SMTP, SendLayer), send programmatically via the Direct API, and test locally with Mailpit.
url: https://nextlyhq.com/docs/guides/email
---

Nextly's email system supports three providers -- Resend, SMTP, and SendLayer -- with database-managed templates, variable interpolation, and a shared header/footer layout. Email is used for password resets, email verification, welcome messages, and any custom notifications you send via the Direct API.

For local development, Nextly ships a **Mailpit** profile in `docker-compose.yml` so you can test email flows without sending anything over the internet -- see [Local email testing with Mailpit](#local-email-testing-with-mailpit) below.

## Provider configuration

Configure your email provider in `nextly.config.ts` as a code-first fallback. Database-managed providers (configured in the admin UI at **Settings -> Email Providers**) take priority over code-defined config.

> **Note:** `email.providerConfig` is **required** when the `email` block is set. If you only want database-managed providers, you can omit the `email` block entirely.

### Resend

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  email: {
    providerConfig: {
      provider: "resend",
      apiKey: process.env.RESEND_API_KEY!,
    },
    from: "My App <noreply@example.com>",
  },
});
```

### SMTP

```typescript
// nextly.config.ts
export default defineConfig({
  email: {
    providerConfig: {
      provider: "smtp",
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT) || 587,
      secure: false,
      auth: {
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!,
      },
    },
    from: process.env.SMTP_FROM || "noreply@example.com",
  },
});
```

### SendLayer

```typescript
// nextly.config.ts
export default defineConfig({
  email: {
    providerConfig: {
      provider: "sendlayer",
      apiKey: process.env.SENDLAYER_API_KEY!,
    },
    from: "My App <noreply@example.com>",
  },
});
```

### Conditional provider selection

The playground app shows a useful pattern -- prefer Resend when its API key is set, fall back to SMTP otherwise:

```typescript
// nextly.config.ts
export default defineConfig({
  email: process.env.RESEND_API_KEY
    ? {
        providerConfig: {
          provider: "resend" as const,
          apiKey: process.env.RESEND_API_KEY,
        },
        from: process.env.SMTP_FROM || "onboarding@resend.dev",
      }
    : {
        providerConfig: {
          provider: "smtp" as const,
          host: process.env.SMTP_HOST!,
          port: Number(process.env.SMTP_PORT) || 587,
          secure: false,
          auth: {
            user: process.env.SMTP_USER!,
            pass: process.env.SMTP_PASS!,
          },
        },
        from: process.env.SMTP_FROM || "noreply@example.com",
      },
});
```

## Email config options

| Option              | Type     | Default                      | Description                                |
|---------------------|----------|------------------------------|--------------------------------------------|
| `providerConfig`    | object   | required                     | Provider-specific configuration.           |
| `from`              | `string` | required                     | Default sender address.                    |
| `baseUrl`           | `string` | `NEXT_PUBLIC_APP_URL` env    | Base URL for links in emails.              |
| `resetPasswordPath` | `string` | `'/admin/reset-password'`    | Path for password-reset links.             |
| `verifyEmailPath`   | `string` | `'/admin/verify-email'`      | Path for email-verification links.         |

## Provider resolution order

When sending an email, Nextly resolves the provider in this order:

1. **Specific provider ID** -- if the call passes a `providerId`.
2. **Database default provider** -- the provider marked as default in admin Settings.
3. **Code-first config** -- the `providerConfig` from `defineConfig()`.
4. **Error** -- if none of the above resolve.

This lets you wire a code-first provider for development and configure a production provider through the admin UI without changing code.

## Built-in email templates

Nextly automatically creates three email templates on first startup:

| Template             | Slug                  | Purpose                              |
|----------------------|-----------------------|--------------------------------------|
| Welcome              | `welcome`             | Sent after user registration.        |
| Password Reset       | `password-reset`      | Contains the reset link.             |
| Email Verification   | `email-verification`  | Contains the verification link.      |

Templates are stored in the database and edited through the admin UI (**Settings -> Email Templates**) using a Lexical-based rich-text editor. They support `{{variable}}` placeholder syntax with HTML escaping.

### Template variables

Templates receive context-appropriate variables.

**Password Reset:**
- `{{resetLink}}` -- full password reset URL.
- `{{userName}}` -- user's name or email.
- `{{userEmail}}` -- user's email.
- `{{appName}}` -- application name.
- `{{expiresIn}}` -- token expiry duration.
- `{{year}}` -- current year.

**Email Verification:**
- `{{verifyLink}}` -- full verification URL.
- `{{userName}}`, `{{userEmail}}`, `{{appName}}`, `{{expiresIn}}`, `{{year}}`.

**Welcome:**
- `{{userName}}`, `{{userEmail}}`, `{{appName}}`, `{{year}}`.

### Shared header / footer layout

Templates can opt into a shared layout via the `useLayout` flag (enabled by default). The layout uses reserved slugs `_email-header` and `_email-footer`. The final email is composed as:

```
header HTML + template body + footer HTML
```

Layout templates also support `{{variable}}` interpolation, so common variables like `{{year}}` and `{{appName}}` work in headers and footers.

## Code-first template overrides

You can override the built-in email templates in `defineConfig()` without touching the database:

```typescript
// nextly.config.ts
export default defineConfig({
  email: {
    providerConfig: {
      provider: "resend",
      apiKey: process.env.RESEND_API_KEY!,
    },
    from: "noreply@example.com",
    templates: {
      passwordReset: (data) => ({
        subject: "Reset your password",
        html: `
          <p>Hi ${data.user.name ?? data.user.email},</p>
          <p>Click <a href="${data.url}">here</a> to reset your password.</p>
          <p>This link expires in 1 hour.</p>
        `,
      }),
      welcome: (data) => ({
        subject: `Welcome to our app!`,
        html: `<p>Hi ${data.user.name}, thanks for signing up!</p>`,
      }),
      emailVerification: (data) => ({
        subject: "Verify your email",
        html: `<p>Click <a href="${data.url}">here</a> to verify your email.</p>`,
      }),
    },
  },
});
```

Resolution order for templates: **database template** (if active) > **code-first override** > **error**.

## Sending emails programmatically

The Direct API exposes `nextly.email.send()` and `nextly.email.sendWithTemplate()`.

### Using a template

```typescript
import { nextly } from "@/nextly";

await nextly.email.sendWithTemplate({
  template: "password-reset",
  to: "user@example.com",
  variables: {
    resetLink: "https://example.com/admin/reset-password?token=abc123",
    userName: "Jane",
    appName: "My App",
  },
});
```

### Sending raw

```typescript
await nextly.email.send({
  to: "user@example.com",
  subject: "Your order has shipped",
  html: "<p>Your order #1234 is on its way!</p>",
});
```

Both calls return `{ success: boolean; messageId?: string }`.

### Auth flow auto-sends

The `AuthService` handles email sending for auth flows automatically when an email service is configured:

- `generatePasswordResetToken(email)` -- generates a token and sends the reset email.
- `generateEmailVerificationToken(email)` -- generates a token and sends the verification email.
- `sendWelcomeEmail(to, user)` -- sends the welcome template.

If no email service is configured, tokens are returned in the API response as a development-only fallback (with a console warning). In production, configure a real provider so password resets and email verification work.

## Local email testing with Mailpit

For local development, the Nextly repo's `docker-compose.yml` ships a `with-mailpit` profile that runs [Mailpit](https://github.com/axllent/mailpit) -- an SMTP server and web UI for catching outgoing email locally.

### Start Mailpit

```bash
docker compose --profile with-mailpit up -d mailpit
```

This starts the `axllent/mailpit:latest` container with:

- **SMTP** on host port `1025`.
- **Web UI** on host port `8025`.
- No authentication (Mailpit is dev-only).

### Configure Nextly to use it

Point your SMTP env vars at the local Mailpit instance. Empty `SMTP_USER` / `SMTP_PASS` is fine -- Mailpit accepts any credentials.

```bash
# .env.local
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASS=
SMTP_FROM=dev@nextly.local
```

Then either let `getStorageFromEnv()`-style auto-detection pick up SMTP, or wire it explicitly in `nextly.config.ts`:

```typescript
// nextly.config.ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  email: {
    providerConfig: {
      provider: "smtp",
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT) || 1025,
      secure: false,
      auth: {
        user: process.env.SMTP_USER || "",
        pass: process.env.SMTP_PASS || "",
      },
    },
    from: process.env.SMTP_FROM || "dev@nextly.local",
  },
});
```

### Inspect captured email

Open `http://localhost:8025` in your browser. Every email Nextly sends locally lands in the Mailpit inbox -- password resets, verification links, welcome emails, and anything you fire via `nextly.email.send()`. The web UI lets you preview HTML, view raw source, and inspect headers.

The container is dev-only and gated behind a Compose profile, so it does **not** auto-start with `docker compose up`.

## Environment variables

| Variable           | Provider   | Description                      |
|--------------------|------------|----------------------------------|
| `RESEND_API_KEY`   | Resend     | API key from the Resend dashboard. |
| `SENDLAYER_API_KEY`| SendLayer  | API key (Bearer token).          |
| `SMTP_HOST`        | SMTP       | Server hostname.                 |
| `SMTP_PORT`        | SMTP       | Server port (587 for TLS, 1025 for Mailpit). |
| `SMTP_USER`        | SMTP       | Authentication username (empty for Mailpit). |
| `SMTP_PASS`        | SMTP       | Authentication password (empty for Mailpit). |
| `SMTP_FROM`        | Any        | Default sender address.          |

## Next steps

- [Authentication](https://nextlyhq.com/docs/guides/authentication) -- understand how the auth flows trigger emails.
- [Deployment](https://nextlyhq.com/docs/guides/deployment) -- production email-provider setup.
- [Environment variables](https://nextlyhq.com/docs/configuration/environment) -- full env-var reference.
- [Configuration reference](https://nextlyhq.com/docs/configuration/nextly-config) -- full `defineConfig()` email options.

---
title: Draft / Published Status
description: Enable a Draft / Published lifecycle on collections and singles, with side-by-side examples for code-first config and the Visual Schema Builder.
url: https://nextlyhq.com/docs/guides/draft-published-status
---

Nextly supports an opt-in Draft / Published lifecycle for collections and singles. When enabled, every record carries a `status` system column (`'draft'` or `'published'`); the admin entry create/edit page splits its primary action into **Save Draft** + **Publish** (or **Update**), and public-facing API queries can filter unpublished records out by default.

This is a meta-level toggle on the collection or single -- you do not declare a `status` field yourself. Nextly injects the column at schema-generation time when you opt in.

## Enabling on a collection

### Code-first

Set `status: true` at the top level of `defineCollection`:

```typescript
import { defineCollection, text, richText } from "nextly/config";

export const Posts = defineCollection({
  slug: "posts",
  status: true, // enable Draft / Published lifecycle
  labels: { singular: "Post", plural: "Posts" },
  fields: [
    text({ name: "title", required: true }),
    text({ name: "slug", required: true, unique: true }),
    richText({ name: "content" }),
  ],
});
```

### Visual Schema Builder

1. Open the collection in the Builder.
2. Click the **Settings** icon in the toolbar.
3. Switch to the **Advanced** tab.
4. Toggle **Status (Draft / Published)** on.
5. Click **Save**. Nextly will run a schema migration that adds the `status` column to the data table; existing rows backfill to `'draft'` so nothing is accidentally published.

Both paths produce identical runtime behaviour -- the same column, the same admin UI, the same query shape.

## What the system column does

| Property | Value |
|---|---|
| Type | `varchar(20)` on Postgres / MySQL, `text` on SQLite |
| Default | `'draft'` |
| Nullable | No (NOT NULL) |
| Indexed | Yes — `{collection}_status_idx` |
| Allowed values | `'draft'`, `'published'` |

The Nextly runtime injects this column when `status: true` is set on the collection or single config. You never declare a `status` field yourself in `fields: [...]` -- and if a user-defined field with the same name exists, the system flag will conflict with it. Migrate any legacy `select({ name: "status" })` field off before toggling the system flag.

## Enabling on a single

Same shape -- set `status: true` at the top level of `defineSingle`:

```typescript
import { defineSingle, richText } from "nextly/config";

export const Homepage = defineSingle({
  slug: "homepage",
  status: true,
  label: { singular: "Homepage" },
  fields: [
    richText({ name: "hero" }),
  ],
});
```

In the Visual Schema Builder, the toggle lives in the same Settings → Advanced tab on the single's Builder page.

## Localized documents: moving every language at once

On a localized collection or single, the publication state lives per language:
the main row carries the document's own `status`, and each translation carries
its own `_status`. An ordinary write moves the language it names, which is what
lets you publish a German translation without touching the English one.

That leaves a third thing to say — "move the whole document, every language" —
and it is spelled with the wildcard locale:

```typescript
// Take the document down in every language it has.
await nextly.update({
  collection: "pages",
  id: page.id,
  locale: "*",
  data: { status: "draft" },
});
```

Without it, a write that names no locale moves the DEFAULT language only, so a
takedown would leave the other translations live.

Two things to know about the wildcard:

- **It moves a publication status and nothing else.** A write that names any
  other field alongside it is rejected, because "write these values into every
  language" would copy one translation's text over all the others. To change
  field values, name the language they belong to.
- **It only reaches languages that exist.** A translation with no stored row has
  nothing to publish, and one is not created for it — the absence of a row is
  the record that the document was never translated into that language.

Scheduled releases use this automatically: a release member that names no
language moves every translation of its document when the release runs.

## Filtering on the public site

Use the standard field-filter syntax with the column name `status`:

```typescript
import { nextly } from "nextly";

// Public list page — only published posts.
const published = await nextly.find({
  collection: "posts",
  where: { status: { equals: "published" } },
});

// Admin-only path — show all entries regardless of status.
const all = await nextly.find({ collection: "posts" });
```

The `nextly` proxy above assumes Nextly is already initialised in the process, and most projects are not. Of the scaffolds, only `blog` ships a `src/instrumentation.ts` that calls `createRegister(config)()` before the first request; `base` and `blank` ship none, so on those the proxy throws `Nextly services not initialized` the moment it is the first Nextly code a worker runs. The same applies to a standalone script, and to any app that removed the hook.

Use `await getNextly({ config })` unless you know the process has been initialised. It initialises rather than assuming, so it is correct in both cases; the proxy is the lighter import for code that provably runs after initialisation.

The query shape (`{ status: { equals: "published" } }`) works identically across all three dialects. The system column is indexed, so filtering by status is fast even on large tables.

## Admin behaviour

### Action bar

When `status: true` is enabled on a collection or single, the entry create/edit page action bar splits its primary action:

- **Create mode**: `[Save Draft]` (ghost) + `[Publish]` (primary). Pressing Save Draft creates the entry as `'draft'`; Publish creates it as `'published'`.
- **Edit mode**: `[Save Draft]` (ghost) + `[Update]` (primary). Save Draft demotes to `'draft'`; Update saves with the entry's current status (or `'published'` if the entry was already published).

When `status: false` (the default), the action bar collapses to a single `[Create]` / `[Save]` button.

### Document panel + meta strip

The current state is visible in two places:

- **Document panel (right rail, when expanded)**: a labeled "Status" row with a `DRAFT` or `PUBLISHED` pill, alongside ID, Created, and Updated.
- **Meta strip (below the title bar, when the rail is collapsed)**: the same pill renders inline before the slug, so editors can see state without re-opening the rail.

## Toggling status off

Disabling `status: true` on a collection that previously had it enabled is a destructive change -- the column gets dropped and any existing `draft` / `published` values are lost.

- **Code-first**: removing `status: true` from your config and saving the file triggers the schema-change pipeline. You'll get a confirmation dialog (or the CLI `--accept-data-loss` flag in non-interactive contexts) before the column is dropped.
- **Builder UI**: toggling Status off in Settings → Advanced and saving prompts the same destructive-change confirmation dialog. Acknowledge to drop the column.

There is no soft-delete or migration script — the column goes away. If you need to retain the data, export your entries first.

## Migrating from a user-defined `status` field

If your collection already has a user-defined `select({ name: "status" })` field -- for example, the legacy blog template shipped this pattern before the system flag existed -- migrate by:

1. **Remove the user-defined field** from `fields: [...]` in your config.
2. **Add `status: true`** at the top of the same collection.
3. **Run the schema migration** (Nextly will detect the field removal and the system column addition; both are applied together).
4. **Verify your queries** still use `{ status: { equals: "published" } }` -- the column name and value space are preserved, so query call-sites don't need to change.
5. **Verify your seed** writes the same `status: 'draft' | 'published'` values -- the system column accepts the same shape.

The blog template (`create-nextly-app` blog) ships this migration applied; new projects scaffolded from the blog template after this release get the unified Save Draft / Publish admin UI for free.

## See also

- [Collection configuration reference](../configuration/index.mdx)
- [Schema Builder admin UI](../schema-builder/index.mdx)
- [Production migrations](./production-migrations.mdx)

---
title: ISR and caching
description: Cache your content pages and revalidate them the moment content changes. Tag reads with nextlyTags/cachedFind and Nextly busts them on every write.
url: https://nextlyhq.com/docs/guides/isr-caching
---

Nextly turns every content change into a cache invalidation. Tag a page's data
with the collection/entry it reads, and a create, update, publish, unpublish,
delete, or slug change busts exactly those tags — the page regenerates on the
next visit, with no rebuild and no `force-dynamic`.

This is [Next.js Incremental Static Regeneration](https://nextjs.org/docs/app/guides/incremental-static-regeneration)
driven by your content, not a timer.

## How it works

1. A read tags its cached data with the `nextly:*` tags for the collection (and,
   for a detail page, the entry id).
2. A write computes the same tags and, after it commits, calls Next's
   `revalidateTag` for each — so any page tagged with them is invalidated.

The write side is automatic once the admin route is wired (see below). You only
add the read-side tags.

## Enable it

Register the adapter once per server process. The most reliable place is Next's
[`instrumentation.ts`](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation),
whose `register()` runs at startup, before any route, Server Action, or
serverless worker handles a request — so **every** write context busts tags,
not just the ones that happen to have loaded the admin route:

```ts
// instrumentation.ts (project root, next to your app/ directory)
export async function register() {
  const { registerNextCacheRevalidator } = await import("nextly/runtime");
  registerNextCacheRevalidator();
}
```

Mounting the admin route handler also registers it, which is enough if every
content write goes through the admin API in the same process:

```ts
// app/admin/[[...params]]/route.ts
import { createDynamicHandlers } from "nextly/runtime";

export const { GET, POST, PATCH, DELETE } = createDynamicHandlers();
```

If you write content through the Direct API (`nextly.create(...)`) from a Server
Action, a custom route, or the admin API, register from `instrumentation.ts` as
above — relying on the admin route alone leaves those contexts on the no-op
revalidator, and their writes would not refresh cached pages. A write in a
context with no adapter registered is a silent no-op for revalidation (never an
error), so it is safe but stale.

### Writes must run inside a request

Automatic revalidation fires for a write that runs **inside a Next.js request or
render** — a Route Handler, a Server Action, or the admin API. That is where
`revalidateTag` is valid, and it covers how content is normally edited.

A write from **outside** a request — a cron job, a CLI, or a background worker
with no request in flight — cannot call `revalidateTag` (there is no cache scope
to invalidate), so the adapter safely skips it (the write still succeeds). Those
callers should either run the write in a Route Handler / Server Action, or
invalidate the cache themselves. This mirrors how on-demand ISR works in Next.js
generally: revalidation is request-scoped.

## Tag a read

Use `cachedFind` to cache a data read and `nextlyTags` to tag it:

```tsx
// app/(site)/blog/[slug]/page.tsx
import { getNextly } from "nextly";
import { cachedFind, nextlyTags } from "nextly/runtime";

import config from "../../../../nextly.config";

export default async function Post({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const nx = await getNextly({ config });

  const post = await cachedFind(
    async () => {
      const { items } = await nx.find({
        collection: "posts",
        where: { slug: { equals: slug }, status: { equals: "published" } },
        limit: 1,
      });
      return items[0] ?? null;
    },
    { tags: nextlyTags("posts"), keyParts: ["posts", "detail", slug] }
  );

  if (!post) return null;
  return <article></article>;
}
```

Publishing or editing any post now busts `nextly:posts` and this page
regenerates. For a listing page, tag it the same way — `nextlyTags("posts")` —
and it revalidates on any change in the collection.

### `nextlyTags(collection, id?, locale?)`

Builds the tags a read should carry:

- `nextlyTags("posts")` — the collection tag; for lists, indexes, sitemaps.
- `nextlyTags("posts", id)` — adds the entry-id tag; for a detail page, so a
  change to that one entry invalidates it. Tags by the **immutable id**, so a
  slug rename or a status change still invalidates.
- `nextlyTags("posts", id, locale)` — adds the per-locale id tag.

A detail read intentionally carries the collection tag too, so it also refreshes
when the collection changes around it. Because a match on **any** tag
invalidates the entry, that broadens invalidation: any change in the collection
(or any locale of the entry) refreshes the read, rather than only that one
locale's page. That is safe — a stale read is never served, only re-fetched more
often. If you need strictly per-entry or per-locale granularity on a
high-traffic route, tag with the entry/locale tag alone rather than this helper's
broad, safe default.

For a singleton (global) use `nextlySingleTags("header")`.

## Security: caching a per-user read

`cachedFind`'s `keyParts` decide which requests share a cache entry. **Include
anything the result varies by** — and for a read that applies per-caller access
rules (owner-only scoping, role-based visibility, an API key's narrowed scope),
that means the caller's identity:

```tsx
// Per-user list — the caller's id is in the key, so it never leaks.
declare const user: import("nextly").UserContext;
// `nx` is the instance the page obtains above, inside its own component. Each
// fence here stands alone, so it is declared rather than assumed in scope.
declare const nx: Awaited<ReturnType<typeof import("nextly").getNextly>>;

const mine = await cachedFind(() => nx.find({ collection: "orders", user }), {
  tags: nextlyTags("orders"),
  keyParts: ["orders", "list", user.id], // <-- caller identity
});
```

If you cache an owner-filtered read under a stable key that omits the caller, two
different users share one cache entry and one is served the other's rows — a
cross-tenant data leak, not a stale-cache annoyance. For genuinely public content
(the same for every reader, like a published blog post) a stable key is correct
and gives the full caching benefit.

## Opt a write out of revalidation

A bulk import, seed, or CLI write that owns its own cache strategy can skip the
per-row revalidation with `disableRevalidate`:

```ts
await nx.create({ collection: "posts", data, disableRevalidate: true });
```

The write still records its outbox event (webhooks and retention are
unaffected); it just does not bust any cache tags.

## Notes

- Works across the supported Next range (`^14 || ^15 || ^16`) on the stable
  `revalidateTag` / `unstable_cache` primitives.
- `cachedFind` runs the reader directly (no caching) outside a Next runtime, so
  the same code works in tests and non-Next callers.
- Add `revalidate: <seconds>` to `cachedFind` for a time-based safety net on top
  of tag-based busting.

---
title: Routing and SEO
description: Turn content into pages with correct metadata, sitemap, and robots. The nextly/runtime helpers resolve a slug to a published, access-enforced entry, build a Next.js Metadata object from an seo field group, and deliver sitemap.xml and robots.txt.
url: https://nextlyhq.com/docs/guides/routing-and-seo
---

Nextly ships a small set of Next.js helpers for the last mile of a content
site: resolve a URL to the right entry, build its `<head>` metadata, and serve
`sitemap.xml` / `robots.txt`. They live in `nextly/runtime` and read your
content through the [Direct API](https://nextlyhq.com/docs/api-reference/direct-api), so every read
is publish-state aware, access aware, and cached with
[F1 tag-based ISR](https://nextlyhq.com/docs/guides/isr-caching).

SEO **data** (the `metaTitle` / `metaDescription` / `ogImage` / `canonical` /
`noindex` fields) is opt-in via the agnostic
[`@nextlyhq/plugin-seo`](https://nextlyhq.com/docs/plugins) plugin; the **behavior** below is
Next-only and lives in `nextly/runtime`. Nothing here forces `next` onto a
headless or admin-only deployment — every `next` import is type-only and
`next/navigation` is resolved lazily.

## resolveContent — slug to a published entry

`resolveContent(collection, slug, options?)` resolves a URL slug to a single
entry and returns `null` on a genuine miss (render `notFound()`), rethrowing a
transient read error so a DB blip never bakes a permanently-cached 404.

```ts
import { resolveContent, type ContentEntry } from "nextly/runtime";
import { notFound } from "next/navigation";

// `ContentEntry` is `Record<string, unknown>`: the entry is whatever the
// collection holds, so read fields off it deliberately rather than assuming a
// shape. `nextly generate:types` is what turns this into a named type.
function Post({ entry }: { entry: ContentEntry }) {
  return <article>{String(entry.title ?? "")}</article>;
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await resolveContent("posts", slug, { depth: 2 });
  if (!post) notFound();
  return <Post entry={post} />;
}
```

**Publish state.** By default `resolveContent` reads `status: "published"`.
This is the lifecycle-aware scope, not a `where` clause on a `status` column, so
it also constrains a localized collection's per-locale companion status — a
draft translation under a published main row is never returned. On a status-less
collection (no built-in Draft/Published lifecycle) the scope is a no-op and
every row is live, so you can mix lifecycle and status-less collections freely.

**Pending edits.** Publish state is only half the picture. An entry that has
never been published is covered by `status`, but pending edits to an
**already-published** entry are stored as a separate working draft that no
`status` scope can see — the live row keeps serving until you publish. Pass
`draft: true` to read those instead:

```ts
// The page as the editor last saved it, not as visitors see it.
await resolveContent("posts", slug, { draft: true, overrideAccess: true });
```

The two layers are gated differently, and that difference is the important part:

- **Pending edits** are judged per row, by an update-capability probe, so asking
  for them is safe from anywhere. A caller who cannot edit the document gets the
  published row instead.
- **Never-published entries** are judged by nothing — the query simply returns
  them. So `draft: true` widens `status` to `"all"` **only on a trusted read**
  (`overrideAccess: true`). Without that, a draft read still sees published rows
  and overlays their pending edits.

That split exists because a `draft` flag wired from an untrusted request would
otherwise publish unpublished pages. An explicit `status` always wins.

A draft read is **never cached**, because cache tags are busted by writes to the
live row while a draft changes on every save.

**Access.** By default `resolveContent` **enforces** the collection's read
policy (`overrideAccess: false`). A rule-less (public) collection still renders;
a collection with a stored member-only or role-based read rule is hidden from an
unauthenticated request and resolves to `null` (→ `notFound()`, so the URL does
not reveal that the entry exists). Pass a `user` to render member content, or
`overrideAccess: true` for a fully trusted read.

```ts
// Anonymous public read (default): stored access rules are enforced.
await resolveContent("posts", slug);

// Render member-only content for a signed-in reader.
await resolveContent("posts", slug, { user: { id, role } });

// Trusted read that ignores access rules (e.g. a preview route you gate yourself).
await resolveContent("posts", slug, { overrideAccess: true, status: "all" });
```

> An anonymous read enforces stored rules that **deny outright**
> (public/authenticated/role-based). A **row-level constraint** rule (owner-only,
> or a custom rule returning a query) and inline `defineCollection({ access })`
> code rules need a `user` context to evaluate, so they are not applied for an
> anonymous read. Gate that content behind an authenticated read (pass a `user`)
> rather than the anonymous default.

**Caching.** Only a **trusted** (`overrideAccess: true`) read with no `user` is
F1-cached — an enforced read is never cached, because its result depends on an
access decision that a content-tag bust can't invalidate (a stored read-policy
change doesn't write an entry). So a public site that wants cached pages should
read its public content with `overrideAccess: true`; access-gated or member
content runs fresh per request.

Other options: `slugField` (default `"slug"`), `depth`, `locale`,
`richTextFormat`, `tags` (extra cache tags for populated relations),
`revalidate` (a time-based safety net for cached reads), and `cacheScope` (a
discriminator when distinct readers — per tenant or database — resolve the same
slug).

## createContentRoute — the optional catch-all

For the pages-collection model (add an `/about` entry and it just works), wire
one `app/[[...slug]]/page.tsx` optional catch-all:

```tsx
// app/[[...slug]]/page.tsx
import { createContentRoute, buildMetadata } from "nextly/runtime";

const route = createContentRoute({
  collections: ["pages"],
  render: entry => <Page entry={entry} />,
  buildMetadata: entry => buildMetadata(entry),
});

export const generateMetadata = route.generateMetadata;
export default route.ContentPage;
```

`createContentRoute` reads **access-enforced** content: the collections' read
rules decide, so the answer depends on who is asking and the page renders per
request. It deliberately returns no `generateStaticParams` — Next classifies a
route as static because that export exists, and a route that must render
dynamically cannot also claim to be static.

When the content in those collections is public, say so and the route
pre-renders:

```tsx
// app/[[...slug]]/page.tsx
import { createPublicContentRoute, buildMetadata } from "nextly/runtime";

const route = createPublicContentRoute({
  collections: ["pages"],
  render: entry => <Page entry={entry} />,
  buildMetadata: entry => buildMetadata(entry),
});

export const generateStaticParams = route.generateStaticParams;
export const generateMetadata = route.generateMetadata;
export const dynamicParams = true;
export default route.ContentPage;
```

A public route reads trusted, so its reads are cacheable and its paths
pre-renderable. It refuses `draft` and `staticParamsLimit: 0` at construction —
both would force the render dynamic while the route still told Next it was
static. Use `createContentRoute` for preview or for a site that pre-renders
nothing.

Both factories resolve a path across the configured collections (first match
wins) and call `notFound()` on a genuine miss or a reserved path (`/admin`,
`/api`, `/_next`, `/static`, and metadata files like `sitemap.xml`). `status`
behaves as in `resolveContent`.

**Which factory you call decides whether access rules are consulted at all, so
choose it per collection set, not per preference.**

- `createContentRoute` reads **enforced**. A rule-less collection still renders;
  a stored member-only or role-based one is hidden from these anonymous
  requests.
- `createPublicContentRoute` reads **trusted** — access rules are not consulted,
  on the resolved read and on the `generateStaticParams` scan alike. That is
  what makes its reads cacheable and its paths pre-renderable, and it means
  **every collection you list must be public**. A restricted collection listed
  here has its entries read trusted and its paths pre-rendered into public HTML.
  That statement is now exactly true: the collections you list are the ones
  trusted, and a relationship reaching past them is read enforced unless you
  name it (see below).

### What a populated relationship is read as

A page often populates a relationship — a post reaching its author, a page
reaching its hero image. That target is a collection you did **not** list: it
was reached through a field.

**`createPublicContentRoute` reads those targets as a visitor would**, unless
you say otherwise. Their own access rules apply, and only their published rows
come back. Name the ones your pages populate to have them read trusted too:

```ts
export const { ContentPage, generateMetadata, generateStaticParams } =
  createPublicContentRoute({
    collections: ["posts"],
    // Posts populate an author; authors are public too.
    trustedCollections: ["posts", "authors"],
    depth: 1,
    render: (entry) => <Post entry={entry} />,
  });
```

`trustedCollections` defaults to the `collections` you listed, so a route that
populates nothing needs no extra config, and one that does gets an explicit
decision rather than an inherited one.

> **Trusting a collection does not admit its drafts.** A public route
> pre-renders, so an unpublished row pulled in through a relationship is written
> into a static artifact and stays there after the row is unpublished —
> unpublishing cannot take back a page already built. Trust decides *who* may
> read a row; being published decides whether it is ready for anyone. Nothing in
> this config widens a lifecycle.

`createContentRoute` needs none of this for its ordinary reads — it reads
enforced already, and **its previews trust nothing by default.** A draft grant
turns the bypass on for one request, but it authorizes ONE document and says
nothing about what that document points at — including a sibling row in the
same collection. So a preview populates relations exactly as an anonymous
visitor would see them. Name a target in `trustedCollections` if you know it is
public and want it populated in preview too.

> **Cached pages are point-in-time copies.** A public route pre-renders, so a
> target whose read policy tightens after the build is not reflected until that
> page is revalidated — and the same is true of the page's own content, bound or
> not. Name the related collections in `tags` so a write to one busts the page,
> and use `revalidate` as a time-based safety net for a policy change, which
> writes no row and therefore busts no tag.

**`createPublicContentRoute` defaults to `depth: 0`** — no relation expansion at
all — so a route that never populates anything cannot be surprised by any of
this. Set `depth` when your pages do populate relations.

**The route factories take no `overrideAccess` option** — unlike
`resolveContent`, which still does, because a page calling it directly knows who
is asking. Two settings that had to agree is what produced a route behaving
differently depending on whether the database had rows in it when the build ran;
for a route, the posture is now the name of the function you call.

This route always resolves **anonymously** — its config is captured once at
module scope, so it cannot carry a per-request user. For a route that renders
per-visitor member content, call `resolveContent` with the request's `user`
inside your own page rather than using `createContentRoute`.

### Previewing drafts

Whether a visitor is previewing is a per-request fact, and route config is not —
so `draft` takes a function the route asks on every request. Wire it to Next's
draft mode:

The function is handed the collection and slug being resolved, so the answer can
be scoped to a document:

```ts
import { createContentRoute, readPreviewScope } from "nextly/runtime";

const route = createContentRoute({
  collections: ["pages"],
  draft: async ({ collection }) => {
    const scope = await readPreviewScope();
    // A Single's token names no collection, so it cannot grant this route's draft.
    if (scope === null || !("collection" in scope)) return false;
    if (scope.collection !== collection) return false;
    // Name the entry, do not just answer yes: slugs are not unique.
    return { entryId: scope.entryId };
  },
  render: page => <Page {...page} />,
});
```

Return `{ entryId }` rather than `true` whenever a token is backing the
decision. A slug need not be unique — the resolver supports duplicates and
settles them by sorting on `id` — so a bare `true` grants whichever row the
route happens to resolve, which may not be the one the token named. With an
`entryId` the route discards the draft when the path resolved elsewhere.

**Use that argument.** Next's draft mode is a single boolean for the whole host:
`draftMode().isEnabled` tells you a visitor opened _a_ valid preview link, never
_which_ document it was for. Answering from it alone turns a link scoped to one
unpublished page into a key to every unpublished page in the configured
collections, for the life of the session — which is exactly what a preview
token's scope exists to prevent.

**Returning `true` is an authorization decision, not a display preference.** The
route resolves anonymously and the working draft is only shown to a caller who
could edit the document, so a request this returns `true` for is read trusted.
Put the check inside that function — a verified preview cookie, a session — and
never in a query parameter a visitor controls.

`draft` belongs to `createContentRoute` only. `createPublicContentRoute` refuses
it at construction: a draft read is never cacheable, so it marks the render
dynamic — while the public route's `generateStaticParams` tells Next the route
is static, and a dynamic marking inside a static render is an error. Preview and
pre-rendering are not compatible on one route; mount previewable paths on a
dynamic one.

A literal `draft: true` is accepted for a route mounted behind your own auth. It
means **every** visitor sees unpublished content, which is almost never what a
public site wants.

> **Next 16 Cache Components:** an exported `generateStaticParams` must return at
> least one entry under Cache Components. For a no-prerender or empty-site setup
> in that mode, export only `ContentPage` and `generateMetadata` and let paths
> render on demand.

Not every blog needs this: if you already have typed per-type routes
(`/blog/[slug]`, `/authors/[slug]`), keep them and use `resolveContent` +
`buildMetadata` inside each — `createContentRoute` is for the single-catch-all
pages model.

## buildMetadata — the seo group to Next Metadata

`buildMetadata(entry, options?)` turns the plugin's `seo` field group into a
Next.js `Metadata` object (title, description, canonical, OpenGraph, Twitter
card, and `robots` from `noindex`). Blank `seo` fields fall back to the values
you pass; caller `openGraph` / `twitter` extras win.

```ts
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
  if (!post) return {};
  return buildMetadata(post, {
    fallback: {
      title: post.title,
      description: post.excerpt,
      image: post.featuredImage?.url,
      canonical: `/blog/${slug}`,
    },
    openGraph: { type: "article", publishedTime: post.publishedAt },
  });
}
```

A `canonical` is validated to a root-relative path or an absolute http(s) URL
(a `mailto:`/`javascript:` value falls back), and a page ships `index, follow`
unless `seo.noindex` is set.

## nextlySitemap and nextlyRobots

`nextlySitemap({ entries, tags })` builds the default export for
`app/sitemap.ts` from a caller-supplied `entries` provider and caches it with
F1. Pass each collection's `nextlyTags(...)` so a publish or delete busts
`/sitemap.xml` in lockstep with the pages. With no tags and no `revalidate` it
reads uncached (and marks the render dynamic) so it never freezes stale.

```ts
// app/sitemap.ts
import { nextlySitemap, nextlyTags } from "nextly/runtime";
import { buildSitemapUrls } from "@nextlyhq/plugin-seo";

export default nextlySitemap({
  tags: nextlyTags("posts"),
  entries: async () =>
    (await buildSitemapUrls(services, { collections: ["posts"], baseUrl })).map(
      u => ({ url: u.loc, lastModified: u.lastModified })
    ),
});
```

`nextlyRobots({ sitemap })` builds `app/robots.ts`, keeping `/admin` and `/api`
out of the index on a path boundary (so `/administration` is not swallowed) and
advertising the sitemap:

```ts
// app/robots.ts
import { nextlyRobots } from "nextly/runtime";
export default nextlyRobots({ sitemap: "https://example.com/sitemap.xml" });
```

## Reference: the blog template

The `blog` template dogfoods these helpers: `app/robots.ts` is `nextlyRobots`,
`app/sitemap.ts` is `nextlySitemap` over the published post/category/tag/author
slugs, and the post detail page's `generateMetadata` is `buildMetadata` reading
the Posts `seo` group. Its per-type typed routes keep `resolveContent`-style
reads inside each page rather than a single catch-all.

---
title: Plugins
description: Extend Nextly with official and custom plugins that add collections, admin views, hooks, and API endpoints.
url: https://nextlyhq.com/docs/plugins
---

> **Alpha (`0.x`) — pin your versions.**
>
> The plugin API surface is now **stable and semver-protected** (see [API stability](https://nextlyhq.com/docs/plugins/stability)); the packages themselves are still `0.x` alpha. Build against `@nextlyhq/plugin-sdk` — the stability boundary — and pin your `nextly` / `@nextlyhq/plugin-sdk` versions.

Plugins extend Nextly with new functionality without modifying core code. A plugin can add collections, register lifecycle hooks, inject custom admin views, and transform configuration -- all through a single `plugins` array in your config.

## Official Plugins

| Plugin | Package | Description |
|--------|---------|-------------|
| [Form Builder](https://nextlyhq.com/docs/plugins/form-builder) | `@nextlyhq/plugin-form-builder` | Visual drag-and-drop form builder with submission management, email notifications, spam protection, and export |

## Community Plugins

Community plugins are distributed on npm — search the [`nextly-plugin`](https://www.npmjs.com/search?q=keywords:nextly-plugin) keyword. To get yours listed here, see [Contributing a plugin](https://nextlyhq.com/docs/plugins/contributing).

_No community plugins listed yet — be the first._

## Adding a Plugin

Install the plugin package, then add it to your `defineConfig` call.

```typescript
// nextly.config.ts
import { defineConfig } from 'nextly';
import { formBuilder } from '@nextlyhq/plugin-form-builder';

const fb = formBuilder();

export default defineConfig({
  plugins: [fb.plugin],
  collections: [Posts, Users, Media],
});
```

Plugin collections are merged automatically -- you do not need to spread them into the `collections` array yourself. The plugin's `config()` transformer handles this during initialization.

For simpler setups where you do not need to customize plugin options, use the pre-configured default instance:

```typescript
// nextly.config.ts
import { defineConfig } from 'nextly';
import { formBuilderPlugin } from '@nextlyhq/plugin-form-builder';

export default defineConfig({
  plugins: [formBuilderPlugin],
  collections: [Posts, Users, Media],
});
```

## How Plugins Work

Every plugin implements the `PluginDefinition` interface from `nextly`. The lifecycle has two phases:

### 1. Declarative + setup phase

Plugins declare schema, permissions, routes, and admin UI in `contributes` (read by the host without running the plugin). Before services start, Nextly also runs each plugin's optional `setup(config)` escape hatch — all `setup`s run before any `init`. Don't mutate the config; spread and return a new object.

```typescript
import { definePlugin } from '@nextlyhq/plugin-sdk';

export const myPlugin = definePlugin({
  name: '@acme/nextly-plugin-example',
  version: '1.0.0',
  nextly: '^1.0.0',
  contributes: {
    collections: [MyCollection], // merged automatically by the pipeline
  },
  setup(config) {
    return { ...config }; // escape hatch for advanced config transforms
  },
});
```

### 2. Initialization Phase

After all services are registered, Nextly calls each plugin's `init(ctx)` with a `PluginContext`. It provides:

- **`services`** -- managed, secure-by-default data access (`{ as: 'system' }` to elevate)
- **`db`** -- raw Drizzle escape hatch (unmanaged)
- **`hooks`** / **`events`** / **`filters`** / **`actions`** -- in-transaction hooks, post-commit events, typed seams
- **`self`** -- your entities' resolved slugs after any host `.rename()`
- **`logger`**, **`config`**, **`nextlyVersion`**

```typescript
import { definePlugin } from '@nextlyhq/plugin-sdk';

export const auditPlugin = definePlugin({
  name: 'audit-log',
  version: '1.0.0',
  nextly: '^1.0.0',

  async init(ctx) {
    ctx.hooks.on('afterCreate', '*', async (context) => {
      ctx.logger.info('Created entry', {
        collection: context.collection,
        id: context.data?.id,
      });
    });
  },
});
```

See the **[Plugin Author Guide](https://nextlyhq.com/docs/plugins/author-guide)** for the full workflow.

## Plugin Admin Integration

Plugins can control where their collections appear in the admin sidebar and customize their visual appearance.

```typescript
const plugin: PluginDefinition = {
  name: 'my-plugin',
  collections: [MyCollection],

  admin: {
    order: 50,
    description: 'What this plugin does',
    appearance: {
      icon: 'BarChart',
      label: 'Analytics',
      badge: 'Beta',
      badgeVariant: 'secondary',
    },
  },
};
```

Plugins can also register custom admin view components. The Form Builder plugin, for example, replaces the default collection edit view with a visual drag-and-drop builder. Components are referenced by path strings (e.g., `@nextlyhq/plugin-form-builder/admin#FormBuilderView`) and auto-registered when the admin panel loads.

## Overriding Plugin Behavior

Host applications can override a plugin's sidebar placement and appearance through the `admin.pluginOverrides` section of `defineConfig`:

```typescript
// nextly.config.ts
import { AdminPlacement } from 'nextly';

export default defineConfig({
  plugins: [fb.plugin],
  admin: {
    pluginOverrides: {
      '@nextlyhq/plugin-form-builder': {
        placement: AdminPlacement.COLLECTIONS,
        order: 10,
        appearance: {
          label: 'Contact Forms',
        },
      },
    },
  },
});
```

## Next Steps

**Build a plugin**
- [Plugin Author Guide](https://nextlyhq.com/docs/plugins/author-guide) -- the overview: lifecycle, `ctx`, and the scaffold → dev → test → publish loop
- [Lifecycle, dependencies & order](https://nextlyhq.com/docs/plugins/lifecycle) -- `setup`/`init`/`destroy`, load order, `dependsOn`, version compatibility, `enabled`
- [Data access](https://nextlyhq.com/docs/plugins/services) -- `ctx.services`, queries, bulk ops, `{ as: "system" }`
- [Permissions](https://nextlyhq.com/docs/plugins/permissions) -- declare-but-never-grant, route gating, `useCan`/`<Can>`
- [HTTP routes](https://nextlyhq.com/docs/plugins/routes) -- `contributes.routes`, secure-by-default, middleware
- [Admin UI](https://nextlyhq.com/docs/plugins/admin-ui) -- menu, pages, view overrides, placement
- [Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema) -- collections, `extend`, relations, provenance, uninstall
- [Testing](https://nextlyhq.com/docs/plugins/testing) -- `createTestNextly` + real-database tests

**Ship & maintain**
- [API stability](https://nextlyhq.com/docs/plugins/stability) -- what's `@public` vs `@experimental`, semver + deprecation policy
- [Publishing & distribution](https://nextlyhq.com/docs/plugins/distribution) -- publish, discovery, the trust model
- [Contributing a plugin](https://nextlyhq.com/docs/plugins/contributing) -- the quality checklist + how to get listed

**Reference**
- [Plugin API Reference](https://nextlyhq.com/docs/plugins/api-reference) -- the public `@nextlyhq/plugin-sdk` surface
- [Plugin Error Reference](https://nextlyhq.com/docs/plugins/error-reference) -- fail-fast boot errors and how to fix them
- [Configuration Reference](https://nextlyhq.com/docs/configuration/nextly-config) -- full `defineConfig` options including the `plugins` array

---
title: Plugin Author Guide
description: Build a Nextly plugin — the lifecycle, the plugin context, and the scaffold → dev → test → publish loop.
url: https://nextlyhq.com/docs/plugins/author-guide
---

> **Alpha (`0.x`) — pin your versions.**
>
> The plugin API surface is now **stable and semver-protected** (see [API stability](https://nextlyhq.com/docs/plugins/stability)); the packages themselves are still `0.x` alpha. Build against `@nextlyhq/plugin-sdk` — it is the stability boundary — and pin your `nextly` / `@nextlyhq/plugin-sdk` versions.

A plugin extends Nextly with new collections, hooks, events, routes, permissions, and admin UI — without modifying core. This guide is the overview; deeper topics each have their own page:

- [Lifecycle, dependencies & order](https://nextlyhq.com/docs/plugins/lifecycle) — `setup`/`init`/`destroy`, load order, `dependsOn`, version compat, `enabled`
- [Data access](https://nextlyhq.com/docs/plugins/services) — `ctx.services`, queries, bulk ops, `{ as: "system" }`
- [Permissions](https://nextlyhq.com/docs/plugins/permissions) — declare-but-never-grant, route gating, `useCan`/`<Can>`
- [HTTP routes](https://nextlyhq.com/docs/plugins/routes) — `contributes.routes`, secure-by-default, middleware
- [Admin UI](https://nextlyhq.com/docs/plugins/admin-ui) — menu, pages, view overrides, placement
- [Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema) — collections, `extend`, relations, provenance, uninstall
- [Testing](https://nextlyhq.com/docs/plugins/testing) · [API stability](https://nextlyhq.com/docs/plugins/stability) · [Publishing & distribution](https://nextlyhq.com/docs/plugins/distribution)

## Scaffold a plugin

```bash
npm create nextly-app -- --template plugin
```

This generates a publishable package whose plugin code lives in `src/` plus an embedded `dev/` playground — a minimal Nextly app on SQLite with hot-reload that **registers your plugin** so you can exercise it in a real admin. `dev/` is never published (only `dist/` ships).

```
my-plugin/
├── src/                 # your plugin (published as dist/)
│   ├── index.ts
│   ├── plugin.ts        # definePlugin(...)
│   ├── collections/
│   └── admin/
├── dev/                 # local playground — NOT published
│   ├── nextly.config.ts # registers your plugin
│   ├── next.config.ts   # source-mode HMR for src/
│   └── instrumentation.ts
└── package.json         # files: ["dist"]; nextly-plugin keyword
```

## The plugin object

Author with `definePlugin` from `@nextlyhq/plugin-sdk`:

```ts
import { definePlugin } from "@nextlyhq/plugin-sdk";

export const myPlugin = (opts: MyPluginOptions = {}) =>
  definePlugin({
    name: "@acme/nextly-plugin-greetings",
    version: "0.1.0",
    nextly: ">=0.0.2-alpha.63", // core-compatibility range, boot-checked
    dependsOn: {}, // required plugin deps → version range
    enabled: true, // false skips behavior but keeps schema (D49)
    contributes: {
      /* declarative nouns — see below */
    },
    setup(config) {
      return config;
    }, // escape hatch — all setups run before any init
    init(ctx) {
      /* runtime wiring */
    },
    destroy(ctx) {
      /* teardown on shutdown / HMR / test */
    },
  });
```

### Choosing the `nextly` range

The floor names **the release that introduced the newest core API your plugin
actually calls** — not the version you happened to develop against, and not the
latest release.

Get it too low and the failure is confusing: your plugin boots against a core
that lacks the API, the import resolves to nothing, and the crash names a
symbol rather than a version. Too high, and installs that would have worked are
refused.

There is one case that catches people out. If the API you need is landing in
the *same release as your plugin* — you added it to core yourself, or you are
building inside the Nextly monorepo — then the version to name **does not exist
yet**. Writing the next one is a guess about a release that has not happened,
and it makes your plugin unusable in the source tree, where core carries the
current version: every boot fails compatibility before a single test runs.

Where your package and core version together, say so directly instead:

```ts
import { version } from "../package.json";

definePlugin({
  name: "@acme/nextly-plugin-greetings",
  version: "0.1.0",
  // Released in lockstep with core, so a core at least as new as this build is
  // exactly the compatibility that is meant — and it stays true after every
  // release without being edited.
  nextly: `>=${version}`,
  // …
});
```

That only applies where the two genuinely ship together. A plugin released on
its own schedule should name the real floor, and leave it alone until it calls
something newer.

### `contributes` (declarative)

`contributes` is data the host can read **without running your plugin** (so the admin and codegen can reason about it):

- `collections` / `singles` / `components` — new, plugin-owned schema entities.
- `extend` — add fields to existing entities by slug.
- `permissions` — custom (non-CRUD) permissions; CRUD is auto-seeded per collection/single.
- `events` — custom event names you may emit.
- `routes` — HTTP endpoints, namespaced under `/api/plugins/<name>/…`, secure by default.
- `admin` — menu, pages, settings, and per-collection view overrides (referenced by string component path).

### Lifecycle

`contributes → setup → init → destroy`. All plugins' `setup`s run before any `init`. Load order is a **topological sort** over `dependsOn` (array order breaks ties). A missing/incompatible/cyclic dependency is a **fail-fast boot error** (see the [error reference](https://nextlyhq.com/docs/plugins/error-reference)).

## The plugin context (`ctx`)

`init(ctx)` and `destroy(ctx)` receive:

| Field | Use |
|---|---|
| `ctx.services` | Managed data access — **secure by default** (acts as the ambient user, RBAC on). Pass `{ as: "system" }` to elevate. Validation/hooks/events always run. |
| `ctx.db` | Raw Drizzle escape hatch — **unmanaged** (you own consistency + portability). |
| `ctx.hooks` | In-transaction hooks — can **modify or abort** an operation. |
| `ctx.events` | Post-commit event bus — **observe-only, best-effort** (may be dropped). React/notify here. |
| `ctx.filters` / `ctx.actions` | Typed seams to transform values / run ordered side-effects. |
| `ctx.self` | Your entities' **resolved** slugs after any host `.rename()`. Always reference your own entities through this. |
| `ctx.logger` | Structured logging. |
| `ctx.config` | Read-only Nextly config. |
| `ctx.nextlyVersion` | The running core version (feature detection). |

**Hooks vs events:** need to change or block an operation → use a **hook**; need to react after it commits → use an **event**.

**Never hardcode your own slugs** in `init`. Use `ctx.self` so your plugin keeps working when an integrator renames an entity:

```ts
init(ctx) {
  ctx.hooks.on("afterCreate", ctx.self.collections.submissions, sendEmail);
  ctx.events.on(`collection.${ctx.self.collections.submissions}.created`, notify);
}
```

## The dev loop

```bash
pnpm install
pnpm dev          # runs the dev/ playground (next dev) → open /admin
```

Editing files under `src/` hot-reloads the playground (the `dev/next.config.ts` transpiles your plugin source). Your plugin's `destroy()` runs on each reload, so clean up subscriptions there.

> **HMR gotcha:** Nextly's registries (hooks, events, filters) survive hot-reload because they live on `globalThis`. If *you* keep state in a module-scoped singleton, it will be recreated on every reload and your subscriptions lost. Register through `ctx.hooks`/`ctx.events`/`ctx.filters` instead.

## Test

```ts
import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
import { myPlugin } from "../src";

const t = await createTestNextly({
  plugins: [myPlugin()],
  collections: myPlugin().contributes.collections,
});
// drive t.nextly / assert t.hooks, t.events, inspect t.adapter …
await t.destroy();
```

`createTestNextly` boots a real Nextly on in-memory SQLite and runs your full lifecycle.

To check your plugin against a real database, pass `dialect`. Each boot gets its own database, created and dropped by `destroy()`, so runs never contaminate each other:

```ts
import {
  createTestNextly,
  getConfiguredTestDialects,
} from "@nextlyhq/plugin-sdk/testing";

// "sqlite" is always included; the others are included when TEST_POSTGRES_URL /
// TEST_MYSQL_URL point at a server you are willing to create databases on.
// Configured, not probed: a URL you set but cannot reach fails rather than
// skipping, which is usually what you want from a broken environment.
for (const dialect of getConfiguredTestDialects()) {
  describe(`myPlugin (${dialect})`, () => {
    it("works", async () => {
      const t = await createTestNextly({ dialect, plugins: [myPlugin()] });
      // …
      await t.destroy();
    });
  });
}
```

Worth doing if your plugin contributes collections or touches the database directly: column types, default expressions, and JSON handling differ between dialects in ways SQLite alone will not reveal.

## Type safety (codegen)

Run `nextly generate:types` in the consuming app to narrow `CollectionSlug`, `PermissionSlug`, and `EventName` to the real, installed values — including your plugin's. When a plugin contributes admin components, the same command emits a `plugin-admin-imports.generated.ts` import map so those React components load with no manual host imports.

## Publish

Build (`tsup`), publish to npm, and add the `nextly-plugin` keyword to `package.json` so it's discoverable. Declare an honest `nextly` range. See the [API reference](https://nextlyhq.com/docs/plugins/api-reference) for the full public surface and the [error reference](https://nextlyhq.com/docs/plugins/error-reference) for boot-error meanings.

## Stability

The public surface (`definePlugin`/`contributes`/lifecycle, `ctx.services`, `contributes.routes`, `contributes.admin`, `ctx.events` + event names, `HookContext`, and `@nextlyhq/plugin-sdk/testing`) is now **`@public`** — semver-protected, so breaking it requires a Nextly major. Some surfaces are still `@experimental` (the raw `ctx.db`, `ctx.hooks` registration, filters/actions, `secret()`, `useCan`/`<Can>`, admin widgets) and may change. The full ledger is on the [API stability](https://nextlyhq.com/docs/plugins/stability) page. Pin versions while we are pre-`1.0`.

---
title: Auth extensibility
description: Extend authentication from a plugin — custom strategies (OAuth/SSO), auth-flow hooks, and first-class multi-step challenges (2FA) — without forking core.
url: https://nextlyhq.com/docs/plugins/auth
---

> **Alpha (`0.x`) — `@experimental`.** The auth-extensibility surface (D71/D57) is
> new and ships `@experimental`: it works and is integration-tested, but stays
> experimental until a first-party plugin exercises it in production (D55). Pin
> your versions.

Nextly's auth is pluggable through four surfaces, modeled on what Payload, Strapi,
and WordPress allow — and adding first-class **multi-step (2FA)** that those do
piecemeal:

| Surface | What it does | Who provides it |
|---|---|---|
| **Strategies** | Decide *who a user is* (password, OAuth, SSO, magic-link, passkey) | App opt-in (`defineConfig({ auth: { strategies } })`) |
| **Auth-flow hooks** | Modify / abort / **challenge** the login, register, logout, session flow | Plugin `contributes.auth.hooks` |
| **Challenges** | A pending second step (2FA) that pauses login until resolved | Plugin `contributes.auth.challenges` |
| **Auth-page UI** | Provider buttons, challenge views, login-form slots | Plugin `contributes.auth.ui` |

The built-in email/password login is itself just the `password` strategy, always
present (and run last) unless you disable it.

## Strategies are opt-in (the trust boundary)

A strategy authenticates users, so it's the highest-trust extension point. A plugin
may *ship* a strategy, but it only takes effect when the **app** enables it:

```ts
// nextly.config.ts
import { defineConfig } from "nextly/config";
import { googleOAuth } from "@acme/nextly-plugin-google";

export default defineConfig({
  auth: { strategies: [googleOAuth({ clientId: process.env.GOOGLE_ID! })] },
});
```

Hooks, challenges, and UI follow normal contribution rules (active as soon as the
plugin is installed). Strategies don't — that's deliberate (secure-by-default).

## Worked example: an OAuth strategy

A strategy returns one of four outcomes: `authenticated`, `challenge`, `fail`, or
`pass` ("not my credential — try the next strategy"). This is the WordPress
`authenticate`-chain model, typed.

```ts
import type { AuthStrategy, AuthUser } from "@nextlyhq/plugin-sdk";

export function googleOAuth(opts: { clientId: string }): AuthStrategy {
  return {
    name: "oauth-google",
    async authenticate(input, ctx) {
      // Only claim requests carrying a Google id_token; otherwise pass through.
      const idToken = input.body.googleIdToken;
      if (typeof idToken !== "string") return { type: "pass" };

      const profile = await verifyGoogleToken(idToken, opts.clientId);
      if (!profile) return { type: "fail", reason: "invalid-google-token" };

      // Find-or-link the local user via the managed services (secure-by-default).
      const existing = await ctx.services.collections.listEntries(
        "users",
        { where: { email: profile.email } },
        { as: "system" }
      );
      const user = existing.data[0];
      if (!user) return { type: "fail", reason: "no-linked-account" };

      return {
        type: "authenticated",
        user: { id: user.id as AuthUser["id"], email: user.email as string },
      };
    },
  };
}
```

Add a **provider button** so it shows on the login screen
(`contributes.auth.ui.providers`) and you have Strapi-style social login.

## Worked example: TOTP two-factor (a challenge)

2FA is an `afterAuthenticate` hook that returns a **challenge** instead of letting
the session issue, plus a **challenge definition** that resolves the code. Core
handles the hard part — a single-purpose, short-lived **pending token**, the
attempt cap, and re-issuing the session only after the challenge resolves.

```ts
import { definePlugin } from "@nextlyhq/plugin-sdk";

export const twoFactor = definePlugin({
  name: "@acme/nextly-plugin-2fa",
  version: "0.1.0",
  nextly: ">=0.0.2-alpha.63",
  contributes: {
    auth: {
      // 1. After the password (or any strategy) authenticates, require a second
      //    step IF the user has 2FA enabled. Returning `{ challenge }` pauses login.
      hooks: {
        afterAuthenticate: async (user, ctx) => {
          const enabled = await isTotpEnabled(ctx, user.id);
          if (!enabled) return user; // continue → session issues
          return { challenge: { id: "totp", userId: user.id } };
        },
      },
      // 2. Resolve the challenge: validate the TOTP code the client submits.
      challenges: [
        {
          id: "totp",
          resolve: async ({ userId, response }, ctx) => {
            const ok = await verifyTotp(ctx, userId, String(response.code ?? ""));
            return ok ? { ok: true } : { ok: false, reason: "bad-code" };
          },
        },
      ],
      // 3. Render the step UI when the login response is a `totp` challenge.
      ui: { challengeViews: { totp: "@acme/nextly-plugin-2fa/admin#TotpPrompt" } },
    },
  },
});
```

### The challenge flow on the wire

1. `POST /auth/login` with valid credentials → the `afterAuthenticate` hook returns
   a challenge, so the response is **not** a session but:
   ```json
   { "status": "challenge", "challengeType": "totp", "pendingToken": "…" }
   ```
2. The client renders the `challengeViews["totp"]` component, collects the code, and
   calls:
   ```
   POST /auth/challenge/resolve   { "pendingToken": "…", "response": { "code": "123456" } }
   ```
3. Core verifies the pending token (single-purpose, TTL'd, attempt-capped), runs your
   challenge's `resolve`, and on success issues the real session — identical to a
   direct login. A wrong code re-issues a pending token until the cap is hit.

The pending token authorizes **nothing** except resolving the challenge — it can never
establish a session (the access guard rejects it). Challenges are stackable (e.g. 2FA
then a device-confirm).

## Auth-flow hooks reference

All hooks are optional on `contributes.auth.hooks`. Each can **modify** (return a new
value), **abort** (throw → generic error), or — for `afterAuthenticate` — **challenge**.

| Hook | When | Use |
|---|---|---|
| `beforeLogin(input)` | Before any strategy | Pre-checks; throw to block (maintenance mode, IP allowlist) |
| `afterAuthenticate(user)` | After a strategy identifies the user | **Insert 2FA / step-up**; decorate the user |
| `afterLogin(user)` | After the session is issued | Side effects (audit, last-login, notify) |
| `beforeRegister(data)` | Before a new user is created | Normalize / augment the payload |
| `afterRegister(user)` | After a successful register | Welcome email, provisioning, CRM sync |
| `beforeLogout` / `afterLogout` | Around logout | Cleanup, revoke external sessions |
| `determineUser(request)` | Session/refresh resolution | Custom credential (API key, alt token) → return a user or `null` |
| `customizeClaims(claims, user)` | Building the JWT (login **and** refresh) | Add/rename JWT claims |

Hooks observe-or-mutate; they do **not** replace strategies. Use a strategy to
authenticate, a hook to gate/decorate.

## What stays core (and why)

Session/token issuance, cookies, CSRF, rate-limiting, and account lockout stay in core
— they're security-critical and identical for every auth method. You extend *who you
are* and *the flow*, not the session machinery. This matches where Payload, Strapi, and
WordPress draw the line.

## Security notes

- **Strategies are app-opt-in.** Installing a plugin never silently lets it
  authenticate users.
- An enabled strategy/hook runs with **full trust** (D34, no sandbox in v1) — vet auth
  plugins like any dependency.
- Multi-step uses a **single-purpose pending token** (short TTL, attempt-capped) that
  can't be used as a session.
- The whole surface is **`@experimental`** until a first-party plugin graduates it (D55).

See also: [Permissions](https://nextlyhq.com/docs/plugins/permissions) · [Data access](https://nextlyhq.com/docs/plugins/services) · [API reference](https://nextlyhq.com/docs/plugins/api-reference).

---
title: Lifecycle, dependencies & order
description: How and when a plugin runs — the setup/init/destroy lifecycle, load order, declaring dependencies on other plugins, version compatibility, and enabling/disabling.
url: https://nextlyhq.com/docs/plugins/lifecycle
---

This page covers *when* a plugin's code runs, in *what order*, and how to express
ordering and version constraints. For the errors these rules produce, see the
[error reference](https://nextlyhq.com/docs/plugins/error-reference).

## The lifecycle: `contributes → setup → init → destroy` (D4)

```ts
definePlugin({
  name: "@acme/nextly-plugin-thing",
  version: "1.0.0",      // your plugin's semver (used by others' dependsOn ranges)
  nextly: ">=0.0.2-alpha.63", // core-compat range (see Version compatibility)
  contributes: {
    /* declarative nouns: collections, extend, permissions, routes, admin, events */
  },
  setup(config) {
    // Escape-hatch config transform. ALL plugins' setup() run before ANY init().
    // Don't mutate — spread and return a new object.
    return { ...config };
  },
  async init(ctx) {
    // Runtime wiring: subscribe to events, register hooks, read/write via ctx.services.
  },
  async destroy(ctx) {
    // Teardown on shutdown / HMR / test teardown. Undo anything init() set up.
  },
});
```

Phase order:

1. **`contributes`** is read first (without running your plugin) — the host folds your
   schema, permissions, routes, and admin contributions into the merged config.
2. **`setup(config)`** runs for **every** plugin before any `init` — so a plugin can
   adjust config that a later plugin's `init` relies on.
3. **`init(ctx)`** runs once services are live. This is where you do runtime work.
4. **`destroy(ctx)`** runs on shutdown, hot-reload, and test teardown. Always clean up
   here — leaked subscriptions break HMR and tests.

## Load order (D5)

Plugins are run in a **topological sort** over their declared dependencies, so a plugin
always initializes **after** the plugins it depends on. When two plugins have no
dependency relationship, their **array order** in `defineConfig({ plugins: [...] })`
breaks the tie.

```ts
import { defineConfig } from "nextly";

export default defineConfig({
  // a runs before b (array order), unless dependsOn says otherwise
  plugins: [a(), b()],
});
```

A **dependency cycle** is a fail-fast boot error (`PLUGIN_RESOLUTION_ERROR`,
`reason: "dependency-cycle"`).

## Dependencies (D5)

Declare dependencies on other plugins by **package name → version range**:

```ts
definePlugin({
  name: "@acme/nextly-plugin-reports",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  // Hard requirement: must be installed and in-range, and inits first.
  dependsOn: { "@acme/nextly-plugin-core": "^2" },
  // Enhance-if-present: fine if absent; if present it must be in-range and inits first.
  optionalDependsOn: { "@acme/nextly-plugin-search": "^1" },
});
```

- **`dependsOn`.** A missing dependency, or one whose installed version is outside the
  range, is a fail-fast boot error (`reason: "missing-dependency"` /
  `"version-incompatible"`).
- **`optionalDependsOn`.** An **absent** optional dependency is fine; a **present but
  out-of-range** one fails fast (`reason: "optional-version-incompatible"`). Use
  `ctx.nextlyVersion` or feature checks to branch on whether an optional dep is active.

If your plugin **extends or relates to another plugin's entity**, you must declare a
`dependsOn` on it — otherwise you get `NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION`.

## Version compatibility (D6)

Every plugin declares the **core** range it supports via `nextly`. It's checked at boot;
an out-of-range core is a fail-fast error (`reason: "core-incompatible"` /
`"invalid-nextly-range"`).

```ts
nextly: ">=0.0.2-alpha.63", // a range may span multiple majors once they exist
```

Prereleases (alpha/beta) count as in-range. For runtime feature-detection, read
`ctx.nextlyVersion` rather than branching on the declared range.

## Enabling & disabling (D49)

`enabled` defaults to `true`. Setting it to `false` **skips the plugin's behavior**
(`init`, hooks, events, routes, admin UI) but **still applies its declarative schema** —
so disabling a plugin doesn't drop its tables or strand its data. This lets an
integrator turn a plugin's behavior off without a destructive schema change.

```ts
definePlugin({ name: "@acme/nextly-plugin-thing", version: "1.0.0", nextly: ">=0.0.2-alpha.63", enabled: false });
```

To actually remove a plugin's tables and data, remove it from the config and run
`nextly prune` — see [Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema#uninstalling--data-cleanup).

## Inspecting

```bash
nextly plugins list           # installed plugins + their contributions
nextly plugins info <name>    # one plugin's details (resolution runs here too)
```

See also: [Author guide](https://nextlyhq.com/docs/plugins/author-guide) ·
[Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema) ·
[Error reference](https://nextlyhq.com/docs/plugins/error-reference).

---
title: Data access (ctx.services)
description: Read and write data from a plugin through the managed, secure-by-default service layer — queries, bulk operations, and system elevation.
url: https://nextlyhq.com/docs/plugins/services
---

`ctx.services` is the **managed** data path for plugins. Prefer it over the raw
`ctx.db` escape hatch: it enforces validation, hooks, events, and RBAC, and it stays
portable across database dialects. It is `@public` and semver-protected (D56).

```ts
init(ctx) {
  const posts = await ctx.services.collections.listEntries(
    ctx.self.collections.posts, // resolve your own slugs via ctx.self
    { where: { status: "published" }, sort: { field: "createdAt", direction: "desc" } },
    { as: "system" }
  );
}
```

## Secure by default (D35)

Every access method takes a trailing `ServiceOpts` (`{ as, user }`) that decides whose
permissions apply:

| `opts` | Behaviour |
|---|---|
| `{ as: "user", user }` | Runs as that user — **RBAC enforced** by `user.id`. Use this in request handlers; pass the route's `ctx.user`. |
| `{ as: "system" }` | Elevates — **bypasses the access check** for trusted, non-user work (jobs, derived data, lookups). Visible and greppable by design. |
| `{}` / omitted | No user → defaults to **system** (jobs, CLI, migrations). |

Validation, hooks, and events **always run**, even under `{ as: "system" }` — only the
access check is skipped. So a `system` write still fires `afterCreate` hooks and emits
events.

> **v1 limitation:** under `{ as: "user" }`, code-defined `access` rules that read
> `ctx.user.role` see it empty (RBAC is enforced by a DB lookup on `user.id`). Pass
> `{ as: "system" }`, or rely on DB-level RBAC, when you need role-aware access.

Pick the elevation deliberately. A public route that lists published content should use
`{ as: "system" }` (the data is public-derived); a route that returns a user's own
records should use `{ as: "user", user: ctx.user ?? undefined }`.

## Collection methods

`ctx.services.collections` exposes:

| Method | Purpose |
|---|---|
| `createEntry(slug, data, opts?)` | Create one entry. Returns `{ message, item, warnings? }`. |
| `listEntries(slug, query?, opts?)` | List with filter/sort/pagination → `PaginatedResult`. |
| `findEntryById(slug, id, opts?)` | Fetch one by id. |
| `updateEntry(slug, id, data, opts?)` | Update one. Returns `{ message, item, warnings? }`. |
| `deleteEntry(slug, id, opts?)` | Delete one. Returns `{ message, item: { id }, warnings? }`. |
| `count(slug, where?, opts?)` | Count matching rows. |
| `createMany(slug, rows, opts?)` | Bulk insert → `BatchOperationResult`. |

`ctx.services` also exposes `users`, `media`, and `email` services.

## Querying (D56)

`listEntries` takes a `QueryOptions`:

```ts
const result = await ctx.services.collections.listEntries(
  slug,
  {
    where: { status: "published", authorId: someId }, // filter (key/value)
    sort: { field: "createdAt", direction: "desc" },  // single-field sort
    pagination: { limit: 20, page: 1 },               // page through results
    depth: 1,            // 0–5: how deep to populate relations (0 = ids only)
    select: { title: true, slug: true }, // projection: return only these fields
  },
  { as: "system" }
);

result.data;       // the rows for this page
result.pagination; // { total, limit, offset, hasMore }
```

Use `depth: 0` when you only need scalar fields (e.g. building a sitemap) — it avoids
populating relations and is cheaper.

## Bulk operations

`createMany` returns a `BatchOperationResult` with index-keyed errors, so a partial
failure tells you exactly which rows failed:

```ts
const res = await ctx.services.collections.createMany(slug, rows, { as: "system" });
// { successful, failed, ids: string[], errors: [{ index, error }] }
```

## Writes return an envelope

`createEntry`, `updateEntry` and `deleteEntry` resolve to
`{ message, item, warnings? }` — the same shape the Direct API and the REST API
return, so the same failure is equally visible however the write was made.

```ts
const { item, warnings } = await ctx.services.collections.createEntry(
  slug,
  data,
  { as: "system" }
);

if (warnings) {
  // The row IS saved. A post-commit hook (`afterCreate` and friends) runs once
  // the write has committed, so a handler failing there cannot un-save it —
  // report it, don't retry the write.
  ctx.logger.warn("side effects failed", { id: item.id, warnings });
}
```

`deleteEntry` reports `item` as `{ id }`, since there is no row left to return.

## When to drop to `ctx.db`

`ctx.db` (raw Drizzle) is the **`@experimental`** escape hatch — unmanaged: it bypasses
validation, hooks, RBAC, and events, and you own dialect portability. Reach for it only
for things the services layer doesn't cover yet (aggregations beyond `count`). If you
find yourself needing it often, that's a signal worth raising — the goal (D56) is that
most plugins never touch it.

See also: [Permissions](https://nextlyhq.com/docs/plugins/permissions) · [HTTP routes](https://nextlyhq.com/docs/plugins/routes).

---
title: Permissions
description: Declare custom permissions from a plugin, gate routes and admin UI, and check permissions on the client — without ever granting access yourself.
url: https://nextlyhq.com/docs/plugins/permissions
---

Nextly has a single permission primitive: `{ action, resource }`, identified by the
slug `"<action>-<resource>"` (e.g. `"export-submissions"`). Plugins **declare** the
permissions they need; they **never grant** them. An administrator assigns permissions
to roles (D36).

## Declare a permission

CRUD permissions (`create`/`read`/`update`/`delete`) are **auto-seeded** for every
collection and single your plugin contributes — you don't declare those. Declare only
**non-CRUD** custom permissions:

```ts
definePlugin({
  // ...
  contributes: {
    permissions: [
      {
        action: "export",
        resource: "submissions",
        label: "Export Submissions",
        description: "Download form submissions as CSV",
        group: "Forms",
      },
    ],
  },
});
```

Declared permissions are seeded idempotently, tagged with your plugin's provenance, and
made assignable to roles (super-admin can always assign them). On uninstall they are
removed with the rest of your plugin's footprint — see
[Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema).

## Gate a route (server, D28)

Routes are **secure by default**. Set `requiredPermission` to the slug and the
dispatcher enforces authentication **and** that permission before your handler runs:

```ts
contributes: {
  routes: [
    {
      method: "GET",
      path: "/export",
      requiredPermission: "export-submissions", // typed as PermissionSlug
      handler: async (_req, ctx) => {
        // ctx.user is guaranteed here; run as that user:
        const rows = await ctx.services.collections.listEntries(
          ctx.self.collections.submissions,
          {},
          { as: "user", user: ctx.user ?? undefined }
        );
        return Response.json({ items: rows.data });
      },
    },
  ],
}
```

`PermissionSlug` narrows to the union of real seeded slugs once you run
`nextly generate:types` in the consuming app (D47), so typos are caught at compile time.

## Gate the admin UI (client UX, D36)

`requiredPermission` on a menu item, page, or widget hides it for users who lack the
permission. For finer-grained, in-component checks use `useCan` / `<Can>` from
`@nextlyhq/plugin-sdk/client`:

```tsx
import { useCan, Can } from "@nextlyhq/plugin-sdk/client";

function ExportButton() {
  const canExport = useCan("export-submissions");
  return (
    <Can permission="export-submissions">
      <button disabled={!canExport}>Export CSV</button>
    </Can>
  );
}
```

> `useCan`/`<Can>` are **client-side UX only** — they hide or disable controls. They are
> **not** a security boundary. Always enforce the same permission on the server via
> `requiredPermission` (or `{ as: "user" }` on a service call). These client helpers are
> currently [`@experimental`](https://nextlyhq.com/docs/plugins/stability).

## The golden rule

**Define, never grant.** A plugin that silently grants itself or its users access would
break an administrator's trust model. Declare what you need; let the operator decide who
gets it.

See also: [HTTP routes](https://nextlyhq.com/docs/plugins/routes) · [Data access](https://nextlyhq.com/docs/plugins/services).

---
title: HTTP routes
description: Add HTTP endpoints from a plugin — namespaced, secure by default, with typed middleware.
url: https://nextlyhq.com/docs/plugins/routes
---

A plugin can contribute HTTP routes through `contributes.routes`. Each route is mounted
under your plugin's namespace and is **secure by default** (D25/D28).

## Declare a route

```ts
definePlugin({
  name: "@acme/nextly-plugin-reports",
  // ...
  contributes: {
    routes: [
      {
        method: "GET",
        path: "/summary",                  // MUST start with "/"
        requiredPermission: "read-reports", // secure by default
        handler: async (req, ctx) => {
          return Response.json({ ok: true });
        },
      },
    ],
  },
});
```

The route above is served at:

```
/api/plugins/@acme/nextly-plugin-reports/summary
```

i.e. `/api/plugins/<plugin-name><path>`. Paths support `:param` segments
(`/items/:id`), captured into `ctx.params`.

## The handler context

A route handler receives the raw web `Request` plus a `PluginRouteContext` — your full
plugin `ctx` (services/db/events/logger/self/…) **plus** per-request fields:

| Field | Meaning |
|---|---|
| `ctx.user` | The authenticated `AuthUser`, or `null` for a `public` route reached without a session. |
| `ctx.params` | Path parameters captured from `:param` segments. |

Return a standard web `Response`. A thrown error is isolated into a JSON error response
— a handler failure never crashes the server.

## Secure by default (D28)

- **Default:** the request must be authenticated. Add `requiredPermission` to also
  enforce a permission (see [Permissions](https://nextlyhq.com/docs/plugins/permissions)).
- **Opt out:** set `public: true` to make a route callable without a session (e.g. a
  public sitemap or a webhook receiver). `ctx.user` will be `null`.

```ts
{
  method: "GET",
  path: "/sitemap.xml",
  public: true, // no auth — public derived data
  handler: async (_req, ctx) => {
    const xml = await buildSitemap(ctx.services); // use { as: "system" } inside
    return new Response(xml, { headers: { "content-type": "application/xml" } });
  },
}
```

Pair `public: true` with `{ as: "system" }` service calls only for genuinely public,
derived data. For user data, keep the route authenticated and call services with
`{ as: "user", user: ctx.user ?? undefined }`.

## Middleware (D27)

Routes support an ordered, typed middleware chain (onion model). Each middleware calls
`next()` to continue or returns a `Response` to short-circuit:

```ts
const timing: Middleware = async (req, ctx, next) => {
  const res = await next();
  res.headers.set("x-handler", "reports");
  return res;
};

// route: { method, path, middleware: [timing], handler }
```

See also: [Permissions](https://nextlyhq.com/docs/plugins/permissions) · [Data access](https://nextlyhq.com/docs/plugins/services).

---
title: Admin UI
description: Contribute admin menu items, pages, settings, and collection-view overrides from a plugin — and control where they appear in the sidebar.
url: https://nextlyhq.com/docs/plugins/admin-ui
---

A plugin can extend the Nextly admin in two complementary ways:

- **`contributes.admin`.** The *declarative* surface: menu entries, custom pages,
  a settings panel, and per-collection view overrides (D19–D23).
- **`admin`** (on the plugin definition) — *placement & appearance*: where the
  plugin's items sit in the sidebar and how they look (D20).

Both are `@public`. Admin **dashboard widgets** (`PluginAdminWidget`, D22) are rendered
on the admin dashboard today, but the contract remains
[`@experimental`](https://nextlyhq.com/docs/plugins/stability) while its shape settles.

## Component paths

Admin contributions reference React components by **string path**, not by import, so the
declarative surface stays serializable and Node-safe:

```
"<package>/<subpath>#<ExportName>"
// e.g. "@acme/nextly-plugin-reports/admin#ReportsView"
```

Register the components those paths resolve to from your plugin's `/admin` entry, which
runs inside the admin shell:

```ts
// src/admin/index.ts
import { registerComponents } from "@nextlyhq/plugin-sdk/admin";
import { ReportsView } from "./ReportsView";

registerComponents({
  "@acme/nextly-plugin-reports/admin#ReportsView": ReportsView,
});
```

Running `nextly generate:types` emits a `plugin-admin-imports.generated.ts` import map so
these load with no manual host wiring (D60).

## UI building blocks (`@nextlyhq/ui`)

Build your admin components out of the shared **plugin UI kit**, `@nextlyhq/ui` — the
semver-protected surface of React primitives the admin itself is built from (D68/D53).
The host provides it (and React) as a **peer dependency**, so you and the admin share one
version and one theme:

```tsx
// src/admin/ReportsView.tsx
import {
  Button,
  Input,
  Checkbox,
  Select,
  Card,
  Table,
  FormLabelWithTooltip,
} from "@nextlyhq/ui";
```

Which of these primitives are covered by a stability guarantee is recorded in
[`packages/ui/STABILITY.md`](https://github.com/nextlyhq/nextly/blob/main/packages/ui/STABILITY.md):
a component becomes `@public` once a first-party plugin depends on it, and everything
else is `@experimental` and may change in any release.

Register components and reference admin contribution types through
`@nextlyhq/plugin-sdk/admin`; import UI primitives from `@nextlyhq/ui`.

> **Never import from `@nextlyhq/admin`.** It is an application, not a published API —
> reaching into it (e.g. `@nextlyhq/admin/lib/*`) is unsupported and will break. If a
> primitive you need isn't yet exported from `@nextlyhq/ui`, open an issue so it can be
> promoted to the kit rather than copied.

## Styling your admin UI

The admin ships a single, precompiled, isolated stylesheet (every rule scoped under
`.nextly-admin`). Because it is built ahead of time, Tailwind cannot see utilities that
live only in your package — so there are three ways to style a plugin, in order of
preference:

**1. Compose from the kit.** `@nextlyhq/ui` components are already styled by the admin
sheet, so a plugin built from them needs no styling work at all. Reach for the layout
primitives for common structure:

```tsx
import { Card, Stack, Grid, Stat } from "@nextlyhq/plugin-sdk/admin";

<Card>
  <Stack gap={4}>
    <Grid cols={3} gap={4}>
      <Stat label="Submissions" value={1280} />
      <Stat label="This week" value={64} />
      <Stat label="Conversion" value="4.2%" />
    </Grid>
  </Stack>
</Card>;
```

**2. Use safelisted utility classes.** A curated, token-driven set of Tailwind utilities is
always present in the admin sheet, so you can use them directly in your components with no
build step: layout (`flex`, `grid`, `grid-cols-{1..6}`, `gap-{0..8}`, `items-*`,
`justify-*`), spacing (`p-*`, `m-*`, `space-*`), sizing (`w-*`, `max-w-*`, `size-*`),
typography (`text-{xs..2xl}`, `font-*`, `truncate`, `line-clamp-*`), token colors
(`bg-primary`, `text-muted-foreground`, `border-border`, …), and borders/radius/shadow.
These are **token-driven only** — no arbitrary values or raw colors, so your UI themes in
light and dark automatically.

**3. Ship your own CSS (`admin.styles`).** For anything beyond the safelist, compile a
scoped, token-driven stylesheet with the `nextly-build-admin-css` CLI (from
`@nextlyhq/admin-css`, add it as a devDependency) and declare it in your manifest.

Your CSS is compiled in **your** package, not by the host. That is deliberate: the admin
sheet is built when Nextly is released, so it can never scan a plugin that is installed
later, and pointing Tailwind at an installed package with `@source` is not a reliable
substitute — it does not accept package references, and it resolves inconsistently under
pnpm, which is what this repository and many plugin projects use. Compiling ahead of time
means your styles do not depend on the host's build at all.

```css
/* src/admin.css — author against the shared token preset */
@import "tailwindcss";
@import "@nextlyhq/ui/theme.css";
@source "./src";
```

```jsonc
// package.json
{ "scripts": { "build:css": "nextly-build-admin-css src/admin.css dist/admin.css" } }
```

```ts
// your plugin definition
contributes: { admin: { styles: "@acme/plugin/dist/admin.css" } }
```

Then side-effect-import the built file from your admin entry so the host app's bundler
loads it:

```ts
// src/admin/index.ts
import "../../dist/admin.css";
```

The CLI compiles your Tailwind, **scopes every rule under `.nextly-admin`**, and refuses to
emit if a rule would escape that wrapper or if it finds a hardcoded color — so your styles
can never leak into the host page and always theme correctly. Use `--nx-*` tokens (via
`var()` or the token utilities), never literal colors.

## Declarative contributions

```ts
contributes: {
  admin: {
    // Sidebar entries (D20). One level of children is supported.
    menu: [
      { label: "Reports", to: "/admin/plugins/reports", icon: "BarChart",
        order: 10, requiredPermission: "read-reports" },
    ],
    // Custom pages, namespaced under /admin/plugins/<slug>/<path>, RBAC-gated (D21).
    pages: [
      { path: "summary", component: "@acme/nextly-plugin-reports/admin#ReportsView",
        requiredPermission: "read-reports" },
    ],
    // A settings panel rendered at /admin/plugins/<slug> (D21).
    settings: { component: "@acme/nextly-plugin-reports/admin#ReportsSettings" },
    // Per-collection view overrides + injection points, keyed by slug (D23).
    views: {
      posts: {
        beforeList: "@acme/nextly-plugin-reports/admin#PostsBanner",
        edit: "@acme/nextly-plugin-reports/admin#PostsEditor",
      },
    },
  },
}
```

`menu`/`pages`/`widgets` honour `requiredPermission` for client-side gating (see
[Permissions](https://nextlyhq.com/docs/plugins/permissions)). View override slots are `list`, `edit`,
`beforeList`, `afterList`, `beforeEdit`, `afterEdit`.

## Dashboard widgets

A widget is drawn one of two ways, and you pick by what you declare.

### Let the host draw it

Declare an `archetype` and the `query` it is drawn from, and ship no UI code. The host
runs the query for the signed-in user and renders the card.

> **What the host draws today: `metric`, `list`, `table` and `actions`.**
> `text` is accepted by the contract but has no renderer yet, so a widget
> declaring it shows "the text archetype is not rendered yet" in its card unless
> it also ships a `component` to draw the body itself.
>
> A `list` widget draws one row per result. Its query's `select` decides what each
> row shows, in order: the first field is the row's label and the second, if there
> is one, is the muted line under it.
>
> A `table` widget draws a column per selected field, headed by that field's label
> from your collection — so a heading reads "Published at", not `publishedAt`. The
> columns come from what the SERVER returned, not from `select`: a field carrying
> an `access.read` rule that denies the viewer is absent from their rows, and its
> column and heading are absent with it.
>
> A `list` or `table` that selects nothing says so rather than guessing at a field,
> and says it without running a query.
>
> An `actions` widget is a short column of shortcuts, declared rather than
> queried:
>
> ```ts
> {
>   id: "acme/shortcuts",
>   title: "Shortcuts",
>   archetype: "actions",
>   defaultSize: "sm",
>   actions: [
>     { label: "New post", href: "/admin/collections/posts/create" },
>     { label: "Invite user", href: "/admin/users/create", requiredPermission: "create-users" },
>     { label: "Docs", href: "https://nextly.dev/docs", external: true },
>   ],
> }
> ```
>
> Each item is gated on its own `requiredPermission`: a reader who may not use a
> shortcut does not see it, while the card itself stays. That is separate from
> the widget's own `requiredPermission`, which decides whether the card appears
> at all. `external: true` opens the destination in a new tab and says so to a
> screen reader. A card shows at most six shortcuts and counts the rest.

```ts
contributes: {
  admin: {
    widgets: [
      {
        id: "reports-summary",
        title: "Published reports",
        archetype: "metric",                 // metric | table | list | text | actions
        defaultSize: "sm",                   // sm | md | lg | xl | full
        query: { source: "collection:reports", op: "count" },
        requiredPermission: "read-reports",  // client-gated
        defaultOrder: 40,                    // optional; lower sits higher
      },
    ],
  },
}
```

`text` and `actions` are drawn without data, so they take no `query` — declaring one is
a type error. Every other archetype requires it. (`actions` is drawn by the host; `text`
is not yet — see the note above.)

### Where a card sits

`defaultOrder` is optional and sorts ascending; a widget that omits it goes after every
widget that states one. Leave it off unless you mean it — without it your card keeps its
declaration order, which is what nearly every widget wants.

It exists because position would otherwise depend on **how** a widget reached the
dashboard rather than on anything it said: contributions resolve before registrations, so
the same card moved across the grid when its author switched channels. Core's own
dashboard cards state one, which is how they stay above contributed widgets.

Numbers, not indexes — core spaces its own ten apart so a card can be placed between two
without renumbering anything.

A reader's saved layout, once they have arranged their dashboard, wins over this. Think
of it as where the card starts, not where it stays.

### Widgets that draw their own surface

A `custom` widget may set `chrome: "none"` to decline the card frame entirely, and is
then responsible for everything the card would have provided — its heading, its loading
and error states, its own visual boundary.

Reach for it only when your component **is** already a designed surface, such as a
titled section with its own rules. Framing one of those draws a second heading above its
own. If your component draws a body and expects a title around it, leave `chrome` alone.

It is refused on every other archetype, because core composes those bodies **into** the
card — the card owns the title, the footer and the busy state — so an unframed one would
render with no heading and nothing reporting that it was loading.

One consequence worth knowing: an unframed component that renders nothing costs no space
at all. The grid collapses a cell whose widget drew nothing, so a card that hides itself
when it has nothing to say leaves no gap behind.

<Callout type="info">
  `core#` is reserved. Core's own dashboard cards resolve their components under that
  prefix, and the admin refuses to let anything else register or unregister one — a
  plugin claiming the path would replace the body drawn for a card the registry still
  attributes to core.
</Callout>

### Draw it yourself

Ship a `component` and the host gives you the card's frame — header, footer, loading and
error states — while you draw the body:

```ts
contributes: {
  admin: {
    widgets: [
      {
        id: "reports-chart",
        component: "@acme/nextly-plugin-reports/admin#ChartWidget",
        size: "half",                        // "full" | "half"
        requiredPermission: "read-reports",  // client-gated
      },
    ],
  },
}
```

A component-drawn widget may ALSO declare a `query`: the host runs it in the same batch
and hands your component the result, so you do not fetch it again.

Your component receives five props, and you can name their types:

```ts
import type { WidgetComponentProps } from "@nextlyhq/plugin-sdk/widgets";

export function ChartWidget({ slot, isFetching }: WidgetComponentProps) {
  // `slot` is undefined in TWO cases, and `isFetching` tells them apart:
  // the first request is still running, or this widget declared no query.
  if (!slot) return isFetching ? <Skeleton /> : null;
  if (!slot.ok) return <p>{slot.error}</p>;
  if (slot.result.op !== "list") return null;
  return <Chart rows={slot.result.items} busy={isFetching} />;
}
```

| Prop | Type | What it is |
|---|---|---|
| `widgetId` | `string` | The id you registered the widget under. |
| `placementId` | `string` | The **card's** id. One widget may sit on a dashboard twice, and everything belonging to a card — its settings and its answer — is keyed by this, not by `widgetId`. |
| `settings` | `Record<string, unknown>` | This card's settings, already resolved: the reader's stored values where they are usable, your declared defaults everywhere else. |
| `slot` | `WidgetSlot \| undefined` | This card's answer. `undefined` means either that the first request is still in flight **or** that the widget declared no query — see below. |
| `isFetching` | `boolean` | Whether this card's query is in flight, the first request included. Always `false` for a widget with no query. |

An absent `slot` has two causes and they need different UI: `isFetching` is `true` only
for a card whose query is in the batch, so `slot === undefined && isFetching` is the
first load — draw a skeleton — while `slot === undefined && !isFetching` means no answer
is ever coming. Treating them alike draws an empty state over a running request.

`slot` is a discriminated union — `{ ok: true, result }` or `{ ok: false, error }` — so
narrowing on `slot.ok` gives you a typed `result`. A failing query is a value, not a
thrown error: the batch answers with every other widget's data intact, so one query
failing colours one card rather than blanking the dashboard.

These types come from `@nextlyhq/plugin-sdk/widgets`, which carries no runtime code —
importing them adds nothing to your bundle.

Widgets are rendered on the admin dashboard by `WidgetGrid`, in a 12-column grid that
collapses to one column on small screens, and are hidden from users who lack
`requiredPermission`. Every widget on the page is fetched in a single batched request.

An archetype this version of Nextly does not draw reports itself in that card and leaves
the rest of the dashboard alone — whether it is one of the four above or a name from a
newer core this admin has never heard of. A plugin ahead of its host degrades one card
rather than breaking the admin.

The contract is still `@experimental` and is expected to grow: charts, and richer
archetypes. Per-widget settings and saved layouts have since shipped — a widget declares
`settings`, the reader edits them per card, and your component is handed the resolved
values. Pin your Nextly version while it settles.

`requiredPermission` gates whether the widget renders. It does **not** constrain the data
your widget reads — fetch through the access-controlled API so a viewer only ever sees
rows they may read.

Everything else on this page is `@public` today.

## Placement & appearance

The plugin's own `admin` field controls where its items live (D20):

```ts
import { definePlugin } from "@nextlyhq/plugin-sdk";

definePlugin({
  name: "@acme/nextly-plugin-reports",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  // ...
  admin: {
    placement: "collections", // collections | singles | users | settings | plugins | standalone
    order: 10, // lower = higher; default 100
    after: "collections", // anchor for standalone icons
  },
});
```

Placement defaults to `plugins`. `standalone` gives the plugin its own top-level icon,
anchored after the section named by `after`.

The value is written out rather than read from the `AdminPlacement` constant, which ships
from `nextly` and not from `@nextlyhq/plugin-sdk`. The SDK is the only surface a plugin
should depend on, so reaching into core for a constant would tie your plugin to core's
layout for the sake of one string. A host config, which already imports from `nextly`,
can use the constant, and does so below.

## Host overrides (D49)

An integrator can override a plugin's placement without forking it, via
`defineConfig({ admin: { pluginOverrides } })` — keyed by plugin name:

```ts
// nextly.config.ts
import { AdminPlacement, defineConfig } from "nextly";
import { reports } from "@acme/nextly-plugin-reports";

export default defineConfig({
  plugins: [reports()],
  admin: {
    pluginOverrides: {
      "@acme/nextly-plugin-reports": {
        placement: AdminPlacement.SETTINGS, // move it
        order: 5,
        after: "users",
        appearance: { label: "Analytics" }, // shallow-merged
      },
    },
  },
});
```

The override wins over the plugin's own `admin` config, so operators stay in control of
their sidebar.

See also: [Permissions](https://nextlyhq.com/docs/plugins/permissions) · [Author guide](https://nextlyhq.com/docs/plugins/author-guide).

---
title: Schema & data lifecycle
description: Contribute collections, extend existing entities (including Builder-made ones), relate across the merged schema, and clean up safely on uninstall.
url: https://nextlyhq.com/docs/plugins/schema
---

A plugin's schema contributions flow through the **same unified merge pipeline** as your
app's own code-first schema and the Visual Schema Builder's schema (D3). The host can read them
*without running your plugin*, so the admin and codegen can reason about them.

## Contribute new entities

```ts
import { defineCollection, text, select } from "nextly";
import { definePlugin } from "@nextlyhq/plugin-sdk";

const Redirects = defineCollection({
  slug: "redirects",
  fields: [
    text({ name: "fromPath", required: true }),
    text({ name: "toPath", required: true }),
    select({
      name: "type",
      options: [
        { label: "301 (Permanent)", value: "permanent" },
        { label: "302 (Temporary)", value: "temporary" },
      ],
      defaultValue: "permanent",
    }),
  ],
});

definePlugin({
  name: "@acme/nextly-plugin-redirects",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  // ...
  contributes: {
    collections: [Redirects], // also: singles, fieldGroups
  },
});
```

CRUD permissions are auto-seeded per contributed collection/single. The collection is
tagged with your plugin's [provenance](#provenance) and locked from Builder editing
(it's plugin-managed).

## Extend existing entities

`contributes.extend` adds fields to an entity you don't own, by slug (D12):

```ts
contributes: {
  extend: [
    {
      target: "posts",
      fields: [text({ name: "metaTitle" }), text({ name: "metaDescription" })],
    },
    // target can be an array to extend several at once
  ],
}
```

As of the Builder schema lane (P8), `extend` may target a **Builder-made collection**,
not just a code-first one — the extra fields materialize (a migration adds the columns)
and are present at runtime. The added fields are attributed to your plugin in provenance,
so they're cleaned up if your plugin is removed.

> Extending an entity that doesn't exist in the merged schema is a **fail-fast boot
> error** — see the [error reference](https://nextlyhq.com/docs/plugins/error-reference).

## Migrations & databases

A plugin doesn't write SQL or manage tables itself — it **declares** schema through
`contributes`, and the host materializes it through the normal Nextly migration workflow:

```bash
nextly migrate        # generate + apply migrations for the merged schema (incl. plugins)
```

When a consuming app adds your plugin (or you change your contributed schema) and runs
`nextly migrate`, the plugin's collections and `extend` fields are folded into the merged
schema and turned into migrations alongside the app's own. The same plugin works across
Nextly's supported databases (PostgreSQL, MySQL, SQLite) because it goes through the
managed pipeline rather than dialect-specific SQL — **but** SQLite doesn't enforce some
constraints that Postgres/MySQL do, so test against a real database too (see
[Testing](https://nextlyhq.com/docs/plugins/testing)).

> Schema changes are applied on `migrate`, not silently at boot — first boot only
> **creates** missing tables; it never **alters** an existing one. Ship schema changes as
> migrations so existing installs pick them up.

## Relate across the merged schema

A plugin relationship (`relationship(...)`) may target **any** slug in the merged schema
— core (`users`, `media`), another plugin's collection, an app collection, or a
Builder-made one (D15). Targets are validated at boot; an unknown `relationTo` fails
fast.

## Reference your own slugs via `ctx.self`

Never hardcode your own collection slugs in `init`/handlers — an integrator can rename
them with `plugin.rename({...})` (D54). Read the resolved slug from `ctx.self`:

```ts
const slug = ctx.self.collections.redirects; // resolved, post-rename
await ctx.services.collections.listEntries(slug, {}, { as: "system" });
```

## Provenance (D14)

Every schema entity carries a `source`: `"code"`, `"ui"` (Builder), `"built-in"`, or
`"plugin:<name>"`. This is what makes uninstall safe — Nextly knows which tables, fields,
and permissions belong to which plugin, and never touches the user's own (`code`/`ui`)
data.

## Uninstalling & data cleanup

When you remove a plugin from `defineConfig({ plugins })`, its contributed tables become
**orphans** — present in the database, but no longer claimed by any registered plugin.
Nextly does **not** auto-drop them (your data is never deleted behind your back). Use the
`prune` CLI to review and remove them:

```bash
nextly prune           # dry run — lists orphaned plugin:* tables/columns/permissions
nextly prune --force   # actually drops them (and their data + seeded permissions)
```

`prune` only ever targets `plugin:<name>` provenance. Code-first (`code`) and
Builder (`ui`) entities are **always retained** — they're yours, not the plugin's. This
is why declaring everything through `contributes` (rather than hand-writing tables via
`ctx.db`) matters: it's what lets uninstall be clean and reversible.

> **Tip for plugin authors:** anything you create through `contributes` /
> `ctx.services` is provenance-tagged and pruned automatically. Anything you create by
> reaching into `ctx.db` (raw DDL, side tables) is **not** tracked and will be left
> behind on uninstall — document it, or avoid it.

See also: [Data access](https://nextlyhq.com/docs/plugins/services) · [Testing](https://nextlyhq.com/docs/plugins/testing).

---
title: Testing your plugin
description: Integration-test a plugin against a real Nextly instance with createTestNextly — and why you should add at least one real-database test.
url: https://nextlyhq.com/docs/plugins/testing
---

`createTestNextly` (from `@nextlyhq/plugin-sdk/testing`) boots a **real** Nextly on
in-memory SQLite and runs your plugin's full lifecycle — `contributes → setup → init` —
so you can integration-test behaviour, not mocks (D46). It's `@public`.

## Basic shape

```ts
import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
import { myPlugin } from "../src";

const t = await createTestNextly({
  plugins: [myPlugin()],
  collections: myPlugin().contributes.collections, // register the plugin's schema
});

// drive the instance:
await t.nextly /* CRUD facade */;
t.hooks;   // assert hook registration/execution
t.events;  // assert emissions (call settle() to flush best-effort events)
t.adapter; // raw DB inspection

await t.destroy(); // runs your plugin's destroy() + resets singletons
```

Always `await t.destroy()` in teardown — it exercises your `destroy()` (catching
leaked subscriptions) and resets the global registries so tests don't bleed into each
other.

## What to assert

- **Schema:** your contributed collections/fields exist; `extend` added the fields it
  should; CRUD permissions were seeded.
- **Behaviour:** hooks fire and can modify/abort; events emit after commit (use
  `await t.events.settle()` before asserting, since events are best-effort).
- **Routes & permissions:** a route requires the right permission; `{ as: "system" }`
  vs `{ as: "user" }` calls behave as expected.
- **Uninstall:** removing the plugin orphans its tables and `nextly prune` would drop
  only `plugin:*` provenance (see [Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema)).

## Add at least one real-database test

The in-memory SQLite harness is fast and great for logic, but **SQLite does not enforce
several dialect-specific constraints** that Postgres and MySQL do (column length,
stricter typing, some FK behaviours). A bug can pass every SQLite test and still fail on
a real database.

> **Real-world example:** a `varchar(20)` column held provenance values like
> `plugin:@acme/nextly-plugin-name` (well over 20 chars). SQLite silently accepted it;
> Postgres rejected it with `22001 value too long`. It passed CI and broke on first
> deploy.

So: for anything that writes typed or system-metadata columns, add **at least one
Postgres-backed integration test** in addition to the SQLite ones. Point
`createTestNextly`'s adapter at a throwaway Postgres database (or run the test in CI
against a Postgres service container) and exercise the write path on a **clean** schema —
a polluted/drifted dev database can mask migration-diff bugs.

Also use **realistic scoped plugin names** in fixtures (`@acme/nextly-plugin-thing`, not
`@t/x`) so length/constraint problems surface.

See also: [Author guide](https://nextlyhq.com/docs/plugins/author-guide) · [Schema & data lifecycle](https://nextlyhq.com/docs/plugins/schema).

---
title: API stability
description: What's stable vs experimental in the plugin API, the semver guarantee that backs it, and the deprecation policy.
url: https://nextlyhq.com/docs/plugins/stability
---

`@nextlyhq/plugin-sdk` **is** the stability boundary for the plugin platform (D40/D43).
Every export carries a TSDoc release tag — `@public`, `@experimental`, or `@deprecated`
— and the authoritative ledger lives in the SDK's
[`STABILITY.md`](https://github.com/nextlyhq/nextly/blob/main/packages/plugin-sdk/STABILITY.md).
This page summarizes it.

## How a surface becomes stable

Nextly uses a **stability ladder** (D55): nothing is declared stable on paper. A surface
graduates from `@experimental` to `@public` only once **a first-party plugin has
exercised it in production** (against a real database, not just the SQLite test harness).
`ctx.services` is the highest-scrutiny surface and was held experimental the longest
(D56). The public surface is kept deliberately small (D40).

## The semver guarantee

The `@public` surface is the **semver-protected contract**. Once Nextly reaches `1.0`,
**breaking a `@public` export requires a major version bump** (D40). During the current
`0.x` alpha it is *stable-in-intent*: changes follow the deprecation policy below rather
than landing as silent breaks — but **pin your versions** while we're pre-`1.0`.
`@experimental` exports carry **no** compatibility guarantee.

## Stable (`@public`)

- `definePlugin`, `PluginDefinition`, `PluginContributions`, `PluginContext`
- Lifecycle: `setup` / `init` / `destroy`
- Schema: `contributes.collections` / `extend` (+ singles/components)
- Permissions: `PluginPermission`, `PermissionSlug`, `AuthUser`
- Data access: `ctx.services` (incl. `{ as: "system" }`), `QueryOptions`,
  `PaginatedResult`, `BatchOperationResult`, `ServiceOpts`
- HTTP routes: `PluginRoute`, `PluginRouteContext`, `PluginRouteHandler`,
  `Middleware`, `RouteMethod`
- Events: `EventBus`, `EventEnvelope`, `EventHandler`, `EventName`,
  `DocumentEvents` / `AuthEvents` / `MediaEvents`
- Collection/field hook context: `HookContext`
- Admin: `contributes.admin` menu/pages/views, `ComponentPath`, the
  `@nextlyhq/plugin-sdk/admin` registration helpers
- Testing: `@nextlyhq/plugin-sdk/testing` (`createTestNextly`)

## Still `@experimental`

These ship today but carry no guarantee yet — use them, but expect change:

- The raw `ctx.db` escape hatch (D56 — prefer `ctx.services`)
- `ctx.hooks` plugin registration (`PluginHookRegistry`, `HookType`, `HookHandler`)
- Filters & actions (D63): `ctx.filters` / `ctx.actions` + seam types
- Secrets (D37): `secret`, `Secret`, `isSecret`
- Client UX (`@nextlyhq/plugin-sdk/client`): `useCan`, `<Can>`
- Admin dashboard widgets (`PluginAdminWidget`, D22 — rendered; shape still settling)
- `contributes.events`, `dependsOn` / `optionalDependsOn`, `plugin.rename` (D54)

Each graduates once a first-party plugin exercises it.

## Deprecation policy (D41)

When a `@public` export must change incompatibly:

1. It's marked `@deprecated` with the replacement and removal version.
2. A one-time runtime warning is emitted at first use where practical.
3. It's kept for **≥ 1 major version** (the support window).
4. A migration guide ships before removal.

Promotion (`@experimental` → `@public`) is **not** a breaking change.

## Out of scope for v1

Per D0/D42/D34, v1 is **npm-trust**: no marketplace, no UI-install, no runtime sandbox or
verification. Discovery is npm + these docs + the `nextly-plugin` keyword — see
[Publishing & distribution](https://nextlyhq.com/docs/plugins/distribution). These are deferred, not
cancelled.

---
title: Publishing & distribution
description: How to publish a Nextly plugin, how plugins are discovered, and the trust model behind v1.
url: https://nextlyhq.com/docs/plugins/distribution
---

Nextly plugins are plain npm packages, registered in code (D0). There is **no
marketplace, no UI-install, and no runtime sandbox in v1** — distribution and trust ride
entirely on npm.

## Publish

1. **Build** with `tsup` to ESM `dist/` (first-party plugins are ESM-only — see the note
   below).
2. **Set package metadata:**
   - `"type": "module"` and an `exports` map (include `./admin` if you ship admin
     components, like the scaffold does).
   - `"files": ["dist"]` so the embedded `dev/` playground never publishes.
   - Add the **`nextly-plugin`** keyword (this is how plugins are discovered, D42).
   - List `nextly` (and `@nextlyhq/admin`/`react` if you have admin UI) as
     **peerDependencies**, and declare a `nextly` core-compatibility range in your
     `definePlugin` (e.g. `"^1 || ^2"`, boot-checked, D6).
3. `npm publish`.

```jsonc
// package.json (essentials)
{
  "type": "module",
  "keywords": ["nextly-plugin"],
  "files": ["dist"],
  "exports": {
    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.mjs" },
    "./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.mjs" }
  },
  "peerDependencies": { "nextly": "^1" }
}
```

> **ESM-only:** first-party plugins ship ESM only. CommonJS tooling importing them gets
> `ERR_PACKAGE_PATH_NOT_EXPORTED`. Either keep your consuming tooling ESM, or ship a
> dual (ESM+CJS) build if you must support CJS consumers.

## Configuration & secrets

Plugin options are passed where the plugin is registered
(`defineConfig({ plugins: [myPlugin({ ... })] })`). For sensitive values, read from the
environment and wrap them with `secret()` (D37) so they auto-redact in logs, JSON, and
inspection — the real value is only available via `.reveal()`:

```ts
import { secret } from "@nextlyhq/plugin-sdk";
myPlugin({ apiKey: secret(process.env.ACME_API_KEY) });
```

`secret()` is currently [`@experimental`](https://nextlyhq.com/docs/plugins/stability). Never hard-code
secrets in config or commit them.

## Discovery (D42)

In v1, plugins are found through:

- **npm.** Search the **`nextly-plugin`** keyword.
- **The Nextly docs.** First-party and notable community plugins are listed on the
  [plugins index](https://nextlyhq.com/docs/plugins). To get a community plugin listed, see
  [Contributing a plugin](https://nextlyhq.com/docs/plugins/contributing).
- **GitHub.** The `nextly-plugin` topic.

There is intentionally no in-app gallery or one-click install yet.

## Trust model (D34)

v1 is **full-trust**: a plugin runs with the same access as your application code. There
is **no sandbox and no verification gate** — installing a plugin is exactly as much a
trust decision as adding any npm dependency. Vet plugins the way you vet dependencies:
read the source, check the maintainer, pin versions.

Sandboxing, verification, and a curated marketplace are **deferred to a post-v1
milestone** — they're designed-for, not shipped. Until then, trust is npm trust, stated
honestly.

See also: [API stability](https://nextlyhq.com/docs/plugins/stability) · [Contributing a plugin](https://nextlyhq.com/docs/plugins/contributing).

---
title: Contributing a plugin
description: Publish your own Nextly plugin, get it listed, and the quality checklist every plugin should pass — plus how to contribute a plugin to the Nextly repo.
url: https://nextlyhq.com/docs/plugins/contributing
---

There are two ways to contribute to the Nextly plugin ecosystem: **publish your own**
plugin to npm, or **contribute a plugin to the Nextly monorepo**. Both start from the
same scaffold and quality bar.

## Publish your own plugin

1. **Scaffold** it:

   ```bash
   npm create nextly-app -- --template plugin
   ```

   This generates a publishable package (`src/` → `dist/`) plus an embedded `dev/`
   playground — a minimal Nextly app on SQLite with hot-reload — for iterating locally.

2. **Build it** against the SDK (`@nextlyhq/plugin-sdk`) and iterate in the `dev/`
   playground (`pnpm dev` → open `/admin`). See the
   [author guide](https://nextlyhq.com/docs/plugins/author-guide).

3. **Test it** — including at least one real-database test (see
   [Testing](https://nextlyhq.com/docs/plugins/testing)).

4. **Publish** to npm with the `nextly-plugin` keyword and an honest `nextly`
   compatibility range (see [Publishing & distribution](https://nextlyhq.com/docs/plugins/distribution)).

That's it — there's no marketplace submission or approval gate in v1. Trust is npm trust
(D34).

## Get your plugin listed

The [plugins index](https://nextlyhq.com/docs/plugins) carries a curated list of community plugins. To add
yours, open a PR against the Nextly repo that adds a row to the community-plugins table on
that page, with: package name, one-line description, npm link, source link, and the
`nextly` range it supports. We review for the quality checklist below (not for feature
scope) — it's a curated docs list, not a gatekept marketplace.

## Plugin quality checklist

A good Nextly plugin:

- [ ] **Exports clean TypeScript types** and builds to ESM `dist/` (`"type": "module"`,
      `exports` map, `"files": ["dist"]`).
- [ ] **Has the `nextly-plugin` keyword** and declares a `nextly` range in
      `definePlugin` (`peerDependencies` for `nextly`/`@nextlyhq/admin`/`react`).
- [ ] **Declares, never grants, permissions** (define-but-never-grant, D36) and gates
      routes/UI with `requiredPermission`.
- [ ] **Uses `ctx.services`, not raw `ctx.db`**, so its data is managed, secure, and
      prunable — and picks `{ as: "system" }` vs `{ as: "user" }` deliberately.
- [ ] **Contributes schema through `contributes`** (not hand-rolled DDL) so provenance
      tracking and `nextly prune` clean it up on uninstall (D14).
- [ ] **References its own slugs via `ctx.self`**, never hard-coded (survives
      `plugin.rename`).
- [ ] **Reads secrets from env** and wraps them with `secret()` (D37) — never hard-coded.
- [ ] **Has a README** with install, usage, an options table, and any required host
      wiring (e.g. a Next.js rewrite or middleware).
- [ ] **Is tested** with `createTestNextly`, including a real-Postgres test for anything
      writing typed/system columns.
- [ ] **Cleans up in `destroy()`** (subscriptions, timers) so HMR/teardown is leak-free.

## Contribute a plugin to the Nextly repo

First-party plugins live in `packages/plugin-<name>/` and follow the same structure as
`plugin-form-builder` (`src/`, `__tests__/`,
`tsup.config.ts`, `README.md`). To contribute one:

- Read the repo's root `CONTRIBUTING.md` for dev setup (`pnpm install`, env, the dev
  loop) and conventions.
- Use **conventional commits**, scoped to the plugin (e.g.
  `feat(plugin-foo): add lookup route`).
- Add unit **and** integration tests; first-party plugins are the exercisers that
  graduate API surfaces from `@experimental` to `@public` (see
  [API stability](https://nextlyhq.com/docs/plugins/stability)), so cover the surfaces you rely on.
- Don't add a changeset on a feature branch — releases are cut separately.

See also: [Author guide](https://nextlyhq.com/docs/plugins/author-guide) ·
[Publishing & distribution](https://nextlyhq.com/docs/plugins/distribution).

---
title: Plugin API Reference
description: The public plugin surface re-exported by @nextlyhq/plugin-sdk.
url: https://nextlyhq.com/docs/plugins/api-reference
---

> **Alpha (`0.x`) — pin your versions.** `@nextlyhq/plugin-sdk` **is** the stability boundary — if it isn't exported there, it isn't public. Most of this surface is now `@public` (semver-protected); some is still `@experimental`. See [API stability](https://nextlyhq.com/docs/plugins/stability) for the exact ledger.

## Entry points

| Import | Surface | React? |
|---|---|---|
| `@nextlyhq/plugin-sdk` | `definePlugin`, `contributes`/`ctx`/hook/event/filter types, `PermissionSlug`/`EventName`, `secret()` | no |
| `@nextlyhq/plugin-sdk/testing` | `createTestNextly` | no |
| `@nextlyhq/plugin-sdk/client` | `useCan`, `<Can>` | yes (optional peer) |
| `@nextlyhq/plugin-sdk/admin` | `registerComponent`, `registerComponents`, `registerKnownPlugin` | yes (optional peer) |
| `@nextlyhq/plugin-sdk/routing` | `slugToStaticParam` | no |
| `@nextlyhq/plugin-sdk/widgets` | `WidgetComponentProps`, `WidgetSlot`, `WidgetResult`, `WidgetResultField`, `WidgetQueryBatchResponse` — types only, no runtime | no |

## `definePlugin(def): PluginDefinition`

```ts
interface PluginDefinition {
  name: string;
  version: string;
  nextly: string;                              // core-compat range (boot-checked, may span majors)
  dependsOn?: Record<string, string>;          // required deps → version range
  optionalDependsOn?: Record<string, string>;  // enhance-if-present
  enabled?: boolean;                           // default true; false = skip behavior, keep schema
  contributes?: PluginContributions;
  setup?:   (config: NextlyConfig) => NextlyConfig;   // all setups before any init
  init?:    (ctx: PluginContext) => void | Promise<void>;
  destroy?: (ctx: PluginContext) => void | Promise<void>;
  rename?:  (map: Record<string, string>) => PluginDefinition;  // integrator-side remap (D54)
}
```

## `PluginContributions`

```ts
interface PluginContributions {
  collections?: CollectionConfig[];
  singles?:     SingleConfig[];
  fieldGroups?: FieldGroupConfig[];
  extend?:      Array<{ target: string | string[]; fields: FieldConfig[] }>;
  permissions?: PluginPermission[];            // { action, resource, label?, description?, group? }
  fieldTypes?:  PluginFieldType[];             // custom field types — see below
  events?:      Array<{ name: string }>;
  routes?:      PluginRoute[];                 // { method, path, handler, requiredPermission?, public?, middleware? }
  admin?: {
    menu?:     PluginMenuItem[];               // { label, to, icon?, order?, requiredPermission?, children? }
    pages?:    PluginAdminPage[];              // { path, component, requiredPermission? }
    settings?: { component: ComponentPath };
    views?:    Record<string, PluginCollectionView>; // list/edit/before*/after* by collection slug
    widgets?:  PluginAdminWidget[];             // rendered on the dashboard; @experimental
  };
}
```

Component references are string paths: `"<package>/<path>#<Export>"`, e.g. `"@acme/x/admin#ReportsPage"`.

## `PluginContext` (`ctx`)

```ts
interface PluginContext {
  services: NextlyServices;       // managed, secure-by-default; .collections supports { as: 'user' | 'system' }
  db: DatabaseInstance;           // raw Drizzle escape hatch (unmanaged)
  hooks: PluginHookRegistry;      // in-transaction, modify/abort
  events: EventBus;               // post-commit, observe-only, best-effort
  filters: PluginFilterRegistry;  // transform values on typed seams (D63)
  actions: PluginActionRegistry;  // ordered side-effects on typed seams (D63)
  self: { name: string; collections: Record<string,string>; singles: Record<string,string> }; // resolved slugs (D54)
  config: Readonly<NextlyConfig>;
  logger: Logger;
  nextlyVersion: string;
}
```

### Secure-by-default services (D35)

```ts
// Acts as the current user (RBAC enforced):
await ctx.services.collections.listEntries(slug, {}, { as: "user", user: ctx.user });
// Privileged work — explicit, visible elevation:
const { item, warnings } = await ctx.services.collections.createEntry(slug, data, { as: "system" });
```

Writes (`createEntry`, `updateEntry`, `deleteEntry`) resolve to the same
`{ message, item, warnings? }` envelope the Direct API and the REST API return.
`warnings` is present only when a post-commit hook failed: the row is already
saved at that point, so the write succeeds and the failure travels beside it.
Reads are unchanged and return their value directly.

## Hooks & events

```ts
ctx.hooks.on(type, collectionSlug | "*", handler);   // beforeCreate/afterCreate/… — can modify/abort
ctx.events.on(eventName, handler);                   // observe-only; e.g. `collection.${slug}.created`
ctx.events.emit(eventName, payload);                 // declare custom names in contributes.events
```

Event-name constants are exported: `DocumentEvents`, `AuthEvents`, `MediaEvents`.

## Typed slugs (codegen)

`CollectionSlug`, `SingleSlug`, `PermissionSlug`, and `EventName` are `string` by default and **narrow to the installed unions** once `nextly generate:types` runs. Author code stays valid either way.

## Client (`/client`)

```ts
useCan(permission: string): boolean;
const Can: React.FC<{ permission: string; fallback?: ReactNode; children: ReactNode }>;
```

## Admin registration (`/admin`)

```ts
registerComponent(path, Component);
registerComponents({ [path]: Component });
registerKnownPlugin(packagePrefix, async () => { /* register */ });
```

When you run `nextly generate:types`, a `plugin-admin-imports.generated.ts` is emitted that calls `registerComponents` for you — import it once in the app and your `contributes.admin` components load with no manual wiring.

## Testing (`/testing`)

```ts
createTestNextly(opts: {
  plugins: PluginDefinition[];
  collections?: CollectionConfig[];
  dialect?: "sqlite" | "postgresql" | "mysql";  // default sqlite (in-memory)
  serverUrl?: string;                           // else TEST_POSTGRES_URL / TEST_MYSQL_URL
}): Promise<{ nextly; getService; hooks; events; adapter; destroy }>;

getConfiguredTestDialects(): TestDialect[];  // sqlite, plus any whose server URL is set
```

## Custom field types (`contributes.fieldTypes`)

A plugin can add a field type. It persists as one of the existing storage
primitives — the plugin never invents DDL — and renders through its own admin
component.

```ts
interface PluginFieldType {
  type: string;                    // field.type value, e.g. "rating". Must not collide with a built-in
  storage: FieldStoragePrimitive;  // text | longText | boolean | number | timestamp | json
  component: ComponentPath;        // "<package>/<path>#<Export>"
  label?: string;                  // picker label; defaults to a title-cased `type`
  description?: string;
  icon?: string;                   // Lucide icon name
  category?: FieldTypeCategory;    // picker grouping; defaults to "Advanced"
  surfaces?: FieldSurface[];       // where it may be offered; defaults to entries/singles only
  layout?: "takeover";
  validate?: (value, args) => true | string | PluginFieldIssue[] | Promise<…>;  // see below
  validateOptions?: (field) => true | string | PluginFieldIssue[];              // see below
}
```

### `validate` — the type's own rules

Without it a custom type is only ever checked as its storage primitive: a
`json`-backed type would accept any JSON at all. Declare the rules on the type
and every instance gets them, rather than each schema author remembering to
repeat a field-level `validate`.

```ts
fieldTypes: [
  {
    type: "rating",
    storage: "number",
    component: "@acme/ratings/admin#RatingInput",
    validate(value, { field }) {
      // Already a number: the `number` primitive's rules ran first.
      if (typeof value !== "number" || !Number.isInteger(value)) {
        return "Rating must be a whole number";
      }
      const max = typeof field.max === "number" ? field.max : 5;
      if (value > max) return `Rating cannot exceed ${max}`;
      return true;
    },
  },
]
```

`args` carries:

| Key | What it is |
|---|---|
| `data` | The write payload, for rules spanning fields. On update this is the patch, not the merged stored entry. Always the top-level payload, even for a field nested in a repeater row. |
| `req` | Request context; carries `user` when authenticated. Empty for a field inside a field group instance. |
| `field` | The instance, so you can read the options your type declares. A detached copy: records, arrays, dates, sets and maps are rebuilt, so editing them changes nothing. Functions and class instances stay shared — treat it as read-only. |
| `path` | Where this field sits in the write (`"stars"`, `"rows[1].stars"`). |
| `mode` | `"create"` or `"update"`. |

Return `true` to accept, a string for one problem, or an array when one value
can be wrong in several places at once. Issue paths are used as given, so build
them from `args.path` or they will be wrong for a nested instance:

```ts
return [
  { path: `${path}.nodes[2]`, code: "DISALLOWED", message: "That block is not allowed here" },
  { message: "Document exceeds the node limit" },   // path/code default to the field's own
];
```

Ordering: the built-in rules for your `storage` primitive run first, then this,
then the field's own `validate` — so a schema author adds rules on top of yours
rather than replacing them. Two values never reach `validate`: an absent one
(that is what `required` is for) and one the storage primitive already refused,
so you never have to re-check that you were handed the shape your type stores.
For `json` that check is representability — a cycle or a `BigInt` is rejected
before you see it — and nothing more, so the shape of the document is yours to
define.

Anything you return outside `true | string | PluginFieldIssue[]` is a refusal,
as is throwing — a validator that forgets to return fails the write rather than
silently accepting everything.

**Where it runs.** The entry, single, and field group write paths. A type offered
on the `users`, `forms`, or `blocks` surface does **not** run it yet: those
surfaces validate through their own paths. A disabled plugin keeps its field
types registered (its collections are retained) but its `validate` does not
run — that is behavior, and a disabled plugin contributes none.

### `validateOptions` — rules about the declaration

`validate` answers "is this value allowed in this field". `validateOptions`
answers "is this field declared coherently at all". It runs when a schema is
registered, not when a value is written.

The distinction matters because a schema defect reported per write is reported
to the wrong person: the writer cannot fix it, and it fails every write until
whoever declared the field notices.

```ts
validateOptions(field) {
  const policy = field.policy;
  if (policy === undefined) return true;
  if (policy === null || typeof policy !== "object") {
    return [{ path: "policy", message: "policy must be an object" }];
  }
  const { kinds } = policy as { kinds?: unknown };
  if (Array.isArray(kinds) && kinds.length === 0) {
    // Nothing could ever be stored in this field. That is a contradiction in
    // the declaration, not a problem with any particular value.
    return [{ path: "policy.kinds", message: "policy.kinds cannot be empty" }];
  }
  return true;
}
```

Synchronous on purpose: a declaration is checked against itself, and a
config-time rule that needed I/O would make startup depend on something that can
be down. Issue paths are **relative** and get appended to the field's own, so
`"policy.kinds"` reports against `fields[2].policy.kinds` — unlike `validate`,
whose paths are absolute, because this one only ever names an option it already
knows and has no way to learn its own index. Throwing is a rejected declaration,
not a crash. A returned `code` is **not** carried: config errors report through
closed, public code unions, so the canonical member is used and your message
carries the detail.

**Where it runs.** Every path a declaration reaches storage by:

| Path | When |
|---|---|
| boot | over the resolved config and a plugin's own raw contributions, once the registry is populated |
| `db:sync` and its watcher | before anything is serialized or materialized |
| Schema Builder writes | before the payload is stored, and again before the manifest is written |
| direct collection/single/field-group create and update | before the definition is persisted and its DDL runs |
| `nextly build` | over collections, singles and field groups |
| `migrate:create` | over the merged set the migration is generated from |
| HMR reload | after the reload repopulates the registry |

**Not** the `define*` calls, despite their being where a code-first config is
validated. The config bundle is evaluated before `contributes.fieldTypes` is
registered, so a custom type is not yet known at that point and the define call
rejects it as an unknown field type before any option check could run. Do not
reach for `defineCollection` to get your declaration checked — that ordering is
why every gate above sits after registration.

Your check always sees the declaration **as written**. On the Builder path that
is the submitted payload, not the parsed copy: the manifest schema drops keys it
does not declare, while the write persists the original, so your options are
present in what gets stored and absent from what was parsed.

A disabled plugin runs neither hook. Its field types stay registered, because its
collections are retained and their fields still have to map to a column and
render, but `validate` and `validateOptions` are both dropped at registration —
they are behavior, and a disabled plugin contributes none.

**Where your options live.** An option written directly on the field is read as
written, and that is the ergonomic choice while its name differs from every key
the field schema declares — `options`, `fields`, `admin`, `label` and the rest of
the built-in field surface. The manifest applies the built-in shape to every
field whatever its type, so a name that does collide is judged against the core
meaning (`options` as a select's choice array) and rejected before your check
runs.

For a name core already uses, or to be safe against names core may add later,
put the option in the `pluginOptions` container. Core never looks inside it, so
any name is legal there:

```json
{
  "name": "rating",
  "type": "star-rating",
  "pluginOptions": { "options": { "presets": ["a", "b"] } }
}
```

Both are read, and your type is handed **one flat view** either way, so
`field.options` above resolves to your object without your having to know where
it was stored. The container wins when the same name appears in both. Writes
from the Schema Builder go to the container, so a field stored the older way
moves there the next time it is saved; nothing you read changes when it does.

Two names are reserved inside the container: **`type` and `name`**. The instance
you are handed states which field it is under those keys, restated after your
options are folded in, so an option using either would be shadowed and never
reach you. A manifest write declaring one is refused rather than silently
losing it.

Fields nested in a `repeater` or `group` are covered. A type offered only on the
`users`, `forms`, or `blocks` surface is **not**: those surfaces have their own
config validators, which do not consult this registry.

**Declaring one on the `users` surface from code.** `UserFieldConfig` is a union
of the built-in field shapes, so a `select` missing its `options` fails on its
own shape. A plugin type's token is not knowable there, and an arm open enough
to accept it would accept that malformed `select` too and lose the error. Wrap
the declaration in `pluginUserField()` instead, which marks it as belonging to
the open arm:

```ts
import { defineConfig, pluginUserField } from "nextly";

export default defineConfig({
  users: {
    fields: [
      { name: "company", type: "text" },
      pluginUserField({ name: "score", type: "star-rating" }),
    ],
  },
});
```

Options are optional there: pass `pluginOptions`, write them directly on the
field, or pass none at all. Note that these options reach type generation but
are not persisted, so a field read back from the database after boot carries
none of them.

## Secrets

```ts
secret(value): Secret<T>;   // auto-redacts in logs / JSON / inspect; .reveal() to read
isSecret(v): boolean;
```

See the [author guide](https://nextlyhq.com/docs/plugins/author-guide) for the full workflow and the [error reference](https://nextlyhq.com/docs/plugins/error-reference) for boot-error meanings.

---
title: Plugin Error Reference
description: The fail-fast boot errors a plugin can trigger — what each means and how to fix it.
url: https://nextlyhq.com/docs/plugins/error-reference
---

> **Alpha (`0.x`) — pin your versions.** The plugin API surface is now [stable](https://nextlyhq.com/docs/plugins/stability); the packages are still alpha.

Nextly validates plugins **fail-fast at boot** (D7): a bad plugin config stops startup with a specific error rather than failing later in unclear ways. Each error is a `NextlyError` with a stable `code`; the specific cause is in `logContext.reason`. (The user-facing `message` is generic — assert on `code` / `logContext.reason` in tests.)

## Resolution

| Code | Status | Cause | Fix |
|---|---|---|---|
| `PLUGIN_RESOLUTION_ERROR` | 500 | A `dependsOn` is missing, a dependency cycle exists, or a `nextly`/dependency version range is incompatible with what's installed. `logContext.reason` ∈ `missing-dependency`, `dependency-cycle`, `invalid-nextly-range`, `core-incompatible`, `version-incompatible`, `optional-version-incompatible`. | Install/declare the missing dependency, break the cycle, or widen/correct the version range. |

## Schema

| Code | Status | Cause | Fix |
|---|---|---|---|
| `NEXTLY_SCHEMA_SLUG_COLLISION` | 409 | Two sources (a plugin and code/another plugin) contribute the same collection/single/component slug. | Rename one entity, or have the integrator `.rename()` the plugin's slug. |
| `NEXTLY_SCHEMA_RELATION_TARGET_MISSING` | 400 | A `relationTo` points at a slug that isn't in the merged schema. | Point the relationship at an existing slug (core `users`/`media` are always valid). |
| `NEXTLY_SCHEMA_EXTEND_TARGET_UNKNOWN` | 400 | `contributes.extend` targets a slug that doesn't exist in the merged schema (e.g. a Builder-only entity during the code-first gap). | Target an existing code/plugin entity, or declare a `dependsOn` on the plugin that owns it. |
| `NEXTLY_SCHEMA_EXTEND_FIELD_DUPLICATE` | 409 | `contributes.extend` adds a field name already present on the target. | Use a different field name (configurable field names resolve collisions). |
| `NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION` | 409 | A plugin relates to (or extends with a relation into) another plugin's entity without declaring `dependsOn` on it. | Add the other plugin to `dependsOn`. |
| `NEXTLY_SCHEMA_RENAME_UNKNOWN_TARGET` | 400 | `.rename({ from: to })` names a `from` slug the plugin doesn't contribute. | Rename only slugs the plugin actually declares. |

## Permissions

| Code | Status | Cause | Fix |
|---|---|---|---|
| `NEXTLY_PERMISSION_COLLISION` | 409 | A custom permission duplicates another, targets a reserved system resource, or reuses an auto-seeded CRUD `(action, resource)`. `logContext.reason` ∈ `duplicate-permission`, `system-resource-reserved`, `crud-permission-reserved`. | Choose a unique `(action, resource)`; don't redeclare CRUD permissions (they're auto-seeded). |

## Routes

| Code | Status | Cause | Fix |
|---|---|---|---|
| `NEXTLY_ROUTE_COLLISION` | 409 | Two routes share the same `(method, full path)` after namespacing under `/api/plugins/<name>`. | Give each route a distinct method/path. |
| `NEXTLY_ROUTE_INVALID_PATH` | 400 | A route `path` does not start with `/`. | Start the path with `/` (e.g. `/export`). |

## Inspecting plugins

Use the CLI to see what's installed and detect issues without booting the app:

```bash
nextly plugins list                 # table of plugins + contributions
nextly plugins info <name>          # one plugin's details
```

A resolution error surfaces here too (the commands run the same validation).

---
title: Form Builder
description: Create and manage dynamic forms with a visual drag-and-drop builder, submission tracking, email notifications, spam protection, webhooks, and data export.
url: https://nextlyhq.com/docs/plugins/form-builder
---

> **Alpha (`0.x`) — pin your versions.**
>
> The plugin API surface is now **stable and semver-protected** (see [API stability](https://nextlyhq.com/docs/plugins/stability)); the plugin packages themselves are still `0.x` alpha, so pin your versions and read the release notes before upgrading.

The Form Builder plugin adds a complete form management system to Nextly. Build forms visually in the admin panel or define them in code, collect submissions, send email notifications, and protect against spam -- all without writing custom endpoints.

## Installation

```bash
npm install @nextlyhq/plugin-form-builder
```

The plugin requires these peer dependencies (already present in most Nextly projects):

- `nextly` >= 0.0.13
- `@nextlyhq/admin` >= 0.0.13
- `react` ^18 or ^19
- `next` ^14, ^15, or ^16

## Basic Setup

```typescript
// nextly.config.ts
import { defineConfig } from 'nextly';
import { formBuilder } from '@nextlyhq/plugin-form-builder';

const fb = formBuilder();

export default defineConfig({
  plugins: [fb.plugin],
  collections: [Posts, Users, Media],
});
```

This creates two collections automatically:

| Collection | Default Slug | Purpose |
|------------|-------------|---------|
| Forms | `forms` | Stores form definitions (fields, settings, notifications) |
| Submissions | `form-submissions` | Stores submitted data with status tracking |

Both collections appear in the admin sidebar under the **Forms** group.

## Configuration Options

Pass an options object to `formBuilder()` to customize behavior.

```typescript
// nextly.config.ts
const fb = formBuilder({
  // Customize collection slugs and labels
  formOverrides: {
    slug: 'contact-forms',
    labels: { singular: 'Contact Form', plural: 'Contact Forms' },
  },
  formSubmissionOverrides: {
    slug: 'responses',
    labels: { singular: 'Response', plural: 'Responses' },
  },

  // Enable/disable specific field types
  fields: {
    file: false,      // Disable file uploads
    hidden: false,    // Disable hidden fields
  },

  // Email notifications
  notifications: {
    defaultFrom: 'noreply@example.com',
    defaultToEmail: 'submissions@example.com',
    enabled: true,
  },

  // Spam protection
  spamProtection: {
    honeypot: true,
    rateLimit: {
      maxSubmissions: 10,
      windowMs: 60_000,
    },
  },

  // File upload limits
  uploads: {
    maxFileSize: 10_485_760, // 10 MB
    allowedMimeTypes: ['image/*', 'application/pdf', 'text/*'],
    uploadCollection: 'media',
  },

  // Feature flags
  features: {
    builder: true,
    conditionalLogic: true,
    fileUploads: true,
  },

  // Collections that can serve as redirect targets after submission
  redirectRelationships: ['pages'],
});
```

### Collection Overrides

You can add custom fields to the Forms or Submissions collections, or restrict access control.

**Array style** -- appends fields to the defaults:

```typescript
formOverrides: {
  fields: [
    text({ name: 'internalNotes', label: 'Internal Notes' }),
  ],
  access: {
    read: () => true,
    create: ({ user }) => !!user,
  },
}
```

**Function style** -- full control over the field list:

```typescript
formSubmissionOverrides: {
  fields: ({ defaultFields }) => {
    const formIndex = defaultFields.findIndex(f => f.name === 'form');
    return [
      ...defaultFields.slice(0, formIndex + 1),
      { name: 'source', type: 'text' },
      ...defaultFields.slice(formIndex + 1),
    ];
  },
}
```

## Field Types

All 13 field types are enabled by default. Set any to `false` in the `fields` option to remove it from the builder.

| Type | Description | Key Options |
|------|-------------|-------------|
| `text` | Single-line text input | `minLength`, `maxLength`, `pattern` |
| `email` | Email address with format validation | `pattern` |
| `number` | Numeric input | `min`, `max`, `step` |
| `phone` | Phone number input | `pattern` |
| `url` | URL with format validation | `pattern` |
| `textarea` | Multi-line text input | `rows`, `minLength`, `maxLength` |
| `select` | Dropdown menu | `options`, `allowMultiple` |
| `checkbox` | Single boolean toggle | `defaultValue` |
| `radio` | Radio button group | `options` |
| `file` | File upload | `accept`, `multiple`, `maxFileSize` |
| `date` | Date picker | `min`, `max` |
| `time` | Time picker | `defaultValue` (HH:mm format) |
| `hidden` | Hidden value (not shown to users) | `defaultValue` |

Every field supports these common properties: `name`, `label`, `placeholder`, `helpText`, `defaultValue`, `required`, `validation`, `conditionalLogic`, and `admin.width` (25% to 100%).

## Creating Forms

### Visual form builder (admin UI)

Navigate to **Forms** in the admin sidebar and click **Create New**. The form builder provides:

- **Field Library** -- click or drag field types to add them to the form
- **Form Canvas** -- reorder fields with drag-and-drop, click to edit
- **Field Editor** -- configure each field's label, validation, placeholder, help text, and conditional logic
- **Settings Tab** -- submit button text, confirmation type (message or redirect), multiple submission settings
- **Notifications Tab** -- configure email integrations per form
- **Preview** -- see how the form will look to end users

Forms have three statuses:
- **Draft** -- not accepting submissions (use for building)
- **Published** -- live and accepting submissions
- **Closed** -- shows a configurable closed message

### Code-First Definitions

Use the field helper functions to define forms programmatically. These helpers set the `type` property automatically.

```typescript
import {
  text,
  email,
  textarea,
  select,
  checkbox,
  option,
} from '@nextlyhq/plugin-form-builder';

const contactFields = [
  text({ name: 'firstName', label: 'First Name', required: true }),
  text({ name: 'lastName', label: 'Last Name', required: true }),
  email({ name: 'email', label: 'Email Address', required: true }),
  select({
    name: 'subject',
    label: 'Subject',
    required: true,
    options: [
      option('General Inquiry'),
      option('Support Request'),
      option('Feedback'),
    ],
  }),
  textarea({
    name: 'message',
    label: 'Message',
    required: true,
    rows: 5,
    validation: { minLength: 10, maxLength: 2000 },
  }),
  checkbox({ name: 'subscribe', label: 'Subscribe to our newsletter' }),
];
```

The `option()` helper converts labels to slug values automatically (`'General Inquiry'` becomes `'general_inquiry'`). Pass a second argument for an explicit value: `option('United States', 'us')`.

Additional field helpers: `number()`, `phone()`, `url()`, `radio()`, `file()`, `date()`, `time()`, `hidden()`.

### Utility Functions

Create a complete form config with defaults applied in one call:

```typescript
import { createFormConfig } from '@nextlyhq/plugin-form-builder';

const contactForm = createFormConfig('contact', contactFields, {
  settings: {
    submitButtonText: 'Send Message',
    confirmationType: 'message',
    successMessage: 'Thanks! We will get back to you within 24 hours.',
  },
});
```

Validate a form config before saving:

```typescript
import { validateFormConfig, assertValidFormConfig } from '@nextlyhq/plugin-form-builder';

const result = validateFormConfig(contactForm);
if (!result.valid) {
  console.error(result.errors);
}

// Or throw on invalid config
assertValidFormConfig(contactForm);
```

## Form Submissions

The handlers below take a `{ pluginContext, pluginConfig }` context. `pluginContext` is the `ctx` your code already receives from the plugin system -- for example a [plugin route handler](https://nextlyhq.com/docs/plugins/routes)'s `(req, ctx) => ...`, or your own plugin's `init(ctx)`. `pluginConfig` is the object `formBuilder()` returned: keep the result and use `fb.config`. Note that `getFormBuilderConfig(ctx)` is **not** an alternative from another plugin's context — the resolved config is written onto the form-builder's own context during its `init`, and `initializePlugins` gives every plugin a separate one, so that call returns `undefined` anywhere else.

### Handling Submissions

Use the `submitForm` handler to process submissions server-side. It runs the full pipeline: fetch form, validate data, check spam, store submission, and determine redirect.

```typescript
import { submitForm } from '@nextlyhq/plugin-form-builder';
import type { PluginContext } from '@nextlyhq/plugin-sdk';
import type { ResolvedFormBuilderConfig } from '@nextlyhq/plugin-form-builder';

declare const request: Request;
declare const pluginContext: PluginContext;
declare const pluginConfig: ResolvedFormBuilderConfig;

const result = await submitForm(
  {
    formSlug: 'contact',
    data: { firstName: 'Jane', email: 'jane@example.com', message: 'Hello!' },
    metadata: {
      // No ipAddress here on purpose: see "Where the IP has to come from"
      // below. Reading `x-forwarded-for` straight off the request is the one
      // thing not to do.
      userAgent: request.headers.get('user-agent') || undefined,
    },
  },
  { pluginContext, pluginConfig }
);

if (result.success) {
  if (result.redirect) {
    // Redirect the user
  }
  // result.submission contains the stored document
} else {
  // result.error and result.validationErrors describe what went wrong
}
```

### Where the IP has to come from

`submitForm` keys two protections on `metadata.ipAddress`: the per-IP rate limit,
and the one-submission-per-visitor check when `allowMultipleSubmissions` is off. It
also stores the value on the submission.

That makes the header a control input, not a log field. `x-forwarded-for` is
client-supplied on a direct request and on any proxy that forwards it verbatim, so
a bot that varies it on every request gets a fresh rate-limit bucket each time and
walks past a limit that looks configured. Nextly closed exactly this in its own
auth and rate-limit paths, which is why `getTrustedClientIp` exists:

```ts
// nextly.config.ts, or anywhere the application itself runs
import { getTrustedClientIp, parseTrustedProxyIpsEnv } from "nextly";

declare const request: Request;
declare const trustProxy: boolean;

const ipAddress =
  getTrustedClientIp(request, {
    trustProxy,
    trustedProxyIps: parseTrustedProxyIpsEnv(process.env.TRUSTED_PROXY_IPS),
  }) ?? undefined;
```

It walks the forwarded chain from the right, skipping hops in `TRUSTED_PROXY_IPS`,
and returns the first one you did not vouch for. It returns `null` when it cannot
identify a client, and passing `undefined` on is the correct thing to do with that:
the limiter skips a submission it cannot attribute rather than filing every unknown
caller in one bucket.

Two consequences worth stating plainly. `security.trustProxy` defaults to `false`,
so until you set it and list your proxies the resolver returns `null` and the rate
limit does not run. And `getTrustedClientIp` ships from `nextly`, not from
`@nextlyhq/plugin-sdk`, so a distributed plugin cannot reach it through the surface
it is supposed to depend on. An application that hosts its own route, as below, can.

### Validation

The plugin generates [Zod](https://zod.dev) schemas from form field definitions at runtime. Every submission is validated against the schema before storage. Free-text fields are also sanitized by stripping HTML tags to prevent injection.

You can validate data without creating a submission:

```typescript
import { validateSubmission } from '@nextlyhq/plugin-form-builder';
import type { PluginContext } from '@nextlyhq/plugin-sdk';
import type { ResolvedFormBuilderConfig } from '@nextlyhq/plugin-form-builder';

declare const pluginContext: PluginContext;
declare const pluginConfig: ResolvedFormBuilderConfig;

const { valid, errors } = await validateSubmission(
  'contact',
  { firstName: 'Jane', email: 'not-an-email' },
  { pluginContext, pluginConfig }
);
```

### Submission Status

Each submission tracks its review state:

| Status | Description |
|--------|-------------|
| `new` | Unread submission |
| `read` | Reviewed by an admin |
| `archived` | Archived (hidden from default views) |

Admins can also add internal notes to any submission -- these are not visible to the original submitter.

### Statistics

```typescript
import { getFormSubmissionStats } from '@nextlyhq/plugin-form-builder';
import type { PluginContext } from '@nextlyhq/plugin-sdk';
import type { ResolvedFormBuilderConfig } from '@nextlyhq/plugin-form-builder';

declare const pluginContext: PluginContext;
declare const pluginConfig: ResolvedFormBuilderConfig;

const stats = await getFormSubmissionStats('contact', { pluginContext, pluginConfig });
// { total: 42, new: 5, read: 30, archived: 7 }
```

## Email Notifications

Notifications are configured per form in the admin UI under the **Notifications** tab. Each notification integration specifies:

| Setting | Description |
|---------|-------------|
| `templateSlug` | Email template to use (from your [email configuration](https://nextlyhq.com/docs/guides/email)) |
| `recipientType` | `"static"` (fixed email) or `"field"` (value from a form field) |
| `to` | Email address, or `{{fieldName}}` reference when using field recipient |
| `providerId` | Email provider to use (optional, falls back to system default) |
| `cc` / `bcc` | Additional recipients |

Template variables available in your email templates: all submitted field values, plus `formName` and `submissionId`.

### beforeEmail Hook

Modify or filter outgoing emails before they are sent:

```typescript
const fb = formBuilder({
  beforeEmail: async ({ emails, form, submission }) => {
    return emails.map(email => ({
      ...email,
      bcc: ['archive@example.com'],
    }));
  },
});
```

## Spam Protection

Three layers of protection are available, all enabled by default (except reCAPTCHA).

### Honeypot Fields

Hidden form fields that bots fill in automatically. When a honeypot field contains a value, the submission is silently rejected -- the bot receives a fake success response to avoid revealing the detection.

Standard honeypot field names checked: `__honeypot`, `_honeypot`, `honeypot`, `__hp`, `_hp`, `website`, `url_field`, `fax_number`.

### Rate Limiting

Limits submissions per IP address and form within a time window. Defaults to 10 submissions per 60 seconds per IP.

```typescript
spamProtection: {
  rateLimit: {
    maxSubmissions: 5,
    windowMs: 120_000, // 2 minutes
  },
}
```

The rate limit store is in-memory. For multi-instance deployments, consider using a shared store (Redis) or adjusting thresholds.

### reCAPTCHA v3

Configuration is available for Google reCAPTCHA v3. Set the site key and secret key globally or per form.

```typescript
spamProtection: {
  recaptcha: {
    enabled: true,
    siteKey: 'your-site-key',
    secretKey: 'your-secret-key',
    scoreThreshold: 0.5,
  },
}
```

## Conditional Logic

Fields can be shown or hidden based on the values of other fields. Configure conditional logic on any field through the admin UI or in code.

```typescript
import { text, select, option } from '@nextlyhq/plugin-form-builder';

const fields = [
  select({
    name: 'contactMethod',
    label: 'Preferred Contact Method',
    options: [option('Email'), option('Phone')],
  }),
  text({
    name: 'phoneNumber',
    label: 'Phone Number',
    conditionalLogic: {
      enabled: true,
      action: 'show',
      operator: 'AND',
      conditions: [
        { field: 'contactMethod', comparison: 'equals', value: 'phone' },
      ],
    },
  }),
];
```

Supported comparison operators: `equals`, `notEquals`, `contains`, `isEmpty`, `isNotEmpty`, `greaterThan`, `lessThan`.

Multiple conditions can be combined with `AND` (all must match) or `OR` (any must match). The `action` property determines whether matching conditions **show** or **hide** the field.

## Webhooks

Forms support webhook integrations that fire on submission events. Webhooks are asynchronous -- they do not block the submission response. Failed webhooks are logged but do not cause submission failures.

```typescript
// In a form's notification config
webhooks: [
  {
    url: 'https://api.example.com/webhooks/form-submissions',
    events: ['submission.created'],
    secret: 'your-webhook-secret',
    includeData: true,
  },
  {
    url: 'https://crm.example.com/api/leads',
    events: ['submission.created', 'submission.updated'],
    headers: { 'X-API-Key': 'abc123' },
    method: 'POST',
  },
]
```

Supported events: `submission.created`, `submission.updated`, `submission.deleted`.

When a `secret` is configured, the request includes an `X-Webhook-Signature` header with an HMAC-SHA256 signature (`sha256=<hex>`). Verify it on the receiving end:

```typescript
// app/api/form-webhook/route.ts
import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  // Fail closed on a missing secret. Defaulting to "" still produces a valid
  // HMAC, and it is one anybody can compute, so the endpoint would authenticate
  // every forged request instead of none.
  const secret = process.env.FORM_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("Webhook secret is not configured", { status: 500 });
  }

  // The RAW body, read once. Signing a re-serialised object instead compares a
  // signature against bytes the sender never sent: `JSON.parse` then
  // `JSON.stringify` is free to reorder keys and drop whitespace, so a correct
  // signature fails whenever the two disagree.
  const raw = await request.text();
  const expected = `sha256=${createHmac("sha256", secret).update(raw).digest("hex")}`;
  const sent = request.headers.get("x-webhook-signature") ?? "";

  // Lengths first: `timingSafeEqual` throws on a mismatch, which turns a forged
  // signature into a 500 rather than a rejection.
  const a = Buffer.from(sent);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload: unknown = JSON.parse(raw);
  // ... handle the verified payload

  return Response.json({ received: true });
}
```

## Exporting Submissions

Export submissions to CSV or JSON from code or the admin UI. The examples below assume you already have `form` (a `FormDocument`) and `submissions` (a `SubmissionDocument[]`) -- for example, from `ctx.services.collections` in a plugin route or hook.

### CSV Export

```typescript
import { exportToCSV, downloadFile, generateExportFilename } from '@nextlyhq/plugin-form-builder';
import type { FormDocument, SubmissionDocument } from '@nextlyhq/plugin-form-builder';

declare const form: FormDocument;
declare const submissions: SubmissionDocument[];

const csv = exportToCSV(submissions, form, {
  includeMetadata: true,
  delimiter: ',',
  includeBOM: true,       // Excel compatibility
  dateFormat: 'iso',
});

// Browser download
const filename = generateExportFilename('contact', 'csv');
// "contact-submissions-2026-03-20.csv"
downloadFile(csv, filename, 'text/csv;charset=utf-8');
```

### JSON Export

```typescript
import { exportToJSON } from '@nextlyhq/plugin-form-builder';
import type { FormDocument, SubmissionDocument } from '@nextlyhq/plugin-form-builder';

declare const form: FormDocument;
declare const submissions: SubmissionDocument[];

const json = exportToJSON(submissions, form, {
  includeMetadata: true,
  includeFormDefinition: true,
  indent: 2,
});
```

### One-Step Export

```typescript
import { exportAndDownload } from '@nextlyhq/plugin-form-builder';
import type { FormDocument, SubmissionDocument } from '@nextlyhq/plugin-form-builder';

declare const form: FormDocument;
declare const submissions: SubmissionDocument[];

// In a React component
const handleExport = (format: 'csv' | 'json') => {
  exportAndDownload(submissions, form, format);
};
```

## Example: Contact Form

A complete contact form setup from config to submission handling.

**1. Configure the plugin:**

```typescript
// nextly.config.ts
import { defineConfig } from 'nextly';
import { formBuilder } from '@nextlyhq/plugin-form-builder';

const fb = formBuilder({
  notifications: {
    defaultFrom: 'noreply@mysite.com',
  },
  spamProtection: {
    honeypot: true,
    rateLimit: { maxSubmissions: 5, windowMs: 60_000 },
  },
});

export default defineConfig({
  plugins: [fb.plugin],
  collections: [Posts, Users, Media],
});
```

**2. Define the form fields (code-first):**

```typescript
import {
  text, email, textarea, select, checkbox, option, hidden,
  createFormConfig,
} from '@nextlyhq/plugin-form-builder';

const contactForm = createFormConfig('contact', [
  text({ name: 'name', label: 'Full Name', required: true }),
  email({ name: 'email', label: 'Email', required: true }),
  select({
    name: 'subject',
    label: 'Subject',
    required: true,
    options: [
      option('General Inquiry'),
      option('Support'),
      option('Partnership'),
    ],
  }),
  textarea({
    name: 'message',
    label: 'Message',
    required: true,
    rows: 5,
    validation: { maxLength: 5000 },
  }),
  checkbox({ name: 'newsletter', label: 'Subscribe to updates' }),
  hidden({ name: 'source', label: 'Source', defaultValue: 'website' }),
]);
```

`createFormConfig` builds the definition and stops there. Nothing in the plugin accepts
a `FormConfig`: `formBuilder()` takes no `forms` option, and `submitForm` resolves a slug
by querying the **forms collection**, so a form exists at submission time only as a row in
that collection. Create the `contact` form in the admin under Forms before going further,
or seed the row yourself; a submission to a slug with no row is answered as a form that
does not exist, before validation or storage. Closing that gap is tracked as
`createFormConfig` having no path to a row.

**3. Handle submissions in an API route:**

`submitForm` takes two context values: `pluginContext`, which is a plugin's `ctx`, and
`pluginConfig`, which is the resolved form-builder config. Both are reachable from your
own config file. A route contributed through [`contributes.routes`](https://nextlyhq.com/docs/plugins/routes)
is handed the `ctx` as its second argument, and `formBuilder()` returns its resolved
config as `fb.config`, which is why step 1 keeps the return value rather than inlining it.

So the endpoint is a small plugin of your own, declared beside the form-builder in
`nextly.config.ts`:

```ts
// nextly.config.ts
import {
  defineConfig,
  getTrustedClientIp,
  parseTrustedProxyIpsEnv,
} from "nextly";
import { definePlugin } from "@nextlyhq/plugin-sdk";
import { formBuilder, submitForm } from "@nextlyhq/plugin-form-builder";

const fb = formBuilder({
  notifications: { defaultFrom: "noreply@mysite.com" },
  spamProtection: {
    honeypot: true,
    rateLimit: { maxSubmissions: 5, windowMs: 60_000 },
  },
});

const contactEndpoint = definePlugin({
  name: "@acme/contact-endpoint",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  contributes: {
    routes: [
      {
        method: "POST",
        path: "/contact",
        // A visitor has no session, so the route opts out of auth. What stops
        // abuse is `submitForm` itself: the honeypot and rate limit configured
        // above run on every call, and a route that skipped it would skip them.
        public: true,
        handler: async (request, ctx) => {
          const data = await request.json();

          // Through the trust-proxy gate, never straight off the header: this
          // value keys the rate limit above, so a forgeable one hands a bot a
          // fresh bucket per request. `null` becomes `undefined`, which the
          // limiter reads as "cannot attribute" and skips.
          const ipAddress =
            getTrustedClientIp(request, {
              trustProxy: ctx.config.security?.trustProxy ?? false,
              trustedProxyIps: parseTrustedProxyIpsEnv(
                process.env.TRUSTED_PROXY_IPS
              ),
            }) ?? undefined;

          const result = await submitForm(
            {
              formSlug: "contact",
              data,
              metadata: {
                ipAddress,
                userAgent: request.headers.get("user-agent") ?? undefined,
              },
            },
            { pluginContext: ctx, pluginConfig: fb.config }
          );

          return Response.json(result);
        },
      },
    ],
  },
});

export default defineConfig({
  plugins: [fb.plugin, contactEndpoint],
  // collections: [...] as in step 1
});
```

The route is mounted under the contributing plugin's namespace, so the form posts to
`/api/plugins/@acme/contact-endpoint/contact`.

## Next Steps

- [Plugins Overview](https://nextlyhq.com/docs/plugins) -- how the plugin system works and how to create custom plugins
- [Email Configuration](https://nextlyhq.com/docs/guides/email) -- set up email providers and templates for form notifications
- [Collections](https://nextlyhq.com/docs/configuration/collections) -- understand how plugin collections work alongside your own

---
title: Webhooks
description: Tell another system when your content changes, with signed payloads and retries you can inspect.
url: https://nextlyhq.com/docs/webhooks
---

A webhook is an HTTP call Nextly makes when something happens to your content — a post is
published, a page is deleted — so another system can react without polling.

## Availability

| | |
|---|---|
| Built in | No plugin required |
| Admin | A **Webhooks** section for endpoints, secrets and delivery history |
| Permission | Managing endpoints is governed by `create-webhooks`, `update-webhooks` and `delete-webhooks` grants |

## Endpoints

An endpoint is a URL plus a filter describing which events it wants. Registering everything
to one URL works, but filtering per endpoint means a receiver is not woken for events it
will ignore.

## Signing

Every delivery is signed so the receiver can prove it came from you and was not modified.

Nextly follows [Standard Webhooks](https://www.standardwebhooks.com/). A secret is shown to
you as `whsec_` followed by base64 key material, and **the key is the decoded bytes, not the
string you were shown**:

```
key           = base64_decode(secret without its "whsec_" prefix)
signedContent = "<id>.<timestamp>.<rawBody>"
signature     = base64(HMAC_SHA256(key, signedContent))
```

The `webhook-signature` header carries versioned tokens shaped `v1,<signature>`. During a
secret rotation a delivery is signed with **every** active secret, and the tokens are joined
by **spaces**:

```
webhook-signature: v1,<sigA> v1,<sigB>
```

So verification is: **check the timestamp is recent, then** split the header on whitespace,
split each token on its comma, and accept if any token matches.

The freshness check is not optional. Signing the timestamp proves it was not altered; it does
not make the delivery expire. Nextly's own `verifySignature` rejects anything outside a
**300-second (5 minute)** tolerance *before* it compares signatures, and a receiver that skips
that step will accept a captured request forever.

<Callout type="warn">
Three ways to reject every authentic delivery, in the order people hit them: using the
`whsec_...` string as the HMAC key instead of its decoded bytes; comparing against the whole
header without stripping `v1,`; and splitting only on commas, which folds the next token into
the first signature and breaks the moment you rotate a secret.

And one way to accept an inauthentic one: matching the HMAC but never checking the timestamp,
which leaves you replayable indefinitely.

A Standard Webhooks verifier library does all four correctly. Prefer one over hand-rolling
this.
</Callout>

Three headers travel with each delivery:

| Header | Holds |
|---|---|
| `webhook-id` | The delivery's id, and part of the signed content |
| `webhook-timestamp` | When it was signed, also part of the signed content |
| `webhook-signature` | The signature itself |

Because the timestamp is signed, a captured payload cannot be replayed later under its
original signature.

Verify against the **raw body**, before any JSON parsing. Re-serializing first changes the
bytes and the signature will not match — the usual reason a correct implementation appears
to fail.

## Delivery, retries and the outbox

An event is written to a durable **outbox** in the same transaction as the content change,
and delivered from there. So a webhook cannot be lost because the process died between
saving a document and making the HTTP call, and it cannot fire for a change that was
rolled back.

Delivery is then retried on a schedule:

| | |
|---|---|
| Attempts | 6 by default |
| First retry | 30 seconds |
| Longest delay | 1 hour |

A `2xx` response counts as delivered. A `429` or any `5xx` is retried. Other `4xx`
responses are not retried, because a receiver rejecting the request as malformed will
reject it again.

## Delivery history

Deliveries are recorded so you can see what was sent, what came back and how many attempts
it took. That history is trimmed on a schedule — see
[retention](https://nextlyhq.com/docs/webhooks/retention).

## Related

- [Retention](https://nextlyhq.com/docs/webhooks/retention) — how long delivery history is kept
- [Background jobs](https://nextlyhq.com/docs/jobs) — work that runs outside the request
- [ISR caching](https://nextlyhq.com/docs/guides/isr-caching) — updating your own pages on a change

---
title: Webhook queue retention & VACUUM
description: How Nextly prunes the webhook event ledger and delivery log, plus Postgres autovacuum tuning and SQLite VACUUM guidance for the nextly_events and nextly_webhook_deliveries tables.
url: https://nextlyhq.com/docs/webhooks/retention
---

Nextly records outbound webhook activity in two high-churn tables:

- **`nextly_events`.** The event ledger (the outbox). A content change writes a row here **only when recording is active**: an enabled webhook endpoint exists, or the `webhooks.audit` seam is on. An install with no enabled endpoint and audit off records nothing, so the table does not grow.
- **`nextly_webhook_deliveries`.** **One row per (endpoint, event)**, carrying the retry state. Each retry is appended to that row's in-row attempt log, not added as a new row, so more matching endpoints add rows while retries enlarge existing ones.

When recording is active these tables fill continuously and are pruned automatically. This page explains the retention policy, the manual `nextly webhooks:prune` command, and how to keep the underlying tables from bloating on Postgres and SQLite.

## How retention works

Retention runs **opportunistically on content writes** and as part of the delivery **drain** — you do not need to schedule anything for it to work. Each pass deletes:

- **Terminal deliveries** (`delivered` / `failed`) older than `deliveriesMaxAgeMs`.
- **Events** older than `eventsMaxAgeMs`, once they have been fanned out and no delivery still references them. (A separate window governs audit-class events, and is never shorter than this one — see the note below the table.)

Passes are bounded so a single write never turns into an unbounded delete.

### Configuration

Set `webhooks.retention` in `nextly.config.ts`. Every field is optional; the defaults suit most installs.

```ts
import { defineConfig } from "nextly/config";

export default defineConfig({
  webhooks: {
    retention: {
      eventsMaxAgeMs: 30 * 24 * 60 * 60 * 1000, // webhook events — default 30 days
      auditEventsMaxAgeMs: 90 * 24 * 60 * 60 * 1000, // audit events — default 90 days
      deliveriesMaxAgeMs: 7 * 24 * 60 * 60 * 1000, // terminal deliveries — default 7 days
      intervalMs: 60 * 60 * 1000, // min gap between AUTOMATIC passes — default 1 hour
      batchSize: 500, // rows per delete batch — default 500
      maxBatchesPerRun: 20, // batches per pass — default 20
    },
  },
});
```

| Field | Default | Meaning |
|---|---|---|
| `eventsMaxAgeMs` | 30 days | Age after which a fanned-out `webhook`-class event is prunable. `false` keeps events forever. |
| `auditEventsMaxAgeMs` | 90 days | Age for `audit`-class events. `false` keeps them forever. Raised to `eventsMaxAgeMs` if that is longer — see the note below. |
| `deliveriesMaxAgeMs` | 7 days | Age after which a `delivered`/`failed` delivery row is prunable. `false` keeps them forever. |
| `intervalMs` | 1 hour | Minimum gap between **automatic** retention passes (the opportunistic and drain-driven ones). Does not affect `nextly webhooks:prune`, which always runs a pass when invoked. |
| `batchSize` | 500 | Rows deleted per batch (capped at 900). |
| `maxBatchesPerRun` | 20 | Batches per pass, so one write never triggers an unbounded delete. |

**On the audit class:** an event's class follows from why it was recorded. A write admitted only because a webhook endpoint exists is `webhook`-class and pruned on `eventsMaxAgeMs`. A write admitted by the audit seam — `webhooks.audit`, which records events whether or not anything is subscribed — is `audit`-class and pruned on `auditEventsMaxAgeMs`. A write that is both takes the audit window, because that is the longest retention the row needs and evicting it on the delivery schedule would lose history nothing can reconstruct.

Because of that promise, `auditEventsMaxAgeMs` is **raised to `eventsMaxAgeMs` whenever the webhook window is longer** (including `false`, which means forever). Configuring a shorter audit window than webhook window would otherwise prune a dual-purpose row earlier than your webhook setting allows. The cost is that a row which is audit-only is kept as long as the webhook window in that configuration — retention errs toward keeping an audit trail rather than losing one.

The audit seam is **off** unless you enable it, so an install that has not turned it on records only `webhook`-class rows and is pruned exactly as before.

**If you already run with `webhooks.audit` enabled,** note that those events previously fell under `eventsMaxAgeMs`, because nothing wrote the audit class. They now fall under `auditEventsMaxAgeMs` — at the defaults, 90 days instead of 30 — which retains roughly three times as many event rows. That is the point of the class, but it is a storage change worth planning for; lower `auditEventsMaxAgeMs` if you want the shorter window back.

Set `webhooks.retention: false` to disable pruning entirely. Both the automatic passes **and** `nextly webhooks:prune` then do nothing, so the tables grow until you either re-enable retention or clean them up at the database level yourself.

## Pruning by hand: `nextly webhooks:prune`

`nextly webhooks:prune` runs one retention pass immediately.

```bash
nextly webhooks:prune            # run one retention pass now
nextly webhooks:prune --dry-run  # report what a pass would remove, delete nothing
```

The command reports how many webhook events, audit events, and terminal delivery rows it removed. If a batch bound stops the pass before it finishes, it says so — run it again to continue. It reads the same `webhooks.retention` policy as the automatic passes, and does nothing when retention is disabled.

**`webhooks:prune` is cleanup, not delivery.** It does not fan out or deliver anything. Its behaviour splits on whether an enabled endpoint exists:

- **With an enabled endpoint,** an event that was never fanned out is **kept**. It may still be delivered, so prune only reclaims already-fanned-out events plus terminal (`delivered`/`failed`) deliveries. You still need the **drain running** to fan out and deliver; `webhooks:prune` supplements it with scheduled cleanup, it does not replace it.
- **With no enabled endpoint** (an audit-only install, `webhooks.audit` on), there is nothing to deliver to, so aged un-fanned events are reclaimable and `webhooks:prune` is all you need to keep the ledger bounded.

A daily cron is a good baseline where you want scheduled cleanup:

```bash
0 3 * * *  cd /path/to/app && nextly webhooks:prune
```

Global flags inherited from the root `nextly` command apply: `--config <path>`, `--cwd <path>`, `--verbose`, `-q/--quiet`. Note that `--cwd` selects where the config is discovered, but `nextly` loads `.env` and reads `DATABASE_URL` from the directory you actually run it in — so invoke `webhooks:prune` from the app directory, or export the database environment yourself, when using `--cwd`.

## Keeping the tables small

Deleting rows frees logical space but does not always return it to the operating system, and queue-shaped tables (many inserts, many deletes) are exactly the workload that outpaces a database's default reclamation.

### Postgres: tune autovacuum for the queue tables

`nextly_events` and `nextly_webhook_deliveries` churn far faster than a typical content table, so the default `autovacuum_vacuum_scale_factor` (0.2 — vacuum after 20% of rows change) lets dead tuples accumulate between vacuums and the tables bloat. Lower the scale factor for just these two tables so autovacuum runs more often, and drop the fillfactor a little so updates can reuse space on the same page:

```sql
ALTER TABLE nextly_events
  SET (autovacuum_vacuum_scale_factor = 0.02, fillfactor = 90);
ALTER TABLE nextly_webhook_deliveries
  SET (autovacuum_vacuum_scale_factor = 0.02, fillfactor = 90);
```

This is a per-table override; the rest of your schema keeps the server defaults. On managed Postgres (Neon, Supabase, RDS) these `ALTER TABLE ... SET` options apply normally.

### SQLite: do not auto-VACUUM

Do **not** run `VACUUM` automatically after pruning. `VACUUM` takes a whole-database exclusive lock and rewrites the entire file, which stalls every other connection; in WAL mode it also needs a following checkpoint before the space is actually reclaimed. Let pruning delete the rows, and only run `VACUUM` (or set `PRAGMA auto_vacuum` at database creation) deliberately, during a maintenance window when the app is idle. For most self-hosted SQLite deployments the freed pages are simply reused by later inserts, and no manual reclamation is needed at all.

## Keeping content out of the outbox

Recording is per entity. A collection or single that holds personal data can opt
out, and its writes then reach neither the outbox nor any subscribed endpoint.

In code:

```ts
defineCollection({
  slug: "enquiries",
  webhooks: false, // or { record: false }
  fields: [text({ name: "message" })],
});
```

In the admin, open the collection or single in the **Schema Builder**, then
**Settings → Advanced → Webhook recording**. The switch is on by default; turning
it off stores the opt-out on the entity's registry row, so it holds across
restarts as well as for the running process.

For an entity defined in code, the code config wins: the switch reflects what is
stored, but a `webhooks` value in `defineCollection`/`defineSingle` is
republished on every boot and overrides the row. Change it in code for
code-first entities.

The plugin-provided `form-submissions` collection ships opted out, because
submissions carry visitor-entered content plus `ipAddress` and `userAgent`.

> **Deploying a Builder-set opt-out:** turning the switch off is a metadata-only
> change, and `migrate:create` only emits a migration when a table's schema
> changes. The setting therefore applies to the database you are working against
> but does not reach another environment until a schema change ships with it. If
> you need the opt-out in production now, set `webhooks: false` in code-first
> config instead: it is republished on every boot and needs no migration.

> **Upgrading:** the switch is stored in a registry column added in this release.
> An existing install must run `nextly migrate` before the setting can persist;
> until then `nextly migrate` reports the column as core-schema drift and
> recording continues exactly as before.

## Related

- [Production migrations](https://nextlyhq.com/docs/guides/production-migrations) — the `nextly migrate` model these system tables evolve through.
- [Draft & published status](https://nextlyhq.com/docs/guides/draft-published-status) — the status transitions that produce publish/unpublish events.

---
title: Background Jobs
description: Run work outside the request that triggered it, with retries and a visible history.
url: https://nextlyhq.com/docs/jobs
---

Some work should not happen while a user waits: sending a batch of email, regenerating
images, calling a slow third-party API. A job is that work, queued and run later.

## Availability

| | |
|---|---|
| Built in | No plugin required |
| Admin | A **Background Jobs** screen showing queued, running, failed and completed work |
| Permission | Viewing jobs is an admin capability; a job runs as a user you nominate |

## Define a job

```ts
import { defineJob } from "nextly";

export const sendDigest = defineJob({
  slug: "send-digest",
  handler: async ctx => {
    // ctx carries the payload the job was enqueued with.
  },
});
```

`defineJob` only builds the definition. Register it in your config, or nothing will run it:

```ts
import { defineConfig } from "nextly";

import { sendDigest } from "./jobs/send-digest";

export default defineConfig({
  jobs: [sendDigest],
});
```

<Callout type="warn">
A job that is defined but not listed in `jobs` is absent from the registry. Rows queued for
its slug sit there with no handler to pick them up.
</Callout>

## Retries and backoff

A failed job is retried with exponential backoff, starting at **1 second** and capped at
**1 hour**, with jitter so a batch of simultaneous failures does not retry in lockstep.

`attemptCount` counts the attempt that just failed, so a job with a budget of three
attempts gives up when the third fails — not after a fourth. That boundary is the usual
bug in retry code, so it is worth stating rather than leaving to be discovered.

## Who a job runs as

A job is not run with the authority of whoever enqueued it. It resolves a **run-as** user,
and that identity is what access control sees while the job runs, so a job cannot quietly
do more than the user it runs as is allowed to do.

## Retention

Finished jobs are pruned on a schedule, so the table holds recent history rather than
everything that has ever run.

## Related

- [Webhooks](https://nextlyhq.com/docs/webhooks) — telling another system that something changed
- [Audit log](https://nextlyhq.com/docs/audit-log)

---
title: Dashboard Widgets
description: Put the numbers your team actually checks on the admin dashboard.
url: https://nextlyhq.com/docs/widgets
---

The admin dashboard is built from widgets. Each one declares what it wants to know, and the
system runs that query on its behalf, scoped to the permissions of whoever is looking.

## Availability

| | |
|---|---|
| Built in | The widget system, the built-in sources and admin rendering all ship |
| Plugin-contributed widgets | **Experimental.** They render, but the contribution shape is still settling — see the [stability ladder](https://nextlyhq.com/docs/plugins/stability) |
| Permission | A widget's query runs scoped to the viewer, so two people can see the same dashboard and different numbers |

## Archetypes

A widget declares an archetype rather than drawing itself, so dashboards stay visually
consistent no matter who contributed the widget:

| Archetype | Shows |
|---|---|
| `metric` | One number |
| `stats` | Several labelled, clickable numbers |
| `table` | Rows and columns |
| `list` | An ordered list of items |
| `actions` | Buttons for things to do |
| `custom` | Your own component, when none of the above fit |

A `text` archetype exists in the type union but core has **no renderer for it yet**. A text
widget that also ships no component of its own draws a card reading "not rendered yet"
instead of prose — visible rather than silently missing, but not what you wanted. Use
`custom` with your own component for prose today.

Sizes are `sm`, `md`, `lg`, `xl` and `full`; heights are `short` and `tall`.

## Declared, not fetched

A widget does not run its own database query. It **declares** one, and the system executes
it. That is what makes permission scoping reliable rather than something each widget author
has to remember: a widget cannot read what its viewer could not have read directly.

It also means most widgets need no data-fetching code at all.

<Callout type="warn">
Contributing a widget from a plugin works today, but `PluginAdminWidget` is marked
`@experimental` and its shape may change before it settles. Building on it is reasonable;
depending on it in something you cannot easily update is not.
</Callout>

## Related

- [Plugin admin UI](https://nextlyhq.com/docs/plugins/admin-ui) — contributing admin surfaces
- [Plugin stability](https://nextlyhq.com/docs/plugins/stability) — what is settled and what is not

---
title: Admin Panel
description: Overview of the Nextly admin panel, including navigation, default permissions, and how to access it.
url: https://nextlyhq.com/docs/admin
---

Nextly ships with a full-featured admin panel for managing your collections, singles, media library, users, and settings without leaving the browser. It is mounted at `/admin` and is rendered by the same Next.js app that exports the Nextly route handlers, so there is no separate service to deploy.

## Accessing the admin panel

The first time you visit `/admin` and the database has no users, Nextly redirects you to a setup wizard at `/admin/setup` to create the initial Super Admin account. After that, sign in at `/admin/login`.

```
https://your-app.com/admin
```

Authentication is custom (email + password, JWT-backed sessions, API keys, RBAC) — see [Authentication](https://nextlyhq.com/docs/guides/authentication) for the full reference.

## Navigation structure

The admin uses a dual-sidebar layout on desktop. A narrow icon strip on the far left lists the top-level sections; clicking one reveals a wider inner sidebar with the items inside that section. On screens narrower than 1024px the layout switches to a single hamburger drawer automatically — no configuration required.

The top-level sections (in order) are:

| Section | Route | What it contains |
|---|---|---|
| Dashboard | `/admin` | Landing page after login |
| Builder | `/admin/builder/collections` | Schema management for Collections / Singles / Components — the [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) |
| Collections | `/admin/collections/[slug]` | Per-collection content surface; the icon appears in the sidebar once at least one collection exists and lands on the most-recently-created collection |
| Singles | `/admin/singles/[slug]` | Per-single content surface; same dynamic visibility rule as Collections |
| Media Library | `/admin/media` | Upload, browse, and edit files referenced by `upload` fields |
| Plugins | `/admin/plugins` | Only visible when at least one plugin is installed and registers admin pages |
| Users | `/admin/users` | Users, Roles, Custom user fields |
| Settings | `/admin/settings` | General, API keys, Email providers, Email templates, Email layout, Image sizes |

Collection and Single icons are added to the primary sidebar dynamically as you register collections / singles in `nextly.config.ts` (or create them via the Visual Schema Builder). The Builder icon is always present but can be hidden in production; see [Schema Builder visibility](https://nextlyhq.com/docs/admin/branding#schema-builder-visibility) for the `admin.branding.showBuilder` toggle.

## What you can do in each section

### Content management

Every collection registered in `nextly.config.ts` gets a list view with filtering, sorting, pagination, and search. Click an entry to open the editing form; inputs are rendered field-type-aware (rich-text editor for `richText`, date picker for `date`, file picker for `upload`, related-document picker for `relationship`, and so on).

Singles render a single editing form at `/admin/singles/[slug]` instead of a list view, since each Single has exactly one document.

### Media Library

A central media library at `/admin/media` supports drag-and-drop uploads, thumbnails, and file metadata editing. `upload` fields across all collections reference this library; uploading from inside an `upload` field writes to the same store. The default backend writes to `./public/uploads/` on local disk; configure a different storage adapter in `nextly.config.ts` to use S3, Vercel Blob, or UploadThing.

### Visual Schema Builder

The Visual Schema Builder lets you create and edit Collections, Singles, and Field Groups without writing TypeScript. It generates the same artifacts the code-first approach produces. See [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) for the full reference.

### Users, Roles, and Custom Fields

The Users section groups three pages:

- **Users** (`/admin/users`) — list, create, edit, and disable user accounts.
- **Roles** (`/admin/security/roles`) — create roles and assign permissions to them. The setup wizard seeds a `Super Admin` role that holds every permission and assigns it to the first user.
- **Custom Fields** (`/admin/users/fields`) — add extra fields to the user model. Only scalar field types are accepted on user records; see the [`users` reference](https://nextlyhq.com/docs/configuration/nextly-config#users) in `nextly.config.ts`.

### Settings

The Settings inner sidebar is split into sub-groups:

- **System.** General (site-wide settings) and API Keys.
- **Email.** Email Providers (Resend, SMTP, etc.), Email Templates, and Email Layout.

Image-size presets and the (programmatic) Permissions page also live under settings.

## Permissions

Nextly's RBAC model uses permission slugs in the form `<action>-<resource>` (e.g. `read-users`, `create-roles`, `update-api-keys`, `manage-settings`). Permissions and the `Super Admin` role are seeded the first time the database is set up — for the core resources (`users`, `roles`, `permissions`) the seeder creates one row per `(action, resource)` pair across `create`, `read`, `update`, `delete`. See [`packages/nextly/src/database/seeders/permissions.ts`](../packages/nextly/src/database/seeders/permissions.ts) for the seeder source.

The admin sidebar is permission-gated. The built-in mapping is:

| Sidebar item | Required permission |
|---|---|
| Dashboard | Always visible |
| Collections list / entries | Per-collection read permissions |
| Singles list / entries | Per-Single read permissions |
| Media Library | `read-media` |
| Users | `read-users` |
| Roles | `read-roles` |
| Custom Fields | `manage-settings` |
| General settings | `manage-settings` |
| API Keys | `update-api-keys` |
| Email Providers / Templates / Layout | `manage-settings` |
| Plugins overview | `manage-settings` |
| Builders (Collections / Singles / Field Groups Builder) | Gated by the `admin.branding.showBuilder` toggle |

Permissions for collections you define in `nextly.config.ts` follow the same slug pattern (`read-posts`, `update-posts`, etc.); they are wired up automatically when the collection is registered. Assign permissions to roles from `/admin/security/roles`.

## Plugins in the admin

A plugin can register sidebar entries via its `admin.placement` setting. Until at least one plugin is installed, the Plugins section is hidden. When a plugin does add entries, they appear under the section the plugin chose (Collections, Singles, Users, Settings, Plugins, or Standalone). You can override the placement and appearance per-plugin from `admin.pluginOverrides` in `nextly.config.ts`; see [Customization](https://nextlyhq.com/docs/admin/customization#plugin-overrides).

## Next steps

- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — design content types without writing code
- [Customization](https://nextlyhq.com/docs/admin/customization) — sidebar config, navigation permissions, plugin overrides
- [Branding](https://nextlyhq.com/docs/admin/branding) — logo, favicon, color scheme, Builder visibility
- [Collections](https://nextlyhq.com/docs/configuration/collections) — code-first collection definitions
- [Singles](https://nextlyhq.com/docs/configuration/singles) — code-first Single definitions

---
title: Customization
description: Configure admin panel behavior, plugin placement, navigation permissions, and per-collection sidebar options.
url: https://nextlyhq.com/docs/admin/customization
---

The admin panel is configured through the `admin` key in your `nextly.config.ts`. This page covers structural customization — sidebar options, navigation permissions, and plugin overrides. For visual customization (logo, colors, favicon), see [Branding](https://nextlyhq.com/docs/admin/branding).

## Admin configuration shape

The `admin` block on `defineConfig()` accepts two top-level keys:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";

export default defineConfig({
  admin: {
    branding: {
      /* logo, colors, favicon — see Branding page */
    },
    pluginOverrides: {
      /* per-plugin sidebar overrides — see below */
    },
  },
});
```

There is no top-level `admin.sidebar` config today. Sidebar grouping for built-in entries is fixed; per-collection entries are configured on each collection's `admin` block; per-plugin entries are configured in the plugin definition and can be overridden by `admin.pluginOverrides`.

## Per-collection sidebar options

Each collection's `admin` block on `defineCollection()` controls how that collection appears in the sidebar:

```typescript title="src/collections/posts.ts"
import { defineCollection, text, richText } from "nextly";

export default defineCollection({
  slug: "posts",
  labels: { singular: "Post", plural: "Posts" },
  admin: {
    icon: "FileText",                            // Lucide icon name
    group: "Content",                            // Sidebar group label
    hidden: false,                               // Hide from the sidebar (still reachable by URL)
    order: 10,                                   // Sort position (lower = higher; default 100)
    useAsTitle: "title",                         // Field used as the entry title in list views
    defaultColumns: ["title", "status", "createdAt"],
    sidebarGroup: "marketing",                   // Optional custom group slug — moves the entry out of "Collections" into a custom inner section
  },
  fields: [
    text({ name: "title", required: true }),
    richText({ name: "content" }),
  ],
});
```

| Option | Type | Default | Description |
|---|---|---|---|
| `icon` | `string` | `"FileText"` | Lucide icon name shown in the sidebar |
| `group` | `string` | — | Group label inside the Collections section |
| `hidden` | `boolean` | `false` | Hide from sidebar navigation |
| `order` | `number` | `100` | Sort order within the section (lower = higher) |
| `useAsTitle` | `string` | — | Field name displayed as the entry title in list views |
| `defaultColumns` | `string[]` | — | Columns shown by default in the list view |
| `sidebarGroup` | `string` | — | Custom group slug — moves this collection out of `Collections` into its own inner section |

Singles accept the same `admin` shape on `defineSingle()`.

## Plugin overrides

Plugins can register their own admin sidebar entries via `admin.placement` in the plugin definition. From your `nextly.config.ts`, you can override that placement and appearance per-plugin without modifying the plugin's source:

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";

export default defineConfig({
  admin: {
    pluginOverrides: {
      "form-builder": {
        placement: "settings",       // Move the plugin's admin pages into Settings
        order: 80,                   // Sort order within the target section
        after: "media",              // For STANDALONE plugins: which built-in section to render after
        appearance: {
          icon: "FileText",          // Override the sidebar icon (Lucide name)
        },
      },
    },
  },
});
```

The override key is the plugin slug (derived from the plugin name). Overrides use a shallow merge — only the fields you set are replaced; everything else keeps the plugin author's defaults.

### Override fields

| Field | Type | Description |
|---|---|---|
| `placement` | `AdminPlacement` | Target sidebar section. One of `"collections"`, `"singles"`, `"users"`, `"settings"`, `"plugins"`, or `"standalone"`. |
| `order` | `number` | Sort position within the target section. |
| `after` | `string` | Only meaningful when `placement` is `"standalone"`. Names the built-in top-level section the plugin's icon should appear after: `"dashboard"`, `"collections"`, `"singles"`, `"media"`, `"plugins"`, `"users"`, or `"settings"`. |
| `appearance` | `Partial<PluginAdminAppearance>` | Shallow-merged override of the plugin's sidebar appearance (icon, label, etc.). |

The `AdminPlacement` constants ship from the package root for autocomplete:

```typescript
import { AdminPlacement } from "nextly";

AdminPlacement.COLLECTIONS;  // "collections"
AdminPlacement.SINGLES;      // "singles"
AdminPlacement.USERS;        // "users"
AdminPlacement.SETTINGS;     // "settings"
AdminPlacement.PLUGINS;      // "plugins"
AdminPlacement.STANDALONE;   // "standalone"
```

A plugin only contributes admin entries if its definition declares them. Plugin-driven sidebar items appear only when that plugin is registered in `nextly.config.ts`.

## Navigation permissions

The admin sidebar is permission-gated. Items only render for users who have the matching permission on their assigned roles:

| Sidebar item | Required permission |
|---|---|
| Dashboard | Always visible |
| Per-collection entries | Per-collection `read-<slug>` |
| Per-Single entries | Per-Single `read-<slug>` |
| Media Library | `read-media` |
| Users | `read-users` |
| Roles | `read-roles` |
| Custom Fields | `manage-settings` |
| General Settings | `manage-settings` |
| API Keys | `update-api-keys` |
| Email Providers / Templates / Layout | `manage-settings` |
| Image Sizes | `manage-settings` |
| Plugins overview | `manage-settings` |
| Builders (Collections / Singles / Components) | Gated by `admin.branding.showBuilder` |

Permissions are stored as `<action>-<resource>` slugs and can be assigned to roles from `/admin/security/roles`. The default seeded roles and permissions are documented in [Admin Panel Overview](https://nextlyhq.com/docs/admin#permissions).

## Responsive behaviour

The admin layout adapts automatically to screen size:

- **Desktop** (1024px and above) — dual sidebar (icon strip + inner sidebar).
- **Tablet / mobile** (below 1024px) — single hamburger drawer.

There is no configuration knob for this; the layout switches based on viewport width.

## Next steps

- [Branding](https://nextlyhq.com/docs/admin/branding) — logo, colors, favicon, Builder visibility
- [Admin Panel Overview](https://nextlyhq.com/docs/admin) — full navigation guide and permission map
- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — design content types without writing code
- [Collections](https://nextlyhq.com/docs/configuration/collections) — full collection-level admin options

---
title: Branding
description: Customize the admin panel logo, favicon, brand colors, and Visual Schema Builder visibility.
url: https://nextlyhq.com/docs/admin/branding
---

The `admin.branding` key in `nextly.config.ts` controls the visual identity of the admin panel. You can replace the default logo, set a custom favicon, override the primary and accent brand colors, and toggle the Visual Schema Builder's visibility.

## Full example

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";

export default defineConfig({
  admin: {
    branding: {
      logoUrl: "/logo.svg",
      logoUrlLight: "/logo-light.svg",
      logoUrlDark: "/logo-dark.svg",
      logoText: "Acme CMS",
      favicon: "/favicon.ico",
      colors: {
        primary: "#6366f1",
        accent: "#f59e0b",
      },
      showBuilder: true,
    },
  },
});
```

## Logo

You can ship a single logo for both light and dark modes, or a separate logo per mode.

| Option | Type | Description |
|---|---|---|
| `logoUrl` | `string` | Logo image URL used in both modes. Absolute URL or path under your Next.js `public/` directory. When set, takes priority over the per-mode variants. |
| `logoUrlLight` | `string` | Logo for light mode. Used when `logoUrl` is not set. |
| `logoUrlDark` | `string` | Logo for dark mode. Used when `logoUrl` is not set. |
| `logoText` | `string` | Text shown in the sidebar header. Doubles as the `alt` attribute on the logo image. Default: `"Nextly"`. |

If neither `logoUrl` nor the per-mode variants are set, the sidebar falls back to a default Nextly mark and shows `logoText` next to it.

```typescript title="nextly.config.ts"
// Single logo for both modes
admin: {
  branding: {
    logoUrl: "/logo.svg",
    logoText: "Acme CMS",
  },
},
```

```typescript title="nextly.config.ts"
// Separate logos per mode
admin: {
  branding: {
    logoUrlLight: "/logo-light.svg",
    logoUrlDark: "/logo-dark.svg",
    logoText: "Acme CMS",
  },
},
```

The mode-aware variants are wired up in `packages/admin/src/components/shared/ThemeAwareLogo.tsx`, which switches between `logoUrlLight` and `logoUrlDark` based on the resolved theme. `logoUrl` always wins when set.

## Favicon

`favicon` injects a custom favicon into every admin page (the `<link rel="icon">` element is replaced at runtime).

```typescript title="nextly.config.ts"
admin: {
  branding: {
    favicon: "/favicon.ico",
  },
},
```

The path can be absolute or a path under your Next.js `public/` folder. Common formats: `.ico`, `.png`, `.svg`. If `favicon` is unset, the admin uses a default inline SVG that follows the user's `prefers-color-scheme`. Browsers do not reliably react to JS-driven theme toggles for favicons, so the in-app dark/light switch will not change the favicon on the fly.

## Brand colors

```typescript title="nextly.config.ts"
admin: {
  branding: {
    colors: {
      primary: "#6366f1",  // indigo
      accent: "#f59e0b",   // amber
    },
  },
},
```

`branding.colors` accepts two 6-digit hex tokens that the admin actually consumes:

| Token | Type | Used for |
|---|---|---|
| `primary` | hex string | Primary brand color (replaces the default blue): buttons, active states, links, focus rings, field accents. |
| `accent` | hex string | Accent brand color (replaces the default cyan): secondary highlights. |

Foreground colors for text and icons over each background are calculated automatically to meet WCAG AA contrast — you do not configure them. Both tokens are converted to HSL on the server and injected as CSS custom properties (`--primary`, `--primary-foreground`, `--accent`, `--accent-foreground`) so the change applies globally without runtime JS work. Invalid hex values are silently dropped; only `#rrggbb` is recognised.

If your `nextly.config.ts` is imported by your app's `layout.tsx`, you can render the generated CSS yourself with `getBrandingCss(config.admin?.branding)` from `nextly/config` to avoid a flash of default colors before the admin's runtime fetch.

## Schema Builder visibility

`showBuilder` toggles the Builders top-level icon (Collections Builder, Singles Builder, Field Groups Builder) in the admin sidebar.

| Value | Behavior |
|---|---|
| `true` | Builders icon is always visible. |
| `false` | Builders icon is always hidden. |
| Not set (default) | Visible when `process.env.NODE_ENV !== "production"`, hidden in production. |

```typescript title="nextly.config.ts"
// Force visible, even in production
admin: {
  branding: {
    showBuilder: true,
  },
},
```

```typescript title="nextly.config.ts"
// Force hidden, even in development
admin: {
  branding: {
    showBuilder: false,
  },
},
```

The toggle is evaluated server-side and shipped via the `/api/admin-meta` response, so changes take effect on the next admin reload. Hiding the Builder entry does not lock down the underlying routes — direct visits to `/admin/builder/collections` etc. still work for users with permission. Treat `showBuilder: false` as "hide from the sidebar in production", not as an authorization control.

## Branding options reference

| Option | Type | Default | Description |
|---|---|---|---|
| `logoUrl` | `string` | — | Logo image URL (used in both modes when set) |
| `logoUrlLight` | `string` | — | Logo for light mode |
| `logoUrlDark` | `string` | — | Logo for dark mode |
| `logoText` | `string` | `"Nextly"` | Sidebar header text and logo `alt` attribute |
| `favicon` | `string` | — | Custom favicon URL |
| `colors.primary` | `string` (hex) | — | Primary brand color |
| `colors.accent` | `string` (hex) | — | Accent brand color |
| `showBuilder` | `boolean` | per `NODE_ENV` | Toggle the Builders sidebar entry |

## Next steps

- [Customization](https://nextlyhq.com/docs/admin/customization) — sidebar config, plugin overrides, navigation permissions
- [Admin Panel Overview](https://nextlyhq.com/docs/admin) — full navigation and feature guide
- [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder) — what it does and how to use it

---
title: Telemetry
description: What Nextly's CLI collects, why, and how to opt out.
url: https://nextlyhq.com/docs/telemetry
---

Nextly collects anonymous usage data from its CLI tools (`create-nextly-app` and `nextly`) to understand which features are used, catch regressions, and make data-driven product decisions during alpha.

Telemetry is **anonymous**, **opt-out**, automatically disabled in CI, Docker, production, and non-interactive shells, and can be disabled permanently with one command or one environment variable.

## How to opt out

Any of these is enough. The first one you set wins.

```bash
# Option 1: one-time command, persists in ~/.config/nextly/config.json
nextly telemetry disable

# Option 2: environment variable, per-session
NEXTLY_TELEMETRY_DISABLED=1 next dev

# Option 3: community standard (also respected by other tools)
DO_NOT_TRACK=1 next dev
```

## What we collect

Every event includes this base context:

| Field | Example | Description |
|---|---|---|
| `cli_name` | `"nextly"` | Which CLI emitted the event |
| `cli_version` | `"0.1.3"` | Version of the CLI |
| `node_version` | `"22.11.0"` | Node.js runtime version |
| `os` | `"darwin"` | `darwin / linux / win32 / freebsd / other` |
| `arch` | `"arm64"` | `arm64 / x64 / other` |
| `package_manager` | `"pnpm"` | From `npm_config_user_agent` |
| `is_ci` / `is_docker` | `false` | Always false in practice (telemetry is off in CI and Docker) |
| `schema_version` | `1` | Version of this event schema |
| `project_id` | `"a1b2c3d4e5f6"` | 12-char one-way hash of your cwd plus a per-machine salt; lets us count distinct projects without knowing their paths. Only present for `nextly` commands, not `create-nextly-app`. |

### `create-nextly-app` events

| Event | Extra properties |
|---|---|
| `scaffold_started` | Flag presence booleans (`yes`, `demoData`, `skipInstall`, `useYalc`) |
| `template_selected` | `template`, `approach` |
| `database_selected` | `database` |
| `install_started` | (none) |
| `install_completed` | `duration_ms` |
| `install_failed` | `duration_ms`, `error_code` |
| `scaffold_completed` | `total_duration_ms`, `template`, `database`, `approach`, `demo_data` |
| `scaffold_failed` | `stage`, `error_code`, `duration_ms` |

### `nextly` command events

| Event | Extra properties |
|---|---|
| `command_started` | `command`, `flags_count` (the number of flags passed, never their names or values) |
| `command_completed` | `command`, `duration_ms` |
| `command_failed` | `command`, `duration_ms`, `error_code` |

### `error_code` taxonomy

Errors map to a fixed enum. Raw error messages and stack traces never leave your machine.

- `install_failed`, `install_network`, `install_permission`, `install_disk_full`
- `template_download_failed`, `template_parse_failed`
- `config_generation_failed`
- `db_connection_failed`, `migration_conflict`
- `unknown`

## What we never collect

- Project name, directory name, or any file path.
- Git remote URL, username, email, or hostname.
- IP address. We set `disableGeoip: true` on PostHog so the server does not derive one either.
- File contents, schema names, collection names, or field names.
- `.env` values, API keys, database URLs, or auth secrets.
- Raw error messages or stack traces.
- Next.js or Nextly config file contents.

## How anonymous identity works

On first run, Nextly generates two random values:

- **`anonymousId`** -- 256 bits of entropy, stored in your user config directory (`~/.config/nextly/config.json` on Linux; OS-appropriate paths elsewhere). Sent with every event as the `distinct_id`. Never linked to any account or email.
- **`salt`** -- 128 bits of entropy, stored alongside the ID. Used to hash your project paths. The salt never leaves your machine.

You can rotate both with:

```bash
nextly telemetry reset
```

This will also re-show the first-run notice on your next CLI invocation.

## When telemetry is disabled automatically

- `DO_NOT_TRACK=1` is set.
- `NEXTLY_TELEMETRY_DISABLED=1` is set.
- `NODE_ENV=production`.
- CI is detected (`CI=1`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `TRAVIS`, `JENKINS_URL`, `BUILDKITE`, `VERCEL`, `NETLIFY`, `RENDER`).
- Docker is detected (`/.dockerenv` present).
- Stdout is not a TTY (e.g., output is piped to a file).

## Source code

Every line of telemetry code is open-source. Audit it yourself:

- [`packages/telemetry/src/events.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/telemetry/src/events.ts) -- the full event catalog
- [`packages/telemetry/src/is-disabled.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/telemetry/src/is-disabled.ts) -- disable resolution order
- [`packages/telemetry/src/client.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/telemetry/src/client.ts) -- PostHog client wrapper
- [`packages/telemetry/src/index.ts`](https://github.com/nextlyhq/nextly/blob/main/packages/telemetry/src/index.ts) -- the public API

---
title: Templates
description: Starter projects you can scaffold with create-nextly-app.
url: https://nextlyhq.com/docs/templates
---

Templates are starter projects you scaffold via `create-nextly-app`. The CLI prompts you to pick one during setup, or you can pass `--template <name>` for a non-interactive scaffold. Each template ships a working `nextly.config.ts`, the standard project layout, and (for non-blank templates) example collections, singles, and frontend pages.

## Scaffold a project

**pnpm:**

```bash
pnpm create nextly-app@alpha my-app
```

**npm:**

```bash
npx create-nextly-app@alpha my-app
```

**yarn:**

```bash
yarn create nextly-app@alpha my-app
```

**bun:**

```bash
bun create nextly-app@alpha my-app
```

Without `--template`, the CLI prompts you to pick one. To skip the prompt, pass `--template <name>`:

```bash
pnpm create nextly-app@alpha my-app --template blank
pnpm create nextly-app@alpha my-app --template blog
```

## Available templates

- **[Blank](https://nextlyhq.com/docs/templates/blank)** -- Empty config, define your own schemas. Good when you want to start from scratch.
- **[Blog](https://nextlyhq.com/docs/templates/blog)** -- Complete blog with posts, categories, tags, frontend pages, and demo content. Good when you want a working starter to learn from.

More templates are planned for the beta release.

## Next Steps

- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Full installation walkthrough including database and storage setup.
- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Build a blog from scratch in five minutes.
- [Configuration](https://nextlyhq.com/docs/configuration) -- Configure collections, singles, plugins, and more.

---
title: Blank Template
description: Start from an empty Nextly config and define your own schemas.
url: https://nextlyhq.com/docs/templates/blank
---

The **Blank** template scaffolds a minimal Nextly project with no collections or singles defined. You get the full Next.js App Router setup, the admin route, the standard environment configuration, and an empty `nextly.config.ts` ready for you to fill in. It's the starting point when you want to design your schema from scratch.

## Scaffold

**pnpm:**

```bash
pnpm create nextly-app@alpha my-app --template blank
```

**npm:**

```bash
npx create-nextly-app@alpha my-app --template blank
```

**yarn:**

```bash
yarn create nextly-app@alpha my-app --template blank
```

**bun:**

```bash
bun create nextly-app@alpha my-app --template blank
```

## What it ships

- **Empty `nextly.config.ts`** with `collections: []` and `singles: []`. Add definitions here as you build.
- **Standard Next.js App Router setup** -- root `layout.tsx`, `page.tsx`, `globals.css`, and a `favicon.ico`. The landing page is a simple "Welcome" screen with a link into the admin.
- **Generated admin route** at `src/app/admin/[[...params]]/`. The page wires up `RootLayout`, `QueryProvider`, `ErrorBoundary`, and the form-builder plugin's CSS imports. The layout reads admin branding from `nextly.config.ts` and injects the resulting CSS variables.
- **Health and media routes** under `src/app/api/`.
- **Default `next.config.ts`** with the canonical `serverExternalPackages` list. See [Project Structure](https://nextlyhq.com/docs/getting-started/project-structure) for the full list and what each entry does.
- **Default `.env.example`** with `DB_DIALECT`, `DATABASE_URL`, `NEXTLY_SECRET`, `NEXT_PUBLIC_APP_URL`, and a storage block populated based on the storage option you picked in the CLI.
- **Generated `nextly-types.ts`** stub under `src/types/generated/` so type generation has a destination on first run.

## File tree

```
my-app/
├── src/
│   ├── app/
│   │   ├── admin/
│   │   │   ├── [[...params]]/
│   │   │   │   ├── layout.tsx
│   │   │   │   └── page.tsx
│   │   │   └── api/
│   │   │       └── [[...params]]/
│   │   │           └── route.ts
│   │   ├── api/
│   │   │   ├── health/
│   │   │   │   └── route.ts
│   │   │   └── media/
│   │   │       └── [[...path]]/
│   │   │           └── route.ts
│   │   ├── favicon.ico
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── types/
│       └── generated/
│           └── nextly-types.ts
├── public/
├── .env
├── .env.example
├── eslint.config.mjs
├── next.config.ts
├── nextly.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.json
```

## Next steps

- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Create your super-admin account on first run.
- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Build something concrete (a blog with posts and categories) to learn the API.
- [Configuration](https://nextlyhq.com/docs/configuration) -- Define your first collections and singles in `nextly.config.ts`.

---
title: Blog Template
description: A complete blog starter with posts, categories, tags, frontend pages, and demo content.
url: https://nextlyhq.com/docs/templates/blog
---

The **Blog** template is a production-quality blog starter. It ships posts, categories, tags, three admin-editable site singles, a full set of public-facing pages under a `(frontend)` route group, RSS feeds, sitemap, OG images, RBAC access policies, and a one-click demo-content seeder. Use it when you want a working starter to read, run, and modify rather than building from scratch.

## Scaffold

**pnpm:**

```bash
pnpm create nextly-app@alpha my-blog --template blog
```

**npm:**

```bash
npx create-nextly-app@alpha my-blog --template blog
```

**yarn:**

```bash
yarn create nextly-app@alpha my-blog --template blog
```

**bun:**

```bash
bun create nextly-app@alpha my-blog --template blog
```

To skip the schema-approach prompt, pass `--approach`:

```bash
pnpm create nextly-app@alpha my-blog --template blog --approach code-first
pnpm create nextly-app@alpha my-blog --template blog --approach visual
```

## Schema approach

The Blog template supports two approaches:

- **`code-first`** (default) -- Collections and singles are defined in TypeScript files under `src/collections/` and `src/singles/`. The CLI copies `configs/codefirst.config.ts` to the project root as `nextly.config.ts`. Best for version control and type safety.
- **`visual`** -- Collections and singles are created via the Visual Schema Builder in the admin. The CLI copies `configs/visual.config.ts` (an empty config) to the project root as `nextly.config.ts`. After scaffolding, define your schemas through the admin UI; demo data (if selected) seeds the schemas and content on first run.

## What it ships

### Collections

- **Posts** -- Title, slug, rich-text content, featured image, author (relation to users), categories, tags, excerpt, publish date, featured flag, SEO group (metaTitle, metaDescription, ogImage, canonical, noindex), and draft/published status. Auto-generates a slug from the title and computes reading time and word count on save.
- **Categories** -- Name, slug, description.
- **Tags** -- Name, slug, description.

The template uses the built-in `users` collection for authors. Posts relate to users via the `author` field, and `users` is extended with three scalar fields (`bio`, `avatarUrl`, `slug`) -- there is no separate `authors` collection.

### Singles

- **Site Settings** -- Site name, tagline, description, logo, social handles. Drives the header, footer, and SEO metadata.
- **Navigation** -- Header link list, footer "Read" link list, theme-toggle and search-icon visibility flags.
- **Homepage** -- Hero title and subtitle, plus toggles for featured-post, latest-grid, category-strip, and newsletter-CTA sections, and the newsletter heading and subheading.

### Frontend pages

Public-facing routes live under the `src/app/(frontend)/` route group:

- `/` -- Homepage (hero, featured, latest grid, category strip, newsletter CTA).
- `/blog` -- All posts, paginated.
- `/blog/[slug]` -- Post detail with reading-progress bar, auto-generated table of contents, share bar, author card, and prev/next.
- `/categories` and `/categories/[slug]` -- Category index and per-category archive.
- `/tags` and `/tags/[slug]` -- Tag cloud and per-tag archive.
- `/authors/[slug]` -- Author profile page.
- `/search` -- Client-side search powered by Pagefind.

SEO routes live at the root of `src/app/`:

- `/sitemap.xml`, `/robots.txt`, `/feed.xml` (site-wide RSS).
- Per-category, per-tag, and per-author RSS at `/{categories,tags,authors}/[slug]/feed.xml`.
- Default OG image at `/opengraph-image`, plus per-page OG handlers under each `(frontend)` segment.

### Components

A set of React components for the frontend lives under `src/components/`, including `PostCard`, `PostGrid`, `FeaturedPost`, `Hero`, `Header`, `Footer`, `CategoryCardGrid`, `CategoryStrip`, `TagCloud`, `Pagination`, `NewsletterCta`, `RichTextRenderer`, `ThemeToggle`, `ReadingProgressBar`, `PostTOC`, `PostShareBar`, `PostPrevNext`, `AuthorCard`, `JsonLd`, and a few smaller helpers.

### Access control

RBAC policies under `src/access/` gate each CRUD operation:

- `anyone` -- public read.
- `authenticated` -- any logged-in user.
- `is-admin` -- the `admin` role.
- `is-author-or-editor` -- `admin`, `editor`, or `author`.

Three roles (`admin`, `editor`, `author`) are seeded on first run alongside the demo content.

### Demo data

Selecting "Seed demo content" populates 15 posts, 3 authors, 4 categories, and 8 tags. Seeding runs through the **Seed Demo Content** card on the admin dashboard (rendered by `SeedDemoContentCard`) -- click it to start the seed, watch progress, and confirm completion. The seed is idempotent and uses placeholder gradient SVGs that you can replace later.

### Newsletter form

The homepage and footer newsletter forms submit through the form-builder plugin. The seed creates a form with slug `newsletter`; submissions are stored in the `form-submissions` collection and viewable at `/admin/collections/form-submissions`.

## File tree

```
my-blog/
├── configs/
│   ├── codefirst.config.ts        # Code-first config (default)
│   └── visual.config.ts           # Empty config for the visual approach
├── scripts/
│   └── build-search-index.mjs     # Pagefind index builder
├── src/
│   ├── access/                    # RBAC access functions
│   ├── actions/                   # Server actions (newsletter)
│   ├── app/
│   │   ├── (frontend)/            # Public-facing pages and OG handlers
│   │   ├── admin/                 # Generated admin route + seed endpoints
│   │   ├── authors/[slug]/feed.xml/
│   │   ├── categories/[slug]/feed.xml/
│   │   ├── tags/[slug]/feed.xml/
│   │   ├── feed.xml/route.ts
│   │   ├── opengraph-image.tsx
│   │   ├── robots.ts
│   │   ├── sitemap.ts
│   │   ├── globals.css
│   │   └── layout.tsx
│   ├── collections/
│   │   ├── Categories.ts
│   │   ├── Posts/
│   │   └── Tags.ts
│   ├── components/                # Frontend React components
│   ├── endpoints/seed/            # Demo-content seed phases and media
│   ├── singles/
│   │   ├── Homepage/
│   │   ├── Navigation/
│   │   └── SiteSettings/
│   ├── hooks/                     # Shared collection hooks (auto-slug, etc.)
│   └── lib/                       # Cached query helpers, RSS builder, OG layout
├── .env.example
├── next.config.ts
├── package.json
└── tsconfig.json
```

## Next steps

- [Installation](https://nextlyhq.com/docs/getting-started/installation) -- Pick your database, create the super-admin account, and run the dev server.
- [Quick Start](https://nextlyhq.com/docs/getting-started/quick-start) -- Walk through building a blog from scratch to compare against the template.
- [Configuration](https://nextlyhq.com/docs/configuration) -- Add fields, create new collections, or define your own singles.