@nacelle/compatibility-connector/README.md

Connect @nacelle/client-js-sdk to Nacelle's v2 back end with minimal code changes

# Nacelle Compatibility Connector

Connects [`@nacelle/client-js-sdk`](https://www.npmjs.com/package/@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:

```bash
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`:

```bash
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.

```javascript
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.

```javascript
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](https://en.wikipedia.org/wiki/IETF_language_tag) 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](https://docs.getnacelle.com/api-reference/client-js-sdk.html#data-module) 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.

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

### Using with `@nacelle/nacelle-nuxt-module`

When using [`@nacelle/nacelle-nuxt-module`](https://www.npmjs.com/package/@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:

```javascript
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.

```javascript
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`