A compatibility layer that lets legacy @edx/frontend-platform consumers and legacy @openedx/frontend-plugin-framework (FPF) env.config.jsx configuration run on top of @openedx/frontend-base sites, as a migration aid during the FPF deprecation window.
The package does three coupled jobs from one install:
-
@edx/frontend-platformdrop-in. It re-exports the i18n and auth surfaces from frontend-base (souseIntl,defineMessages,getAuthenticatedHttpClient, etc. resolve to frontend-base's implementations), and exposes agetConfigadapter that reads through togetSiteConfig()andcommonAppConfig. A dependency alias points@edx/frontend-platform[/...]at the compat package, so real frontend-platform is never installed. -
FPF drop-in. It re-exports the public surface of
@openedx/frontend-plugin-framework(Plugin,PluginSlot,DIRECT_PLUGIN,IFRAME_PLUGIN,PLUGIN_OPERATIONS) so the package can stand in for FPF via a second dependency alias. -
FPF translation. It exports
createLegacyPluginApp({ appId, envConfig, mfeId?, routeMap?, slotMap?, widgetMap? }), which invokes a legacysetConfigfunction, translates itspluginSlotsinto a frontend-baseSlotOperation[], and returns anAppwhoseslotscarry the result. PassmfeIdto scope the translated ops to a single legacy MFE's routes.
See ADR 0001 for the design and trade-offs.
The compat package only covers the runtime import surface of @edx/frontend-platform and @openedx/frontend-plugin-framework. The following concerns sit outside that boundary:
The shim does not shim DOM or CSS. Brand and plugin stylesheets written against legacy MFE markup no longer match what frontend-base renders, and operators are expected to rewrite the affected selectors or move the styling into brand theming. See ADR 0001 for why a CSS shim is out of scope.
One specific gotcha worth calling out: frontend-base renamed the theme-variant attribute and storage key. Brand stylesheets and any plugin CSS that keys off the legacy names will not match what frontend-base puts on the DOM. The mapping is:
Legacy (frontend-platform) |
Current (frontend-base) |
Where it appears |
|---|---|---|
data-paragon-theme-variant |
data-theme-variant |
<html> element and <link> theme stylesheets |
data-brand-theme-variant |
(no equivalent) | brand-override <link> elements; frontend-base collapses brand into the variant <link> itself |
selected-paragon-theme-variant |
selected-theme-variant |
localStorage key for the active variant |
Brand authors should rename the corresponding selectors and storage reads at the source. The shim deliberately does not bridge these at runtime: a DOM mirror would have to fight React's own effects, and brand authors are already touching CSS during the frontend-base migration for unrelated markup changes.
The compat package does not provide any shims for @openedx/frontend-build. Plugin packages that ship preinstall hooks invoking fedx-scripts will fail to install in a frontend-base site, because the consumer tree does not have those build tools or the plugin's devDependencies.
In the site's package.json, install the compat package directly (so operator code can import { createLegacyPluginApp, defaultSlotMap, ... } from '@openedx/frontend-base-compat'), alias @edx/frontend-platform and @openedx/frontend-plugin-framework to it, and mirror those aliases in overrides with the exact same specs:
{
"dependencies": {
"@openedx/frontend-base-compat": "^1.0.0",
"@edx/frontend-platform": "npm:@openedx/frontend-base-compat@^1.0.0",
"@openedx/frontend-plugin-framework": "npm:@openedx/frontend-base-compat@^1.0.0"
},
"overrides": {
"@edx/frontend-platform": "npm:@openedx/frontend-base-compat@^1.0.0",
"@openedx/frontend-plugin-framework": "npm:@openedx/frontend-base-compat@^1.0.0"
}
}The direct entry puts the compat package at node_modules/@openedx/frontend-base-compat/ for the site's own imports. The two aliases additionally place the package at node_modules/@edx/frontend-platform/ and node_modules/@openedx/frontend-plugin-framework/, so any import of either legacy name resolves to the stubs. The matching overrides entries force every transitive resolution (peer or regular) to the same alias, which is what lets plugins that pin these as peer dependencies at the real version ranges (e.g. @openedx/frontend-plugin-aspects, which pins @edx/frontend-platform: ^8.3.1 and @openedx/frontend-plugin-framework: ^1.7.0) install without ERESOLVE and without needing --legacy-peer-deps. The two specs must match exactly; npm errors if a direct dep and its override disagree.
With the first alias in place, plugin code that imports from @edx/frontend-platform keeps working unchanged:
import { getConfig, camelCaseObject } from '@edx/frontend-platform';
import { useIntl, defineMessages } from '@edx/frontend-platform/i18n';
import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';The i18n and auth subpaths re-export frontend-base's existing implementations directly. getConfig() returns a Proxy that resolves UPPER_SNAKE_CASE keys against:
- A curated translation table mirroring edx-platform's
SITE_CONFIG_TRANSLATION_MAP, reading the corresponding camelCase field fromgetSiteConfig(). getSiteConfig().commonAppConfigfor everything else, which is where edx-platform's compatibility layer puts non-translatedMFE_CONFIGvalues (INDIGO_*, plugin-specific keys, etc.).
Unknown keys return undefined. The Proxy re-reads getSiteConfig() on every access, so it stays current under mergeSiteConfig updates.
Place the legacy env.config.jsx under the site's src/ directory. (The frontend-base webpack config only runs ts-loader over files in src/.) Then, in site.config.build.tsx / site.config.dev.tsx, import the legacy config and register a shim App:
import { createLegacyPluginApp } from '@openedx/frontend-base-compat';
import envConfig from './src/env.config.jsx';
const config: SiteConfig = {
// ...
apps: [
// ... regular frontend-base Apps ...
createLegacyPluginApp({
appId: 'org.openedx.frontend.app.compat',
envConfig,
}),
],
};createLegacyPluginApp also accepts optional slotMap and widgetMap arguments that override or extend the shim's curated defaultSlotMap and defaultWidgetMap. The typical pattern is to spread the defaults and add site- or plugin-specific deltas:
import {
createLegacyPluginApp,
defaultSlotMap,
defaultWidgetMap,
} from '@openedx/frontend-base-compat';
import envConfig, { compatSlotMap, compatWidgetMap } from './src/env.config.compat.jsx';
createLegacyPluginApp({
appId: 'org.openedx.frontend.app.compat',
envConfig,
slotMap: { ...defaultSlotMap, ...compatSlotMap },
widgetMap: { ...defaultWidgetMap, ...compatWidgetMap },
});A frontend-base site that hosts more than one legacy MFE in the same shell needs each MFE's plugin ops to fire only on that MFE's routes. Without scoping, a Hide for one MFE's chrome would leak into another's, since translated ops apply globally by default. Pass mfeId to opt every op for that app into condition: { active: [...] }, scoped to the route roles registered by the corresponding frontend-base port:
import { createLegacyPluginApp } from '@openedx/frontend-base-compat';
import envConfig from './src/env.config.dashboard.jsx';
createLegacyPluginApp({
appId: 'org.openedx.frontend.app.compat.learnerDashboard',
envConfig,
mfeId: 'learner-dashboard',
});The shim ships defaultRouteMap, a curated mfeId -> routeRoles[] table covering the legacy MFEs whose frontend-base ports already exist (learner-dashboard, authn, ...). Override or extend it via the routeMap argument the same way as slotMap/widgetMap.
If mfeId is set but neither the supplied routeMap nor defaultRouteMap has an entry for it, the shim warns once and registers the app as a no-op.
| FPF op | Translation |
|---|---|
Insert (DIRECT_PLUGIN) |
WidgetOperationTypes.APPEND with component/element. |
Insert (IFRAME_PLUGIN) |
WidgetOperationTypes.APPEND with url/title. |
Hide |
WidgetOperationTypes.REMOVE. Against default_contents (or keepDefault: false), the shim emits the union of three layers: a synthetic defaultContent REMOVE per mapped sub-slot, one REMOVE per APPEND/PREPEND discovered in mapped apps' slots, and one REMOVE per entry in the slot's curated targetDefaultContent.widgetMap. |
Wrap |
Best-effort: a LayoutOperationTypes.REPLACE whose layout feeds the targeted widget into the FPF wrapper using FPF's { component, pluginProps } shape (pluginProps come from <PluginSlot pluginProps={...}>). Wrappers that read FPF-private context warn. |
Modify, slotOptions.mergeProps |
Not translated; warn once per occurrence. |
priority |
Consumed as a sort key over translated ops. |
This package is a migration aid and is expected to be removed when the MFE deprecation timeline closes.