Skip to content
Adobe Commerce Storefront
Docs Playgrounds Videos

Cart Installation

Our dropins are designed for the browser’s JavaScript runtime without the need for a bundler. You can also install and execute dropins 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 dropin package imports.

Big picture

Use the following steps to install the Cart dropin:

PDP Installation

Step-by-step

Use the following steps to install the Cart dropin on your site.

Install the packages

Use a CDN or NPM (recommended for performance) to install the dropin tools (@dropins/tools) and Cart (@dropins/cart) packages.

npm install @dropins/tools @dropins/cart

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 dropin files from the dropin tools (@dropins/tools) and the Cart dropin (@dropins/cart):

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

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

Import the required files

Import the required files from the dropins tools (@dropins/tools/fetch-graphql.js', @dropin/tools/initializers.js) and the Cart dropin (@dropins/cart) into a JavaScript file for your Cart dropin. 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 dropin for your site:

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


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


// Dropin Functions
import * as pkg from '@dropins/cart/api.js';


// Dropin Provider
import { render as provider } from '@dropins/cart/render.js';


// Dropin Containers
import Cart from '@dropins/cart/containers/Cart.js';
import MiniCart from '@dropins/cart/containers/MiniCart.js';

GraphQL Client

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

Dropin Tools

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

Dropin Functions

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

Dropin Provider

Renders the Cart UI.

Dropin Containers

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

Connect to the endpoint

Connect your Cart dropin 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:

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

Request headers

The Cart dropin does not need additional headers set for basic installation. But if you’re looking to enable features for your dropin, 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:

cart.js
// Set the customer token. This method is specific to @dropins/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 dropin

The code below shows how to register the Cart dropin, 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:

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


  // Register and load the Cart dropin
  initializers.register(pkg.initialize);


  // Mount Initializers (must be called after all initializers are registered)
  window.addEventListener('load', initializers.mount);
</script>
  1. This function registers the Cart dropin to be loaded on the page by the initializers.mount function.
  2. This event handler triggers the initializers.mount function to load the Cart dropin after the page has loaded.

Render the dropin

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

cart.js
// 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 dropin by viewing your Cart page in a browser, or running your local dev or build server. If you see the Cart dropin 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 dropins follow the same pattern demonstrated by installing the Cart dropin: Install, Map, Import, Connect, Register, and Render. We like to call the process iMICRR for short, pronounced eye-mike-er. Actually, we don’t call it that, but if it helps…Enjoy!