Using Drafts with Visual Editing

The following guide requires tinacms: 1.0.2 or later.

Want to skip to the end result? Check out the final result

Using Drafts with Visual Editing

In most cases, you will not want to create pages on your production site for your draft documents. This makes handling drafts a challenge with visual editing. In this example we will show how to add visual editing to a draft document using Next.js preview-mode.

In preview-mode getStaticProps will be called on every request. This means that we can conditionally grab draft documents in preview-mode, and keep them out of your production site.

"Preview-mode" can be added in just a few steps:

1. Add the preview-mode api handlers

If you have not installed @tinacms/auth you can do so by running yarn add @tinacms/auth or npm install @tinacms/auth

Create a file called pages/api/preview/enter.{ts,js} this will handle the request to enter preview-mode. This file should look like this:

This handler verifies (With TinaCloud) that the token is valid and then redirects to the document we want to edit.

Next, create a file called pages/api/preview/exit.{ts,js} this will handle the request to exit preview-mode. This file should look like this:

Both of these files are based on the Next.js preview-mode api handlers.

2. Update tina/config

3. Update data fetching

Updates to getStaticPaths

We'll now update our getStaticPaths, so that draft pages are excluded in our production site.

Depending on your use case you can also safely use any value for fallback.

Updates to getStaticProps

Listing pages

First we will create a util function that will either return all the documents or just the production documents depending on if we are in preview-mode.

util/getPosts.{ts,js}

Use this function anywhere you are fetching a list of posts (Posts index page).

Slug pages (optional)

On pages that use SSR or "incremental static regeneration" (ISR), your getStaticProps function will be called on every request. This means that we need to return a 404 when the document is a draft and we are not in preview-mode.

4. Add the exit preview button

To help with exiting preview-mode we can add a button to the top of the site. The button will show up in any page that returns preview: true in getStaticProps.

In pages/_app.{ts,js} add the following:

Now when an editor logs in they will enter preview mode and be able to contextual edit draft documents.

You can see the final result here and if you want to learn more about preview mode see the Next.js docs.

Working with Editorial Workflows

If you're using Editorial Workflows, you'll likely want to ensure that the preview data is fetching content from the branch you're editing. To enable this, subscribe to the branch:change event via the cmsCallback function in the config:

Add another api endpoint at /api/preview/change-branch, which only updates the branch data if we're in preview mode:

Update our request to include the branch (if provided) in getStaticProps: