Replace InStore POS UI modules

InStore Add-On
Ask about this Page
Copy for AI
View as Markdown

Replace a component of the InStore POS with a micro-frontend that you build and host, registered as an external module.

How POS UI module replacement works

The InStore POS is a host application that loads each of its components as a separate micro-frontend using Module Federation. Module Federation calls each loaded micro-frontend a remote. In InStore, you register a replacement as an external module.

An external module is a record that tells the POS to load your replacement module in place of a built-in component. You register the external module once for your tenant. Then assign it to a location or to a workstation. When a workstation starts, InStore resolves which external modules apply to it. It returns them with the rest of the workstation configuration. The POS loads your replacement module from the address in the record.

Registration and assignment are configuration. The replacement module itself is code that you build, host, and serve.

Components you can replace

You can replace the following components. The type field of the external module record selects which one the replacement module provides:
typeComponent that the replacement module providesImplementation guide
CartCart pageImplement the Cart module
CatalogCatalog browsing and searchImplement the Catalog module
CustomerCustomer lookup pageImplement the Customer module
LookupCustomerCustomer control in the POS headerImplement the Customer module

An external module record describes where your replacement module lives and how to load it, and which component it replaces.

The following table lists the fields in the record you create for a replacement module:

FieldData typeDescription
defaultBooleanWhether the module is the tenant-wide fallback for its type. At most one module per type can be the default.
keyStringUnique identifier for the module within your tenant. Accepts 2 to 256 letters, digits, underscores, and hyphens.
moduleStringPath that the replacement module exposes for the component, such as ./CartApp.
scopeStringModule Federation container name that the replacement module exposes, such as acmeCart.
typeStringComponent that the replacement module provides. See Components you can replace for supported values.
urlStringAddress of the remoteEntry.js file for the replacement module. Accepts http and https addresses up to 2048 characters.

The following request body registers a Cart replacement module:

External module request bodyjson
{
  "key": "external-cart-component",
  "url": "https://modules.example.com/InStore_Example_Cart/remoteEntry.js",
  "type": "Cart",
  "scope": "acmeCart",
  "module": "./CartApp",
  "default": true
}

A replacement module runs inside the POS host and shares the host React instance. It renders within the same providers as a built-in module. Build the replacement module against the Module Federation interface of the component it replaces. Expose the container name and module path that you register.

Due to its hosted nature, the InStore POS loads a replacement module only through the Module Federation interface described on this page. A replacement module that does not expose the registered container name and module path fails to load. The component is then unavailable at every workstation the module is assigned to.

Assignments follow three rules:

  • Each location and each workstation accepts at most one external module per type. To swap an assigned module, remove the existing assignment first.
  • An external module that is still assigned to a location or a workstation can't be deleted. Remove every assignment first.
  • At most one external module per type can be the tenant default.

The InStore State module

The POS keeps its shared state and services in the InStore State module, published as instoreState and consumed through Module Federation. That module owns the active Cart, localization, workstation configuration, the API client, and the theme. Every built-in component reads from it rather than holding its own copy.
A replacement module works the same way. It declares instoreState as a Module Federation remote and reads what it needs from there instead of calling the InStore backend on its own. This keeps a replaced component and the rest of the POS aligned on one Cart, one locale, and one session.
For the build setup that every replacement module needs, see Build a replacement module.

Module resolution model

InStore consults three tiers to decide which external modules apply to a workstation. It uses the first tier that yields an assignment:

  1. Assignments on the workstation.
  2. Assignments on the parent location.
  3. External modules marked as the tenant default.

Tiers apply as a whole rather than merging by type. If a workstation assigns any external module, that assignment set answers in full. The workstation inherits nothing from its location. If no tier yields an external module, the POS loads the module bundled with it.

Changes take effect the next time the POS loads at that workstation.

Relationship to POS theming

Theming and module replacement address different needs. A theme restyles the modules that ship with the POS and leaves their behavior in place. A replacement module substitutes the module itself, so both its behavior and its markup are yours. Because the replacement module renders inside the host providers, it can read the tenant theme, but applying that theme is the responsibility of your replacement module. To change the appearance of the built-in modules instead, see Customize the InStore POS UI.

Next steps

Use the following resources to continue working with InStore POS modules: