Custom Frontend Components

[rvveber]

Proposal: Introducing a Flexible Plugin System

Why now? There is currently no plugin mechanism in the codebase. This proposal introduces one, driven by real‑world requirements from our openDesk production deployments (white‑label/government Kubernetes instances that must integrate seamlessly into their existing digital suites).

---

Goals

1. Custom Functionality Without Forking – Enable openDesk and other whitelabel instances to add or swap features without shipping a custom container image of the entire application.
2. Protect Core Velocity – Keep the main repository lean; extensibility must not complicate the upstream codebase.
3. Positioning Power – Allow plugins to be injected before / after / prepend / append / replace any matching DOM node so integrators can position, augment, or even fully replace existing UI components.
4. Predictable Governance – This is not intended as a free‑for‑all community marketplace. Each instance decides which plugins it loads, preserving security, branding and user‑experience guarantees.

---

Proof‑of‑Concept (Module Federation)

I invested engineering time to build a working POC that demonstrates:

• Dynamic runtime loading of remote modules listed in a simple plugins.json file (no rebuild required).
• Bi‑directional sharing of React components, context, and state between host ↔ plugin.
• Selector‑based injection so the instance configuration chooses where each plugin renders.

Repo: https://github.com/rvveber/react-dynamic-bi-directional-module-federation-poc

Run locally (single copy‑paste):

git clone https://github.com/rvveber/react-dynamic-bi-directional-module-federation-poc
cd react-dynamic-bi-directional-module-federation-poc
./demo.sh

Once you open http://localhost:3001 you can see the demonstration.

---

How This Differs from Classic Slot‑Based Systems

Classic Slots	Proposed Selector‑Injection
Fixed "slot" components hard‑wired into the code	Any element matching a CSS selector can act as an anchor
Core devs must anticipate every slot	Core remains agnostic; DOM structure is the contract
Refactors often break plugins	As long as selectors stay stable, refactors are safe

---

FAQ & Open Questions

• Security / isolation?
  Remote entries are loaded only from whitelisted origins; each deployment controls its allow‑list.

• Version skew?
  Module Federation shares singletons (React, react‑query, etc.) to avoid duplicate bundles.

• Performance impact?
  Plugins load after DOMContentLoaded and are cached independently, so cold‑start cost is minimal.

---

Call for Feedback

Please share your opinions, concerns, and questions. I'm happy to iterate on the POC, update documentation, and drive the initial integration PR once we agree on direction.

Looking forward to the discussion!

[AntoLC]

Seems nice!
Would it be lot of work to do a simple POC in Docs ?

[rvveber]

We'll see - i'm starting the work on it 👍🏼
Issue -> #1301

[rvveber]

Little Update:
The plugin POC is technically working.
I'll work on answering some questions and writing some documentation next.

[rvveber]

The PR is to be found here:
#1556
It is currently in Draft because it includes a example plugin that i will remove when it emerges from Draft.
Once someone has tested it locally and given their Feedback i will clean it up and open for proper Review.

[virgile-dev]

Thanks for opening this thread. Interesting approach! @rvveber could you provide examples of how you would use this for the OpenDesk version of Docs ? Thanks !

[rvveber]

Certainly!

A straight forward example is the Header and the need for the central menu to access other apps of the suite.

[virgile-dev]

Thanks Robin, and the current way to create a custom theme of Docs doesn’t allow you to do this ?
For our prod instance we have a deployment repo where we add this exact same menu to access other apps.
So I’m a bit struggling to see why we should introduce something new to do this kind of things

[rvveber]

@virgile-dev
Are you talking about La Gaufre?
Because that is a custom feature built into the App, it is just enabled/disabled by a true/false variable.
But it is a variable that needs to be set on bundle/build-time.
Anything we change on bundle/build-time requires us to build ourself.
If we build ourselves, we need the source, and we need to do manual work to extend the code and basically maintain a fork of Docs.

The only theming thats available in Docs at run-time is CSS (Styling) of existing features - but that can't be used to add new features. And the links to La Suite in La Gaufre are existing features, but we need the Links to opendesk suite, which we need to resolve dynamically from an API and there are new features, impossible to do with styling only.

Since we want to avoid maintaining a Fork to keep up with Docs updates more quickly, we need an encapsulated way of adding our custom sometimes specific per instance features into the Frontend of Docs.

With this POC proposal, you would be able to specify a plugins.json (conceptionally similar how you would specify a CSS file for the runtime theming).
The plugins.json would contain all the information for loading actual JS features into the App at runtime.

For docs code, that means to simply provide a universal runtime entrypoint for extra code.
It allows to extend the Docs frontend, while using the original frontend image.

From technical side, there is no other solution that works with a statically built JS app.
If Docs was rendered on the server-side (SSR: NodeJS compiling and serving on the fly) we would have other options.
But SSR also has disadvantages, running a NodeJS server is way more ressource intensive than statically serving html,js,css with a web server (nginx) - which is probably the reason why Docs is statically compiled in the first place.

After adding this, technically the existing runtime CSS theming is redundant, because Plugins come with CSS.
We could replace it, so delegate the complexity for theming to a plugin entirely.
(I wouldn't do that for now - just so you know its not just something extra, its also something that can take some existing extras out of the App and make it simpler in the long run.)

[virgile-dev]

yeah I was talking about La Gauffre. I didn't realize it was a feature flag.
I understand better your point now thanks.
I saw you opened a PR. Are you happy with how it panned out ? @AntoLC should we test to implement la gauffre using this method ?

[rvveber]

@virgile-dev I haven't created the integration PR yet,
wanted to publish it before vacation - but it was not finished,
will publish as soon as i get to it.

[rvveber]

Whlie implementing the POC into Docs, i improved the system, the PR for the integration POC is available here:
#1556

It is currently in Draft because it includes a example plugin for testers, that i will remove when it emerges from Draft.
Once someone has tested it locally and given their feedback in the form of comments on the PR i will clean it and open it up for proper Review.