Skip to content
Adobe Commerce Storefront

Search is only available in production builds. Try building and previewing the site to test it out locally.

Initializer

// my-domain-package/initializer.ts


import { Initializer } from '@adobe/elsie/lib';
// import { events } from '@adobe/event-bus';


type ConfigProps = {};


export const initialize = new Initializer<ConfigProps>({
  init: async (config) => {
    const defaultConfig = {};
    initialize.config.setConfig({ ...defaultConfig, ...config });
  },


  listeners: () => [
    // events.on('authenticated', (authenticated) => {
    //   console.log('authenticated', authenticated);
    // }),
  ],
});


export const config = initialize.config;
// Host Site
import { initializers } from '@dropins/elsie/initializer.js';
import { initialize as pkg } from 'my-domain-package/initializer.js';


// Register Packages
initializers.register(pkg, { ...config });


// Mount Initializers
window.addEventListener('load', initializers.mount);

setImageParamKeys(params)

The setImageParamKeys method is part of the initializers module in the @dropins/tools package. It allows you to set image parameters globally for all drop-in components that use the Image component. CDN-based image optimization services, such as Fastly and Cloudflare, rely on these parameters to optimize images.

Default behavior

Since Fastly is the default CDN for Adobe Commerce on Cloud, drop-in components add the following Fastly-style parameters to all image URLs by default:

  • width
  • height
  • auto
  • quality
  • crop
  • fit

Example:

/media/catalog/product/adobestoredata/ADB150.jpg?auto=webp&quality=80&crop=false&fit=cover&width=960&height=1191`

Technical details about CDN-based image optimization differ depending on your backend Adobe Commerce solution:

  • PaaS only Fastly is the default CDN-based image optimization service for Adobe Commerce on Cloud projects. Fastly-style parameters are used by default unless overridden via setImageParamKeys.

  • SaaS only Cloudflare is the default CDN-based image optimization service for Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer projects. Fastly-style parameters are used but are proxied through a Cloudflare Worker to transform the parameters to Cloudflare-style parameters. Overriding the default parameters using setImageParamKeys may interfere with the proxy transformation and lead to unexpected results.

Parameters

  • params - { [key: string]: string | ((data: any) => [string, string]) }
    • An object of key-value pairs to map image parameters to their respective keys in the URL.
    • The value can be a string or a function that takes the parameter value as an argument and returns a tuple of the new key and transformed value.

Functionality

  • If a parameter key is provided via setImageParamKeys, it is used in generating image URLs instead of the default Fastly parameters.
  • If a parameter key is not provided via setImageParamKeys, it is omitted from the generated image URLs.
  • If a mapped key is a function and it is not specified as a parameter in the Image component, it is called with null. It should return a tuple of the key and value.
  • If a mapping callback is provided, the callback is called with the parameter value (if it exists) and should return a tuple of the new key and transformed value.
  • If a mapping callback returns null, the parameter is omitted from the generated image URLs.

Usage

Call the setImageParamKeys() function before the mountImmediately() function in the application layer.

// Set global image parameters
initializers.setImageParamKeys({
  // Re-map the width parameter to imgWidth
  width: 'imgWidth',
  // Transform the quality parameter
  quality: (value) => ['imgQuality', value * 100],
  // Add an additional parameter to the image URL
  extraParam: () => ['extraParam', 'extraValue'],
});


// Register and Mount Initializers immediately
initializers.mountImmediately(pkg.initialize, {
  // other configurations...
});

Now, when a dropin uses the Image component to render an image with a width of 300 pixels and quality value of 0.8:

<Image
  loading={'lazy'}
  src={'https://example.com/image.jpg'}
  alt={'Example Image'}
  width="300"
  height="300"
  params={{ width: 300, quality: 0.8 }}
/>

It renders the following image element:

<img
  loading="lazy"
  src="https://example.com/image.jpg"
  srcset="https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 768w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1024w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1366w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1920w"
  alt="Example Image"
  width="300"
  height="300"
/>

In this example, the width parameter is mapped to imgWidth and the value of the quality parameter is modified and mapped to imgQuality.

setGlobalLocale(locale)

The setGlobalLocale() method is part of the initializers module in the @dropins/tools package. It allows you to set a global locale for all drop-ins that use locale-sensitive components like the Price component.

Default behavior

By default, locale-sensitive components use the browser’s locale or fallback to ‘en-US’ if no global locale is set. Locale-sensitive components follow this fallback hierarchy:

  1. Component-specific locale prop (highest priority)
  2. Global locale set via setGlobalLocale()
  3. Browser’s locale (navigator.language)
  4. Default fallback locale ('en-US') (lowest priority)

This ensures that your storefront always displays properly formatted content, even when specific locales are not configured.

Parameters

  • locale - string - The locale string (e.g., ‘en-US’, ‘es-MX’, ‘fr-FR’, ‘de-DE’).

Functionality

  • If a global locale is set via setGlobalLocale(), it will be used by components that support locale configuration.
  • Component-specific locale props will take precedence over the global locale.
  • If no global locale is set, components will fall back to the browser’s locale or a default locale.

Usage

Call the setGlobalLocale() function before the mountImmediately() function in the application layer.

// Set global locale for consistent formatting across all drop-ins
initializers.setGlobalLocale('fr-FR');


// Register and Mount Initializers immediately
initializers.mountImmediately(pkg.initialize, {
  // other configurations...
});

Basic Example

When a drop-in uses the Price component without specifying a locale prop:

<Price
  amount={100}
  currency="EUR"
/>

It will render with the global locale (fr-FR) formatting:

<span class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
  100,00 €
</span>

Override Example

If the same component is used with a specific locale prop, that will take precedence over the global setting:

<Price
  amount={100}
  currency="EUR"
  locale="en-US"
/>

It will render with the specified locale (en-US) formatting:

<span class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
  €100.00
</span>