Blocks and drop-ins

Your Git repository is where blocks connect to drop-ins: its decorators, initializers, styles, and configuration load the correct drop-in for each commerce block on the page.

Comparing blocks and drop-in components

Each document table becomes a block div that EDS and your JavaScript identify. Your repo connects commerce blocks to drop-ins through decorators, scripts/initializers/, styles, and storefront configuration, then pushes to GitHub to drive Edge Delivery builds.

Authoring references: Document Authoring documentation , Document Authoring and Experience Workspace Quick Starts, authoring page , AEM documentation . For packages and shared vocabulary, see Drop-ins at a glance and Boilerplate overview.

	Content blocks	commerce blocks	Drop-in components
Role	Layout and marketing UI (cards, heroes, columns, headers, footers)	Interactive Commerce experiences (cart, checkout, account, PDP, …)	Packaged UI and logic that commerce blocks load and initialize
Where it comes from	Block Collection and custom blocks in blocks/	commerce blocks in blocks/, mapped in the boilerplate	npmNode's package manager. You use it to install drop-in packages — for example, `npm install @dropins/storefront-cart` — in your storefront repository. packages such as @dropins/storefront-cart
Authored as document tables	Yes	Yes	No — developers add packages and wire initializers in code
Typical tie to Adobe Commerce	None — no Commerce GraphQL for most blocks	Yes — GraphQL, REST, and services through the boilerplate	Direct — Commerce API calls (GraphQL, REST, services) are built into each package
Learn more	Block Collection	Key files and folders · Blocks reference	Drop-ins introduction

Commerce Storefront SDK

Drop-in components are built on shared Commerce Storefront SDKThe Drop-in SDK used to build custom drop-ins and related integration logic. patterns (initialization, rendering, slots, and extension hooks) so behavior and structure stay consistent across cart, checkout, product discovery, and the rest of the set.

• Commerce Storefront SDK — Reference for APIs, design components, and utilities used across drop-in components
• Drop-ins introduction — Full map of B2C and B2B drop-in components and how they install into the boilerplate

Content blocks and commerce blocks

Both kinds are document tables EDS turns into HTML. The split is what runs next. Content blocks are layout and marketing (cards, columns, headers, footers from the Block Collection ). They contain no drop-ins or Commerce GraphQL. commerce blocks load interactive cart, checkout, account, PDP, and similar flows via initializers and @dropins/* calling Commerce GraphQL and related APIs. Prefer plain JavaScript for commerce blocks, since React can make a top Lighthouse score hard to achieve. See Libraries for the details, and use the boilerplate’s existing blocks as patterns for your own.

How blocks connect to drop-ins

Every commerce block wires itself to a drop-in the same way. Here is Cart as an example:

1. The block file imports its initializer at the top of the file, so its setup finishes before decorate() ever runs. The import doesn’t capture anything the initializer exports. Its only purpose is to run the initializer’s setup code.

   blocks/commerce-cart/commerce-cart.js

   import '/scripts/initializers/cart.js';

   That import runs the initializer, which sets the drop-in’s GraphQL endpoint, loads its UI labels, and calls initializers.mountImmediately(), passing the drop-in package’s initialize function to activate the drop-in.

   scripts/initializers/cart.js

   import { initializers } from '/@dropins/tools/initializer.js';
   import { initialize, setEndpoint } from '/@dropins/storefront-cart/api.js';
   import { initializeDropin } from '/index.js';
   import { CORE_FETCH_GRAPHQL, fetchPlaceholders } from '/commerce.js';
   
   await initializeDropin(async () => {
     setEndpoint(CORE_FETCH_GRAPHQL);
     const labels = await fetchPlaceholders('placeholders/cart.json');
     const langDefinitions = { default: { ...labels } };
     return initializers.mountImmediately(initialize, { langDefinitions });
   })();

2. The block also imports render functions and containers from the drop-in package at the top of the file. Inside its decorate() function, the block calls those functions to mount the drop-in’s UI into the block’s DOM.

   blocks/commerce-cart/commerce-cart.js

   import { render as provider } from '/@dropins/storefront-cart/render.js';
   import CartSummaryList from '/@dropins/storefront-cart/containers/CartSummaryList.js';
   
   export default async function decorate(block) {
     const cartList = document.createElement('div');
     block.append(cartList);
     provider.render(CartSummaryList, { /* ... */ })(cartList);
   }

The same pattern repeats for every commerce block: import the initializer, let it configure and activate the drop-in, then call the drop-in’s render function.

Key files and folders

The Adobe Commerce boilerplate separates core AEM block delivery from Commerce-specific code (scripts/commerce.js, scripts/initializers/, and storefront configuration) so both sides stay maintainable independently.

For the full repository map, see Exploring the code in Boilerplate overview. The table below explains the key files and folders that wire a commerce block to a drop-in. For the full Scripts folder in the boilerplate and blocks/:

File/Folder	Role
scripts/scripts.js	Page load, block decoration, fonts, and orchestration of eager, lazy, and delayed loading phases. Imports from scripts/aem.js and scripts/commerce.js. Also the extension point for global DOM decorators, third-party plugins (such as experimentation tools), and any code that must run eagerly on page load.
scripts/commerce.js	Commerce-specific loading, templates, page type detection, Adobe Client Data Layer (ACDL) initialization, and storefront configuration. ACDL is a JavaScript library that captures shopper behavior for analytics. You will see it again in How drop-ins coordinate and Analytics events. Centralizes all commerce features and keeps them distinct from core AEM logic.
scripts/initializers/	One initializerA JavaScript module that configures a drop-in when imported, such as setting endpoints, registering dictionaries, and preparing runtime behavior. file per drop-in. See How blocks connect to drop-ins above for the full sequence, and Connect a drop-in for the code pattern.
blocks/	Where commerce block decorators call drop-in initializers; content blocks render markup only. See Content blocks and commerce blocks above.

Customize and connect: Customize blocks, Blocks reference, Storefront configuration.