JavaScript Storefront SDK

The Nacelle Storefront SDK (package name: @nacelle/storefront-sdk) allows merchant front-end developers to interact with Nacelle’s V2 Storefront GraphQL API using JavaScript. The Storefront SDK provides a convenience layer that sits ontop of Nacelle's GraphQL API.

Installing

In a Node.js project

npm i @nacelle/storefront-sdk

Adding to a project

Get credentials

Get the storefrontEndpoint and public Storefront Token from the Nacelle Dashboard

The Storefront Endpoint and Public Storefront Token can be copied with a press of a button.

Initialize the SDK

Import the SDK and initialize it with your storefrontEndpoint and token from the Nacelle Dashboard.

import Storefront from "@nacelle/storefront-sdk";

const client = Storefront({
  storefrontEndpoint: "<your-storefront-endpoint>",
  token: "<your-public-storefront-token>",
  locale: "en-US", // Optional, defaults to "en-US"
  currencyCode: "USD" // Optional, defaults to "USD"
});

Querying Data

Products

The products method accepts an object with the following properties to define the options of the query:

  • nacelleEntryIds - (String[], Optional) An array of ids is assigned to the product by Nacelle.

  • handles - (String[], Optional) An array of product handles.

  • locale - (String, Optional, default: "en-US") An IETF locale.

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned products.

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns Product objects or ProductEdge objects. When false, ProductEdge objects are returned. Product edges have a cursor and node which contains the product data. The cursor value can be used for paginating.

  • cursor - (String, Optional) Returned entries will come after this cursor value.

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated products Storefront API query. If you need to paginate requests, it is recommended to use the cursor, and the cursor values returned when edgesToNodes is false

  • advancedOptions - (Object, Optional)

  • entriesPerPage - (Number, Optional) - The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Product examples

// Get all products in a space
await client.products();

// Get the first 5 products.
await client.products({
  maxReturnedEntries: 5
});

// Get products by handles.
await client.products({
  handles: ["product-1", "product-2"]
});

// Get products after a specified ID.
await client.products({
  startAfterEntryId: "SomeNacelleEntryId"
});

// Using cursors to manually retrieve paginated results
const batchOne = await client.products({
  maxReturnedEntries: 5,
  edgesToNodes: false
});

const batchTwo = await client.products({
  maxReturnedEntries: 5,
  edgesToNodes: false,
  cursor: batchOne[batchOne.length - 1].cursor
});

// When using Typescript
const [ firstProductEdge ] = await client.products({
  maxReturnedEntries: 5,
  edgesToNodes: false
});
const { cursor, edge } = firstProductEdge as ProductEdge;
const { naceleEntryId } = edge;

const [ firstProduct ] = await client.products({ maxReturnedEntries: 5 });
const { nacelleEntryId } = firstProduct as Product;

Product collections

The productCollections method accepts an object with the following properties to define the options of the query

  • nacelleEntryIds - (String[], Optional) An array of ids assigned to the product collections by Nacelle.

  • handles - (String[], Optional) An array of product collection handles.

  • locale - (String, Optional, default: "en-US") An IETF locale.

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned collections.

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns ProductCollection objects or ProductCollectionEdge objects. When false, ProductCollectionEdge objects are returned. ProductCollection edges have a cursor and node which contains the product data. The cursor value can be used for paginating.

  • cursor - (String, Optional) Returned entries will come after this cursor value.

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated productCollections Storefront API query. If you need to paginate requests, it is recommended to use cursor and the cursor values returned when edgesToNodes is false.

  • maxReturnedEntriesPerCollection - (Number, Optional) The number of products to be queried for each collection returned

  • advancedOptions - (Object, Optional)
    entriesPerPage - (Number, Optional) The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Examples

// Get the first 5 product collections.
await client.productCollections({
  maxReturnedEntries: 5
});

// Get product collections by handles.
await client.productCollections({
  handles: ["collection-1", "collection-2"]
});

// Get product collections after a specified ID.
await client.productCollections({
  startAfterEntryId: "SomeNacelleEntryId"
});

// Get the first 50 products for each collection
await client.productCollections({
  maxReturnedEntriesPerCollection: 50
})

// How to access products on a collection
const collections = await client.collections();
const { products, productConnection } = collections[0];

const { nacelleEntryId } = products[0]; // An array of type Product

const { pageInfo, edges } = productConnection;
const { cursor, node } = edges[0];
const { nacelleEntryId } = node;

Product collection entries

The productCollectionEntries method accepts an object with the following properties to define the options of the query:

  • collectionEntryId - (String, Optional) The nacelleEntryId for the collection’s products you want to query. Either collectionEntryId or handle is required.

  • handle - (String[], Optional) The handle of the collection’s products you want to query.

  • locale - (String, Optional, default: "en-US") An IETF locale.

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned products.

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns Product objects or ProductEdge objects. When false, ProductEdge objects are returned. ProductCollection edges have a cursor and node which contains the product data. The cursor value can be used for paginating.

  • cursor - (String, Optional) Returned entries will come after this cursor value.

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated productCollections Storefront API query. If you need to paginate requests, it is recommended to use cursor and the cursor values returned when edgesToNodes is false.

  • advancedOptions - (Object, Optional)
    entriesPerPage - (Number, Optional) The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Product collection entry examples

// Get all the products belonging to collection with handle "shoes"
await client.productCollectionEntries({
  handle: 'shoes',
  maxReturnedEntries: -1
});

// Get first 20 products belonging to collection with handle "hats"
await client.productCollectionEntries({
  handle: 'hats',
  maxReturnedEntries: 20
})

Content

The content method accepts an object with the following properties to define the options of the query:

  • nacelleEntryIds - (String[], Optional) An array of ids assigned to the content by Nacelle.

  • handles - (String[], Optional) An array of content handles.

  • locale - (String, Optional, default: "en-US") An IETF locale.

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned content entries.

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns Content objects or ContentEdge objects. When false, ContentEdge objects are returned.Content edges have a cursor and node which contains the content entry data. The cursor value can be used for paginating.

  • cursor - (String, Optional) Returned entries will come after this cursor value.

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated content Storefront API query. If you need to paginate requests, it is recommended to use cursor and the cursor values returned when edgesToNodes is false.

  • type - (String, Optional) Allows for querying by content type

  • advancedOptions - (Object, Optional)
    entriesPerPage - (Number, Optional) The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Content examples

// Get the first 5 content entries.
await client.content({
  maxReturnedEntries: 5
});

// Get content by handles.
await client.content({
  handles: ["content-1", "content-2"]
});

// Get only articles
await client.content({ type: 'article' })

Content collections

The contentCollections method accepts an object with the following properties to define the options of the query:

  • nacelleEntryIds - (String[], Optional) An array of ids assigned to the content collections by Nacelle.

  • handles - (String[], Optional) An array of content collection handles.

  • locale - (String, Optional, default: "en-US") An IETF locale.

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned content collections.

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns ContentCollection objects or ContentCollectionEdge objects. When false, ContentCollectionEdge objects are returned. ContentCollection edges have a cursor and node which contains the product data. The cursor value can be used for paginating.

  • cursor - (String, Optional) Returned entries will come after this cursor value.

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated contentCollections Storefront API query. If you need to paginate requests, it is recommended to use cursor and the cursor values returned when edgesToNodes is false

  • maxReturnedEntriesPerCollection - (Number, Optional) The number of content entries to be queried for each collection returned

  • advancedOptions - (Object, Optional)
    entriesPerPage - (Number, Optional) The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Content collection examples

// Get the first 5 content collections.
await client.contentCollections({
  maxReturnedEntries: 5
});

// Get content collections by handles.
await client.contentCollections({
  handles: ["content-collection-1", "content-collection-2"]
});

// Get content collections after a specified ID.
await client.contentCollections({
  startAfterEntryId: "SomeNacelleEntryId"
});

Content collection entries

The contentCollectionEntries method accepts an object with the following properties to define the options of the query:

  • collectionEntryId - (String, Optional) The nacelleEntryId for the collection’s content entries you want to query. Either collectionEntryId or handle is required.

  • handle - (String[], Optional) The handle of the collection’s content entries you want to query.

  • locale - (String, Optional, default: "en-US") An IETF locale

  • maxReturnedEntries - (Number, Optional) Sets an upper limit on the number of returned content entries

  • edgesToNodes - (Boolean, Optional, default: true) Sets whether the method returns Content objects or ContentEdge objects. When false, ContentEdge objects are returned. Content edges have a cursor and node which contains the product data. The cursor value can be used for paginating

  • cursor - (String, Optional) Returned entries will come after this cursor value

  • startAfterEntryId - (String, Optional) Returned entries will come after this specified ID. Uses deprecated productCollections Storefront API query. If you need to paginate requests, it is recommended to use cursor and the cursor values returned when edgesToNodes is false

  • advancedOptions - (Object, Optional)
    entriesPerPage - (Number, Optional) The SDK is configured to automatically request entries in batches. The number of entries it will attempt to request at a time can be optionally tuned using this parameter.

Content collection entry examples

// Get all the products belonging to collection with handle "shoes"
await client.productCollectionEntries({
  handle: 'shoes',
  maxReturnedEntries: -1
});

// Get first 20 products belonging to collection with handle "hats"
await client.productCollectionEntries({
  handle: 'hats',
  maxReturnedEntries: 20
})

Navigation

The navigation method has no required parameters. It accepts an optional params object with the following properties:

  • groupId - (String, Optional) The group ID is assigned to a navigation group in the Nacelle Dashboard.

Navigation example

// Get all Navigation Groups
await client.navigation();

// Get a single Navigation Group
await client.navigation({
  groupId: "footer"
});

Space properties

// Get all Space Properties
await client.spaceProperties();

Custom GraphQL query

The query method accepts an object with the following properties:

  • query - (String, Required) A GraphQL query.
  • variables - (String, Optional) Variables used in the query.

Custom Graphql query example

// Get product handles from the "collection-1" collection
const query = `
  query ProductHandles($filter: ProductCollectionFilterInput) {
    allProductCollections(filter: $filter) {
      edges {
        node {
          productConnection {
            edges {
              node {
                content {
                  handle
                }
              }
            }
          }
        }
      }
    }
  }
`;

const variables = JSON.stringify({
  filter: {
    handles: 'collection-1'
  }
});

await client.query({
  query,
  variables
});

Troubleshooting

  • Syntax errors may indicate that the option parameter is not a correctly structured object. Ensure this parameter is an object with the properties listed in this document.

  • A Variable "$filter" got invalid value error occurs when the wrong type is provided in the option parameter object. Make sure the value matches the type listed in this document.