@nacelle/contentful-preview-connector
v2.0.1
Published
Extends the [`@nacelle/client-js-sdk`](https://www.npmjs.com/package/@nacelle/client-js-sdk) to enable previewing of unpublished content from Contentful.
Downloads
7,166
Maintainers
Keywords
Readme
Extends the @nacelle/client-js-sdk
to enable previewing of unpublished content from Contentful.
Nacelle Contentful Preview Connector
The Nacelle Client JS SDK uses connectors in the data
module for fetching Nacelle data. By default the SDK is either fetching data from Nacelle's GraphQL or from static JSON files generated during the Nuxt build process.
With this package we can update the data
module so that by default it will fetch data directly from Contentful's Preview API. That way you can view edits and changes on Contentful without needing to reindex those updates with Nacelle.
Usage
import NacelleClient from '@nacelle/client-js-sdk'
import { createContentfulPreviewConnector } from '@nacelle/contentful-preview-connector'
// Initialize the Nacelle Client
const client = new NacelleClient(clientOptions)
// Initialize the Preview Connector
const contentfulConnector = createContentfulPreviewConnector(client, {
// the parameters in `contentfulConfig` match the constructor for
// the Contentful client (https://github.com/contentful/contentful.js#configuration),
// with the exception of `host`, which is optional, and defaults to 'preview.contentful.com'
contentfulConfig: {
space: '<your-contentful-space-id>',
accessToken: '<your-contentful-preview-api-token>'
// Note: the Contentful Preview API token is not the same as your Content Delivery API token
},
// Optional Parameter defaults
contentfulPreviewLocales: ['en-US'],
include: 3
})
// Update the data module with the new connector
client.data.update({
connector: contentfulConnector
})
// Homepage data will be fetched directly from preview API
const pageData = await client.data.page({ handle: 'homepage' })
Differences from Nacelle Client JS SDK Methods
The Nacelle Client JS SDK's data.article(params)
method assumes that if a blogHandle
parameter isn't provided, that the an article's blogHandle
should default to 'blog'
.
In order to accomodate content models for article
s that don't contain a blogHandle
field, the @nacelle/contentful-preview-connector
does not assign a default value for blogHandle
. If your article
content model does contain a blogHandle
field, please supply this blogHandle
as a parameter to the preview connector's .article
method.
For example:
// EXAMPLE A: Articles contain a 'blogHandle' field:
// @nacelle/client-js-sdk
nacelle.data.article({ handle: 'chapter-one' })
nacelle.data.article({ handle: 'chocolate-cake', blogHandle: 'recipes' })
// @nacelle/contentful-preview-connector
contentfulConnector.article({ handle: 'chapter-one', blogHandle: 'blog' })
contentfulConnector.article({ handle: 'chocolate-cake', blogHandle: 'recipes' })
// EXAMPLE B: Articles don't contain a 'blogHandle' field:
// @nacelle/client-js-sdk
nacelle.data.article({ handle: 'chapter-one' })
nacelle.data.article({ handle: 'chocolate-cake' })
// @nacelle/contentful-preview-connector
contentfulConnector.article({ handle: 'chapter-one' })
contentfulConnector.article({ handle: 'chocolate-cake' })
Examples
See our examples for setting up this package with our different frontend app frameworks:
Nuxt
Setting up your Nacelle Starter Project to enable Contenful previews is a straightforward process using Nuxt plugins.
1. Add contentful-previews.js
into your Nuxt project
Create a file contentful-previews.js
in your Nuxt's /plugins
directory and paste the following code.
import { createContentfulPreviewConnector } from '@nacelle/contentful-preview-connector'
export default ({ app }) => {
if (process.env.NACELLE_PREVIEW_MODE === 'true') {
// Checks .env file for proper config variables
if (!process.env.NACELLE_CMS_PREVIEW_TOKEN) {
throw new Error(
"Couldn't get data from your CMS. Make sure to include NACELLE_CMS_PREVIEW_TOKEN in your .env file"
)
}
if (!process.env.NACELLE_CMS_PREVIEW_SPACE_ID) {
throw new Error(
"Couldn't get data from your CMS. Make sure to include NACELLE_CMS_PREVIEW_SPACE_ID in your .env file"
)
}
// Initialize the Contentful Preview Connector
const contentfulConnector = createContentfulPreviewConnector(
app.$nacelle.client,
{
contentfulConfig: {
space: process.env.NACELLE_CMS_PREVIEW_SPACE_ID,
accessToken: process.env.NACELLE_CMS_PREVIEW_TOKEN
}
}
)
// Update the Nacelle JS SDK Data module to use preview connector
app.$nacelle.data.update({
connector: contentfulConnector
})
}
}
2. Update nuxt.config.js
Update your nuxt.config.js
file to set the ssr key and include the new plugin file you created.
let previewMode = process.env.NACELLE_PREVIEW_MODE
if (previewMode === 'false') previewMode = false
export default {
ssr: !previewMode,
plugins: ['~/plugins/contentful-preview']
}
And update the env
object in the config.
env: {
nacelleSpaceID: process.env.NACELLE_SPACE_ID,
nacelleToken: process.env.NACELLE_GRAPHQL_TOKEN,
buildMode: process.env.BUILD_MODE,
NACELLE_PREVIEW_MODE: process.env.NACELLE_PREVIEW_MODE,
NACELLE_CMS_PREVIEW_SPACE_ID: process.env.CONTENTFUL_SPACE_ID,
NACELLE_CMS_PREVIEW_TOKEN: process.env CONTENTFUL_PREVIEW_API_TOKEN
},
3. Update .env
Update your Nuxt app's .env
file to include variables for initializing the Contentful preview connector.
# .env
NACELLE_PREVIEW_MODE=true
NACELLE_CMS_PREVIEW_SPACE_ID=your-contentful-space-id
NACELLE_CMS_PREVIEW_TOKEN=your-contentful-preview-api-token
You're all set! Running npm run dev
your Nacelle Nuxt app will now fetch data directly from Contentful. Try updating a piece of content and refreshing the page without publishing.
Upgrading from 0.1.x
If upgrading from @nacelle/[email protected]
, please update your preview connector client constructor as follows:
// 0.1.x
const contentfulConnector = new NacelleContentfulPreviewConnector({
contentfulSpaceID: '<your-contentful-space-id>',
contentfulToken: '<your-contentful-preview-api-token>'
// ...other config,
})
// 2.x.x
// Initialize the Nacelle Client
const client = new NacelleClient(clientOptions)
// Initialize the Preview Connector
const contentfulConnector = createContentfulPreviewConnector(client, {
contentfulConfig: {
space: '<your-contentful-space-id>',
accessToken: '<your-contentful-preview-api-token>'
},
// Optional Parameter defaults
contentfulPreviewLocales: ['en-US'],
include: 3
})
Also, please see the docs on the use of blogHandle
with the .article
method.
Upgrading from 1.x.x to 2.x.x
// 1.x.x
import NacelleContentfulPreviewConnector from '@nacelle/contentful-preview-connector'
const contentfulConnector = new NacelleContentfulPreviewConnector({
contentfulConfig: {
space: '<your-contentful-space-id>',
accessToken: '<your-contentful-preview-api-token>'
// other Contentful config (https://github.com/contentful/contentful.js#configuration)
}
// ...other config,
})
// 2.x.x
import { createContentfulPreviewConnector } from '@getnacelle/contentful-preview-connector'
const contentfulConnector = createContentfulPreviewConnector(
// Add NacelleClient object as first argument
client,
// Include existing NacelleContentfulPreviewConnector options
{
contentfulConfig: {
space: '<your-contentful-space-id>',
accessToken: '<your-contentful-preview-api-token>'
// other Contentful config (https://github.com/contentful/contentful.js#configuration)
}
// ...other config,
}
)