Gatsby-Source-Nacelle
This plugin connects Gatsby to Nacelle’s Hail Frequency API, which gives you access to the product data (individual products, collections, etc.) and content data (blog posts, articles, etc.) needed to build an eCommerce storefront.
What is Nacelle?
Nacelle is a headless eCommerce platform made for developers who want to create superior customer buying experiences. When you connect your Shopify, Magento, or custom eCommerce store to Nacelle, our proprietary indexing system supplies a high-performance connection to your back end.
To learn more, check out the Nacelle docs.
Quick Start
Follow these steps to add gatsby-source-nacelle
to your Gatsby site:
Install
With Yarn
yarn add @nacelle/gatsby-source-nacelle
With NPM
npm i @nacelle/gatsby-source-nacelle
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.
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.
# .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 to support incremental builds. If you’d like to force @nacelle/gatsby-source-nacelle
to re-source product, collection, and content data from Nacelle’s Hail Frequency 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
provides a way to easily integrate with Gatsby’s powerful image processing tools to enable progressive image loading with visually-compelling loading strategies such as Traced SVG and Background Color. 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, gatsby-plugin-sharp
, and gatsby-transformer-sharp
:
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
or Gatsby’s latest offering, gatsby-plugin-image
. Please refer to the example project to see how @nacelle/gatsby-source-nacelle
can be used with gatsby-plugin-image
.
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 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.
Next Steps
Once you’ve established a connection to Nacelle’s Hail Frequency API, it’s time to start building out your store. Check out the example project to learn how to create a basic eCommerce store with product & content data provided by @nacelle/gatsby-source-nacelle
.