PDP installation

Our dropin-in components are designed for the browser’s JavaScript run-time without the need for a bundler. But they can also be installed and executed in a build-time environment with bundlers like Webpack and Vite. The installation steps for both run-time and build-time environments are the same after the initial drop-in component package imports.

Prerequisites

Before you install the product details page (PDP) drop-in component, ensure you have the following prerequisites:

Workflow

The steps for installing the PDP drop-in component are as follows:

Step-by-step

The following steps show how to install the product details component into your site.

Install the packages

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

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

<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-pdp@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 PDP drop-in component (@dropins/storefront-pdp):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/node_modules/@dropins/tools/",
      "@dropins/storefront-pdp/": "/node_modules/@dropins/storefront-pdp/",
    }
  }
</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 product details component (@dropins/storefront-pdp):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/scripts/__dropins__/tools/",
      "@dropins/storefront-pdp/": "/scripts/__dropins__/storefront-pdp/",
    }
  }
</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 product details component (@dropins/storefront-pdp):

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

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

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

Import the required files

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

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

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

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

// Drop-in component container
import ProductDetails from '@dropins/storefront-pdp/containers/ProductDetails.js';

Connect to the endpoint

Connect your product details component to the Catalog Service GraphQL 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
product.setEndpoint('https://<catalog-service-endpoint>/graphql');

product.setFetchGraphQlHeaders({
  // Environment required headers
  'Magento-Environment-Id': 'your-environment-id',
  'Magento-Store-View-Code': 'your-store-view-code',
  'Magento-Website-Code': 'your-website-code',
  'x-api-key': 'your-api-key',
  'Magento-Store-Code': 'main_website_store',
  'Magento-Customer-Group': 'your-customer-group',
  'Content-Type': 'application/json',
});

Register and load the drop-in

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

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

  // Register and load the product details component
  initializers.register(pdp.initialize);

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

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

Render the drop-in

Render the product details component on the page. The example below provides the minimal configuration options required to render the default product details component:

// Render product details
productRenderer(ProductDetails, {
  sku: 'SKU-001',
  // other configuration options
  // slots for adding custom elements, components, and functions
})(document.getElementById('your-pdp-element'));

Test the product details component by viewing your PDP page in a browser, or running your local dev or build server. If you see the product details component 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 dropin-in components follows the same pattern demonstrated by installing the PDP drop-in: 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!