Guides

Storefront SDK Commerce Queries Plugin

Suggest Edits

The Nacelle Commerce Queries Plugin (package name: @nacelle/commerce-queries-plugin) lets developers add REST-style methods to Storefront SDK 2.x.

Adding to a project

Prerequisite

In order to use the Commerce Queries plugin, it is necessary to first have the Storefront SDK 2.x working in your project.

Install

Begin by installing the Commerce Queries plugin in your Node.js project:

npm i @nacelle/commerce-queries-plugin

Transpile (optional, as needed)

The Storefront SDK 2.x and the Commerce Queries Plugin use modern JS language features such as private class fields. Depending on the framework you're using, this package code must be transpiled in order for the project to build. Here is an example transpilation configuration for a Nuxt 2 project that uses the Commerce Queries Plugin:

export default {
  // ...other config,
  build: {
    // ...other `build` config
    transpile: [
      // ...other `transpile` config
      ({ isLegacy }) => isLegacy && '@nacelle/storefront-sdk',
      ({ isLegacy }) => isLegacy && '@nacelle/commerce-queries-plugin',
    ],
  },
};

Initialize the plugin

Import the Storefront SDK and the Commerce Queries plugin, then wrap the StorefrontClient with CommerceQueries before initializing it with your Storefront Endpoint.

import { StorefrontClient } from '@nacelle/storefront-sdk';
import { CommerceQueries } from '@nacelle/commerce-queries-plugin';

const ClientWithCommerceQueries = CommerceQueries(StorefrontClient);

const client = new ClientWithCommerceQueries({ 
	storefrontEndpoint: '<your-storefront-endpoint>' 
});

Types

If using TypeScript, Commerce Queries types can be imported from @nacelle/plugin-commerce-queries:

import { CommerceQueries } from '@nacelle/commerce-queries-plugin';

import type {
  Content,
  ContentEdge,
  FetchProductCollectionsMethodParams,
  FetchCollectionEntriesMethodParams,
  FetchContentMethodParams,
  NavigationFilterInput,
  NavigationGroup,
  Product,
  ProductEdge,
  ProductFilterInput,
  ProductCollection,
  ProductCollectionEdge,
  SpaceProperties
} from '@nacelle/commerce-queries-plugin';

Methods

Navigation

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

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

Navigation examples

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

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

TypeScript types

  • Params type: NavigationFilterInput
  • Return type: NavigationGroup[]

Space properties

The spaceProperties method returns Space Properties data. It's called without any parameters.

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

TypeScript types

  • Return type: SpaceProperties

Products

The products method returns an array of product data. It accepts an object with the following query properties:

  • nacelleEntryIds - (string[], Optional) An array of product.nacelleEntryIds, which are unique IDs assigned to products 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. ProductEdges have a cursor and node. The cursor value can be used for paginating; the node contains the product data.

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

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

Products 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']
});

// 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.at(-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;

TypeScript types

  • Params type: ProductFilterInput
  • Return type: Product[], unless params.edgesToNodes is explicitly set to false , in which case ProductEdge[] is returned instead.

Product collections

The productCollections method returns arrays of collection objects that contain both (a) merchandising data intrinsic to the collection (such as the collection's content.title) and (b) an array of products in the collection. It accepts an object with the following query properties:

  • nacelleEntryIds - (string[], Optional) An array of productCollection.nacelleEntryIds, which are unique IDs assigned to 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. ProductCollectionEdges have a cursor and node. The cursor value can be used for paginating; the node contains the collection data.

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

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

Product collections 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 the first 50 products for each collection
await client.productCollections({
  maxReturnedEntriesPerCollection: 50
})

// How to access products on a collection
const [collection] = await client.productCollections({
  handles: ['collection-of-interest']
});

const { products, productConnection } = collection;
// `products` is an array of product data.
// `productConnection` is an object containing product data (in the `edges` property)
// and pagination info (in the `pageInfo` property). For more information about connections 
// like `productConnection`, see https://relay.dev/graphql/connections.htm#sec-Connection-Types

TypeScript types

  • Params type: FetchProductCollectionsMethodParams
  • Return type: ProductCollection[], unless params.edgesToNodes is explicitly set to false , in which case ProductCollectionEdge[] is returned instead.

Product collection entries

The productCollectionEntries method returns an array of products associated with a collection. Unlike the productCollections method, it does not return any merchandising data associated with the collection (such as the collection's content.title). It accepts an object with the following query properties:

  • 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. ProductEdges have a cursor and node. The cursor value can be used for paginating; the node contains the product data.

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

  • 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 entries examples

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

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

TypeScript types

  • Params type: FetchCollectionEntriesMethodParams
  • Return type: Product[], unless params.edgesToNodes is explicitly set to false , in which case ProductEdge[] is returned instead.

Content

The content method returns an array of content entries. It accepts an object with the following query properties:

  • nacelleEntryIds - (string[], Optional) An array of content.nacelleEntryIds, which are unique IDs assigned to individual content entries 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. ContentEdges have a cursor and node. The cursor value can be used for paginating; the node contains the content data.

  • entryDepth - (number, Optional) Sets the maximum level of content resolution depth in content.fields. For more details, see Content Resolution.

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

  • 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' })

TypeScript types

  • Params type: FetchContentMethodParams
  • Return type: Content[], unless params.edgesToNodes is explicitly set to false , in which case ContentEdge[] is returned instead.

Updated 8 months ago