This package has been deprecated

Author message:

Please see docs.nacelle.com for up-to-date guidance on building frontend projects powered by Nacelle

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 articles 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/contentful-preview-connector@0.1.x, 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,
  }
)