AEM Commerce Prerender

The AEM Commerce Prerender solution enables your Edge Delivery Services Commerce Storefront to serve data-hydrated product page markup to search engines and AI crawlers before JavaScript executes. This can improve SEO rankings and makes your product catalog accessible to LLMs.

How it works

You deploy an App Builder application that runs continuously in Adobe’s cloud, monitoring your catalog and generating complete HTML for each product. This HTML is published to Edge Delivery Services and served as the initial HTML “source” to page visitors. Then, your product-details block enhances the pre-rendered HTML with interactive features powered by the PDP drop-in. You should deploy the App Builder app first because your storefront integration depends on the HTML it generates.

Pre-read: Bring Your Own Markup

The prerender solution uses Edge Delivery Services’ Bring Your Own Markup (BYOM) API to publish HTML content. Understanding how BYOM works helps clarify how prerendered content integrates with your storefront. The prerender app publishes HTML files that Edge Delivery Services serves as overlay content, enhancing your existing pages with prerendered product data.

Why use prerender?

Adobe Commerce on Edge Delivery Services historically used client-side JavaScript to render product information, limiting discoverability by search engines and AI systems that don’t execute JavaScript. Edge Delivery Services has no concept of server-side rendering in its stack; the prerender solution (which uses BYOM) is the closest equivalent. Prerendering solves this by generating complete HTML with structured data before pages are requested and publishing it via the Bring Your Own Markup API.

Key Benefits:

• Enhanced SEO: Complete HTML for search engines improves indexing and rankings
• LLM Readability: Structured markup that AI systems can parse and understand
• Improved Performance: Reduces the time-to-first-byte and serves immediate content
• Natural Fallback: Pre-rendered content displays while client-side drop-ins load
• Automated Updates: Monitors the product catalog and updates markup when products change

Implementation roadmap

This guide walks you through implementing the prerender solution in both required repositories. Follow these steps in order:

Loading diagram...

Complete implementation workflow showing the step-by-step process for setting up prerendered product pages in your storefront.

Prerequisites

Before implementing the prerender solution, verify you have:

Required access and permissions

• Adobe Developer Console access with “Developer” role for your organization
• App Builder workspace (Stage and Production workspaces recommended)
• AEM Admin API access for your Edge Delivery Services project (see AEM Admin API documentation)
• Adobe Commerce instance with Catalog Service configured and operational

Storefront requirements

Your Edge Delivery Services Commerce Storefront must be:

• Built on the Commerce boilerplate
• Configured with valid storefront configuration connecting to your Adobe Commerce backend
• Using product URLs with consistent format (typically /products/{urlKey}/{sku})

Technical requirements

• Node.js (current LTS version) installed locally
• Adobe I/O CLI (@adobe/aio-cli) installed globally
• Git for cloning the prerender repository
• Familiarity with JavaScript, Handlebars templates, and GraphQL

How it works

The prerender system operates as a continuous background process:

1. The store admin manages products in Adobe Commerce.
2. The Prerender Stack detects product changes.
3. The Prerender Stack renders pages with semantic markup.
4. The pages are published via the AEM Admin API.
5. The sitemap is updated via the AEM Admin API.
6. Store customers access the pre-rendered product details pages.

Loading diagram...

High-level workflow showing how product data flows from Store Admin through the Prerender Stack to deliver Product Details Pages to Store Customers.

Architecture components

The solution consists of these components:

• App Builder Actions: Serverless functions that handle product fetching, change detection, and markup generation
• Scheduled Triggers: Automated intervals (configurable) that invoke actions to keep content synchronized
• Catalog Service Integration: Queries product data from your Adobe Commerce backend
• AEM Admin API: Publishes generated markup to your Edge Delivery Services project
• Storage Layer: Maintains product state and generated markup in App Builder storage
• Management UI: Web interface for monitoring, configuration, and troubleshooting

Loading diagram...

Complete architecture showing App Builder actions, content management, and how pre-rendered and dynamic content are delivered to consumers.

Catalog Size Considerations

For catalogs exceeding 50,000 products, consult the AEM indexing limits documentation for sitemap splitting strategies and scaling considerations.

Installation and configuration

The AEM Commerce Prerender repository provides complete installation instructions. The following overview highlights the key configuration steps and values you’ll need.

Clone the repository and install dependencies

git clone https://github.com/adobe-rnd/aem-commerce-prerender.git
cd aem-commerce-prerender
npm install

Run the setup wizard

Run the setup wizard to generate your .env configuration:

npm run setup

The wizard prompts for your App Builder workspace selection and Adobe I/O authentication.

Configure environment variables

Configure environment variables in the generated .env file with your storefront-specific values:

Variable	Description	Example
ORG	Your GitHub organization or username	adobe
SITE	Your AEM site/repository name	your-storefront
CONTENT_URL	Your AEM content URL (auto-populated by setup wizard)	https://main--your-storefront--adobe.aem.live
STORE_URL	Your Commerce store URL (auto-populated by setup wizard)	https://main--your-storefront--adobe.aem.live
PRODUCTS_TEMPLATE	URL for the product template page (auto-populated by setup wizard)	https://main--your-storefront--adobe.aem.live/products/default
PRODUCT_PAGE_URL_FORMAT	URL pattern for product pages (auto-populated by setup wizard). Supports tokens: {locale}, {urlKey}, {sku}	/{locale}/products/{urlKey}
LOCALES	Comma-separated list of locales (e.g., en-us,en-gb,fr-fr) or empty for non-localized sites	en-us,fr-fr
AEM_ADMIN_API_AUTH_TOKEN	Long-lived authentication token for AEM Admin API (valid for 1 year). The setup wizard exchanges your temporary token for this automatically.	your-admin-token-here

Commerce configuration

The prerender app reads Commerce configuration (endpoints, headers, and store context) from your storefront’s config.json file, not from environment variables. Ensure your storefront has a properly configured config.json file with Commerce endpoints and headers as documented in the Storefront configuration documentation. For Adobe Commerce Optimizer, configure the appropriate headers (AC-View-ID, AC-Source-Locale, AC-Price-Book-ID) in your storefront’s config.json file.

Obtain required credentials

AEM Admin API token: To obtain your token:

1. Login to the AEM Admin API (select the link from your preferred Identity Provider; the ones suffixed by “_sa” allow you to select a specific account rather than the one currently logged in)
2. Once redirected to the JSON response, open your browser’s Developer Tools (F12)
3. Go to the Application tab (Chrome) or Storage tab (Firefox)
4. Under Cookies, find and copy the value of the auth_token cookie
5. Paste that token in the setup wizard textarea (the setup wizard exchanges your temporary token for a long-lived token automatically)

App Builder credentials: To configure the credentials:

1. Go to the Adobe Developer Console
2. Open your project and navigate to the workspace you want to use (Stage or Production)
3. Click the “Download All” button in the top-right to download the App Builder configuration file (a .json file)
4. Run aio app use <file_name> in the root directory of your prerender project to activate the credentials

Commerce credentials (Adobe Commerce as a Cloud Service): Access your Commerce Admin → System → Services → Commerce Services Connector for environment and API configuration

Commerce credentials (Adobe Commerce Optimizer): Configure your Commerce backend connection according to your deployment type. See the Storefront configuration documentation for details on configuring Optimizer headers and endpoints.

Note: Commerce configuration (endpoints and headers) is read from your storefront’s config.json file, not from environment variables. Ensure your storefront has a properly configured config.json file before deploying the prerender app.

Required: maxVersion in productDependencies

If your app.config.yaml includes a productDependencies array, each entry must include maxVersion or aio app build will fail with a validation error.

Correct format:

productDependencies:
  - code: <PRODUCT_CODE>
    minVersion: <MIN_VERSION>
    maxVersion: <MAX_VERSION>  # Required

Incorrect format (will cause build failure):

productDependencies:
  - code: <PRODUCT_CODE>
    minVersion: <MIN_VERSION>
    # Missing maxVersion - build will fail

See the Troubleshooting section below if you encounter this error.

Deploy to App Builder

npm run deploy

This deploys all actions and schedules to your selected workspace (Stage or Production).

Test the deployment

Manually invoke actions using the Management UI or via CLI commands:

# Fetch all products from Catalog Service and store them
aio rt action invoke aem-commerce-ssg/fetch-all-products

# Check for product changes and generate markup
aio rt action invoke aem-commerce-ssg/check-product-changes

# Clean up and unpublish deleted products
aio rt action invoke aem-commerce-ssg/mark-up-clean-up

Verify product markup generation for sample SKUs and check that pages publish successfully to your AEM project.

Enable automated synchronization

• Use the Management UI to start the change detector
• Configure polling intervals in the app.config.yaml file (default: checks for changes every 5 minutes)
• Monitor the product index to verify continuous updates

Management UI

After deployment, access the web-based Management UI to monitor and control your prerender deployment. The UI requires configuration with your App Builder workspace credentials before it displays deployment-specific data.

The Management UI provides:

• Monitoring capabilities to view published products and track the product index
• Change detector controls to start, stop, and configure scheduled product polling
• Markup preview to view generated HTML for product pages before publication
• Logs and activations for debugging App Builder action executions
• Storage management to trigger manual product operations and manage blob storage
• Configuration settings to review environment variables and deployment parameters

Access and authentication details are configured during the initial deployment process. Refer to the repository documentation for setup instructions.

Storefront integration

After installing the prerender solution, modify your Commerce boilerplate to integrate prerendered markup with your product detail pages.

Understanding the two-repository architecture

The prerender solution involves two separate codebases that work together:

1. The aem-commerce-prerender repository (App Builder app)

   • This repository is the one that you cloned, configured, and deployed in the previous section
   • Runs as a serverless application in Adobe App Builder
   • Generates prerendered HTML and publishes it to your Edge Delivery Services site
   • Operates independently as a background process

2. Your storefront repository (Commerce boilerplate)

   • Your customer-facing website code
   • Built on the Commerce boilerplate
   • Needs code modifications to properly consume the prerendered HTML
   • This repository is where you make the integration changes described below

How they connect: The App Builder app publishes prerendered HTML to its own blob store. The AEM Admin API configures the link to that blob store in your Edge Delivery Services configuration file as an overlay. The prerendered HTML is then served at URLs matching your product pages (for example, /products/acme-widget/sku123 - note that SKUs must be lowercase in URLs). When a visitor (or crawler) requests a product page, Edge Delivery Services serves this prerendered HTML from the overlay. Your storefront JavaScript then enhances the page by replacing the static HTML with the interactive PDP drop-in.

Loading diagram...

Two-repository architecture showing how the App Builder prerender app publishes HTML that your storefront code consumes and enhances for visitors.

How prerendered HTML reaches your storefront

The prerendered HTML flows from the App Builder app to your storefront through App Builder storage and Edge Delivery Services overlay configuration:

Publishing mechanism:

1. The App Builder app generates HTML → Creates complete HTML files with prerendered product markup
2. HTML stored in App Builder blob store → The App Builder app stores the HTML files in its own blob store
3. Overlay configured in EDS → The AEM Admin API configures the link to the App Builder blob store in your Edge Delivery Services configuration file as an overlay
4. Sitemap updated → The AEM Admin API also updates your sitemap to include the new and updated product pages
5. Content available → Edge Delivery Services now serves the prerendered HTML from the overlay when product page URLs are requested

The Commerce Prerender app uses App Builder storage and Edge Delivery Services overlay configuration. It is not an event-based system. Each time the App Builder app detects a product change and generates HTML, it stores the HTML in its blob store and configures the overlay link via the AEM Admin API. When the overlay is configured, the prerendered HTML is served at the product URLs automatically; the storefront does not need to perform any additional fetching or configuration.

How the storefront serves prerendered HTML

When a visitor requests a product page URL (for example, /products/acme-widget/sku123), Edge Delivery Services serves the prerendered HTML as the actual page. The HTML already contains the product-details block populated with prerendered content; your storefront doesn’t fetch it separately.

The delivery sequence:

1. Request arrives → Edge Delivery Services receives the URL request
2. HTML served → EDS returns the prerendered HTML file (published by the App Builder app)
3. Page loads → The browser displays the page with prerendered content (crawlers stop here)
4. JavaScript executes → Your storefront code runs
5. Enhancement → The product-details block’s decorate() function replaces static HTML with interactive UI

This process is called progressive enhancement: The prerendered HTML is the initial page that everyone sees. The storefront code reads the existing DOM, extracts the SKU from the meta tag, and upgrades the page to an interactive experience for users with JavaScript. This approach ensures that crawlers and users without JavaScript always see complete product information, while users with JavaScript get the full interactive experience.

Modifying your product-details block

Developers must modify the product-details block in their Commerce boilerplate to integrate prerendered markup with the PDP drop-in.

Location

The `product-details` block lives in your boilerplate at:

blocks/product-details/product-details.js

Integration pattern

Your block decorate() function should:

1. Preserve prerendered markup: The block already contains server-rendered HTML visible to crawlers before JavaScript executes.
2. Retrieve the SKU: Get the product SKU from the <meta name="sku"> tag instead of parsing the sanitized URL.
3. Replace with PDP drop-in: Clear the prerendered content and render the interactive PDP component.

Simplified code example

The following code example shows a simplified integration pattern for clarity. The actual boilerplate implementation uses event-based data loading and more complex rendering logic. For the complete implementation, refer to the `product-details` block in the Commerce boilerplate.

// File location: blocks/product-details/product-details.js
// Import paths are relative to blocks/product-details/product-details.js
import { getProductSku } from '../../scripts/commerce.js';
import { render as productRenderer } from '@dropins/storefront-pdp/render.js';
import { ProductDetails } from '@dropins/storefront-pdp/containers/ProductDetails.js';

export default async function decorate(block) {
  // Step 1: Preserve prerendered markup
  // The block already contains prerendered HTML from the App Builder app.
  // Crawlers see this content before JavaScript executes, ensuring SEO visibility.
  // No action needed here; the HTML is already present in the DOM.

  // Step 2: Retrieve the SKU from the meta tag (with URL fallback)
  // getProductSku() checks for <meta name="sku"> first, then falls back to URL parsing
  // This ensures correct SKU retrieval even if URLs are lowercase-sanitized
  const sku = getProductSku();

  // Step 3: Replace prerendered HTML with interactive PDP drop-in
  block.innerHTML = ''; // Clear the prerendered static content
  await productRenderer.render(ProductDetails, { sku })(block); // Render interactive UI
}

URL format and SKU handling

The prerender system generates markup files that match your storefront product URL structure. By default, this uses the format:

/products/{urlKey}/{sku}

The PRODUCT_PAGE_URL_FORMAT can be customized in your .env configuration .

SKU Lowercase Requirement

Starting with the October 2025 Adobe Commerce Storefront release, all SKUs in product URLs are automatically converted to lowercase to ensure URL consistency and proper resolution. When the prerendered markup is generated, the actual SKU (with original casing) is stored in a meta tag:

<meta name="sku" content="MY_PRODUCT_123">

This allows your PDP drop-in to retrieve the correct SKU regardless of URL transformations, which is why the code example above retrieves the SKU from the meta tag rather than parsing it from the URL.

For complete implementation examples, refer to the `product-details` block in the Commerce boilerplate.

Customization

The prerender solution provides these customization options:

Customization	Purpose and Configuration
Templates	Control HTML markup structure and styling. By default, markup is handled on the client side at {store_url}/product/default. If the default template is not available, you can edit the template at `actions/pdp-renderer/templates/product-details.hbs`
Structured Data	Customize JSON-LD schemas in `actions/pdp-renderer/ldJson.js` to optimize product rich snippets for search engines
GraphQL Queries	Extend product data by modifying GraphQL queries in `actions/queries.js` . The rendering logic that uses these queries is implemented in the generateProductHtml method in `actions/pdp-renderer/render.js`
URL Patterns	Match your storefront URL structure by configuring PRODUCT_PAGE_URL_FORMAT in the .env file
Rendering Logic	Transform product data before markup generation by implementing custom logic in App Builder actions

For implementation details, see the AEM Commerce Prerender repository , particularly the actions/ directory and repository root for templates and configuration files.

Troubleshooting

For troubleshooting during development and operations, consult the prerender runbook .

Build error: Missing maxVersion in productDependencies

Error: must have required property 'maxVersion' in /productDependencies/0

Fix: Add maxVersion to each entry in your productDependencies array:

productDependencies:
  - code: <PRODUCT_CODE>
    minVersion: <MIN_VERSION>
    maxVersion: <MAX_VERSION>  # Required field

Then redeploy:

npm run deploy

productDependencies vs requiredProducts

The productDependencies field is validated by the Adobe I/O CLI schema. For publicly distributed apps, Adobe App Builder documentation uses requiredProducts instead. Both fields serve similar purposes but may be used in different contexts. If you’re using productDependencies, ensure maxVersion is included for each entry to pass validation.

Authentication failures

Fix: Generate a new AEM Admin API token and update your .env file:

1. Get a new token from the AEM Admin API
2. Update AEM_ADMIN_API_AUTH_TOKEN in your .env file
3. Redeploy:

npm run deploy

Verify token expiration: Decode your token using jwt.io or check your AEM project admin panel . Tokens expire after 1 year.

Product not rendering

Fix: Verify the product exists in Catalog Service and check action logs:

# Check action logs
aio rt activation list

# Query Catalog Service directly
# Use the GraphQL Product API: https://developer.adobe.com/commerce/services/graphql/catalog-service/products/

Verify: Use the Management UI to view the product index and confirm the SKU is listed.

Markup not updating

Fix: Check if the Change Detector is running and manually trigger if needed:

1. Access the Management UI — change detector status should show “Running”
2. Check activation logs:

aio rt activation list

3. Manually trigger the change detector from the Management UI to test functionality

For more details, see the runbook .

Additional resources

• App Builder Documentation: Adobe Developer App Builder
• Catalog Service Guide: Adobe Commerce Catalog Service
• Edge Delivery Services: Publishing to Edge Delivery Services
• AEM Admin API: AEM Admin API (The prerender app automatically uses this API to publish content; useful for understanding the publishing mechanism and troubleshooting authentication issues)

Support

For technical issues or questions during implementation, consult the runbook or contact Adobe Commerce support.

Merchant documentation Explain prerendering benefits to store administrators