next-tinacms-contentful
A utility library for using Contentful with TinaCMS and Next.js
Usage
If you are looking to use Contentful in client-side JS, please see one of the following:
If you are looking to use Contentful inside of Next.js' build-time and serverless logic like API routes, getStaticProps
and getServerSideProps
, continue reading:
Installation
To install the package, run:
npm install next-tinacms-contentful react-tinacms-contentful tinacms-contentful contentful contentful-management
Fetching Entries On The Server
Fetching A Single Entry
To fetch a single entry, you can use getEntry
:
import getEntry from 'next-tinacms-contentful'
const contentfulOptions = {
spaceId: /* Contentful Space ID */,
defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
accessTokens: {
delivery: /* Contentful delivery access token for the space */,
preview: /* Contentful preview access token for the space */,
}
clientId: /* OAuth App Client ID */,
redirectUrl: /* OAuth App Callback URL */,
rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
}
export async function getStaticProps() {
try {
const entry = await getEntry('EXAMPLE_ID', contentfulOptions);
return {
props: {
entry
}
}
} catch (error) {
console.error(error)
return {
notFound: true
}
}
}
Fetching Many Entries
To fetch many entries, you can use getEntries
:
import getEntries from 'next-tinacms-contentful'
const contentfulOptions = {
spaceId: /* Contentful Space ID */,
defaultEnvironmentId: /* Contentful environment ID to use by default. Default: master */,
accessTokens: {
delivery: /* Contentful delivery access token for the space */,
preview: /* Contentful preview access token for the space */,
}
clientId: /* OAuth App Client ID */,
redirectUrl: /* OAuth App Callback URL */,
rateLimit: /* API Rate Limit for your Contentful Plan (Requests per second). Default: 4 */,
insecure: /* If true, uses same-site HTTPS cookies to create a session. Default: false */
}
export async function getStaticProps() {
try {
const entry = await getEntries({ content_type: "EXAMPLE_CONTENT_TYPE_ID" }, contentfulOptions);
return {
props: {
entry
}
}
} catch (error) {
console.error(error)
return {
notFound: true
}
}
}
Edit Mode
Server-side Sessions with Next.js Preview Mode
You can enable an "edit mode" for your site using server-side sessions with Next.js Preview mode, which uses HTTP only cookies to allow server-side logic to be run in front of requests, providing a user specific payload of data on context.previewData
in getStaticProps
, getServerSideProps
, and in API routes, as well as allowing getStaticProps
to work like getServerSideProps
when users log in to edit pages to allow editing-specific business logic.
First, in pages/api
add a new API route called editing.js
with the following contents:
import { editModeHandler } from 'next-tinacms-contentful'
export const editingHandler = editModeHandler(60)
editModeHandler
creates a serverless function that handles creating an "editing session" by enabling Next.js preview mode for the current user if it is not enabled, and adding metadata to Next.js' preview data to allow changing how the page behaves for editing.
Values
Key | Type | Description |
---|---|---|
context.previewData.tina_enabled |
boolean |
True if logged in, false if not |
context.previewData.contentful_bearer_token |
string | null |
If defined, is the bearer token for the current logged in user |
Then, you need to update the CMS to enable edit mode when the user finishes logging in. We do this by adding some configuration to the ContentfulProvider
, which is usually found in pages/_app.js
:
import { toggleEditing } from 'next-tinacms-contentful'
export function MyApp({ pageProps, Component }) {
const cms = useMemo(() => {
...
}, [])
return (
<TinaProvider cms={cms}>
<ContentfulProvider
onLogin={() => toggleEditing(true)}
onLogout={) => toggleEditing(false)}
>
<Component {...pageProps} />
</ContentfulProvider>
</TinaProvider>
)
}
toggleEditing
makes a HTTP POST request to the api/editing
route, enabling or disabling the cms based on the boolean value passed in, and logs any errors to the user's console.
Finally in any of your pages, you can use getStaticProps
or getServerSideProps
to check if edit mode is enabled:
export function getStaticProps(context) {
const entry = getEntry('EXAMPLE_ID', {
...contentfulOptions,
mode: context.previewData.tina_enabled ? "preview" : "delivery"
})
return {
props: {
entry
}
}
}
APIs
The library has the following core APIs:
- ContentfulClient: an API client for communicating with Contentful that integrates directly with the CMS.
-
ContentfulMediaStore: a media store that uses a
ContentfulClient
to manage media for a single space. - Provider: a React provider for official plugins and authorization.
- Hooks: a series of React Hooks for interacting with Contentful in your React app and CMS Plugins.
- Server-side Methods: utility methods for interacting with Contentful on the server.
There are other public APIs as well. To learn more, read the full Next.js API documentation or read the full JavaScript API documentation.
Server-side Methods
-
getEntry
: fetch a publisheddelivery
, draftpreview
, or editablemanagement
entry. -
getEntries
: fetch multiple publisheddelivery
, draftpreview
, or editablemanagement
entries. -
getAsset
: fetch a publisheddelivery
, or draftpreview
asset. -
getAssets
: fetch multiple publisheddelivery
, or draftpreview
assets. -
proxy
: [EXPERIMENTAL] proxies requests to Contentful in server side logic, attaching bearer tokens from edit mode on the way. -
toggleEditing
: sends a fetch request to enable edit mode. -
editModeHandler
: a serverless request handler for toggling edit mode in a Next.js API function.