@nacelle/contentful-preview-connector
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    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 previewConnector = createContentfulPreivewConnector(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'],
      contentfulIncludeDepth: 3
    })
    
    // Update the data module with the new connector
    client.data.update({
      connector: previewConnector
    })
    
    // 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 include the new plugin file you created.

    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 previewConnector = new NacelleContentfulPreviewConnector({
      contentfulSpaceID: 'CONTENTFUL_PREVIEW_SPACE_ID',
      contentfulToken: 'CONTENTFUL_PREVIEW_API_TOKEN'
      // ...other config,
    })
    
    // 1.x.x
    const contentfulConnector = new NacelleContentfulPreviewConnector({
      contentfulConfig: {
        space: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.CONTENTFUL_PREVIEW_API_TOKEN
        // other Contentful config (https://github.com/contentful/contentful.js#configuration)
      }
      // ...other config,
    })

    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: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.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: process.env.CONTENTFUL_SPACE_ID,
          accessToken: process.env.CONTENTFUL_PREVIEW_API_TOKEN
          // other Contentful config (https://github.com/contentful/contentful.js#configuration)
        }
        // ...other config,
      }
    )

    Keywords

    none

    Install

    npm i @nacelle/contentful-preview-connector

    DownloadsWeekly Downloads

    4,375

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    306 kB

    Total Files

    27

    Last publish

    Collaborators

    • dzouras
    • badiolaignacio
    • leviwhalen
    • andrew-nacelle
    • nwrichmond
    • brianvanderson
    • cbodtorf
    • johnstonbl01
    • krisq
    • curbol
    • irnoble
    • jongeyer
    • alexnacelle
    • nacelle-bot
    • austin1237