You're reading docs for Nextly Alpha. APIs may change between releases.

Guides

Draft / Published Status

Enable a Draft / Published lifecycle on collections and singles, with side-by-side examples for code-first config and the Visual Schema Builder.

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:

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

PropertyValue
Typevarchar(20) on Postgres / MySQL, text on SQLite
Default'draft'
NullableNo (NOT NULL)
IndexedYes — {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:

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.

What a publish checks

Moving a document to published validates it as it goes live, not only the fields the request sends. A status-only publish (data: { status: "published" }) judges the stored document with the request's values on top, so a value saved while the document was a draft is checked again before it goes live. That covers a first publication, a republish after an unpublish, a bulk publish, and publishing every language at once.

On a collection entry, the document going live includes its field-group (component) values and its many-to-many relationships, read as they are stored. A required component that has no instance, or a required many-to-many relationship with no links, refuses the publish with a validation error on that field. Fix the field, then publish. The custom validate functions of top-level component and many-to-many fields run too, and so do the rules on each component's own fields: a component instance saved before one of its fields became required, or before a validate was tightened, refuses the publish with an error that names the field inside the component (hero.code). A password field inside a component is the exception: a stored password is never read back, so it is judged only when the instance is written.

On a localized collection, and on one whose components hold translated values, a required component and the rules inside a component are enforced for the default language only, as a translated field's required is, so one finished language can go live while another is still incomplete.

Sending published again to a document that is already live, with no pending draft, is not checked again.

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:

// Read it in every language first: that read's `_rev` covers each
// translation, so the takedown is refused if any of them changed since.
const current = await nextly.findByID({
  collection: "pages",
  id: page.id,
  locale: "*",
});

// Take the document down in every language it has.
await nextly.update({
  collection: "pages",
  id: page.id,
  locale: "*",
  data: { status: "draft", _rev: current._rev },
});

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:

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 reads the Nextly the process has started, and waits for a start still under way. A project starts it when the server starts with a src/instrumentation.ts that calls createRegister(config)() in register(), which the blank and blog scaffolds ship and an existing app adds as part of installation. Where nothing has started it, in a standalone script or an app without the hook, the proxy throws Nextly services not initialized the moment it is the first Nextly code a worker runs.

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