Drafts

FrogBot’s Draft functionality builds on top of Versions to let you change collection documents but publish only when you’re ready. This functionality allows you to build powerful Preview environments for your data, where you can make sure your changes look good before publishing documents.

Drafts rely on Versions being enabled in order to function.

By enabling Versions with Drafts, your collections can maintain newer, unpublished versions of documents. It’s useful when you want to update a document and save your progress without publishing it immediately. Drafts are especially helpful when building preview implementations.

Options

Collections support two ways to configure drafts. Set versions.drafts to true, or pass an object to configure draft properties.

Draft Option	Type	Default	Description
`autosave`	`boolean \| AutosaveConfig`	`false`	Enable `autosave` to automatically save progress while documents are edited. To enable, set to `true` or pass an object with options.
`schedulePublish`	`boolean \| SchedulePublishConfig`	`false`	Allow for editors to schedule publish / unpublish events in the future. More
`validate`	`boolean`	`false`	Validates draft documents when they’re saved.

Database changes

By enabling drafts on a collection, FrogBot will automatically inject a new field into your schema called _status. The _status field is used internally by FrogBot to store whether a document is set to draft or published. Admin UI status indication Within the Admin UI, if drafts are enabled, a document can be shown with one of three “statuses”:

Draft - if a document has never been published, and only draft versions of the document are present
Published - if a document is published and there are no newer drafts available
Changed - if a document has been published, but there are newer drafts available and not yet published

Draft API

If drafts are enabled on your collection, important and powerful changes are made to your REST, GraphQL, and Local APIs that allow you to specify if you are interacting with drafts or with live documents.

Using the `draft` parameter

When drafts are enabled, the create, update, find, and findByID operations for REST, GraphQL, and Local APIs expose a draft parameter. For write operations, it controls validation and where data is written. For read operations, it determines whether to return draft versions.

// REST API
POST /api/your-collection?draft=true

// Local API
await frogbot.create({
  collection: 'your-collection',
  overrideAccess: true,
  data: {
    // your data here
  },
  draft: true,
})

// GraphQL
mutation {
  createYourCollection(data: { ... }, draft: true) {
    // ...
  }
}

Understanding draft parameter and _status field The draft parameter and _status field work together but serve different purposes: draft parameter - Controls two things:

Validation: When draft: true, required fields are not enforced, allowing you to save incomplete documents
Write location: Determines whether the main collection document is updated
- draft: true - Saves ONLY to versions table (main collection unchanged)
- draft: false or omitted - Saves to BOTH main collection AND versions table

_status field - Indicates whether a document is published or in draft state

Defaults to 'draft' when not explicitly provided
Can be explicitly set in your data to 'published' or 'draft'

First document creation When you first create a document, it’s always written to the main collection (since no document exists yet):

If you don’t specify _status, it defaults to _status: 'draft'
A version is also created in the versions table
The draft parameter controls validation but doesn’t change where the initial document is written

Subsequent updates After initial creation, the draft parameter controls where your updates are written:

draft: true - Only the versions table is updated; the main collection document remains unchanged
draft: false or omitted - Both the main collection and versions table are updated

Important: The draft parameter does NOT control whether a document is published or not. A document remains with _status: 'draft' by default unless you explicitly set _status: 'published' in your data. Publishing a document To publish a document, you must explicitly set _status: 'published' in your data. When you do this:

If you use draft: false or omit it, the main collection will be updated with the published status
If you use draft: true, the _status: 'published' takes precedence and will still update the main collection as published (overriding the draft: true behavior)

Quick reference

Operation	`draft` param	`_status` in data	Result
Create	`true` or `false`	omitted	Main collection updated with `_status: 'draft'`
Create	`true` or `false`	`'published'`	Main collection updated with `_status: 'published'`
Update	`true`	omitted or `'draft'`	Only versions table updated, main collection unchanged
Update	`true`	`'published'`	Main collection updated with `_status: 'published'` (override)
Update	`false` or omitted	omitted	Main collection updated with `_status: 'draft'`
Update	`false` or omitted	`'published'`	Main collection updated with `_status: 'published'`

Required fields Setting _status: "draft" will not bypass required field validation. You need to set draft: true to save incomplete documents as shown in the previous examples.

Reading drafts vs. published documents

In addition to the draft argument within create and update operations, a draft argument is also exposed for find and findByID operations. When draft is set to true while reading a document, FrogBot will return the most recent version from the versions table, regardless of whether it’s a draft or published document. Example scenario:

You create a document with _status: 'published' (published in main collection)
You update with draft: true to make changes without affecting the published version
You update again with draft: true to make more draft changes

At this point, your published document remains unchanged in the main collection, and you have two newer draft versions in the _[collectionSlug]_versions table. When you fetch the document with a standard find or findByID operation, the published document from the main collection is returned and draft versions are ignored. However, if you pass draft: true to the read operation, FrogBot will return the most recent version from the versions table. In the scenario above with two draft versions, you’ll get the latest (second) draft. Note: If there are no newer drafts (e.g., you published a document and haven’t made draft changes since), querying with draft: true will still return the latest version from the versions table, which would be the same published content as in the main collection.

Important: the draft argument on its own will not restrict documents with _status: 'draft' from being returned from the API. You need to use Access Control to prevent documents with _status: 'draft' from being returned to unauthenticated users. Read below for more information on how this works.

Controlling who can see Collection drafts

If you’re using the drafts feature, it’s important for you to consider who can view your drafts, and who can view only published documents. Luckily, FrogBot makes this extremely simple and puts the power completely in your hands.

Restricting draft access

You can use the read Access Control method to restrict who is able to view drafts of your documents by simply returning a query constraint which restricts the documents that any given user is able to retrieve. Here is an example that utilizes the _status field to require a user to be logged in to retrieve drafts:

import type { CollectionConfig } from 'frogbot'

export const Pages: CollectionConfig = {
  slug: 'pages',
  access: {
    read: ({ req }) => {
      // If there is a user logged in,
      // let them retrieve all documents
      if (req.user) return true

      // If there is no user,
      // restrict the documents that are returned
      // to only those where `_status` is equal to `published`
      return {
        _status: {
          equals: 'published',
        },
      }
    },
  },
  versions: {
    drafts: true,
  },
  //.. the rest of the Pages config here
}

Note regarding adding versions to an existing collectionIf you already have a collection with documents, and you opt in to draft functionality after you have already created existing documents, all of your old documents will not have a _status field until you resave them. For this reason, if you are adding versions into an existing collection, you might want to write your Access Control function to allow for users to read both documents where _status is equal to "published" as well as where _status does not exist.

Here is an example for how to write an Access Control function that grants access to both documents where _status is equal to “published” and where _status does not exist:

import type { CollectionConfig } from 'frogbot'

export const Pages: CollectionConfig = {
  slug: 'pages',
  access: {
    read: ({ req }) => {
      // If there is a user logged in,
      // let them retrieve all documents
      if (req.user) return true

      // If there is no user,
      // restrict the documents that are returned
      // to only those where `_status` is equal to `published`
      // or where `_status` does not exist
      return {
        or: [
          {
            _status: {
              equals: 'published',
            },
          },
          {
            _status: {
              exists: false,
            },
          },
        ],
      }
    },
  },
  versions: {
    drafts: true,
  },
  //.. the rest of the Pages config here
}

Controlling who can publish

You can use update Access Control to restrict who can publish documents by returning a query constraint on the _status field. When this constraint prevents publishing, the Admin UI automatically hides the Publish and Unpublish buttons. Here is an example where admins can publish, but editors can only save drafts:

import type { CollectionConfig } from 'frogbot'

export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    update: ({ req: { user } }) => {
      if (!user) {
        // If there is no user, they can't update anything
        return false
      }

      // Admins can update any document, including publishing
      if (user?.role === 'admin') return true

      // Editors can only update documents that are not published.
      return {
        _status: {
          equals: 'draft',
        },
      }
    },
  },
  versions: {
    drafts: true,
  },
}

The update function returns a query constraint instead of a boolean. FrogBot appends this constraint to the update query, so only documents where _status is not published can be updated by editors. This also blocks scheduled publish jobs from executing for those users. The create function uses a data check instead since there is no existing document to query against.

Scheduled publish

FrogBot provides for an ability to schedule publishing / unpublishing events in the future, which can be helpful if you need to set certain documents to “go live” at a given date in the future, or, vice versa, revert to a draft state after a certain time has passed. Enable this functionality on a collection with the versions.drafts.schedulePublish: true property. Pass an object instead to configure the time picker:

Option	Type	Default	Description
`timeFormat`	`string`	`'h:mm aa'`	Time format for the picker, such as `'HH:mm'` for a 24-hour clock.
`timeIntervals`	`number`	`5`	Minutes between the times offered by the picker.

Important: if you are going to enable scheduled publish / unpublish, you need to make sure your FrogBot app is set up to process Jobs. This feature works by creating a Job in the background, which will be picked up after the job becomes available. If you do not have any mechanism in place to run jobs, your scheduled publish / unpublish jobs will never be executed.

Unpublishing drafts

If a document is published, the FrogBot Admin UI will be updated to show an “unpublish” button at the top of the sidebar, which will “unpublish” the currently published document. Consider this as a way to “revert” a document back to a draft state. On the API side, this is done by simply setting _status: 'draft' on any document.

Reverting to published

If a document is published, and you have made further changes which are saved as a draft, FrogBot will show a “revert to published” button at the top of the sidebar which will allow you to reject your draft changes and “revert” back to the published state of the document. Your drafts will still be saved, but a new version will be created that will reflect the last published state of the document.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Options

Database changes

Draft API

Using the `draft` parameter

Reading drafts vs. published documents

Controlling who can see Collection drafts

Restricting draft access

Controlling who can publish

Scheduled publish

Unpublishing drafts

Reverting to published

​Options

​Database changes

​Draft API

​Using the draft parameter

​Reading drafts vs. published documents

​Controlling who can see Collection drafts

​Restricting draft access

​Controlling who can publish

​Scheduled publish

​Unpublishing drafts

​Reverting to published

Options

Database changes

Draft API

Using the `draft` parameter

Reading drafts vs. published documents

Controlling who can see Collection drafts

Restricting draft access

Controlling who can publish

Scheduled publish

Unpublishing drafts

Reverting to published