@nacelle/compatibility-connector

Nacelle Compatibility Connector

Connects @nacelle/client-js-sdk to Nacelle's v2 back end, and transforms data to match the Nacelle v1 data shapes used in existing Nacelle projects.

Installation

If your @nacelle/client-js-sdk version is below 3.7.1, please install the @latest version:

npm i @nacelle/client-js-sdk@latest

Once you have @nacelle/client-js-sdk@3.7.1 or above installed, install both @nacelle/compatibilty-connector and @nacelle/storefront-sdk:

npm i @nacelle/compatibility-connector @nacelle/storefront-sdk

Usage

Setting Up The Connector

Provide the connector with Storefront API credentials available from the Nacelle Dashboard. Then initialize the NacelleClient SDK with the compatibility connector.

import NacelleClient from '@nacelle/client-js-sdk';
import createCompatibilityConnector from '@nacelle/compatibility-connector';

// Initialize the Compatibility Connector
const compatibilityConnector = new createCompatibilityConnector({
  endpoint: 'nacelle-v2-storefront-endpoint',
  token: 'nacelle-v2-public-storefront-token'
});

// Initialize the SDK client
const client = new NacelleClient({
  connector: compatibilityConnector
});

Alternatively, the connector can be initialized with a Nacelle v2 Storefront client instead of the endpoint and token parameters.

import NacelleClient from '@nacelle/client-js-sdk';
import Storefront from '@nacelle/storefront-sdk';
import createCompatibilityConnector from '@nacelle/compatibility-connector';

// Initialize the v2 Storefront SDK
const storefrontClient = new Storefront({
  endpoint: 'nacelle-v2-storefront-endpoint',
  token: 'nacelle-v2-public-storefront-token'
});

// Initialize the Compatibility Connector
const compatibilityConnector = new createCompatibilityConnector({
  client: storefrontClient
});

// Initialize the SDK client
const client = new NacelleClient({
  connector: compatibilityConnector
});

Optional Parameters

In addition to the required endpoint and token params or client param, you can also pass the following optional params:

• locale - the default locale used across client.data methods. This can be overridden on-the-fly by specifying a locale in the arguments to any of the client.data methods. See the @nacelle/client-js-sdk docs for details. If no locale is provided, a default value of en-US will be set. If the client param is provided, the locale will be set to the locale of the provided client.

Fetching Data

Once the connector has been initialized and the client updated, you can fetch data using any of the @nacelle/client-js-sdk methods. Below is an example of fetching a product.

const product = await client.data.product({
  handle: 'handle-1'
});

Using with @nacelle/nacelle-nuxt-module

When using @nacelle/nacelle-nuxt-module, additional steps are required in order to use the Compatibility Connector.

First, please ensure that your version version of @nacelle/nacelle-nuxt-module is 5.0.0 or higher. If it's below 5.0.0, install the latest version of @nacelle/nacelle-nuxt-module:

npm i @nacelle/nacelle-nuxt-module@latest

In nuxt.config.js, initialize @nacelle/compatibility-connector by providing the Nacelle v2 Storefront API credentials. Next, initialize @nacelle/client-js-sdk with the compatibility connector. Then pass the SDK client to buildClient in the nacelle options. See below for an example:

import NacelleClient from '@nacelle/client-js-sdk';
import createCompatibilityConnector from '@nacelle/compatibility-connector';

// Initialize the Compatibility Connector
const compatibilityConnector = new createCompatibilityConnector({
  endpoint: 'nacelle-storefront-endpoint',
  token: 'nacelle-storefront-token',
  locale: 'en-US'
});

// Initialize the SDK client
const client = new NacelleClient({
  connector: compatibilityConnector
});

export default {
  // ...
  // Rest of nuxt.config.js settings
  // ...

  nacelle: {
    buildClient: client // The client that was initialized and updated above.
  }
};

Now whenever $nacelle is used, data will be fetched from Nacelle's v2 back end.

const product = await this.$nacelle.data.product({
  handle: 'handle-1'
});

Limitations

General

Media with the type external_video will now return as video.

Products & Collections

The fields pimSyncSource and pimSyncSourceDomain will return an empty string.

Content

The field cmsSyncSourceDomain will return an empty string.

Contentful

For content entries with relatedArticles, each of the relatedArticles will have createdAt and updatedAt values of 0.

Space

The name and domain returned with client.data.space() will be an empty string.

When using version 1.7.0 and above of @nacelle/storefront-sdk, link lists returned by client.data.space() will have their type mapped correctly from corresponding Nacelle v2 Navigation Items. If using a version of @nacelle/storefront-sdk below 1.7.0: for link lists returned with client.data.space(), absolute URLs (e.g. https://nacelle.com/some/page) will have their type set to External, while relative URLs (e.g. /path/to/some/page) will have their type set to Page.

Supported link type:

• Blog
• Collection
• External
• General
• Page
• Product