Vercel
The Vercel App from Contentful helps your team easily configure and maintain working preview environments for your Next.js application hosted on Vercel and powered by Contentful.
With a bit of upfront configuration, your content creators will be able to preview content changes before publishing them directly from Contentful's "side by side" preview editor. With a bit more effort your team can also implement Contentful's Live Preview SDK, which unlocks an even more powerful set of previewing features like live updates and in-place editing.
Overview
Once installed and configured, the Vercel App will enable content previews in Contentful's side by side preview editor for any content type you specify.
The Vercel App also provides shareable preview URLs that are accessible to your team members who may not have direct access to your Vercel project.
The Vercel App drastically simplifies the process for configuring and maintaining working preview URLs that are compatible with Contentful's preview features.
Requirements
To set up the Vercel App, you will need:
Space Admin access to the Contentful space where you are installing it
Project Admin access to the Vercel project where your Next.js application connected to Contentful is deployed
A developer from your team to help you adapt your Next.js application to work with Contentful's preview features
Note: This guide assumes that you already have a working Next.js application, deployed on Vercel and connected to a Contentful space. If you're starting a project from scratch you might want to consult a getting started guide to quickly bootstrap a new project.
Step 1: Configuring your Next.js application to support Draft Mode
Before your team can even begin to use the Vercel App, your Next.js application will need to be set up to support "Draft Mode." Draft Mode is a Next.js feature that allows your team to switch between viewing pages on your site in "production mode" (i.e. as your end users would see them) and viewing pages in "preview mode" (as your content creators want to see them while editing unpublished content).
You will either need to be a developer or to enlist the help of a developer on your project to make the changes in your codebase required to support both activating Draft Mode as well as viewing preview content when Draft Mode is enabled.
Though this first step is not trivial, Contentful provides a developer guide alongside developer tooling to ease the implementation of Draft Mode in your project. This guide will cover in depth the following important topics:
Setting up a route handler to activate Draft Mode. Your developer will need to install a "route handler" that the Vercel App will make use of to securely enable preview features in your application when your team is using Contentful's preview tool. This is a required step.
Adding support for Draft Mode in your application. Our developer documentation provides higher level guidance to your developer on how to incorporate Draft Mode into the Contentful API queries in your application, as well as on how to implement Contentful's more powerful Live Preview features like in-place editing and live updates.
Note: Your team does not need to fully implement all of Contentful's preview features in order to make use of the Vercel App. However, your application should support the route handler guidance given above and should implement at least some of Contentful's preview features before you proceed to the next step.
Step 2: Installing the app and connecting to Vercel
The app can be installed either through the Contentful Marketplace or within your Contentful space.
Configuring access to Vercel
On the first step of the app installation process, you will need to paste in a "Vercel Access Token" that gives the Vercel App access to your team's Vercel projects.
To obtain a Vercel Access Token to use with the App:
Follow these instructions from Vercel for creating an Access Token. Name the token whatever you wish.
Important: You must choose a Team from the list of scopes on the "Create Token" form. If you're a member of multiple Teams in Vercel, choose the one that contains the Vercel project you are trying to connect to.
Be sure to specify "No expiration" -- otherwise you will need to visit the app config page and regenerate your token regularly.
Copy the the token value, and paste it into the "Vercel Access Token" field of the Contentful app.
If you successfully created and pasted a valid Vercel Access Token, you should see an option to choose a Project.
Connecting to your Vercel project
From the "Project" dropdown, choose a Vercel project to connect to. This should be the project that the Contentful space you are installing the app in is connected to.
Next you'll need to specify the "route" in your project that is configured to enable Draft Mode. (You will need to work with your developer to install such a route, as described in Step 1 above.)
Note: If there are multiple routes available in the dropdown and you're uncertain which one to choose, speak with your development team. If your developer followed our guidance the correct route should be named "api/enable-draft" or something similar.
Step 3: Defining preview environments for content types
Now that you've successfully connected to your Vercel project, you can configure preview environments for specific content types you'd like your content editors to be able to view in preview.
The app itself will take care of providing a domain and other elements that are required for your preview environment to work correctly with Contentful. But for each content type you will still need to specify the path where content entries of a particular content type are viewable.
In general the "path" is simply a URL on your website where certain kinds of content can be viewed. But since different content entries will have distinct URLs, you also need to provide the "token" your app uses to identify a specific content entry to preview.
A detailed guide of which "tokens" are available to use can be found here or in a pop up reference that appears when you click "View tokens":
A few examples illustrate how this could work in a hypothetical application:
Your project hosts a blog where blog posts are viewable in a URL that looks like http://www.example.com/blog/a-blog-post-for-today. The value "a-blog-post-for-today" is present in a "slug" field in your Blog Post content type. For the "path" field you would put:
/blog/{entry.fields.slug}Your project hosts a knowledge base where knowledge articles are viewable in a URL that looks like http://www.example.com/help/questions/7yr4hfr17dfsasdf. The value "7yr4hfr17dfsasdf" is the Contentful ID of your Knowledge Article content entries. For the "path" field you would put:
/help/questions/{entry.sys.id}
Note: Constructing a working preview path requires some knowledge about how your application's routes are structured as well as which fields in Contentful those routes use to identify specific content entries. Consult with your development team if you are unclear about how to configure a working preview path.
Using the app
Once you have successfully configured preview paths for the content types, your content team can start taking advantage of preview features available in Contentful's side by side preview editor immediately.
Setting up content preview
Normally, your team would configure and manage content preview environments by going to Settings > Content preview. Though you can continue to add and configure additional preview environments, you will not need to do extra configuration to operationalize previews provided by the Vercel app.
Once the Vercel app is installed correctly, you will see a section on the content preview settings that directs your users back to app config page where they can manage Vercel-specific content preview settings (described above):
There are a few additional settings on this page that remain pertinent:
You will still need to specify the "Preview mode" your app supports -- either "Live preview" or "Preview in new tab"
Custom preview tokens are still configured and managed from the content preview settings screen. Any custom tokens you define here will be available in the preview path field as described in the section above.
Using content preview
Your users can trigger preview mode directly from the entry sidebar:
If you have multiple preview environments (as in the image above), the preview environment provided by the Vercel App will be labeled as such. Your users can switch between preview modes using the "change" link.
Note: If the Vercel App is the only environment you have configured for a space, your users will not see the "Platform" and "change" options.
Troubleshooting
You may find particular error messages appear while configuring the Vercel app. Below are some of the most common errors you might encounter for each configuration step and suggestions on how best to remedy the errors.
Authentication
Invalid access token. The token may not be a valid Vercel access token. Follow our instructions above for creating a valid Vercel access token.
Token is not scoped to a team. The access token you have created within Vercel is not scoped to a specific team, but rather scoped to the entire account. Ensure that when creating the token, you select a specific team for the specification titled Scope.
Token has expired. The access token you have added is expired. Try creating a new token within Vercel. We recommend creating a token without an expiration.
Project selection
The project you have configured is no longer available. Please select another one. The project you had previously configured is no longer available in the list of available Vercel projects, as it was most likely deleted within Vercel. Try selecting a different project.
It looks like you’ve configured an environment variable, CONTENTFUL_SPACE_ID, in the selected Vercel project that doesn’t match the current id of the space, <space_id>, where this app is installed. Ensure that the environment variable is pointing to the correct Contentful space ID where the app is installed. The environment variable can be found within your Vercel project under Settings > Environment Variables. (Note that this message is a warning -- it's possible that your developers are using a different way to identify the space where your Contentful content resides. If things are working correctly you may safely ignore this warning.)
The project you have configured does not have protection bypass enabled. Please enable it. Ensure that the selected Vercel project has Protection Bypass for Automation enabled -- this is critical for your application to load correctly in Contentful's side-by-side preview window. This setting can be found within your Vercel project under Settings > Deployment Protection; scroll down to the Protection Bypass for Automation section where you can then enable the setting.
Draft Mode route handler selection
The route you have configured is no longer available. Please select another one. The route you had previously selected for enabling Draft Mode is no longer available in the list of configured routes associated with your project. Try selecting a different route from the dropdown, and speak with your development team if you can't find the appropriate route.
It looks like your Vercel project doesn't have any routes configured yet. The error will appear along with a text input to support manual input of the route. This may be an indicator that your application is not yet set up correctly (see Step 1 above for guidance on what's required from your development team to support the Vercel app). You can also confirm that these routes exist by viewing your project on Vercel. Under Deployments, click on the latest deployment. Under the Deployment Details section of your latest deploy, click Deployment Summary > Functions, where the routes should be listed (e.g
/api/enable-draft).
Content type and preview path selection
Field is empty. Ensure there exists a preview path for each content type you have configured under Preview settings.
Path must start with a "/", and include a {token}. Ensure your preview path begins with a forward slash and includes a dynamic token enclosed by curly braces e.g
/blogs/{entry.fields.slug}.See this guide if you're having difficulties working out how to construct a preview path that works correctly with how your team is using Contentful.