Prebuilt connectors are back-end time savers when paired with traditional monolithic systems. They often leverage webhooks for near-real-time data syncs and write the transformations on your behalf.

🚧
Prebuilt connectors are opinionated and, while they are great for most, they may not be the best match for every enterprise merchant

Shopify Connector

The Shopify Connector indexes products and collections into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Shopify and Nacelle Dashboards.

Shopify Setup

Head over to Shopify and log in to the store.

Create a Private App

A private app must be created to allow Nacelle to communicate with Shopify. To do so, open the store settings and go to the Apps and Sales Channels tab. Next, click on "Develop apps for your store", and then "Create an app".

Name your private app something memorable, like "Nacelle". It’s important to note that this name will show up in Shopify reports and other parts of the UI as a sales channel.

Storefront Access Token Configuration

Next we'll allow Storefront API access. Under the "Configuration" tab, click the "Configure" button under "Storefront API integration". Check all the boxes for all headings and click "Save".

Admin Access Token Configuration

Only applies to merchants using a Shopify Storefront API version that's later than V2022-07

Starting from 2023-04, in order to index Shopify metafields data into Nacelle, merchants need to provide their Shopify Admin Access Token with read_products access scope.

Install App

Finally, go to the "API Credentials" tab. Click "Install app", agree. Copy your Storefront API access token and admin access token and store them in a secured note. You will need these tokens for Nacelle to index your data.

Nacelle Setup

Now, head over to the Nacelle Dashboard and log in.

Connector Setup

In the sidebar, click the dropdown for "Space" and select the space to use (or create one). Then, click the top tab "Data Connectors".

Click the "Add Data Connectors" button, and select "Shopify" in the dropdown.

Enter the Shopify store’s .myshopify subdomain and the Storefront Access Token we copied before. To index metafields for merchants using Shopify storefront API version later than 2022-07, also enter your Admin Access Token configured in the above section.

We can leave the "Webhook Shared Secret" empty for now. Once you click Save, Nacelle will ingest your data from Shopify.

Initial Sync

Once the connector is added, you’ll see the connector information, including Nacelle's Source ID for the connector. The "Re-index Shopify" button will be disabled, indicating a reindex is in progress. You can come back here at any time to manually reindex all of your Shopify data.

Once ingestion is complete, you can verify that your products and collections have been properly ingested by visiting the appropriate tab in your space or by querying for the data using the Nacelle Storefront API.

Shopify Webhook Setup

You can use Shopify's webhooks to automatically update your data ingested by Nacelle.

To create a new outgoing webhook connection, log in to your Shopify dashboard. All webhook settings are found in Settings > Notifications. At the bottom of the window, click the button for Create webhook. For this example we will create a webhook to tell Nacelle to reindex a product when it has been updated in Shopify.

In the Add a webhook modal, in the dropdown for Event select Product update. For Webhook API Version select 2022-04. Then in the field for Url paste the URL for Nacelle's webhook receiver API, including your Nacelle spaceId at the end (found in the Nacelle sidebar). Click Save webhook

<https://shopify-webhook.api.nacelle.com/product/update?spaceId=><your_space_id>

Next copy the webhook signing key at the bottom of your webhook list. Nacelle will use this to verify that webhook updates are coming from Shopify. Back in Nacelle, navigate to your Space Settings, go to the Data Connectors tab, edit the Shopify connector that we've just created. Finally, paste the signature into the Webhook Shared Secret field and save.

Any time a product is updated in your Shopify storefront, it will now trigger Nacelle to reindex that product and keep your data in sync.

🚧
Note that automated updates to smart collections will not trigger a Shopify webhook.
Similarly, re-ordering manually sorted collections will not trigger a Shopify webhook. This is a limitation of Shopify. As a workaround, if the collection is otherwise updated (title, description, etc), then this collection update will trigger a Shopify webhook that will trigger Nacelle to fetch updates on smart collections and sort order

Webhook Endpoints

There are six endpoints for receiving different Shopify webhook events that you should configure following the steps above:

Product Create

<https://shopify-webhook.api.nacelle.com/product/create?spaceId=><your_space_id>

Product Update:

<https://shopify-webhook.api.nacelle.com/product/update?spaceId=><your_space_id>

Product Delete:

<https://shopify-webhook.api.nacelle.com/product/delete?spaceId=><your_space_id>

Collection Create:

<https://shopify-webhook.api.nacelle.com/collection/create?spaceId=><your_space_id>

Collection Update:

<https://shopify-webhook.api.nacelle.com/collection/update?spaceId=><your_space_id>

Collection Delete:

<https://shopify-webhook.api.nacelle.com/collection/delete?spcaeId=><your_space_id>

Contentful Connector

The Contentful connector indexes content into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Contentful and Nacelle Dashboards.

📘
If you use internationalization within your CMS, we recommend you leverage the Ingestion API directly

Contentful Setup

Head over to Contentful and log in to the space.

Create an API token

An API Key needs to be created to allow Nacelle to communicate with Contentful. To do so, click on the Settings dropdown, followed by the API Keys link.

Give your key any name you would like, such as "Nacelle". Select the environments to connect the key to.

Before leaving, make a note of the Space ID and the Content Delivery API Access Token. These will be needed later.

Nacelle Setup

Head over to the Nacelle Dashboard and log in.

Connector Setup

From the dashboard home:

Click the settings icon for the space where you’d like to add the connector.

Then, select the "Data Connectors" tab and click the Add Connector button in the top right of the UI.

From the modal, select "Contentful" in the dropdown.

Enter the Contentful space’s ID, the Environment, and the Delivery Token. Optionally, you can add the Webhook Secret and Preview Token so you can add Contentful preview data. The connector is now ready for action.

From a space:

Select Space Settings from the primary navigation pane and then select the Data Connectors tab. Next, click the Add Connector button in the top right of the UI

From the modal, select "Contentful" in the dropdown.

Enter the Contentful space’s ID, the Environment, and the Delivery Token. Optionally, you can add the Webhook Secret and Preview Token to add Contentful preview data. The connector is now ready for action.

Run Initial Sync

Once the connector is added, you’ll now have the option to Re-Index the connector. Click the Re-Index button in the connector to ingest your Contentful data

Contentful Preview Data

To enable Preview Data from Contentful, follow these steps.

From the Contentful dashboard, navigate to Settings, then API keys.

Under the Content delivery/preview tokens tab, select the API key used in your Contentful ingestion connector settings.

The preview token will be found under the label Content Preview API - access token.

Now, head over to the Nacelle dashboard and either click the settings gear icon for the space you’re updating, select the space, go to Space Settings in the primary navigation pane, and click the Data Connectors tab.

Next, click the 3 dots “menu” icon on the Contentful connector and choose Edit.

In the field labeled Contentful Preview Token, add the preview token created in Contentful.

Now, click the Save and Re-Index button, and you’re all set.

Nacelle Contentful CMS App

Nacelle's app for Contentful makes it easy to link products and collections to your content.

🚧
Saving product or collection data within content in the CMS can add risk to your composable stack's data consistency. Avoid this by using Nacelle's CMS apps.

It is important to avoid the composable anti-pattern of daisy-chaining, which you can learn more about here: https://nacelle.com/blog/cms-antipatterns-in-headless-commerce.

By using the Nacelle CMS app, you ensure best practices are followed, and daisy chaining is avoided.

Installation

Inside Contentful, click your organization's name in the top left corner of the app
In the slide-out menu that appears, click "Organization settings & subscriptions"
In the top navigation, click "Apps"
On the next page, click "Create an App"
Name the app whatever you want (we recommend "Nacelle")
Provide the Nacelle App URL: https://contentful-app-nacelle.netlify.app
In the "Locations" section that appears on the page, check the boxes for "App configuration screen" and "Entry field"
Check the box for "Short text" inside the "Entry field" location
Click "Create app"
On the next screen, click "Install to space" in the top right corner
In the modal that appears, select the environment to deploy to. Typically this will be "master"
On the next screen, enter your Nacelle Space ID and Token, and click "Install"

Field Setup

Navigate to the Content Model you want to set up the link for. Add a new field and name it "Product Handle" or "Collection Handle". The Field ID will auto-populate but should be manually set to handle. This will ensure that your content will appear as expected in the Nacelle dashboard.

Navigate to the Appearance settings for the new field. Scroll to the right, where you will see the new Nacelle app.

When you add a new content entry, that field will let you select products or collections from your catalog. Making a selection will populate the content field with a reference to the product or collection of interest.

Contentful webhook setup

Navigate to Contentful Webhooks Settings, via the top navbar, Settings > Webhooks, and click Add Webhook

For the Name field, enter any value, e.g. My Webhook

For the URL field, Select POST and add the URL:
<https://contentful.api.nacelle.com/webhook/contentful>

Triggers

Check Select specific triggering events

Check Publish and Unpublish cells in the Entry and Asset row

Headers

Click + Add secret header

For Key enter x-contentful-secret

For Value enter any arbitrary value, e.g. 5f4dcc3b5aa765d61d8327deb882cf99 (md5 hash of “password”)

Click + Add custom header

For Key enter x-nacelle-space-id

For Value enter your Nacelle space id

For Content-type select application/json

Update the Contentful Connector in the Nacelle Dashboard

Navigate to your Nacelle dashboard, select on your desired space, then go to Space Settings in the primary navigation pane, and click the Data Connectors tab.

Next, click the 3 dots “menu” icon on the Contentful connector and choose Edit.

For Contentful Webhook Secret, enter the value you used above for the secret header, x-contentful-secret

Sanity Connector

The Sanity connector indexes content into Nacelle. The connector uses webhooks to ensure data in Nacelle is always up to date. Setting up the connector is a straightforward process that requires a few updates in the Sanity and Nacelle Dashboards.

Sanity setup

Let's start by getting the Sanity project ID by going to the Sanity dashboard and selecting the project.

Once you are in the desired Sanity project, the project ID will be displayed in the header at the top of the screen. Copy this for later.

Click on the “datasets" tab within the Sanity project. (note, you may have multiple). You will need the name of the desired dataset - in this case, “production” - that Nacelle will ingest, so take note of this name.

Private datasets and content previews

For ingestion of private datasets or content previews, you can create an access token and provide it to Nacelle.

In the Sanity project settings, go to the API tab. Click "Add API token", name the token as you'd like, and leave the default "Viewer" permission. Save and copy the generated API token, as you'll need to provide it to Nacelle in the next steps.

Nacelle's setup

Now that your Sanity project is setup, head over to the Nacelle Dashboard and log in.

In the sidebar, click the dropdown for "Space" and select the space to use (or create one). Then, click the top tab "Data Connectors".

Click the "Add Data Connectors" button, and select "Sanity" in the dropdown.

Enter the Sanity Project ID, the Sanity Dataset to ingest, and your Sanity project's Webhook Secret. If desired, include the Sanity API token, which will allow ingestion of draft content and private datasets.

Once you click Save, Nacelle will begin to ingest data from Sanity.

Configure Sanity Webhooks

We can set up Sanity to automatically sync with Nacelle when content is updated. We will set up two webhooks for each Nacelle space, one for create/update and one for delete.

Return to the desired project within Sanity. After opening the project, navigate to the API tab, and create a “GROQ-powered Webhook.”

Name your Webhook
Add the correct URL. For Create/Update, it should be <https://sanity-webhook.api.nacelle.com/create>. For Delete, it should be https://sanity-webhook.api.nacelle.com/delete
Choose your data set from the drop-down (the same data set that was entered from your initial inputs)
Select both CREATE and UPDATE, or DELETE from the trigger actions.
Make sure the “enable webhook” box is checked.
Add a header x-nacelle-space-id, with the value being your Nacelle space ID (located in the Nacelle sidebar)
Add a header x-nacelle-source-id, with the value being your connector's Nacelle source ID. You can find this in the Space Settings, Data Connectors tab.
Choose API version v2021-03-25 from the drop-down.
Create a webhook secret. This is a merchant-created string that's entered into Sanity. It should be the same for both of your Nacelle webhooks. Note it for later as Nacelle will use it to verify the security of your data.
Hit Save

Example fields to modify from default:

Finally, be sure to go to your Nacelle space, go to the Data Connector tab, and edit the Sanity connector settings to include the webhook secret from above.

Now when your content is changed, Nacelle will continually be updated!

Nacelle Sanity CMS plugin

We have made a Sanity plugin to make it easy to link products and collections to your custom Content types.

🚧
Linking product and content data within the CMS can add risk to your composable stack's data consistency. Avoid this with Nacelle's CMS pattern.

It is important to avoid the composable anti-pattern of daisy-chaining, which you can learn more about here: https://nacelle.com/blog/cms-antipatterns-in-headless-commerce.

By using the Nacelle Sanity plugin, you ensure best practices are followed, and daisy chaining is avoided.

Installation & Setup

In your Sanity codebase, install Peer Dependencies

npm i @sanity/ui styled-components

Install the plugin

sanity install @nacelle/sanity-plugin-nacelle-input

Credentials

You'll need to provide the ID and Token associated with your Nacelle space. These credentials can be found in the Nacelle Dashboard.

Config file for single space

./config/@nacelle/sanity-plugin-nacelle-input.json

{
  "nacelleEndpoint": "your-nacelle-storefront-api-endpoint",
  "nacelleSpaceToken": "your-nacelle-graphql-token"
}

Within

.env.development / .env.production

SANITY_STUDIO_NACELLE_SPACE_ENDPOINT=your-nacelle-storefront-endpoint
SANITY_STUDIO_NACELLE_SPACE_TOKEN=your-nacelle-public-storefront-token

Adding Credentials to Multiple Spaces

Create a config file at

./config/@nacelle/sanity-plugin-nacelle-input.json.

Then add a nacelleSpaces array:

"nacelleSpaces": [
  {
    "spaceName": "Space 1",
    "nacelleEndpoint": "space-1's-nacelle-storefront-endpoint",
    "nacelleSpaceToken": "space-1's-nacelle-public-storefront-token"
  },
  {
    "spaceName": "Space 2",
    "nacelleEndpoint": "space-2's-nacelle-storefront-endpoint",
    "nacelleSpaceToken": "space-2's-nacelle-public-storefront-token"
  }
]

Use in Schema Documents

Set the type field to nacelleReference to use the custom input component:

{
  name: 'reference',
  title: 'Reference',
  type: 'nacelleReference',
}

Options

The custom input component default allows you to reference products or collections.

Realistically, you probably want to restrict the component to either products or collections. To do that, provide either ['products'] or ['collections'] to options.dataType:

// example: collections ONLY
{
  name: 'collectionReference',
  title: 'Collection',
  type: 'nacelleReference',
  options: {
    dataType: ['collections']
  }
}
// example: products ONLY
{
  name: 'productReference',
  title: 'Product',
  type: 'nacelleReference',
  options: {
    dataType: ['products']
  }
}

Data shape

The custom input component will store a reference object with the following format:

{
  type: 'NacelleReference',
  referenceType: 'PRODUCT', // PRODUCT or COLLECTION
  nacelledEntryId: '123455'
  handle: 'blue-shirt'
  locale: 'en-US'
}

Backward Compatibility with `@nacelle/sanity-plugin-pim-linker`

For projects using the legacy @nacelle/sanity-plugin-pim-linker for product/collection references, we provide a backward-compatible custom input called nacelleData. This input stores only the handle of a particular product or collection rather than a structured nacelleReference object.

Use in Schema Documents

Set the type field to nacelleData to use the custom input component:

{
  name: 'handle',
  title: 'Handle',
  type: 'nacelleData',
}

Data Shape

The backward-compatible custom input component will store only a reference handle.

{
  handle: 'blue-shirt'
}

🚧Prebuilt connectors are opinionated and, while they are great for most, they may not be the best match for every enterprise merchant

Shopify Connector

Shopify Setup

Create a Private App

Storefront Access Token Configuration

Admin Access Token Configuration

Install App

Nacelle Setup

Connector Setup

Initial Sync

Shopify Webhook Setup

🚧Note that automated updates to smart collections will not trigger a Shopify webhook.

Webhook Endpoints

Contentful Connector

📘If you use internationalization within your CMS, we recommend you leverage the Ingestion API directly

Contentful Setup

Create an API token

Nacelle Setup

Connector Setup

Run Initial Sync

Contentful Preview Data

Nacelle Contentful CMS App

🚧Saving product or collection data within content in the CMS can add risk to your composable stack's data consistency. Avoid this by using Nacelle's CMS apps.

Installation

Field Setup

Contentful webhook setup

Triggers

Headers

Update the Contentful Connector in the Nacelle Dashboard

Sanity Connector

Sanity setup

Private datasets and content previews

Nacelle's setup

Configure Sanity Webhooks

Nacelle Sanity CMS plugin

🚧Linking product and content data within the CMS can add risk to your composable stack's data consistency. Avoid this with Nacelle's CMS pattern.

Installation & Setup

Credentials

Adding Credentials to Multiple Spaces

Use in Schema Documents

Options

Data shape

Backward Compatibility with @nacelle/sanity-plugin-pim-linker

Use in Schema Documents

Data Shape

🚧
Prebuilt connectors are opinionated and, while they are great for most, they may not be the best match for every enterprise merchant

🚧
Note that automated updates to smart collections will not trigger a Shopify webhook.

📘
If you use internationalization within your CMS, we recommend you leverage the Ingestion API directly

🚧
Saving product or collection data within content in the CMS can add risk to your composable stack's data consistency. Avoid this by using Nacelle's CMS apps.

🚧
Linking product and content data within the CMS can add risk to your composable stack's data consistency. Avoid this with Nacelle's CMS pattern.

Backward Compatibility with `@nacelle/sanity-plugin-pim-linker`