Extension registration

AEM UI extensions are specialized App Builder app, based on React and use the React Spectrum UI framework.

To define where and how the AEM UI extension appears, two configurations are required in the extension’s App Builder app: app routing and the extension registration.

App routes app-routes

The extension’s App.js declares the React router that includes an index route that registers the extension in the AEM UI.

The index route is invoked when the AEM UI initially loads, and target of this route defines how the extension is exposed in the console.

import ExtensionRegistration from "./ExtensionRegistration"
...
function App(props) {
  return (
    <Router>
      <ErrorBoundary onError={onError} FallbackComponent={fallbackComponent}>
        <Routes>
          {/* The index route maps to the extension registration */}
          <Route index element={<ExtensionRegistration />} />
          ...
        </Routes>
      </ErrorBoundary>
    </Router>
  )
  ...
}

Extension registration

ExtensionRegistration.js must be immediately loaded via the index route of the extension, and acts the registration point of the extension.

Based on the AEM UI extension template selected when initializing the App Builder app extension, different extension points are supported.

Conditionally include extensions

AEM UI extensions can execute custom logic to limit the AEM environments the extension appears in. This check is performed before the register call in the ExtensionRegistration component, and immediately returns if the extension should not be displayed.

This check has limited context available:

The most common checks for loading an extension are:

The example below illustrates limiting the extension to all environments in program p12345.

function ExtensionRegistration() {
  const PROGRAM_ID = 'p12345';

  // Get the current AEM Host (author-pXXX-eYYY.adobeaemcloud.com) the extension is loading on
  const aemHost = new URLSearchParams(window.location.search).get('repo');

  // Create a check to determine if the current AEM host matches the AEM program that uses this extension
  const aemHostRegex = new RegExp(`^author-${PROGRAM_ID}-e[\\d]+\\.adobeaemcloud\\.com$`)

  // Disable the extension if the Cloud Manager Program Id doesn't match the regex.
  if (!aemHostRegex.test(aemHost)) {
    return; // Skip extension registration if the environment is not in program p12345.
  }

  // Else, continue initializing the extension
  const init = async () => { .. };

  init().catch(console.error);
}