NACELLE DOCS

You are viewing the v1 Nacelle Docs for existing merchants.New merchants can find the V2 docs here: nacelle.com/docs.

# Client JS SDK

The Nacelle client javascript SDK allows you to easily perform all the actions needed in your frontend store such as fetching data, processing checkouts, and triggering events.

It is designed to easily integrate with the frontend framework or your choosing, or to be used in a framework-less, vanilla-js environment.

# Getting started

npm install @nacelle/client-js-sdk

In your project you can now import and initialize the client with some basic settings.

import NacelleClient from '@nacelle/client-js-sdk'

const settings = {
  id: '<your-nacelle-space-id>',
  token: '<your-nacelle-public-token>',
  nacelleEndpoint: 'https://hailfrequency.com/v3/graphql',
  useStatic: false,
}

const client = new NacelleClient(settings)

With the client initialized you now have access to four modules, data, checkout, events, and status that will allow your app to interact with Nacelle and your data.

# Settings

  • id - (Required) Nacelle space id
  • token - (Required) Nacelle space public token
  • nacelleEndpoint (Required) Storefront API endpoint (e.g. https://hailfrequency.com/v3/graphql)
  • eventsEndpoint - (Optional) Endpoint for sending Nacelle events. Defaults to Nacelle's tracking event receiver.
  • staticBasePath - (Optional) Remote or relative path where the data module's static API should fetch files from the edge. Defaults to '/'.
  • locale - (Optional) An internationalization locale string. Defaults to 'en-us'
  • useStatic - (Optional) If the Nacelle data module should use the the static API or fetch data from the Storefront API by default. Defaults to true.
  • disableEvents - (Optional) Disables the event module from posting events to the events endpoint. Defaults to false.

# Data Module

The data module is for fetching Nacelle object data: products, collections and content.

The module uses connectors that determine the source of the data and how it is retrieved. By default the data module uses connectors for fetching data from the Static API, or from the Storefront API with graphQL requests.

# Options

  • connector - (Optional) A NacelleConnector class object
  • locale - (Optional) An internationalization locale string. Defaults to 'en-us'
  • currencyCode - (Optional) An currency code string. Defaults to 'USD'

# Methods

# update(options)

This method can be used for updating the data module after the NacelleClient has been initialized. It accepts all the same parameters as the data module constructor.

client.data.update(newSettings)

# product(options)

Get a product object by its handle.

Options

  • handle - The product handle
  • locale - (Optional) Locale string
const product = await client.data.product({ handle: 'cool-blue-shirt' })

# products(options)

Get an array of products from an array of handles.

Options

  • handles - Array of product handles
  • locale - (Optional) Locale string
const products = await client.data.products({
  handles: ['cool-blue-shirt', 'red-shirt'],
})

# collection(options)

Get a collection object by its handle.

Options

  • handle - The collection handle
  • locale - (Optional) Locale string
const collection = await client.data.collection({ handle: 'winter-shorts' })

# collectionPage(options)

Get a all products or a "page" of products from a collection's products array.

Collections store their product lists as an array of handles. This method allows you to fetch the product data from this array.

Options

  • handle - (Optional) The collection handle
  • collection - (Optional) Collection object
  • list - (Optional) Collection product list slug. Defaults to 'default'.
  • paginate - (Optional) Boolean to determine whether to return all products or a slice. Default: false.
  • index - (Optional) The starting index in the product array if paginating. Default: 0.
  • itemsPerPage - (Optional) Number of products to return from the array starting from the index. Default: 30.
  • locale - (Optional) Locale string
const products = await client.data.collectionPage({
  handle: 'winter-shorts',
  paginate: true,
  itemsPerPage: 12,
})

# content(options)

Get a content object by its handle.

Options

  • handle - The content handle
  • type - The type of content either predefined Nacelle content type ('page', 'blog', 'article'), or a custom type ('heroBanner').
  • blogHandle - (Optional) The parent blog handle if type is set to 'article'
  • locale - (Optional) Locale string
const contentEntry = await client.data.content({
  handle: 'hero-banner',
  type: 'heroBanner',
})

# page(options)

Get a page content object by its handle.

Options

  • handle - The page handle
  • locale - (Optional) Locale string
const page = await client.data.page({ handle: 'about-us' })

# pages(options)

Get an array of page objects from an array of handles.

Options

  • handles - Array of page handles
  • locale - (Optional) Locale string
const pages = await client.data.pages({
  handles: ['about-us', 'summer-landing-page'],
})

# article(options)

Get a blog article content object by its handle.

Options

  • handle - The article handle
  • blogHandle - (Optional) The article's parent blog handle, if your store uses multiple blogs. Defaults to 'blog'.
  • locale - (Optional) Locale string
const article = await client.data.article({ handle: '10-fall-fashion-tips' })

const newsBlogPost = await client.data.article({
  handle: 'our-new-brick-and-mortar',
  blogHandle: 'news',
})

# articles(options)

Get an array of articles from an array of handles.

Options

  • handles - Array of article handles
  • blogHandle - (Optional) The articles' parent blog handle, if your store uses multiple blogs. Defaults to 'blog'.
  • locale - (Optional) Locale string
const articles = await client.data.articles({
  handles: ['fresh-spring-looks', 'shoe-selection-guide'],
})

# blog(options)

Get a blog content object by its handle.

Options

  • handle - The blog handle
  • locale - (Optional) Locale string
const blog = await client.data.blog({ handle: 'news' })

# blogPage(options)

Get a all articles or a "page" of articles from a blog's articles array.

Blogs store their article lists as an array of handles. This method allows you to fetch the article data from this array.

Options

  • handle - (Optional) The blog handle
  • collection - (Optional) Blog object
  • list - (Optional) Blog article list slug. Defaults to 'default'.
  • paginate - (Optional) Boolean to determine whether to return all articles or a slice. Default: false.
  • index - (Optional) The starting index in the product array if paginating. Default: 0.
  • itemsPerPage - (Optional) Number of articles to return from the array starting from the index. Default: 30.
  • locale - (Optional) Locale string
const articles = await client.data.blogPage({
  handle: 'blog',
  paginate: true,
  itemsPerPage: 6,
})

# space()

Get the Nacelle space object data.

const space = await client.data.space()

# allProducts(options)

Retrieve all the products from your catalogue.

const entireCatalogue = await client.data.allProducts()

# allCollections(options)

Returns all the collections indexed in Nacelle.

Note: This method only works if the NacelleClient's useStatic setting is set to 'false' or if the data module is using a custom connector.

const remoteClient = new NacelleClient({
  ...settings,
  useStatic: false,
})

const collections = await remoteClient.data.allCollections()

# allContent(options)

Returns all the content indexed in Nacelle.

Note: This method only works if the NacelleClient's useStatic setting is set to 'false' or if the data module is using a custom connector.

Arguments

  • type: Returns only the content types specified
  • limit: Returns the number of items specified (default is 2000)
const remoteClient = new NacelleClient({
  ...settings,
  useStatic: false,
})

const items = await remoteClient.data.allContent({ type: 'blogPost' })

# after(methodName, callback)

Subscribe to and modify the response from the data module methods.

Arguments

  • Method name string
  • Callback function that takes the response object as an argument and returns it.
client.data.after('product', (product) => {
  // ...do something with product object

  return product
})

// Somewhere else in your project
const modifiedProduct = await client.data.product({ handle: 'jean-shorts' })

# Checkout Module

The checkout module uses the Storefront API for processing checkouts with Shopify or other e-commerce platforms.

# Methods

# process(options)

Creates a new checkout instance via the Storefront API.

Options

  • cartItems - An array of cart line items

Each cart item is expected in this shape:

{
  cartItemId: '',
  variantId: '',
  quantity: 1,
  metafields: [
    { key: '', value: '' }
  ]
}
  • note - A string containing an order note (optional)
  • metafields - An array of key/value pairs for passing metadata (optional)
  • checkoutId - Id of existing checkout. It can be an empty string if not existent
const checkoutObj = await client.checkout.process({ cartItems, checkoutId })

# get(options)

Queries the Storefront API for the checkout object so that we can determine if the checkout was completed or not.

Options

  • id - Checkout id string
  • url - Checkout url
const checkoutObj = await client.checkout.get({ id, url })

if (checkoutObj.completed) {
  // Checkout complete! Clear the local cart
}

# Status Module

The status module is for getting inventory status on your variants. Nacelle is built around the principle of keeping your data cached on the edge. For this reason when the data module is fetching data from cached static json files it is important to have access to up-to-date variant availability data in Nacelle's index.

# Methods

# isVariantAvailable(options)

Use this to check the availableForSale property of a variant in your Nacelle product index. It will return a boolean.

The Nacelle Nuxt Starter generates static JSON files of your data during the build process. If your products inventory is updating frequently, availableForSale may change before a new build is triggered. This method allows you to check for availability and prevent a user from adding the product to their cart.

Included with the starter project is a CartWatch component. This will check any time a product has been added to the cart, and automatically remove unavailable items while notifying the user.

Options

  • productId - the Nacelle product ID
  • variantId - The product variant's ID
const available = client.status.isVariantAvailable({
  productId,
  variantId,
})

if (!available) {
  // The customer can not purchase this item
}

# Wishlist

The Wishlist module is used for adding and getting product wishlists

# Methods

# get(options)

Use this to get a customers wishlists

Options

  • customerId - id of the customer
const wishlists = await client.wishlist.get({
  customerId: '1234',
})

wishlists can be found under data.data.getWishlistsByCustomerSourceId.items the following is an example of the response

{
    "data": {
        "data": {
            "getWishlistsByCustomerSourceId": {
                "items": [
                    {
                        "id": "fe87800e-a0d2-4164-96f8-ecd31bccca8d",
                        "customerSourceId": "splendid-starfish-drqm8CG0Uw::1234",
                        "title": "rackets",
                        "items": [
                            {
                                "variantId": "Z1as;dfa;afjjjsk",
                                "handle": "tennis-ball"
                            }
                        ]
                    },
                    {
                        "id": "c5c0cd6f-3d4a-4e33-b5d4-69240db6f4c8",
                        "customerSourceId": "splendid-starfish-drqm8CG0Uw::1234",
                        "title": "rackets",
                        "items": [
                            {
                                "variantId": "Z1as;dfa;afjjjsk",
                                "handle": "hockey-puck"
                            }
                        ]
                    }
                ],
                "nextToken": null
            }
        }
    },
}

# put(options)

Use this to either add or update a wishlist

Options

  • id - id of the wishlist include this if you want to update an existing wishlist rather than adding a new one
  • title - The name of a given wishlist (ie. "Shopping List")
  • customerId - The unique Identifier for a given customer.
  • items - An array of items to be added to wishlists
const response = await client.wishlist.put({
  id: 'fe87800e-a0d2-4164-96f8-ecd31bccca8d',
  customerId: '1234',
  title: 'rackets',
  items: [
    {
      variantId: 'Z1as;dfa;afjjjsk',
      handle: 'tennis-ball',
    },
  ],
})

The created/updated wishlist can be found under data.data.putWishlist of the response

{
  "data": {
    "data": {
      "putWishlist": {
        "id": "fe87800e-a0d2-4164-96f8-ecd31bccca8d",
        "customerSourceId": "splendid-starfish-drqm8CG0Uw::1234",
        "items": [
          {
            "variantId": "Z1as;dfa;afjjjsk",
            "handle": "tennis-ball"
          }
        ]
      }
    }
  }
}

# getById(options)

Use this to view a specific wishlist

Options

  • customerId - id of the customer
  • id - id of the wishlist
const response = await client.wishlist.getById({
  customerId: '1234',
  id: '782ee90c-1728-4aba-b147-c1e37a3524dc',
})

The desired wishlist can be found under data.data.getWishlist of the response

{
  "data": {
    "data": {
      "getWishlist": {
        "id": "782ee90c-1728-4aba-b147-c1e37a3524dc",
        "title": "test11",
        "customerSourceId": "6789::1234",
        "items": [
          {
            "variantId": "Z1as;dfa;afjjjsk",
            "handle": "test11"
          },
          {
            "variantId": "Z1as;dfa;testtest",
            "handle": "test11-2"
          }
        ]
      }
    }
  }
}

# delete(options)

Use this to remove a customers specific wishlist Options

  • customerId - id of the customer
  • id - id of the wishlist
const response = await client.wishlist.delete({
  customerId: '1234',
  id: '19089ff8-e5cb-47b6-b463-4fea2eb176ec',
})

The deleted wishlist can be found under data.data.deleteWishlist of the response

{
  "data": {
    "data": {
      "deleteWishlist": {
        "id": "19089ff8-e5cb-47b6-b463-4fea2eb176ec",
        "customerSourceId": "6789::1234",
        "items": [
          {
            "variantId": "Z1as;dfa;afjjjsk",
            "handle": "hcokey-test"
          },
          {
            "variantId": "Z1as;dfa;testtest",
            "handle": "hockey-puck"
          }
        ]
      }
    }
  }
}

← Data Ingestion API →