Cart installation

The cart drop-in component, like our other drop-in components, are designed for the browser’s JavaScript runtime without the need for a bundler. You can also install and execute drop-in components in a build-time environment with bundlers like Vite. The installation steps for both runtime and build-time environments are the same after the initial drop-in component package imports.

Step-by-step

Use the following steps to install the cart component:

Install the packages

Use a CDN or NPM (recommended for performance) to install the drop-in component tools (@dropins/tools) and cart (@dropins/storefront-cart) packages.

npm install @dropins/tools @dropins/storefront-cart

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Storefront</title>

  <script src="https://cdn.jsdelivr.net/npm/@dropins/tools@latest"></script>
  <script src="https://cdn.jsdelivr.net/npm/@dropins/storefront-cart@latest"></script>
</head>

Map the packages

In the <head> tag of your index.html or head.html file, use an importmap pointed to the node_modules directory, a custom local directory, or CDN (for run-time environments).

This example shows an importmap added to a head.html The importmap points both packages to the local node_modules directory that contains your installed drop-in component files from the drop-in component tools (@dropins/tools) and the cart (@dropins/storefront-cart):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/node_modules/@dropins/tools/",
      "@dropins/storefront-cart/": "/node_modules/@dropins/storefront-cart/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap added to a head.html The importmap points both packages to local directories that contain all the optimized/minified files from the drop-in component tools (@dropins/tools) and the cart (@dropins/storefront-cart):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/scripts/__dropins__/tools/",
      "@dropins/storefront-cart/": "/scripts/__dropins__/storefront-cart/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap pointing both packages to a CDN for the drop-in component tools (@dropins/tools) and the cart (@dropins/storefront-cart):

<head>
  <script type="importmap">
    {
      "imports": {

        "@dropins/tools/": "https://cdn.jsdelivr.net/npm/@dropins/tools@latest",
        "@dropins/storefront-cart/": "https://cdn.jsdelivr.net/npm/@dropins/storefront-cart@latest",
      }
    }
  </script>
</head>

With the importmap defined for both runtime and build-time environments, you can now import the required files from these packages into your cart block as described in the next step.

Import the required files

Import the required files from the drop-in components tools (@dropins/tools/fetch-graphql.js', @dropin/tools/initializers.js) and the cart (@dropins/storefront-cart) into a JavaScript file for your cart block. The example here shows the imports added to a cart.js file. These imports constitute the minimum imports you need to create a fully functioning cart for your site:

// GraphQL Client
import * as mesh from '@dropins/tools/fetch-graphql.js';

// component tools
import { initializers } from '@dropins/tools/initializer.js';

// drop-in component functions
import * as pkg from '@dropins/storefront-cart/api.js';

// Drop-in component provider
import { render as provider } from '@dropins/storefront-cart/render.js';

// Drop-in component containers
import Cart from '@dropins/storefront-cart/containers/Cart.js';
import MiniCart from '@dropins/storefront-cart/containers/MiniCart.js';

GraphQL client

Enables the ability to set and get endpoints and headers, as well as fetches data and configurations.

Drop-in component tools

The Initializer is responsible for setting up event listeners and initializing a module with the given configuration.

drop-in component functions

Enables the cart API functions: addProductsToCart, createEmptyCart, getCartData… and more.

Drop-in component provider

Renders the cart UI.

Drop-in component containers

Structural elements that are responsible for managing and displaying the UI for the Cart and Mini-cart.

Connect to the endpoint

Connect your cart component to the API Mesh endpoint and set the required headers as shown in the example below. Replace the endpoint URL and header placeholder values with the actual values from your Commerce backend services:

// Set endpoint configuration
mesh.setEndpoint('https://<graphql-service-endpoint>/graphql');

Request headers

The cart does not need additional headers set for basic installation. But if you’re looking to enable features for your drop-in component, the GraphQL request accepts additional headers. The below example shows how you could set the Commerce-Auth header with the customer token for the Authorization header, and how to set the store code header for store specific features. Replace the header values with the actual values from your Commerce backend services:

// Set the customer token. This method is specific to @dropins/storefront-cart package.
pkg.setFetchGraphQlHeader('commerce-auth', '<token>');

// Set store code header. This method is specific to the @dropins/tools package.
mesh.setFetchGraphQlHeader('store', '<default>');

Register and load the drop-in

The code below shows how to register the cart, load it (mount), and enable the logger for debugging purposes. You can add these functions within a <script> tag in your Cart HTML page as shown here:

<script type="module">
  // more code above...

  // Register and load the Cart drop-in
  initializers.register(pkg.initialize);

  // Mount Initializers (must be called after all initializers are registered)
  window.addEventListener('load', initializers.mount);
</script>

This function registers the cart to be loaded on the page by the initializers.mount function.
This event handler triggers the initializers.mount function to load the cart after the page has loaded.

Render the drop-in

Render the cart on the page. The example below provides the minimal configuration options required to render the default Cart drop-in component, along with an example to render Mini-Cart.

// Render Cart
provider.render(Cart, {
  routeProduct: (item) => {
    return `${item.url.categories.join('/')}/${item.url.urlKey}`;
  },
  routeEmptyCartCTA: () => 'your-empty-cart-element',
  routeCheckout: () => 'your-checkout-element',
})(document.getElementById('your-cart-element'));

// Render MiniCart
provider.render(MiniCart, {
  routeProduct: (item) => {
    return `${item.url.categories.join('/')}/${item.url.urlKey}`;
  },
  routeEmptyCartCTA: () => 'your-empty-cart-element',
  routeCart: () => 'your-cart-element',
  routeCheckout: () => 'your-checkout-element',
})(document.getElementById('your-mini-cart-element'));

Test the cart by viewing your cart page in a browser, or running your local dev or build server. If you see the cart rendered in the browser, congrats!, you have a successful installation. If not, check the console for any errors and verify that you have followed all the steps correctly.

Summary

The installation of all drop-in components follow the same pattern demonstrated by installing the cart: Install, Map, Import, Connect, Register, and Render.