Skip to main content
    Norditco logo
    All engineering posts
    Published July 21, 2026Norditco Engineering

    Microfrontends at Norditco - A Shared Shell, Independent Apps

    • architecture
    • microfrontends
    • web-components
    • product

    Norditco does not run one frontend. Learn Persian with Sepideh is a Next.js app. Midad is a Vite and React Router product. Corsorr is Blogger. Trip Planner is a Vercel SPA. The company hub at norditco.com is its own React site. Those choices are intentional: each product ships on the stack that fits it, with its own deploy path and its own release cadence.

    The cost of that independence is fragmentation. A visitor who lands on Freja and later opens Midad should still feel that both belong to Norditco. They need a way to switch products, reach support, and see the company mark without each team reinventing a header. The usual industry answers are a monorepo with Module Federation, a single-spa orchestrator, or iframes. We tried none of those as the primary path.

    What we built instead is a small, CDN-hosted Web Component called the company shell. Product hosts load it as a script and a stylesheet, drop a <company-shell> element into their layout, and keep owning everything below the bar. This post explains why that shape fits Norditco, how the runtime works, and which boundaries we refuse to cross.

    What problem we are actually solving

    Microfrontend talk often starts with “independent deployability.” We already had that. Our problem was narrower and more concrete.

    1. Chrome without coupling. Product teams must be able to ship without waiting for a shared React version or a shared bundler graph.
    2. A living product list. Adding Midad or Freja to the switcher should not require every host app to cut a release.
    3. Honest host ownership. Layout width, theme tokens under the bar, auth, and consent stay with the product. The shell is chrome, not a platform that swallows the page.
    4. One company face. The bar should look the same whether the host is Next.js or Vite, and it should point back at norditco.com.

    That last point matters for the Discovery Mesh as well. Visible “By Norditco” navigation is a human signal that matches the Organization and SoftwareApplication links we publish in schema. The shell is one place those links stay consistent.

    The shape we chose

    Architecture diagram. Expand for a larger view with zoom.

    The shell is a Lit-based custom element, registered as company-shell. Hosts pull an IIFE bundle and a small CSS file from assets.norditco.com. Configuration is a separate JSON document on the same origin. Icons and the company logo live next to that config.

    This is a microfrontend in the original sense: a separately built and separately deployed UI fragment composed into a host at runtime. It is not a rewrite of every product into one framework. It is not a federated module graph. The host stays the application. The shell is a guest with a narrow contract.

    Why not the heavier options

    Module Federation would force shared React and webpack (or equivalent) assumptions across hosts that do not share a bundler. Learn Persian and Midad would both have to care about the federation remotes’ versions. That coupling is exactly what we were trying to avoid.

    single-spa or a similar orchestrator would put a root application in charge of mounting products. Our products are already full sites on their own hostnames. We do not want a second routing layer in front of them.

    iframes would isolate CSS and JS cleanly and also isolate accessibility, deep linking, and performance. A header iframe is a permanent tax on every page view for a bar that should feel native.

    Copy-paste React headers in each repo would drift within a week. We have already seen product icons and Play package ids diverge when the source of truth is informal.

    A Web Component on a CDN sits between those extremes. Any host that can load a script can participate. The shell’s React (or lack of React) never becomes the host’s problem.

    How a host embeds the shell

    Both Learn Persian with Sepideh and Midad follow the same pattern. The host layout (or root route) injects the CSS and JS from the CDN base URL, then renders the custom element with an active-tool-id that matches an entry in the config.

    <link rel="stylesheet" href="https://assets.norditco.com/company-shell/company-shell.css" />
    <script src="https://assets.norditco.com/company-shell/company-shell.js" async></script>
    
    <company-shell
      active-tool-id="midad"
      config-url="https://assets.norditco.com/company-shell/config.json"
      layout="embedded"
      auth-enabled="false"
    ></company-shell>
    

    In React hosts we wrap that in a small CompanyShellHost component. It sets attributes after mount, listens for shell-error, and avoids rendering until the custom element is defined. The important property is that the host never imports the shell’s TypeScript sources into its app bundle for production. Production talks to the CDN.

    Content Security Policy on the host must allow scripts, styles, images, and connect-src for assets.norditco.com. That is deliberate and documented. A shell that cannot load is better than a shell loaded from an unexpected origin.

    Config is the product registry for humans

    The JSON config is the operational heart of the system. It lists tools with id, name, URL, icon, group, optional badge, and feature flags. Production config is uploaded independently of the JS bundle. Cache headers are short for config.json and long for versioned JS and CSS.

    That split is the deployability win. When we add a tool icon for Midad or mark Freja as beta, we update config and icons on the CDN. Host apps do not need a release for the switcher to change. When we change shell behavior (layout modes, event names, chrome), we ship a new JS/CSS build.

    Architecture diagram. Expand for a larger view with zoom.

    Feature flags in config and on the element gate chrome that is not ready everywhere. Auth menus can stay off while the bar still switches tools. That matches how our products actually ship: learning sites and writing tools do not share one identity system yet, and the shell does not pretend they do.

    Layout modes: the host keeps the page

    Early drops of the shell carried a built-in max-width container. That worked for a zero-config demo and fought every host that already had a Tailwind container or a full-bleed header. We fixed that with an explicit layout attribute.

    ModeWhat the shell ownsWhat the host owns
    default (omit)Responsive max-width and paddingPage below the bar
    fluidFull width of the host wrapper, bar backgroundOuter wrapper and page
    embeddedNav content only, transparent chromeFull-bleed header, borders, background

    Midad uses embedded inside a dark header that already belongs to the product. Learn Persian can wrap the shell in its own container. The rule is simple: if the host already designed a header shell, the company bar should not invent a second one.

    Events, not imports

    The shell talks to the host through DOM events: tool-selected, shell-ready, shell-error, theme and announcement hooks, and optional auth clicks. Hosts that care listen. Hosts that only need the visual bar can ignore most of them.

    We prefer this to shared TypeScript packages for runtime behavior. Types can still be published for editors, but the live contract is the custom element and its events. That keeps Python, Blogger, and future non-React hosts in play even if we never use them for the shell tomorrow.

    Where we refuse the shell

    The company hub at norditco.com does not mount company-shell. The hub already has a first-party header and brand. Dropping the CDN bar on top would duplicate chrome and fight the marketing layout. Our agent and human docs say this explicitly: do not reintroduce the shared bar on the hub.

    That is part of embracing microfrontends honestly. Composition is optional. The shell is for product surfaces that need a cross-product switcher. The hub is the entity root and the story, not another tool in the switcher chrome.

    Blogger-based Corsorr and the Trip Planner SPA are listed in the shell config so other products can deep-link to them, but they are not required to embed the bar before they appear in the mesh. The config can advertise a product that has not adopted the element yet.

    Trade-offs we accept

    Flash of unstyled chrome. We ship a small host CSS file to reduce FOUC, but a slow CDN or a blocked script still yields a bar that arrives late. Hosts should keep a sensible top margin so content does not jump into the wrong place.

    Versioning discipline. JS/CSS must be cached as immutable; config must not. If both share one long TTL, tool lists go stale or shell bugs stick around. Our deployment notes encode that split.

    No shared session. The shell can show auth UI when a host enables it, but it does not invent a company-wide login. Until products share identity, auth-enabled="false" is the honest default.

    Design drift under the bar. The shell standardizes the top strip, not the page. Product themes still differ. That is fine. We optimize for recognizability of the company mark and the switcher, not for identical below-the-fold UI.

    CSP and supply chain. Every host trusts assets.norditco.com. That origin is part of our production surface. Treating it casually would be a mistake. Uploads are intentional, config is schema-validated in CI, and hosts pin the CDN base URL in environment configuration.

    How this sits next to the rest of the platform

    The shell is one slice of a larger multi-product system. The VPS edge post explains how hosts reach apps. The Discovery Mesh post explains how products point at the company in schema and crawl files. Consent on the hub is documented separately and stays origin-scoped; the shell does not move consent across subdomains.

    Taken together, the pattern is: independent apps, shared maps, optional shared chrome. Microfrontends here are not a fashion for splitting a single SPA into twelve remotes. They are a way to keep shipping many small products without losing the company in the gaps between them.

    What we would do next

    1. Widen adoption to every first-party web product that has a real header, once CSP and layout modes are verified on that host.
    2. Keep config as the human-facing product list in sync with the ops product registry used for schema and llms.txt, so the switcher and the Discovery Mesh never disagree on names or URLs.
    3. Leave the hub shell-free. If the hub needs richer product switching, it should stay a first-party React surface, not a second mount of the CDN bar.

    Microfrontends earned their place at Norditco by staying small. The company shell is a bar, a config file, and a contract. The products remain the products.