Skip to main content

Storefront SDK

Release Version: Storefront SDK 1.0.3

GitHub: https://github.com/getnacelle/nacelle-storefront-sdk

NPM: npm: @nacelle/storefront-sdk

The Nacelle Storefront SDK (package name: @nacelle/storefront-sdk) allows merchant developers to interact with Nacelle’s Warp 2 Storefront API using JavaScript. The Storefront SDK provides a convenience layer around requesting ingested product & content data, as well as Navigation & Space Properties data created in the Nacelle Dashboard.

Installing

In a Node.js project

npm i @nacelle/storefront-sdk

Adding to Project

Get the storefrontEndpoint and token from the Nacelle Dashboard

1

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

Initializing 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 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 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.

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.

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.

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.

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.

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 assigned to a navigation group in the Nacelle Dashboard.

Examples

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

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

Space Properties

The spaceProperties method accepts no parameters.

Examples

// 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.

Examples

// Get product handles from a provided collection.

const query = `query productCollections($filter: ProductCollectionFilterInput) {
  productCollections(filter: $filter){
    products {
      content {
        handle
      }
    }
  }
}`;

const variables = `{
  "filter": {
    "handles": ["collection-1"]
  }
}`

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

Troubleshooting

  • Syntax errors may indicate that the option parameter is not a correctly structured object. Make sure 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.

How's your docs experience?