npm package: @nacelle/contentful-preview-connector
Description: Extends the [`@nacelle/client-js-sdk`](https://www.npmjs.com/package/@nacelle/client-js-sdk) to enable previewing of unpublished content from Contentful.
Author: Andrew Laskey
Latest version: 2.0.1
Deprecated: Please see docs.nacelle.com for up-to-date guidance on building frontend projects powered by Nacelle

Extends the [`@nacelle/client-js-sdk`](https://www.npmjs.com/package/@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](https://docs.getnacelle.com/api-reference/client-js-sdk.html#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](https://www.contentful.com/developers/docs/references/content-preview-api/). That way you can view edits and changes on Contentful without needing to reindex those updates with Nacelle.

## Usage

```js
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:

```js
// 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](https://docs.getnacelle.com/nuxt/intro-nuxt.html) to enable Contenful previews is a straightforward process using [Nuxt plugins](https://nuxtjs.org/guide/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.

```js
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.

```js
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.

```js
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.

```bash
# .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:

```js
// 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](#differences-from-nacelle-client-js-sdk-methods).

## Upgrading from 1.x.x to 2.x.x

```js
// 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,
  }
)
```