STRIPES-861 - integration of module federation logic with main branch. by JohnC-80 · Pull Request #1679 · folio-org/stripes-core

JohnC-80 · 2025-12-03T19:40:33Z

This PR takes the logic from #105 and implements backward compatibility/opt-in behavior to module federation. Huge thanks to @mkuklis so long ago for his initial lift!

This works with the Stripes-webpack PR and STRIPES-CLI PR to run a federated ui platform.

The changes in this PR implement an <EntitlementLoader> component that, provided an entitlementUrl via stripes-config.okapi, will fetch its list of modules from a dynamic source containing URL's for those module bundles. The bundles are then prefetched individually, translations, icons, loaded. The component passes through any modules provided via the monolithic build stripes-config setup.

Adds addIcon and adjusts setTranslations reducers to accumulate translations from async remote modules (loaded all together up front rather than on-demand at instanciation points such as AppRoutes and Settings (so the synchronous syntax of those implementations remain the same.)

Try the script to clone applicable branches, a few modules and set up a workspace:

mkdir -p module_federation && cd module_federation

# checkout necessary stripes modules
stripes_modules=(
  webpack
  core
  cli
  ui
)

for m in "${stripes_modules[@]}"; do
  git clone "https://github.com/folio-org/stripes-$m.git"
done

# ui-modules/remotes to load
git clone "https://github.com/folio-org/ui-users.git" &
git clone "https://github.com/folio-org/ui-inventory.git" &
wait

# create workspace via package.json
cat > package.json <<EOF
{
  "private": true,
  "workspaces": [
    "*"
  ]
}
EOF

# create stripes.config
cat > stripes.config.js <<EOF
module.exports = {
  okapi: {
    url: 'https://folio-snapshot-okapi.dev.folio.org',
    tenant: 'diku',
    discoveryUrl: 'http://localhost:3001/registry'
  },
  config: {
    logCategories: 'core,path,action,xhr',
    logPrefix: '--',
    showPerms: false,
    hasAllPerms: false,
    languages: ['en'],
    suppressIntlErrors: true,
  },
  modules: {
  }
};
EOF

# install dependencies
yarn

Then you can:
Build a module-federation host app (from the workspace level):

yarn stripes build --federate stripes.config.js

Serve the host app (dev mode from the workspace level)

yarn stripes serve --federate stripes.config.js

Build module bundle for static hosting (at the ui-module level)

yarn stripes build --federate

Serving the federated ui-module (dev mode at the ui-module level)

yarn stripes serve --federate

Have fun! 🎉🚀🎸🤘

…ding of ui-elements

Draft: load translations when loading remote modules Note: QueryClientProvider must be explicitly shared See https://tanstack.com/query/v3/docs/react/reference/QueryClientProvider Refs STCOR-718, STRIPES-861

Load remote icons, and clean up the translation loading a bit; it was still very much in draft form, and still is, but at least it doesn't throw lint errors everywhere now. Refs STCOR-725, STRIPES-861

Correctly set each apps' localized `displayName` attribute. It isn't totally clear to me why this doesn't work via `formattedMessage`. It seems that something is happening asynchronously that we don't realize is async, and therefore don't await, and then we end up calling `formatMessage()` before the translations have been pushed to the store. In any case, pulling the value straight from the translations array works fine. Refs STCOR-718

Correctly handle multiple icons per application. Refs STCOR-725

Major refactoring in stripes-core between this branch's initial work and the present lead to some discrepancies. The only change of note here, I think, is the relocation of `<Suspense>` from ModuleRoutes down into AppRoutes. It isn't clear to me why that was necessary or why it worked. It was just a hunch that I tried ... and it worked. Prior to that change, AppRoutes would get stuck in a render loop, infinitely reloading (yes, even the memoized functions). I don't have a good explanation for the bug or the fix.

…-config

github-actions · 2025-12-03T19:42:53Z

Jest Unit Test Results

1 files ± 0 84 suites +1 1m 39s ⏱️ -3s
523 tests +18 523 ✅ +18 0 💤 ±0 0 ❌ ±0
529 runs +18 529 ✅ +18 0 💤 ±0 0 ❌ ±0

Results for commit 19e3276. ± Comparison against base commit 5887b96.

♻️ This comment has been updated with latest results.

github-actions · 2025-12-03T19:45:11Z

Bigtest Unit Test Results

1 files ± 0 1 suites ±0 0s ⏱️ -6s
2 tests - 148 2 ✅ - 147 0 💤 - 1 0 ❌ ±0
152 runs + 2 152 ✅ + 3 0 💤 - 1 0 ❌ ±0

Results for commit 19e3276. ± Comparison against base commit 5887b96.

This pull request removes 152 and adds 2 tests. Note that renamed tests count towards both.

      equal to check email label in english translation
      equal to check email precautions label in english translation
      equal to sent email precautions label in english translation
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Passing a string to the tag-prop ‑ AppIcon Passing a string to the tag-prop Should render an AppIcon with a HTML tag of "div"
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Passing a string using the children-prop ‑ AppIcon Passing a string using the children-prop Should render an AppIcon with a label
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Rendering an AppIcon using Stripes-context ‑ AppIcon Rendering an AppIcon using Stripes-context Should render an <img>
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Rendering an AppIcon using Stripes-context ‑ AppIcon Rendering an AppIcon using Stripes-context Should render an img with an alt-attribute
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Rendering an AppIcon using an icon-object ‑ AppIcon Rendering an AppIcon using an icon-object Should render an <img>
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Rendering an AppIcon using an icon-object ‑ AppIcon Rendering an AppIcon using an icon-object Should render an img with an alt-attribute
Chrome_144_0_0_0_(Linux_x86_64).AppIcon Rendering an AppIcon using an icon-object ‑ AppIcon Rendering an AppIcon using an icon-object Should render with a className of "My className"
…

Chrome_144_0_0_0_(Linux_x86_64).loadRemoteComponent ‑ loadRemoteComponent should handle errors when loading the remote script
Chrome_144_0_0_0_(Linux_x86_64).loadRemoteComponent ‑ loadRemoteComponent should inject the script tag with the requested src attribute

♻️ This comment has been updated with latest results.

JohnC-80 · 2025-12-16T19:48:24Z

@zburke

if (okapi.entitlementUrl === okapi.url) { ... } // production
else { ... } // development

Let's talk about this part of things... I don't know enough about discovery to confirm this as a assured case.

… tests

zburke

🙌 with this branch I can now serve a federated build, serve a monolith, and build a monolith or code-split bundle. Sweet! 👏👏👏

…ep for stripes-hub

…nto STRIPES-861-int

zburke

~~monkey~~ <<< I cannot explain that except that I typed in some junk text while testing https://github.com/orgs/community/discussions/183653 and the value persisted even though it didn't display in the UI

zburke · 2026-01-15T20:51:11Z

src/components/EntitlementLoader.js

+ * @param {array} remotes
+ * @returns {app: [], plugin: [], settings: [], handler: []}
+ */
+


omit this extra newline

zburke · 2026-01-15T20:55:39Z

src/components/EntitlementLoader.js

+ * settings, handler) where the value of each is an array of corresponding
+ * applications.
+ *
+ * @param {array} remotes


Document all the arguments. What is the shape of an entry in the remotes array? Someday, this'll all be TS, won't it?

zburke · 2026-01-15T20:59:35Z

src/components/EntitlementLoader.js

+      actsAs.forEach(type => modules[type].push({ ...remote }));
+    });
+  } catch (e) {
+    stripes.logger.log('core', `Error preloading modules from entitlement response: ${e}`);


Do we need stripes for anything other than logging and if so, is it worth it? There is only a single catch-clause here; it's not like we're handling errors inside the loop and carrying on with 99 applications if there was only an error in 1. If there's an error, everything stops. Is logging this through stripes a good-enough way to handle this kind of error, or should we throw it up a level, log it via console.error etc?

zburke · 2026-01-15T21:03:32Z

src/components/EntitlementLoader.js

+ */
+const loadIcons = (stripes, module) => {
+  if (module.icons?.length) {
+    stripes.logger.log('core', `loading icons for ${module.module}`);


I know this was probably my code ... but now I'm wondering if we want to log verbose stuff like "Hola! I found an icon!" in a category like core that has been enabled by default since the dawn of FOLIO. Change the category? Skip logging altogether?

src/components/EntitlementLoader.js

zburke · 2026-01-15T21:11:30Z

src/loadRemoteComponent.js

+      // eslint-disable-next-line no-undef
+      await container.init(__webpack_share_scopes__.default);
+
+      const factory = await container.get('./MainEntry');


Let's cross-reference this with the corresponding entry in stripes-webpack/webpack.config.federate.remote. Even just a comment that says "the black magic here has corresponding black magic there" would be helpful. Otherwise, magic-strings like MainEntry remain, uhhhhhhm, magical.

zburke · 2026-01-15T21:17:21Z

src/loginServices.js

+  // if stripes-core is served from a different origin (module-federation) then
+  // we need to fetch translations from that origin as well rather than a relative path.
+  // const stripsesCoreOrigin = 'http://localhost:3000';
+  // const translationUrl = new URL(translationName, stripsesCoreOrigin);
+


This comment confuses me. Here, we are loading translations from the host, right? Let's just say that. Can we remove the commented out lines?

zburke · 2026-01-15T21:28:57Z

src/components/EntitlementLoader.js

+  // if platform is configured for module federation, read the list of registered apps from <fill in source of truth>
+  // localstorage, okapi, direct call to registry endpoint?


Where do you think this "figure out the source of truth" logic belongs -- in loadEntitlement() itself?

in production, it'll be localstorage (having been populated during session init)

in development, it'll be a direct API call to the registry

Both.. if not localstorage, then the local registry or whatever 'entitlementUrl' is provided... There has to be an 'entitlementUrl' in the config at build-time to even reach this logic... but this is worth a short discussion/question - will host-app builds necessarily *always involve an entitlementUrl since stripes-hub is the thing that actually uses it/cares about it the most? In this current state, stripes-core cares about the entitlementUrl, and it can work for setups that may *not use stripes-hub.

zburke · 2026-01-15T21:32:07Z

src/components/EntitlementLoader.js

+        // read the list of registered apps
+        let remotes;
+        try {
+          remotes = await loadEntitlement(okapi.entitlementUrl);


Rather than pulling okapi from the stripes-config import, should we instead be pulling it directly off stripes, which is available to this component via useStripes()?

zburke · 2026-01-15T21:39:33Z

src/components/EntitlementLoader.js

+  // register sounds
+  // TODO loadSounds(stripes, module);


I've lost track of where this work stands. There is handling for sounds in your folio-org/stripes-webpack#173 PR, so should we have corresponding code here, too?

The limited case of sound is - with code in the current state - leaning on the federated app (check-out) falling back to its own optionalDependencies - and loading sound from there if the logic gets to that particular path. check-out uses a dynamic require for pulling sounds from its optionalDependency- @folio/circulation - we * could do something with what a ui-module exposes like globbing together some 'assets' and mapping out entries to the ModuleFederationPlugin's exposes config... but the case is so obscure at the moment and nothing is broken in a federated build with this. There's other cases for this kind of provision - like dashboard importing components from other ui-modules. It's a spike-able aspect to reach beyond 'sounds' and just provide a means for a ui-module to expose bits of code, components, assets, whatever to other ui-modules.

…discovery results/pull discovery results from localForage

src/components/loadEntitlement.js

zburke · 2026-01-26T18:49:43Z

src/components/EntitlementLoader.js

+ * @returns {app: [], plugin: [], settings: [], handler: []}
+ */
+
+export const preloadModules = async (stripes, remotes) => {


omit this extra newline

zburke · 2026-01-26T21:25:43Z

src/components/EntitlementLoader.js

+const loadIcons = (stripes, module) => {
+  if (module.icons?.length) {
+    stripes.logger.log('core', `loading icons for ${module.module}`);
+    module.icons.forEach(i => {


I know this was probably my code ... but now I'm wondering if we want to log verbose stuff like "Hola! I found an icon!" in a category like core that has been enabled by default since the dawn of FOLIO. Change the category? Skip logging altogether?

zburke · 2026-01-26T21:30:00Z

src/components/EntitlementLoader.js

+ * @returns Promise
+ */
+const loadAllModuleAssets = async (stripes, remotes) => {
+  return Promise.all(remotes.map((r) => loadModuleAssets(stripes, r)));


If we change this to Promise.allSettled(), we need to look at how it's called as well because we'l need to iterate through the results to

report on those that reject

probably (?) apply a filter that only accepts those that fulfilled

Right-o. The minor switch alone isn't enough for the durability, but a bit of logic that comes after is required also.

zburke · 2026-01-26T21:31:33Z

src/components/EntitlementLoader.js

+    if (okapi.entitlementUrl) {
+      // fetches the list of registered apps/metadata,
+      // loads icons and translations, then module code,
+      // ultimately stores the result in the modules state to pass down into the modules context.


Rather than pulling okapi from the stripes-config import, should we instead be pulling it directly off stripes, which is available to this component via useStripes()?

src/components/EntitlementLoader.js

src/components/loadEntitlement.js

…ading translations when hostLocation is present in localforage.

… test.

sonarqubecloud · 2026-02-03T22:45:48Z

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
81.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

mkuklis and others added 23 commits December 4, 2024 12:33

STRIPES-861: Setup federation

6da2937

Cleanup

eac40b8

Cache remote components

b6aa8f9

Prefetch handlers

ff5e9a3

Align stripes-shared-context correctly

5ab4837

Update @folio/stripes-shared-context version

9fd0420

wrap Pluggable's rendered Child in suspense to isolate react-dom's hi…

3b4fca0

…ding of ui-elements

STCOR-718 load remote translations (#1309)

86b3273

Draft: load translations when loading remote modules Note: QueryClientProvider must be explicitly shared See https://tanstack.com/query/v3/docs/react/reference/QueryClientProvider Refs STCOR-718, STRIPES-861

STCOR-725 load remote icons (#1317)

72cb6e6

Load remote icons, and clean up the translation loading a bit; it was still very much in draft form, and still is, but at least it doesn't throw lint errors everywhere now. Refs STCOR-725, STRIPES-861

STCOR-725 correctly load multiple icons per app

f66ad62

Correctly handle multiple icons per application. Refs STCOR-725

resolve conflicts

98a6b0e

add registry to token util's set of paths for creds

72a3f54

ship context out to stripes-shared-context

3cf47fd

preload all the things

21dd6ad

go back to memo'd version

3deb33c

clean up

c756333

only import/re-export context/initial values from shared-context

7dc0e1d

module-federation logic is conditional on entitlementUrl from stripes…

a3f0b49

…-config

remove 'prefetch' comment

231e812

sync changes to context with main branch

17c42d2

Merge branch 'main' into STRIPES-861-int

6a2fffa

JohnC-80 added 4 commits December 3, 2025 13:47

import order sync with main branch

aff4513

inject remote modules into build-time modules

36a8ae8

re-add store icons to props on Root

4139c2f

add setTranslations function to stripes

256e9f1

JohnC-80 changed the title ~~STRIPES-861 - integration with main.~~ STRIPES-861 - integration of module federation logic with main branch. Dec 5, 2025

JohnC-80 added 4 commits December 16, 2025 14:12

add test for ADD_ICON okapiReducer

ceafdff

add error handling to loadRemoteComponent, update loadRemoteComponent…

779b6ec

… tests

remove only from lrc test

2cb6e5b

split out more of the loadEntitlement logic from EntitlementLoader

7a4ef26

zburke approved these changes Dec 22, 2025

View reviewed changes

JohnC-80 added 3 commits January 14, 2026 15:07

Merge branch 'main' into STRIPES-861-int

15c509b

loadRemoteComponent does script/src injection, translation loading pr…

2a6dc51

…ep for stripes-hub

Merge branch 'STRIPES-861-int' of github.com:folio-org/stripes-core i…

04e783e

…nto STRIPES-861-int

zburke reviewed Jan 15, 2026

View reviewed changes

JohnC-80 added 7 commits January 22, 2026 00:21

pull stripes-hub api info from localforage

16e460d

sync with actual entitlement response

885cf5c

add a constant for the name of stripes in the host app bundle, shape …

d9c47d8

…discovery results/pull discovery results from localForage

properly set up registry if fetched from the entitlement URL

fedb1cc

use AbortController for handling remote fetching in useEffect

edfcca7

semicolon on entitlement request error handling

4268490

braces on entitlementLoader useEffect

4282ea8

zburke reviewed Jan 25, 2026

View reviewed changes

src/components/loadEntitlement.js Show resolved Hide resolved

zburke approved these changes Jan 26, 2026

View reviewed changes

JohnC-80 and others added 6 commits January 27, 2026 16:05

handle subdirectory hosting of ui-modules

62fb1ef

fix tests for EntitlementLoader and LoadRemoteComponent

50469e7

add default mock for localforage/hostLocation (null), add test for lo…

a1130d1

…ading translations when hostLocation is present in localforage.

isolate localforage wrapper mocks and clean up after loadTranslations…

c8daff7

… test.

s/entitlementUrl/discoveryUrl/g

1afb2c1

logging clean-up, remove dangling space/test bother

ba9179c

zburke approved these changes Feb 3, 2026

View reviewed changes

Merge branch 'main' into STRIPES-861-int

19e3276

JohnC-80 merged commit 060c4f0 into main Feb 3, 2026
16 checks passed

JohnC-80 deleted the STRIPES-861-int branch February 3, 2026 22:51

		// if platform is configured for module federation, read the list of registered apps from <fill in source of truth>
		// localstorage, okapi, direct call to registry endpoint?

Conversation

JohnC-80 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Jest Unit Test Results

Uh oh!

github-actions bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bigtest Unit Test Results

Uh oh!

JohnC-80 commented Dec 16, 2025

Uh oh!

zburke left a comment

Choose a reason for hiding this comment

Uh oh!

zburke left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JohnC-80 Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Feb 3, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JohnC-80 commented Dec 3, 2025 •

edited

Loading

github-actions bot commented Dec 3, 2025 •

edited

Loading

github-actions bot commented Dec 3, 2025 •

edited

Loading

zburke left a comment •

edited

Loading

JohnC-80 Jan 20, 2026 •

edited

Loading