NACELLE DOCS

You are viewing the v1 Nacelle Docs for existing merchants.New merchants can find the V2 docs here: nacelle.com/docs.

# Using Gatsby with Nacelle

Gatsby (opens new window) is a React-based framework for generating Progressive Web Applications. Thanks to Gatsby's plugin ecosystem (opens new window), you can quickly add features to your app and connect to external data sources, including Nacelle.

# Gatsby-Source-Nacelle

# The Basics

Gatsby-Source-Nacelle (opens new window) is a Gatsby plugin that sources data from Nacelle's Storefront API. This connection allows you to get all of a store’s product data and content data.

The nacelle-react repository contains an example project (opens new window) which demonstrates using gatsby-source-nacelle to build out pages for products, collections, and content. This example project makes use of @nacelle/react-components (opens new window) and @nacelle/react-hooks (opens new window), which are used to add cart & checkout functionality.

With a connection to Nacelle for your product data, content, and checkout, you have everything you need to build a custom React storefront with a highly-scalable back end.

# Configuring Your Store

While we recommend setting up your store's pages, blogs, and collections the same way as described in the Nacelle + Nuxt docs, you are free to use a custom setup.

# Install

WARNING

Projects powered by Nacelle's v1 APIs must use a version of @nacelle/gatsby-source-nacelle below 8.0.0. To get the latest v1-compatible version, please install @nacelle/[email protected].

# With Yarn

yarn add @nacelle/[email protected]

# With NPM

npm i @nacelle/[email protected]

# Configure

Then add the plugin to your gatsby-config.js. Be sure to include your nacelle-space-id and nacelle-graphql-token, which you can find in your Space settings in the Nacelle Dashboard (opens new window).

# Adding Your Credentials Securely

Create a .env file with your Nacelle credentials. For more information about using environment variables in a Gatsby project, check out the Gatsby docs (opens new window).

# .env
NACELLE_SPACE_ID=your-nacelle-space-id
NACELLE_GRAPHQL_TOKEN=your-nacelle-graphql-token

// gatsby-config.js
require('dotenv').config()

module.exports = {
  plugins: [
    {
      resolve: '@nacelle/gatsby-source-nacelle',
      options: {
        nacelleSpaceId: process.env.NACELLE_SPACE_ID,
        nacelleGraphqlToken: process.env.NACELLE_GRAPHQL_TOKEN,
      },
    },
  ],
}

# Additional Features

# Incremental Builds

@nacelle/gatsby-source-nacelle uses build caching (opens new window) to support incremental builds (opens new window). If you'd like to force @nacelle/gatsby-source-nacelle to re-source product, collection, and content data from Nacelle's Storefront API after a given interval, you can do so by providing a cacheDuration value (in milliseconds).

For example, a build with the following configuration will force a re-fetch of product, collection, and content data after 24 hours, even if that data hasn't changed:

// gatsby-config.js
require('dotenv').config()

module.exports = {
  plugins: [
    {
      resolve: '@nacelle/gatsby-source-nacelle',
      options: {
        nacelleSpaceId: process.env.NACELLE_SPACE_ID,
        nacelleGraphqlToken: process.env.NACELLE_GRAPHQL_TOKEN,
        cacheDuration: 1000 * 60 * 60 * 24, // 1 day in ms
      },
    },
  ],
}

# Gatsby Image

@nacelle/gatsby-source-nacelle (opens new window) provides a way to easily integrate with Gatsby's powerful image processing tools (opens new window) to enable progressive image loading with visually-compelling loading strategies such as Traced SVG (opens new window) and Background Color (opens new window). Gatsby Image is directly compatible with the featuredMedia of content, collections, and products, as well as the media of products.

Enabling these image processing techniques requires installing gatsby-source-filesystem (opens new window), gatsby-plugin-sharp (opens new window), and gatsby-transformer-sharp (opens new window):

npm i gatsby-source-filesystem gatsby-plugin-sharp gatsby-transformer-sharp

Next, register gatsby-plugin-sharp and gatsby-tranformer-sharp in gatsby-config.js. You don't need to register gatsby-source-filesystem.

// gatsby-config.js

module.exports = {
  plugins: [
    // ...other plugins,
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
  ],
}

You'll also need to install either gatsby-image (opens new window) or Gatsby's latest offering, gatsby-plugin-image (opens new window). Please refer to the example project (opens new window) to see how @nacelle/gatsby-source-nacelle can be used with gatsby-plugin-image (opens new window).

# Previewing Content from Contentful

When Nacelle indexes content data from your Contentful space, only published content entries are indexed. To skip the Nacelle index and instead source unpublished content directly from Contentful, simply provide some additional environment variables and plugin options:

# .env

# always required
NACELLE_SPACE_ID=your-nacelle-space-id
NACELLE_GRAPHQL_TOKEN=your-nacelle-graphql-token

# required for Contentful preview
CONTENTFUL_PREVIEW_SPACE_ID=your-contentful-space-id
CONTENTFUL_PREVIEW_API_TOKEN=your-contentful-preview-api-token
ENABLE_GATSBY_REFRESH_ENDPOINT=true

// gatsby-config.js
require('dotenv').config()

module.exports = {
  plugins: [
    {
      resolve: '@nacelle/gatsby-source-nacelle',
      options: {
        // always required
        nacelleSpaceId: process.env.NACELLE_SPACE_ID,
        nacelleGraphqlToken: process.env.NACELLE_GRAPHQL_TOKEN,
        // required for Contentful preview
        contentfulPreviewSpaceId: process.env.CONTENTFUL_PREVIEW_SPACE_ID,
        contentfulPreviewApiToken: process.env.CONTENTFUL_PREVIEW_API_TOKEN,
        // optional toggle
        cmsPreviewEnabled: true,
      },
    },
  ],
}

Your Contentful Preview API Token can be found in your Contentful Settings under Api keys.

By default, if the contentfulPreviewSpaceId and contentfulPreviewApiToken options are provided, content data will be sourced from Contentful's Preview API instead of the Nacelle content index. Setting cmsPreviewEnabled to false will allow you to toggle back to sourcing content data from the Nacelle content index while still providing contentfulPreviewSpaceId and contentfulPreviewApiToken options.

Adding ENABLE_GATSBY_REFRESH_ENDPOINT=true to .env enables content refreshing (opens new window) during local development. A Refresh Data button will appear in Gatsby's GraphiQL explorer. Typically, content changes made in Contentful take about 5-10 seconds before the data can be successfully refreshed.

For more information about setting up a Gastby Preview site, please refer to the Gatsby docs (opens new window).

# Next Steps

Once you've established a connection to Nacelle's Storefront API, it's time to start building out your store. Check out the example project (opens new window) to learn how to create a basic eCommerce store with product & content data provided by @nacelle/gatsby-source-nacelle.

← Event Dispatcher Recipe →