DEV Community: Nazar Usik

Wrapping Component Libraries

Nazar Usik — Thu, 03 Sep 2026 19:07:11 +0000

How production libraries handle decoupling, and what I learned building my own wrapper layer

The Pattern Everyone Uses (But I Didn't Understand)

Ever notice how you can import Material UI components like this?

import {Button} from '@mui/material';
import {Button} from '@mui/material/Button';  // Also works

Or how Lodash lets you do:

import {debounce} from 'lodash';
import debounce from 'lodash/debounce';  // Also works

I used these libraries for years without thinking about how they worked internally. Then I started building components for the embed examples, importing Material UI directly everywhere:

import {Button, TextField, Select} from '@mui/material';

Worked fine until Material UI released a major version update. Suddenly I'm reading migration guides, updating dozens of files, mapping old prop names to new ones.

That's when I realized: I'd coupled my code directly to Material UI's API. Any change they made rippled through my entire codebase.

And that's when I started looking at how production libraries structure themselves. Turns out, they all use the same pattern: wrapper layers.

The Wrapper Pattern

The concept is simple: add an abstraction layer between your code and the UI library.

// Your application imports from your wrapper
import {Button} from '@company/ui-components';

// Wrapper delegates to whatever library you're using
import {Button as MuiButton} from '@mui/material';

export function Button(props) {
    return <MuiButton {...props} />;
}

Application code never imports Material UI directly. Want to swap libraries? Update the wrapper. Application code stays unchanged.

This is how pretty much every major component library works internally. They wrap their own primitives. But I'd never built one myself, so I didn't understand the TypeScript patterns, the build setup, or the trade-offs.

Time to figure it out.

Starting Simple: Wrapping Button

I started with Button. Seemed simple enough – just wrap Material UI's button, right?

First attempt:

// First attempt - just pass everything through
import {Button as MuiButton, ButtonProps as MuiButtonProps} from '@mui/material';

export interface ButtonProps extends MuiButtonProps {
}

export function Button(props: ButtonProps) {
    return <MuiButton {...props} />;
}

This worked, but it wasn't really abstracting anything. I was just passing through Material UI's entire API. If I switched libraries later, I'd still need to change application code.

Looking at how libraries like Radix UI handle this, I found an alternative approach: define your own prop interface, map it to the underlying library:

import {ButtonProps as MuiButtonProps} from '@mui/material';

// My API - omit MUI-specific props I'm replacing
interface ButtonProps extends Omit<MuiButtonProps, 'variant' | 'color'> {
    variant?: 'primary' | 'secondary' | 'danger';  // My variants, not MUI's
    onClick?: () => void;
    disabled?: boolean;
    children: React.ReactNode;
}

export function Button({variant, ...props}: ButtonProps) {
    // Map my variants to MUI's variants
    const muiVariant = variant === 'danger' ? 'contained' : 'contained';
    const muiColor = variant === 'danger' ? 'error' : variant;

    return <MuiButton variant={muiVariant} color={muiColor} {...props} />;
}

Now the API is independent. Material UI's specifics stay hidden. Switch to a different library? Just update the mapping.

Compound Components (How Libraries Handle Multi-Part Components)

Button was straightforward. Accordion was trickier.

Material UI's Accordion has three parts that users import separately:

import {Accordion, AccordionSummary, AccordionDetails} from '@mui/material';

<Accordion>
    <AccordionSummary>Title</AccordionSummary>
    <AccordionDetails>Content</AccordionDetails>
</Accordion>

How should I wrap this? Three separate exports felt clunky.

Then I looked at how Radix UI structures their components - they use static properties:

// types.ts
import {AccordionProps as MuiAccordionProps} from '@mui/material';
import {ReactElement} from 'react';

export interface AccordionProps extends MuiAccordionProps {
    // Your custom props
}

export type AccordionComponent = (props: AccordionProps) => ReactElement;
export type AccordionComponentType = AccordionComponent & {
    Summary: typeof AccordionSummary;
    Details: typeof AccordionDetails;
};

// index.tsx
import {AccordionSummary} from './summary';
import {AccordionDetails} from './details';

export const Accordion: AccordionComponentType = (props) => {
    return <MuiAccordion {...props} />;
};

Accordion.Summary = AccordionSummary;
Accordion.Details = AccordionDetails;

Usage:

import {Accordion} from '@company/ui-components';

<Accordion>
    <Accordion.Summary>Title</Accordion.Summary>
    <Accordion.Details>Content</Accordion.Details>
</Accordion>

One import. Clear parent-child relationship. TypeScript autocomplete shows .Summary and .Details automatically.

This pattern works great for multi-part components. The TypeScript types are interesting:

export type AccordionComponent = (props: AccordionProps) => ReactElement;
export type AccordionComponentType = AccordionComponent & {
    Summary: typeof AccordionSummary;
    Details: typeof AccordionDetails;
};

That intersection type (&) tells TypeScript that Accordion is both a function component and an object with properties. Same pattern Material UI and Radix use internally.

Theme Extension (Declaration Merging)

For the runtime config system from Article 1 to work, wrapper components need to read custom theme properties.

Material UI uses TypeScript's declaration merging for this:

// Theme declaration merging
declare module '@mui/material/styles' {
    interface Theme {
        custom: {
            button: {
                borderRadius: string;
                fontWeight: number;
            };
        };
    }
}

// Usage in component
import {useTheme} from '@mui/material';

export function Button(props: ButtonProps) {
    const theme = useTheme();
    // theme.custom.button.borderRadius is fully typed
    return <MuiButton sx={{borderRadius: theme.custom.button.borderRadius}} {...props} />;
}

With this in place, TypeScript knows about theme.custom.button.borderRadius everywhere. No any types, no casting, full autocomplete.

Multi-Level Imports (The Build Setup Everyone Uses)

You've probably used both of these import styles:

// Full import
import {Button, TextField} from '@mui/material';

// Targeted import
import {Button} from '@mui/material/Button';

Both work, but the second is better for tree-shaking. The bundler only includes what you import.

To enable both styles, you need index.ts files at every level:

src/
├── index.ts              # Root: export * from './buttons'; export * from './dataDisplay';
├── buttons/
│   ├── index.ts          # export * from './button'; export * from './group';
│   ├── button/
│   │   └── index.tsx     # export { Button }
│   └── group/
│       └── index.tsx
├── dataDisplay/
│   ├── index.ts          # export * from './accordion'; export * from './inputs';
│   ├── accordion/
│   │   └── index.tsx
│   └── inputs/
│       ├── index.ts      # export * from './textField'; export * from './checkbox';
│       ├── textField/
│       └── checkbox/

This enables flexible import paths:

// Import from root (full library)
import {Button, TextField, Accordion} from '@company/ui-components';

// Import from category (targeted)
import {Button} from '@company/ui-components/buttons';
import {TextField} from '@company/ui-components/dataDisplay/inputs';

// Both work! Developer's choice.

Benefits:

Tree-shaking friendly: Bundlers can eliminate unused code
Clear organization: Categories match your mental model
Faster imports: Import only what you need
Better intellisense: Category-based autocomplete

Implementation:

// src/index.ts (root)
export * from './buttons';
export * from './dataDisplay';
export * from './feedback';
export * from './layout';

// src/buttons/index.ts
export * from './button';
export * from './group';

// src/dataDisplay/inputs/index.ts
export * from './textField';
export * from './checkbox';
export * from './date';

Every folder re-exports its children. Simple enough.

But there's a trick: this alone doesn't work. When you import @company/ui-components/buttons, npm looks for
node_modules/@company/ui-components/buttons/package.json.

That's why the build process needs to create individual package.json files for each subdirectory.

The Build Process (How Material UI Does It)

During build, create a package.json in each subfolder:

// Build script creates package.json in each folder
// lib/buttons/button/package.json
{
  "sideEffects": false,
  "module": "../../esm/buttons/button/index.js",
  "main": "../../cjs/buttons/button/index.js",
  "types": "../../types/src/buttons/button/index.d.ts"
}

This tells bundlers where to find the code for each import path. Now when someone imports:

import {Button} from '@company/ui-components/buttons';

The bundler reads lib/buttons/package.json, which points to the actual compiled code. This enables:

Tree-shaking: Only includes imported code
Targeted imports: Import from any depth
Proper module resolution: Works with ESM, CJS, and TypeScript

Build script example:

// Finds all folders with index.ts and creates package.json for each
const directoryPackages = glob.sync('*/index.{js,ts,tsx}', {cwd: 'src/buttons'})
    .map(path.dirname);

for (const dir of directoryPackages) {
    const packageJson = {
        sideEffects: false,
        module: `../../esm/buttons/${dir}/index.js`,
        main: `../../cjs/buttons/${dir}/index.js`,
        types: `../../types/src/buttons/${dir}/index.d.ts`
    };

    writeFileSync(`lib/buttons/${dir}/package.json`, JSON.stringify(packageJson));
}

Look in node_modules/@mui/material/ and you'll find hundreds of these little package.json files. That's the trick.

My build script (scripts/setup-package.mjs) does the same: crawls the src/ folder and generates these files after TypeScript compilation.

Styling Approaches

For styling wrapper components, there are a few common approaches.

I used styled-components initially, but CSS-in-JS libraries are now in maintenance mode. The React team recommends other approaches:

Modern approaches:

Option 1: CSS Modules
Button.module.css

.button {
  border-radius: 8px;
  font-weight: 500;
  text-transform: none;
}

.primary {
  background-color: var(--color-primary);
}

// Button.tsx
import styles from './Button.module.css';
import {Button as MuiButton} from '@mui/material';

export function Button({variant, ...props}: ButtonProps) {
    return (
        <MuiButton
            className={`${styles.button} ${variant === 'primary' ? styles.primary : ''}`}
            {...props}
        />
    );
}

Option 2: Tailwind CSS

import {Button as MuiButton} from '@mui/material';
import clsx from 'clsx';

export function Button({variant, ...props}: ButtonProps) {
    return (
        <MuiButton
            className={clsx(
                'rounded-lg font-medium normal-case',
                variant === 'primary' && 'bg-primary text-white',
                variant === 'secondary' && 'border border-secondary'
            )}
            {...props}
        />
    );
}

Option 3: Material UI's sx prop (if staying with MUI)

export function Button({variant, ...props}: ButtonProps) {
    return (
        <MuiButton
            sx={{
                borderRadius: 2,
                fontWeight: 500,
                textTransform: 'none',
                ...(variant === 'primary' && {bgcolor: 'primary.main'})
            }}
            {...props}
        />
    );
}

Current recommendation: CSS Modules for full control and performance, Tailwind for rapid development, sx prop if staying with Material UI.

Integrating with Config

Wrapper components can read from the config system (Article 1):

import {useTheme} from '@/providers/theme';

export function Button(props: ButtonProps) {
    const theme = useTheme();
    // theme.components.button comes from runtime config
    const borderRadius = theme.components?.button?.borderRadius || '8px';

    return <MuiButton sx={{borderRadius}} {...props} />;
}

Change the config URL, every button updates its styling. No rebuild, no deployment.

Common Patterns and Practices

Start with High-Use Components

Don't wrap everything at once. Start with what you actually use:

High priority:

Button
TextField
Select
Checkbox
Radio

Medium priority:

Dialog
Card
Tabs
Table

Low priority:

Specialized components
Rarely used components

Focus on core components first. Add others as needed.

Opinionated APIs with Escape Hatches

The pattern most libraries use: simple API for common cases, escape hatch for edge cases.

❌ Bad: Expose everything

interface ButtonProps extends MuiButtonProps {
    // Just passes through everything
}

✅ Good: Opinionated API

interface ButtonProps {
    variant?: 'primary' | 'secondary' | 'text';
    size?: 'small' | 'medium' | 'large';
    disabled?: boolean;
    children: React.ReactNode;
    onClick?: () => void;
    // Escape hatch for advanced cases
    muiProps?: Partial<MuiButtonProps>;
}

Most uses are simple. But occasionally you need library-specific features. The escape hatch pattern handles this:

interface ButtonProps {
    variant?: 'primary' | 'secondary';
    muiProps?: Partial<MuiButtonProps>;  // Escape hatch
}

export function Button({muiProps, ...props}: ButtonProps) {
    return <MuiButton {...props} {...muiProps} />;
}

// Normal case
<Button variant="primary">Submit</Button>

// Edge case with library-specific feature
<Button variant="primary" muiProps={{startIcon: <Icon/>}}>Submit</Button>

Type Safety with Declaration Merging

Extend theme types for full type safety:

// typings/theme.d.ts
import '@mui/material/styles';

declare module '@mui/material/styles' {
    interface Theme {
        custom: {
            button: {
                borderRadius: string;
                fontWeight: number;
            };
        };
    }

    interface ThemeOptions {
        custom?: {
            button?: {
                borderRadius?: string;
                fontWeight?: number;
            };
        };
    }
}

Declaration merging gives full type safety for custom theme properties. theme.custom.button.borderRadius has autocomplete everywhere.

Documentation (Storybook)

Visual documentation helps:

// Button.stories.tsx
import {Button} from './Button';

export default {
    title: 'Components/Button',
    component: Button,
};

export const Primary = () => <Button variant="primary">Primary</Button>;
export const Secondary = () => <Button variant="secondary">Secondary</Button>;
export const Sizes = () => (
    <>
        <Button size="small">Small</Button>
        <Button size="medium">Medium</Button>
        <Button size="large">Large</Button>
    </>
);

Developers can see all variants, copy examples, understand usage without reading type definitions.

Versioning

If multiple projects depend on your wrapper, use semantic versioning:

{
  "name": "@company/ui-components",
  "version": "2.1.0",
  "peerDependencies": {
    "@mui/material": "^5.0.0",
    "react": "^18.0.0"
  }
}

Teams can upgrade on their own schedule. Breaking changes go in major versions.

Migration Strategy

If you're adding wrappers to an existing codebase, gradual migration works better than big-bang rewrites.

Phase 1: Build the Wrapper Separately

Create the wrapper as a separate package while existing code continues using the library directly:

# Create package
mkdir ui-components
cd ui-components
npm init

# Structure
ui-components/
├── src/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── types.ts
│   ├── TextField/
│   ├── Select/
│   └── index.ts
├── package.json
└── tsconfig.json

// src/Button/Button.tsx
export function Button(props: ButtonProps) {
    return <MuiButton {...props} />;
}

// src/index.ts
export {Button} from './Button/Button';
export {TextField} from './TextField/TextField';
export {Select} from './Select/Select';

Phase 2: Allow Both Import Styles

Let existing code continue using the library directly:

// Old way (still works)
import {Button} from '@mui/material';

// New way (preferred)
import {Button} from '@company/ui-components';

Add an ESLint warning to encourage wrapper usage:

// .eslintrc.js
module.exports = {
    rules: {
        'no-restricted-imports': [
            'warn',
            {
                paths: [{
                    name: '@mui/material',
                    message: 'Please use @company/ui-components instead'
                }]
            }
        ]
    }
};

New code uses the wrapper. Old code can stay on direct imports.

Phase 3: Automate with Codemod (Optional)

For large codebases, use jscodeshift to automate the migration:

// transform.js
module.exports = function (file, api) {
    const j = api.jscodeshift;
    const root = j(file.source);

    // Find Material UI imports
    root
        .find(j.ImportDeclaration, {
            source: {value: '@mui/material'}
        })
        .forEach(path => {
            // Replace with wrapper imports
            j(path).replaceWith(
                j.importDeclaration(
                    path.value.specifiers,
                    j.literal('@company/ui-components')
                )
            );
        });

    return root.toSource();
};

Handles most imports automatically. Some edge cases need manual fixes.

Phase 4: Enforce (Eventually)

Once most code uses the wrapper, change ESLint from 'warn' to 'error':

// .eslintrc.js
module.exports = {
    rules: {
        'no-restricted-imports': [
            'error',  // Changed from 'warn' to 'error'
            {
                paths: [{
                    name: '@mui/material',
                    message: 'Direct Material UI imports not allowed. Use @company/ui-components'
                }]
            }
        ]
    }
};

Integration with Other Patterns

With Embed Server

For the self-mounting embeds from Article 0, a shared wrapper library keeps everything consistent:

// All embeds import from the same wrapper library
import {Button, TextField} from '@company/ui-components';

All embeds use the same wrapper. Update once, all embeds get the changes.

With Multi-Layer Config

The wrapper components read from the config system (Article 1):

const theme = useTheme();
const borderRadius = theme.components?.button?.borderRadius || '8px';

Buttons read from config. Change the config URL, styling updates. No rebuild needed.

With Declarative Forms

The form system from Article 2 uses wrapped components:

import {TextField, Checkbox, Radio} from '@company/ui-components';
// All form inputs automatically consistent

All form inputs use the same wrappers, reading from the same config. Consistency is automatic.

Trade-offs

What You Gain

Library independence: Switch from Material UI to Ant Design by changing one package. Application code unchanged.

Centralized styling: Button styling in one file. Change once, affects everywhere.

Enhanced functionality: Add analytics, accessibility, loading states in one place. Every usage gets the enhancement automatically.

Consistent API: Teams use the same button API. No variations, no copy-paste styling.

Easier testing: Mock your wrapper, not Material UI. Simpler test setup.

These benefits are significant for multi-application scenarios.

What It Costs

Initial development: Building the wrapper layer takes time. Each component needs wrapping.

Maintenance overhead: Material UI updates require wrapper updates. New features need exposure through wrapper API.

Learning curve: Team needs to learn wrapper API, not just Material UI.

Abstraction leakage: Complex components harder to wrap completely. May need escape hatches to underlying library.

Bundle size: Additional wrapper code. May include unused library features.

When It's Worth It

The pattern makes sense when:

Multiple applications share components
Long-term maintenance expected (multi-year projects)
Library migration likely in the future
Consistent branding required across teams
Runtime configuration needed (Article 1)

It's not worth it when:

Single small project with one developer
Tight deadline with no time for abstraction
Library deeply integrated (major refactor needed)
No future migration planned

Don't over-engineer. Build abstraction when it solves real problems.

Example Implementation

Full example at github.com/NazarUsik/AdaptUI.

Key areas to explore:

src/buttons/button/ - basic wrapper pattern
src/dataDisplay/accordion/ - compound components
src/providers/theme/ - config integration
scripts/setup-package.mjs - build process for multi-level imports

Basic structure:

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   ├── Button.stories.tsx
│   │   └── types.ts
│   ├── TextField/
│   ├── Select/
│   └── index.ts
├── providers/
│   ├── config/
│   └── theme/
└── index.ts

Summary

Wrapper libraries are standard practice in production applications. Material UI, Radix, and most component libraries use this pattern internally.

The benefits:

Library independence
Centralized styling
Consistent APIs across applications

The costs:

Initial development time
Maintenance overhead
Learning curve for new patterns

For single-application projects, direct library imports work fine. For multi-application scenarios with shared components and runtime theming, wrapper layers make sense.

The key patterns:

Opinionated APIs with escape hatches
Compound components for multi-part elements
Multi-level imports for tree-shaking
Declaration merging for type safety
Build scripts for package.json generation

These patterns work together with:

Embed server (Article 0) for shared components
Multi-layer config (Article 1) for runtime theming
Declarative forms (Article 2) for consistent inputs

Start small. Wrap core components first. Add complexity as needed. Don't over-engineer.

Author: Nazar Usik

GitHub: AdaptUI

Related:

When Forms Start Talking to Each Other

Nazar Usik — Thu, 03 Sep 2026 19:07:10 +0000

Declarative Field Dependencies in React: How Configuration Replaces useEffect Spaghetti

The Problem

Complex forms are everywhere in enterprise applications. Registration forms, checkout flows, survey builders, data entry systems. They all share a common challenge: fields that depend on other fields.

Country selection shows state dropdown. Application type determines available submission types. Certain combinations trigger validation rules or show warnings.

The standard React approach? useEffect hooks watching field changes. For simple cases, this works. For complex forms with 30+ fields and multiple dependency chains? It becomes unmaintainable.

This article explores a declarative alternative: describing field relationships in configuration objects instead of imperative effect code.

Note on examples: I use pharmaceutical submission forms as examples throughout. This domain provides good complexity (regulatory requirements, conditional fields, multi-country variations) while being publicly understood. The patterns apply to any complex form domain - e-commerce, finance,
healthcare, government services, etc.

Looking Backward to Move Forward

Years ago, I worked with an XML-driven UI framework that had an interesting feature. You could describe entire forms declaratively, including field relationships:


<field name="city"
       dependsOn="country"
       loadFrom="/api/cities?country={country}"
       clearOnChange="true"/>

No imperative code, no event handlers, no effect hooks. The framework read the configuration and handled all the logic automatically.

This pattern stuck with me. Modern React emphasizes declarative UI, yet field dependencies are typically handled imperatively through effects. Why not apply the declarative approach to form logic?

The challenge: building this as a side project without unlimited time, while still learning modern frontend patterns.

The useEffect Spaghetti Problem

Here's what the imperative approach looks like. A pharmaceutical submission form where fields depend on each other:

function SubmissionForm() {
    const [applicationType, setApplicationType] = useState('')
    const [submissionType, setSubmissionType] = useState('')
    const [country, setCountry] = useState('')
    const [state, setState] = useState('')
    const [states, setStates] = useState([])
    const [submissionTypes, setSubmissionTypes] = useState([])
    const [showState, setShowState] = useState(false)

    // Load submission types when application type changes
    useEffect(() => {
        if (applicationType) {
            fetch(`/api/submission-types?applicationType=${applicationType}`)
                .then(res => res.json())
                .then(data => setSubmissionTypes(data))
        } else {
            setSubmissionTypes([])
        }
    }, [applicationType])

    // Reset submission type when application type changes
    useEffect(() => {
        setSubmissionType('')
    }, [applicationType])

    // Load states when country changes
    useEffect(() => {
        if (country === 'USA') {
            setShowState(true)
            fetch(`/api/states?country=${country}`)
                .then(res => res.json())
                .then(data => setStates(data))
        } else {
            setShowState(false)
            setStates([])
        }
    }, [country])

    // Reset state when country changes
    useEffect(() => {
        setState('')
    }, [country])

    // ... and on and on for 20+ more fields
}

This is 5 fields. Real forms have 30, 40, 50+ fields with complex dependencies. The useEffect hooks create dependency chains so complex that debugging becomes a nightmare. Change one field, three others update, triggering five more updates, sometimes creating infinite loops.

Testing? Mock every effect? Write integration tests for every possible combination of field changes?

Maintenance? Every new field dependency requires tracing through all existing effects to avoid breaking something. It's fragile, hard to understand, and gets worse with every feature.

The Declarative Alternative

What if instead of imperative effects, the form was just described as configuration?

const formModel = [
    {
        name: 'applicationType',
        type: 'select',
        label: 'Application Type'
    },
    {
        name: 'submissionType',
        type: 'select',
        label: 'Submission Type',
        loadDataFrom: '/api/submission-types?applicationType={applicationType}',
        subscribesTo: 'applicationType'  // When applicationType changes, reload my data
    },
    {
        name: 'country',
        type: 'select',
        label: 'Country'
    },
    {
        name: 'state',
        type: 'select',
        label: 'State',
        loadDataFrom: '/api/states?country={country}',
        visibleWhen: (values) => values.country === 'USA',
        subscribesTo: 'country'
    }
]

Just a configuration object. Read it top to bottom and you understand the form. No hunting through effects, no mental gymnastics to figure out what triggers what. The field state literally says "I'm visible when country is USA" and "I subscribe to country changes."

Beautiful, right? In theory, at least. Making it actually work was going to be... interesting.

The Observer Pattern (Because Smart People Already Figured This Out)

I needed the fields to "watch" each other. When Field A changes, Field B needs to know about it and react accordingly. This is a classic programming pattern called the Observer Pattern, but I didn't know that at the time. I just knew what I needed to do.

My first attempt was embarrassingly simple. I literally had a function that ran after every field change and checked every other field to see if it needed to do something:

function handleFieldChange(fieldName, value) {
    // Update the value
    setValue(fieldName, value)

    // Check EVERY OTHER FIELD to see if it cares about this change
    allFields.forEach(field => {
        if (field.subscribesTo === fieldName) {
            // Do something
        }
    })
}

It worked! Sort of. For about 5 fields. With 30 fields, it was painfully slow. Every keystroke triggered a check of 29 other fields, and if any of those fields had actions to perform, those might trigger more checks... You can see where this is going.

State Management: Why MobX

The declarative system needs state management with fine-grained reactivity – where only fields that actually changed re-render, not the entire form.

Comparing options:

Redux/Zustand: Update any state, entire form re-renders. With 50 fields, that's expensive.

MobX: Fine-grained reactivity. Change one field, only components subscribed to that field update. React DevTools shows exactly one component re-rendering.

This makes the subscription system practical. If Field A changes and Field B subscribes to it, only Field B reacts. The other 48 fields don't even know anything happened.

Crucial for both performance and making the declarative pattern work cleanly.

The MobX Pattern: Functions, Not Classes

Here's where things got interesting. Most MobX examples online use classes – you extend some base class, decorate methods with @action and @observable, and it works. But I wasn't a fan of the class-based approach. It felt heavy and old-fashioned compared to React's hooks and functional
components.

So I started experimenting with a functional approach. What if stores were just functions that returned objects? And what if they could automatically register themselves without any manual setup?

I ended up with a pattern that looked like this:

// Define a store as an object with id and implementation function
export const valuesStore = {
    id: 'valuesStoreId',
    implementation: () => {
        return {
            valuesMap: new Map(),
            lastChanged: '',
            getValue(id, name) {
                return this.valuesMap.get(id)?.get(name) || ''
            },
            setValue(id, name, value) {
                this.lastChanged = name
                this.valuesMap.get(id)?.set(name, value)
            },
            // ... more methods
        }
    }
}

// Store auto-registers itself
globalStores.push(valuesStore)

// Export a typed hook
export const useValuesStore = useStore<ValuesStoreImplementation>(valuesStoreId)

The magic happens in the StoreProvider. It takes all registered stores, wraps their implementations with MobX's
useLocalObservable, and makes them available through React Context:

export const StoreProvider = ({children}) => {
    const mobxStores = new Map(globalStores
        .map(store => [store.id, useLocalObservable(store.implementation)]))

    return <StoreContext.Provider value={mobxStores}>{children}</StoreContext.Provider>
}

This meant I could create a new store by just:

Writing a function that returns an object with methods
Pushing it to the global stores array
Exporting a custom hook

No classes, no decorators, no manual provider setup. The store automatically becomes part of the system. And because
useLocalObservable wraps the returned object, all the properties become reactive automatically.

For the form system, I created five stores this way:

valuesStore – Manages all form field values
attributesStore – Manages field configurations
dataStore – Manages loaded data for dropdowns and selects
modelsStore – Manages form mode (view/edit) and structure
validationsStore – Manages validation states

Each store is completely independent, just a function in a file, but they all work together seamlessly. And adding a new store? Just create a new file, follow the pattern, push to globalStores, done.

Looking back, I'm not sure if this is considered best practice for MobX. I couldn't find many examples of this pattern online. But it worked beautifully, kept the code functional and modular, and made it easy to add new stores without understanding all the MobX internals.

The full pattern is in src/providers/store, and you can see it in action in the form stores at src/dataDisplay/model/store.

Building the Subscription Engine

With MobX handling the reactive state, I could focus on making the subscription system work. The core idea was simple:

Each field can declare subscriptions – relationships to other fields
When a field value changes, the system finds all subscriptions that care about that field
The system evaluates the subscription conditions
If conditions match, the system executes the actions

In code, a subscription looked like this:

{
  name: 'state',
  subscribesOn: [
    {
      name: 'showStateField',
      trigger: {
        type: 'fieldChange',
        params: [
          {
            name: 'attribute',
            value: 'country'
          },
          {
            name: 'condition',
            value: {
              operator: 'equals',
              value: 'USA'
            }
          }
        ]
      },
      action: {
        type: 'visible',
        params: [
          {
            name: 'visible',
            value: true
          }
        ]
      }
    }
  ]
}

Reading this, you can understand it: "Field state subscribes to changes in field country. When country equals '
USA', make the state field visible."

The implementation took... a while. I'm not going to lie, this was hard. Handling chains of subscriptions (Field A => Field B => Field C), preventing circular dependencies, making sure data loading happened in the right order, dealing with race conditions when multiple subscriptions fired at once...
Each of these was its own problem to solve.

There were nights when I thought about giving up and just living with the useEffect soup. But every time I looked at the declarative config and compared it to the imperative mess, it seemed worth pursuing.

Two Types of Subscriptions: Visibility and Data

After a few iterations, two main subscription action types emerged:

1. Visibility Subscriptions – Show or hide fields based on conditions

{
  name: 'medicalHistory',
  subscribesOn: [
    {
      trigger: {
        params: [
          {
            name: 'attribute',
            value: 'hasPreExistingCondition'
          }
        ],
        condition: {
          operator: 'equals',
          value: true
        }
      },
      action: {
        type: 'visible'
      }
    }
  ]
}

"Show the medical history field only if they checked the 'has pre-existing condition' box."

2. Data Refresh Subscriptions – Reload a field's options when its dependencies change

{
  name: 'city',
  loadDataFrom: '/api/cities?country={country}',
  subscribesOn: [
    {
      trigger: {
        params: [
          {
            name: 'attribute',
            value: 'country'
          }
        ]
      },
      action: {
        type: 'dataRefresh',
        params: [
          {
            name: 'clearValue',
            value: true
          }
        ]
      }
    }
  ]
}

"When country changes, reload the city options and clear the current selection."

These two actions covered probably 90% of use cases. The other 10% could be handled with custom logic when needed, but having these built-in made the common cases trivial.

Testing the Approach: A Pharmaceutical Form Example

To test this system, I built a pharmaceutical submission form prototype with 40 fields and complex dependencies:

Application type determined which submission types were available
Country selection showed different fields (USA needed states, Canada needed provinces, EU needed different fields entirely)
Certain combinations of selections would show warning messages
Some fields were required only if other fields had specific values

The imperative approach would be 500-600 lines of effect code spread across components, with effects triggering other effects. Hard to read, test, and debug.

The declarative approach? 150 lines of configuration. Readable top to bottom:

const pharmaceuticalFormModel = [
    {
        name: 'applicationType',
        type: 'autocomplete',
        label: 'Application Type',
        required: true,
        loadDataFrom: '/api/application-types'
    },
    {
        name: 'submissionType',
        type: 'select',
        label: 'Submission Type',
        required: true,
        loadDataFrom: '/api/submission-types?applicationType={applicationType}',
        subscribesOn: [{
            trigger: {params: [{name: 'attribute', value: 'applicationType'}]},
            action: {type: 'dataRefresh', params: [{name: 'clearValue', value: true}]}
        }]
    },
    {
        name: 'country',
        type: 'select',
        label: 'Country',
        required: true,
        loadDataFrom: '/api/countries'
    },
    {
        name: 'state',
        type: 'select',
        label: 'State',
        required: true,
        loadDataFrom: '/api/states?country={country}',
        subscribesOn: [{
            trigger: {
                params: [{name: 'attribute', value: 'country'}],
                condition: {operator: 'equals', value: 'USA'}
            },
            action: {type: 'visible'}
        }]
    },
    // ... 36 more fields with similar clarity
]

Backend developers could read this configuration and understand the form logic. That's a good sign for maintainability.

The Hook: useModelRepresent

All of this declarative configuration needed something to interpret and execute it. That's what the useModelRepresent
hook does. It's the engine that makes the magic happen.

You use it like this:

const {attributes, values} = useModelRepresent({
    formId: 'my-form',
    attributes: formModel,  // The declarative config
    mode: 'edit',
    values: initialValues
})

return (
    <Form>
        {attributes.map(attr => (
            <Form.Row key={attr.name} {...attr} />
        ))}
    </Form>
)

Behind the scenes, useModelRepresent is:

Setting up MobX stores for form values, field data, and validations
Processing subscriptions when field values change
Loading data from APIs when fields need it
Managing visibility states
Handling field validation
Clearing dependent fields when their parent changes

All the complexity is hidden. As a form developer, you just pass in your config and render the fields. The hook handles everything else.

The implementation lives in src/dataDisplay/model/useModelRepresent.ts if you want to see how it actually works. Fair warning: it's about 170 lines of TypeScript that took me way longer to write than I'd like to admit.

What This Approach Actually Solved

Testing this pattern across different form types and complexity levels revealed these benefits:

Readability: You can understand a form by reading its configuration. No hunting through effect hooks, no tracing execution paths. It's all right there.

Maintainability: Adding a new field dependency? Just add a subscription to the config. No risk of breaking existing effects or creating infinite loops.

Testability: The configuration is pure data. You can test the subscription engine independently of React. You can test individual subscription rules without mounting components. Way easier.

Performance: Thanks to MobX's fine-grained reactivity, forms with 50+ fields remain responsive. Only the fields that actually need to update do update.

Reusability: Form configurations are portable. The same entity definition works in different contexts with different modes (view vs edit).

What This Approach Didn't Solve (Being Honest)

Of course, it's not perfect. Real downsides encountered during experimentation:

Learning Curve: Custom configuration format means no Stack Overflow answers. Requires good documentation and examples.

Complex Logic: Some business rules are too complex to express declaratively. Requires fallback to custom code, mixing declarative and imperative approaches. Not ideal.

Debugging: Tracing through the subscription engine is harder than tracing explicit useEffect hooks. Requires extensive logging.

TypeScript Complexity: Configuration objects with many possible combinations create TypeScript edge cases. Takes time to get types right.

Performance Edge Cases: Forms with hundreds of fields can have slow initial setup even with MobX optimization. Requires lazy loading for field data.

Worth the tradeoffs? Depends on the use case. For simple forms with basic dependencies, the added complexity might not be worth it. This approach shines when you have:

Many fields with complex dependencies
Multiple similar forms that share patterns
A need to generate forms from backend configuration
Performance requirements for large forms

A Working Example

If you want to see this in action, check out the example in examples/02-field-subscriptions. It's a simplified version that demonstrates the core concepts.

The full implementation in the library includes a lot more features:

Validation subscriptions (change validation rules based on other fields)
Multi-field triggers (subscribe to multiple fields at once)
Custom action handlers
Data caching and race condition handling
Form state management
And probably a few things I'm forgetting

The code is at src/dataDisplay/model if you want to dig into the details.

Comparing to Other Solutions

"Why not just use Formik/React Hook Form/[insert form library]?" is a question I got asked a lot.

The answer is: those libraries are great, but they solve a different problem. Formik and React Hook Form give you excellent tools for managing form state, validation, and submission. But they're still imperative – you write code to define the behavior.

The declarative approach: define the relationships, let the system handle the behavior. The difference:

// Imperative (Formik/React Hook Form)
const formik = useFormik({
    values: {country: '', state: ''},
    validate: values => {
        const errors = {}
        if (values.country === 'USA' && !values.state) {
            errors.state = 'State is required for USA'
        }
        return errors
    }
})

return (
    <>
        <Select name="country" value={formik.values.country} onChange={formik.handleChange}/>
        {formik.values.country === 'USA' && (
            <Select name="state" value={formik.values.state} onChange={formik.handleChange}/>
        )}
    </>
)

// vs Declarative (this approach)
const model = [
    {name: 'country', type: 'select'},
    {
        name: 'state',
        type: 'select',
        subscribesOn: [{
            trigger: {params: [{name: 'attribute', value: 'country'}], condition: {operator: 'equals', value: 'USA'}},
            action: {type: 'visible'}
        }],
        validators: [{type: 'required', when: (values) => values.country === 'USA'}]
    }
]

Both approaches work. Ours has more upfront complexity but scales better for really complex forms. Your mileage may vary.

What I'd Do Differently Now

Looking back after two years, there are things I'd change:

Simpler Configuration Format: The JSON schema is pretty verbose. Starting over, I'd design a more compact syntax, maybe something like:

{
  name: 'state',
  visible: 'country === "USA"',
  // Simple expressions instead of complex objects
  reload: 'country',
  // Just name the dependency
}

Better DevTools: Should have built debugging tools from the start. A visual graph showing field dependencies, a log of subscription events, a way to pause and inspect the subscription engine. These would have saved significant time.

More Examples: Built for personal use without much documentation. For open-sourcing, would create way more examples and use cases.

Gradual Adoption Path: The system is all-or-nothing. Either use the declarative config or don't. Better design: make it incremental – start with simple forms, gradually add declarative features where they make sense.

Was It Worth It?

I spent about six months, on and off, building and refining this system as a side project. Testing different approaches, fixing bugs, iterating on the design.

Six months is a long time. Could have just lived with the useEffect spaghetti and focused on other things.

But once the system was working, building new forms became significantly faster. What took a week of careful effect management became a day of writing configuration. The forms were more reliable, performed better, and were easier to maintain.

Plus, the declarative JSON format opened an interesting possibility: automatic form generation. Backend entity definitions (like those XML files from old frameworks) could be transformed into form configs. This meant UIs could be automatically generated from backend schemas.

That's when it stopped being just a form library and became a framework for rapid UI development.

Try It Yourself

The full implementation is on GitHub at github.com/NazarUsik/AdaptUI. The subscription system lives in src/dataDisplay/model/, and there's a working example in
examples/02-field-subscriptions/.

Is it perfect? No. Is it the right choice for every project? Probably not. But if you're building complex forms with lots of interdependencies, and you're tired of useEffect spaghetti, maybe give the declarative approach a try.

Or at least think about it. Sometimes old approaches (like XML-driven frameworks) had good ideas worth revisiting with modern tools.

Author: Nazar Usik

GitHub: AdaptUI

Related: This pattern works especially well with the multi-layer configuration system
and component wrapper pattern described in other articles.

Building Super-Flexible Web Applications

Nazar Usik — Thu, 03 Sep 2026 19:06:55 +0000

Multi-Layer Runtime Configuration: How to Change Your Entire UI Without Rebuilding

The Problem

Hardcoded configuration is everywhere:

Need to change the primary color? Edit the code, rebuild, redeploy. Want to test two different button styles? Duplicate code or feature flags in your CI/CD. Supporting multiple clients with different branding? Maintain separate codebases or complex build configurations.

CSS variables help with colors, but what about behavior? Feature flags? Icons? Layout preferences? The configuration lives scattered across dozens of files.

This article explores runtime configuration where the entire UI: colors, fonts, layouts, icons, behavior; is driven by JSON loaded from URLs. Change a config file, refresh the page, done.

Think of it like TinaCMS for application configuration, not just content.

The Inspiration: Lightroom Presets

The idea came from an unexpected place: photo editing.

Years ago, I watched my sister (a professional photographer) process wedding photos. She'd have dozens of images but didn't adjust each manually. She used Lightroom presets.

Click. Preset applied. The whole photo transformed: color grading, contrast, brightness, everything. One preset for outdoor weddings, another for indoor ceremonies. Change the preset, change the entire look.

That pattern stuck with me. What if web UIs could work the same way? Prepare different "presets" for different clients or use cases, load them at runtime, and instantly transform the entire application?

Finding More Inspiration

The Lightroom idea was one piece. Material UI's theming system provided another.

Material UI has an interactive theme editor in their documentation. You adjust colors, fonts, spacing, and see changes instantly. IntelliJ IDEA even has a Material UI theme plugin where you select different themes and the entire palette changes immediately.

The key insight: Material UI's theming is data-driven. You pass a theme object to a provider, and all components use it. Change the object, change the entire look. No rebuilding, no find-and-replace, just configuration.

What if an entire application could work like that? Everything driven by a configuration object loaded from different sources, merged together, and changed at runtime?

The Vision: Multi-Layer Configuration

The concept was simple, execution complex:

Everything dynamic goes in config: Colors, fonts, sizes, icons, labels, behavior flags
Multiple layers: Library defaults, application defaults, component defaults, runtime overrides from URLs
Automatic merging: Later layers override earlier ones, deep merging all the way down
Zero-rebuild changes: Update the config file, refresh the page, done

What becomes possible:

Client A wants purple branding, Client B wants orange => Two config URLs, same codebase
Test button placement with 10% of users => Serve different config based on user segment
Shipped a buggy feature? => Set feature.newDashboard.enabled: false in config, instant rollback
CEO wants to see the new design before launch => Give them a special config URL
Rebranding the entire company => Update one JSON file, not 50 React components

Building it was the challenge.

Layer 1: The Library Default

I started with the foundation: a default configuration object baked into the library itself. This would be the fallback, if nothing else is specified, use these values.

Looking at the code now at src/providers/config/config/index.ts, it's... extensive. About 740 lines of configuration covering everything from console log levels to button styles to Material UI theme overrides.

Here's a tiny slice of what it looks like:

export const defaultConfig: WidgetConfig = {
    console: {
        level: {
            log: true,
            info: true,
            error: true,
            warning: true
        }
    },
    fetch: {
        credentials: 'include',
        mode: 'cors',
        authorization: {
            source: {
                type: 'cookie',
                attributeName: 'Authorization'
            },
            destination: {
                type: 'header',
                attributeName: 'Authorization'
            }
        }
    },
    i18n: {
        lng: 'EN',
        fallbackLng: 'EN'
    },
    theme: {
        palette: {
            primary: {main: 'rgb(65, 0, 153)'},
            secondary: {main: 'rgb(84, 86, 90)'}
        }
    }
    // ... hundreds more lines
}

This config includes everything: fonts, colors, spacing, border styles, component-specific settings, internationalization config, authentication settings, you name it. If it can vary between deployments or clients, it went in The Config.

Layer 2 & 3: Application and Embed Defaults

But a single default wasn't enough. Multiple levels of defaults were needed:

Library Default: The base config shipped with the library
Application Default: Overrides specific to the entire application
Component Default: Overrides specific to a particular component/widget
Runtime Config: Overrides loaded from a URL at runtime

Why so many layers? Different parts of the system need different levels of control.

The library default says "here's what a button looks like in general."

The application default says "but in this application, use a different color scheme."

The component default says "and this particular component has a custom title."

The runtime config says "and for this specific client, override everything with their branding."

The implementation is actually pretty elegant. Check out src/providers/config/config.store.ts:

export const configStore = {
    id: 'configStoreId',
    implementation: () => {
        return {
            manualConfig: {},      // Application + Embed defaults
            loadedConfig: {},      // Runtime config from URL
            defaultConfig: {},     // Library default
            get() {
                // The magic: merge all layers
                return resolveConfig(
                    withDefault(
                        merge(this.manualConfig, this.loadedConfig),
                        this.defaultConfig
                    )
                )
            }
        }
    }
}

The get() method merges everything: manual config first, then loaded config (overriding manual), then defaults fill in any gaps. It's using Lodash's deep merge, which means nested objects merge recursively. Perfect.

The Merge Problem

Of course, deep merging configuration objects turned out to be trickier than I expected.

Consider this scenario: The default config has a button with 10 properties. The application config overrides 3 of them. The runtime config overrides 2 more. What should the final config look like?

Answer: All 10 properties, with 5 overridden and 5 still at defaults.

Simple, right? Except when arrays are involved. Or when you want to remove a property, not just override it. Or when merge order matters for some properties but not others.

I spent way too long debugging cases where configs weren't merging the way I expected. The solution was to be very explicit about merge behavior and document it clearly:

// Shallow merge for top-level
const merge = (...configs) => lodash.merge({}, ...configs)

// Deep defaults for filling gaps
const withDefault = (config, defaultConfig) =>
    lodash.defaultsDeep({}, config, defaultConfig)

The order matters: merge first (runtime overrides everything), then defaultsDeep (defaults fill gaps). Get the order wrong, and your runtime config doesn't work. Trust me, I learned this the hard way.

Loading Config From URLs

The fourth layer, runtime config from a URL, was the game changer. This is what enables zero-rebuild rebranding.

The implementation in src/providers/config/useConfig.ts is straightforward:

export const useConfig = (props) => {
    const {configUrl = '', config: manualConfig = {}, defaultConfig = {}} = props
    const configStore = useConfigStore()
    const {get} = useFetch(configStore.get())

    useEffect(() => {
        if (!isEmpty(configUrl)) {
            get(configUrl)
                .then(loadedConfig => {
                    configStore.setLoadedConfig(loadedConfig)
                })
                .catch(error => {/* handle error */
                })
        }
    }, [configUrl])

    return {reload: loadConfig}
}

Pass a URL, the system fetches it, merges it with the other layers, done. The config can be a static JSON file, a dynamic API endpoint, whatever. As long as it returns a valid config object, it gets merged in.

For components using the embed pattern (see Article 0), the config URL goes right in the HTML:


<embed-widget config-url="${RUNTIME_CONFIG_URL}"></embed-widget>

The host application passes in an environment variable, the component fetches it, and client-specific configuration loaded at runtime.

Variable Substitution: Config Referencing Config

Here's where things got really interesting (and maybe a bit crazy). I wanted config values to reference other config values.

Why? Because I didn't want to repeat myself. If I define a primary color once, I want to reuse it everywhere. But JSON doesn't have variables.

Enter json-variables, a library that lets you do this:

{
  "colors": {
    "primary": "rgb(65, 0, 153)",
    "primaryDark": "rgb(50, 0, 120)"
  },
  "button": {
    "background": "[[colors.primary]]",
    "hoverBackground": "[[colors.primaryDark]]"
  }
}

See those [[...]] markers? Those get resolved to the actual values. Change colors.primary once, and it updates everywhere it's referenced.

The resolution happens in resolveConfig():

export const resolveConfig = (widgetConfig) =>
    resolveJson(widgetConfig) as WidgetConfig

This runs after all the merging is done, so the final merged config gets its variables resolved. Neat.

Integrating With Material UI Theme

The config system needed to play nice with Material UI's theming. This meant:

Config structure must match (or extend) Material UI's theme structure
Pass config to Material UI's createTheme()
Make config available to styled-components too

The theme provider at src/providers/theme/index.tsx handles this:

export const ThemeProvider = observer(({children}) => {
    const {theme: themeConfig} = useConfig()
    const [theme] = useTheme({theme: themeConfig})

    return (
        <MuiBaseThemeProvider injectFirst>
            <StyledComponentsThemeProvider theme={theme}>
                <MuiThemeProvider theme={theme}>
                    {children}
                </MuiThemeProvider>
            </StyledComponentsThemeProvider>
        </MuiBaseThemeProvider>
    )
})

Three providers, all getting the same theme object. This means:

Material UI components get the theme
Styled-components get the theme
Custom components get the theme

Everyone's happy.

TypeScript Declaration Merging: Extending MUI Types

But there's a problem. Material UI's theme has specific types. Custom config adds custom properties. TypeScript isn't happy.

The solution? Declaration merging. TypeScript lets you "reopen" existing interfaces and add to them. Check out typings/theme.d.ts:

declare module '@mui/material/styles' {
    interface BreakpointOverrides {
        xxl: true;
        xxxl: true;
    }

    interface Theme extends AdaptTheme {
    }

    interface ThemeOptions extends AdaptTheme {
    }

    interface Palette {
        neutral: Palette['primary']
    }

    interface CommonColors {
        silver: string
    }
}

declare module 'styled-components' {
    export interface DefaultTheme extends Theme {
    }
}

This tells TypeScript: "Hey, Material UI's theme? It also has these properties now." And TypeScript just... accepts it. No errors, full type safety for custom config.

This pattern is documented in Material UI's own docs for adding custom colors, and it works perfectly for extending the entire theme with custom config systems.

Authorization In Config

One interesting use case: authorization. Components need to authenticate with backend APIs, but auth mechanisms vary by deployment.

Auth configuration goes in the config:

{
  "fetch": {
    "authorization": {
      "source": {
        "type": "cookie",
        "attributeName": "Authorization"
      },
      "destination": {
        "type": "header",
        "attributeName": "Authorization"
      }
    }
  }
}

This says: "Get the auth token from a cookie named 'Authorization', and put it in a header named 'Authorization'."

Then a custom useFetch hook reads this config and automatically applies it:

const config = useConfig()
const authSource = config.fetch.authorization.source
const authDest = config.fetch.authorization.destination

// Read token from cookie
const token = readCookie(authSource.attributeName)

// Add to request headers
headers[authDest.attributeName] = token

Change the config, change how auth works. No code changes required. This was huge for testing different auth mechanisms without rebuilding.

Internationalization: Labels In Config

Similarly, i18n configuration integrates into the config. It specifies:

Default language
Fallback language
Where to load translations from

{
  "i18n": {
    "lng": "EN",
    "fallbackLng": "EN",
    "backend": {
      "http": {
        "loadPath": "/api/translations/{{lng}}"
      }
    }
  }
}

Throughout the config, instead of hardcoded text, use label keys:

{
  "elements": {
    "layout": {
      "widget": {
        "header": {
          "title": {
            "text": "widget.header.title"
          }
        },
        "toolbar": {
          "close": {
            "hint": "common.button.hint.close"
          }
        }
      }
    }
  }
}

These keys get resolved by i18n-next at runtime. Change the language, all labels change. Have a client that speaks German? Point their config to German translations. Done.

Icons In Config: The SVG to Base64 Adventure

Here's where I maybe went a bit overboard. I wanted icons in the config too.

The challenge: Many components have icons hardcoded in CSS (background images, pseudo-elements, etc.). How do you make those configurable?

The solution I came up with: Convert React icon components to Base64-encoded SVG URLs, then use those in CSS.

The config would specify icon names:

{
  "elements": {
    "layout": {
      "widget": {
        "header": {
          "closeButton": {
            "icon": {
              "name": "FaRegWindowClose",
              "color": "rgb(255, 255, 255)",
              "size": "1.25rem"
            }
          }
        }
      }
    }
  }
}

Then in code:

Import the icon from React Icons: import {FaRegWindowClose} from 'react-icons/fa'
Render it to an SVG string
Encode it as Base64
Create a url("data:image/svg+xml;base64,...") string
Use it in CSS

This worked! But it was slow. Rendering dozens of icons to Base64 on every render was painful.

So I added caching. First render, generate the URL and cache it. Subsequent renders, use the cached version. Much faster.

Looking back, this might have been overkill. But it worked, and it meant truly everything visual could be configured, even icons in CSS.

The Demo That Can Buy Management

With all pieces in place, here's a compelling demo scenario:

Show the application running with default branding
Open the config JSON file in an editor
Change the primary color from purple to orange
Save the file
Refresh the page
The entire application is now orange

Then demonstrate live changes: colors, fonts, sizes, icons: all in real-time just by editing JSON. No rebuilds, no deployments, just instant changes.

The question that inevitably comes: "Can clients customize their own branding?"

Absolutely. That's the entire point of the system.

Using Config with the Declarative Forms

Remember the declarative form system I wrote about in the previous article? The Config system plays perfectly with it.

Form configurations can be stored in the config and loaded dynamically:

{
  "widgets": {
    "entityForm": {
      "attributes": [
        {
          "name": "firstName",
          "type": "text",
          "label": "form.field.firstName",
          "required": true
        }
      ]
    }
  }
}

This means the same form component can render different forms based on configuration. One client needs a 5-field form, another needs 20 fields? Just different configs, same code.

The form engine reads from the config, applies the declarative dependencies, and everything just works together. The multi-layer system means library defaults provide basic form styling, application config customizes for the product, and runtime config adapts per client.

What This Pattern Enables

The power shows up in unexpected ways:

Instant visual updates: Marketing changed their mind about the color scheme at 4 PM on Friday? Update the config JSON, refresh. Five minutes, not five days.

Per-client customization: Client says "we need our logo in the header." Add header.logo.url to their config. No custom build, no special branch, just configuration.

Safe feature rollout: Launch a feature but keep the kill switch ready. One line in production config disables it if things go wrong. No emergency deploy.

Designer collaboration: Designers can iterate on spacing, colors, icon sizes by editing JSON and seeing results immediately. No waiting for developer availability.

Testing variations: Does a bigger button convert better? Load different configs for different user groups. Same deployed code, different experience.

The Costs (Being Honest)

Of course, this wasn't without downsides:

Complexity: The config file grew to over 700 lines. Finding what you need isn't always obvious. Requires good documentation and examples.

Merge Bugs: Deep merging objects is tricky. Several bugs emerged where configs didn't merge as expected, especially with arrays. Took time to iron out.

Type Safety: TypeScript helps, but config is ultimately JSON loaded at runtime. Type errors become runtime errors. Caught a few in production during development.

Learning Curve: The config structure is custom, not standard React or Material UI. Takes time to learn.

Performance: Loading and merging large configs does have overhead. Not much, but it's there. And that icon encoding system I built? Definitely added some milliseconds to initial render.

Over-Configuration: Not everything benefits from being in config. Finding the right balance is trial and error.

Worth these costs? Depends on the use case. For multi-tenant applications or platforms needing runtime flexibility, absolutely. For smaller single-tenant apps, might be overkill.

What I'd Do Differently

If I were starting over:

Smaller Default Config: 700 lines is too much. I'd be more selective about what goes in by default. Maybe split it into modules.

Config Editor UI: A visual editor for configs (like Material UI's theme editor) would be valuable for non-technical users. Never built one, but it's a logical next step.

Validation: Runtime config validation would catch errors earlier. Invalid configs making it to production is a real risk. JSON Schema or similar would help.

Better Documentation: Documentation for the config structure needs extensive examples for every major section.

Lazy Loading: Load config sections on-demand instead of all at once. Most pages don't need the entire config.

The Real Win: Flexibility

The biggest benefit is the flexibility.

When someone asks "Can we change X?" the answer is "Yes, in the config."

Need to disable a buggy feature in production? Config flag, done in seconds.

Want to test a new design with 10% of users? A/B test via config.

The config system transforms a rigid, hard-coded application into a flexible, configurable platform. That flexibility is what matters most.

Complementary Tools; Not Alternatives

Platforms like ConfigCat, LaunchDarkly, Split.io, and Flagsmith are often mentioned in the same breath as runtime configuration. They're excellent at what they do, feature flags with targeting rules, percentage rollouts, and analytics; but they solve one slice of the problem.

Multi-layer config is a whole-system approach. Feature flags are one dimension: theming, typography, icons, layout, i18n labels, component behavior, and form structure are others. A feature flag service tells you whether to show a feature. Multi-layer config tells you how the entire UI should
look and behave.

These tools aren't alternatives, they're complementary. ConfigCat or LaunchDarkly can feed into the runtime config layer as a data source:

// Feature flag platform as one input to the runtime layer
const runtimeConfig = {
    features: {
        newDashboard: await configCat.getValueAsync('newDashboard', false),
        betaExport: await configCat.getValueAsync('betaExport', false),
    },
    // Everything else: theming, layout, icons; lives here too
    theme: {palette: {primary: {main: tenantBranding.primaryColor}}},
    icons: tenantBranding.iconSet,
    i18n: tenantBranding.labels,
}

The same applies to other tools in the space:

TinaCMS / Contentful / Strapi: Content management. They handle text, images, pages. Multi-layer config handles application behavior and styling. Use both: CMS for content, config system for everything else.

Firebase Remote Config / AWS AppConfig: Cloud-based config with versioning and rollback. They can serve as the backend behind the runtime config URL, the config system doesn't care where the JSON comes from.

The key difference: feature flag platforms give you booleans and strings. Multi-layer config gives you a deeply merged, typed configuration object that drives your entire component tree, from button border radius to form field visibility to icon mappings. Use the specialized tools for what
they're best at, and let the config system unify everything into one coherent runtime shape.

A Complete Example

Here's a real example from examples/01-multi-layer-config:

import {Widget} from 'adaptui'

function App() {
    return (
        <Widget
            // Application-level config
            config={{
                theme: {
                    palette: {
                        primary: {main: '#1976d2'}
                    }
                }
            }}

            // Runtime config from URL
            configUrl="/api/config"

            // Library defaults used for everything else
        >
            <MyApplication/>
        </Widget>
    )
}

The Widget component automatically wraps everything in ConfigProvider, which loads and merges all the configs. Then any component inside can access the merged config:

import {useConfig} from 'adaptui'

function MyComponent() {
    const config = useConfig()

    return (
        <div style={{backgroundColor: config.theme.palette.primary.main}}>
            {/* Styled from config */}
        </div>
    )
}

Simple API, powerful flexibility.

Wrapping Up

Multi-layer configuration trades initial complexity for long-term flexibility. The setup takes time: designing the config structure, implementing merging logic, integrating with your component library. But once built, changes that used to take hours happen in minutes.

The pattern works best when you need runtime adaptability. For static applications with one deployment and no variation, it's overkill. For platforms serving multiple clients or needing frequent visual updates, it's transformative.

The ideas here are patterns, not prescriptions. Two layers might be enough. Your merging strategy might differ. What matters is separating configuration from code and loading it at runtime.

Hopefully these patterns help someone build their own version and avoid the pitfalls discovered along the way.

The Code

The full implementation is on GitHub at github.com/NazarUsik/AdaptUI.

Key files:

Config store and provider: src/providers/config
Default config: src/providers/config/config/index.ts
Theme integration: src/providers/theme
TypeScript extensions: typings/theme.d.ts
Working example: examples/01-multi-layer-config

Is it perfect? No. Is it the right choice for every project? Probably not. But if you're facing multiple rebrandings, multi-tenant requirements, or just want your UI to be more flexible, the multi-layer config pattern is worth considering.

Author: Nazar Usik

GitHub: AdaptUI

Related: This pattern works especially well with the declarative form dependencies
and component wrapper pattern described in other articles.

Self-Mounting Micro-Frontends: A Simple Pattern

Nazar Usik — Thu, 03 Sep 2026 19:06:43 +0000

How to embed modern React/Vue/Svelte into legacy applications without complex orchestration

The Problem

How do you put a micro-frontend project onto a monolithic page?

Not just theoretically, practically. You have a legacy application (JSP, PHP, Django templates, whatever). You want to add modern React components without rewriting everything. You need them to coexist on the same page.

The established solutions are complex: Single-SPA requires runtime orchestration, Module Federation needs Webpack configuration, iFrames create styling headaches. What if there was something simpler?

The Simple Solution

The pattern requires just two things:

1. Custom HTML tags + script tag in your legacy page:


<embed-counter></embed-counter>
<script src="${EMBED_SERVER_URL}/embeds/counter-embed.js"></script>

2. A JavaScript bundle that finds those tags and renders into them

That's it. No complex orchestration. No shared dependencies. No runtime coordination.

How It Works

The pattern breaks down into three technical challenges:

1. How to pack an application into one file?

Use a bundler with IIFE format. Vite, Webpack, Rollup: all can bundle your entire application into a single JavaScript file that executes immediately when loaded.

// vite.config.js
export default defineConfig({
    plugins: [react()],
    build: {
        rollupOptions: {
            output: {
                entryFileNames: 'counter-embed.js',
                format: 'iife',  // Immediately Invoked Function Expression
                inlineDynamicImports: true
            }
        }
    }
})

IIFE format wraps everything in a function scope, preventing variable collisions between embeds or with the host page.

2. How does the application render itself?

Standard framework mounting, but with custom tag selector. React, Vue, Angular all have mounting APIs. Instead of mounting to #root, mount to all instances of your custom tag:

// React example - main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'

const mountEmbed = () => {
    const containers = document.querySelectorAll('embed-counter')

    containers.forEach(container => {
        const root = ReactDOM.createRoot(container)
        root.render(<App/>)
    })
}

if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', mountEmbed)
} else {
    mountEmbed()
}

The same pattern works for Vue (createApp().mount()), Svelte (new App({ target })), or any framework with a mounting API.

3. How to deliver and orchestrate multiple applications?

A static file server + build orchestration. The simplest version is just serving files, but for multiple embeds you need to coordinate builds.

Embed Server Implementation

Two approaches work well depending on your stack:

Option A: Java + Spring Boot + Gradle

Spring Boot serves static files by default. Gradle can orchestrate frontend builds:

The key insight: it doesn't have to be Gradle. The same pattern works with npm workspaces, Turborepo, or any build tool. The point is coordinating multiple frontend builds and collecting outputs in one place.

Build configuration:

// Root build.gradle
tasks.register('deploy') {
    dependsOn ':embeds:counter-embed:installEmbed'
    dependsOn ':embeds:todo-embed:installEmbed'
    dependsOn ':embeds:dashboard-embed:installEmbed'
}

// Each embed's build.gradle
tasks.register('buildEmbed', Exec) {
    workingDir projectDir
    commandLine 'npm', 'install'

    doLast {
        exec {
            workingDir projectDir
            commandLine 'npm', 'run', 'build'
        }
    }
}

tasks.register('installEmbed', Copy) {
    dependsOn buildEmbed
    from 'dist'
    into "${rootProject.projectDir}/src/main/resources/static/embeds"
}

One Gradle command builds all embeds and the Spring Boot server. Embeds end up in static resources, served by Spring Boot.

Usage in legacy page:

<%-- Legacy JSP page --%>
<html>
<body>
    <h1>Legacy Application</h1>

    <%-- Existing legacy content --%>
    <jsp:include page="legacy-component.jsp"/>

    <%-- Modern embed mount point --%>
    <embed-counter></embed-counter>
    <script src="${EMBED_SERVER_URL}/embeds/counter-embed.js"></script>

    <%-- More legacy content --%>
</body>
</html>

The EMBED_SERVER_URL is an environment variable. Different environments (dev, staging, prod) point to different embed server instances.

Option B: Node.js + Express + npm workspaces

Lighter alternative using JavaScript tooling throughout:

// Express server
import express from 'express'
import path from 'path'

const app = express()

// Serve embeds
app.use('/embeds', express.static(path.join(__dirname, '../public/embeds')))

// CORS for cross-origin embedding
app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*')
    res.header('Access-Control-Allow-Methods', 'GET')
    next()
})

app.listen(8080, () => {
    console.log('Embed server running on port 8080')
})

npm workspaces coordinate multiple embed builds:

{
  "name": "embed-server-nodejs",
  "workspaces": [
    "packages/server",
    "embeds/*"
  ],
  "scripts": {
    "build": "npm run build:embeds",
    "build:embeds": "npm run build --workspaces --if-present",
    "start": "npm start --workspace=packages/server"
  }
}

Same pattern, different tooling. Choose based on your existing stack.

Both implementations are available:

Java: github.com/NazarUsik/embed-server
Node.js: github.com/NazarUsik/embed-server-nodejs

Why This Pattern Matters

The embed server itself is simple: static file serving + build orchestration.

But it's a foundation that enables other patterns:

Runtime configuration: Embeds can fetch config from URLs and apply it at runtime:


<embed-entity config-url="${CONFIG_URL}/entity-form-config.json"></embed-entity>

The embed fetches config, merges with defaults, applies theming. Without this pattern, config changes require rebuilding. (See multi-layer config article)

Complex form systems: Self-contained forms with dependencies become simple:


<embed-entity entity-id="${ENTITY_ID}" mode="edit" config-url="${CONFIG_URL}"></embed-entity>

One tag, entire complex form system loaded. Stores, subscriptions, field dependencies, data loading: all encapsulated. (See declarative forms article)

Consistent component libraries: Share styling across embeds while keeping them independent. (See component wrapper article)

Everything builds on custom HTML tags that self-mount applications.

Production Considerations

CORS configuration: Cross-domain embedding requires careful CORS setup. The monolith and embed server run on different domains, so API calls need proper CORS headers for each environment (dev, staging, prod) with allowlist entries.

Authentication: Session-based auth from the host page needs to pass to embeds. Common approach:

Reading the auth cookie from the host page
Including it in embed API calls
Configuring this in the multi-layer config

{
  "fetch": {
    "authorization": {
      "source": {
        "type": "cookie",
        "attributeName": "JSESSIONID"
      },
      "destination": {
        "type": "header",
        "attributeName": "Authorization"
      }
    }
  }
}

CSS isolation: No Shadow DOM, no automatic isolation. Options:

CSS Modules in Vite
Strict naming conventions (embed-name__component-name__element)
Component wrapper library providing consistent base styles

Bundle sizes: Each embed includes its own copy of React. Simple counter ~144 KB, complex forms 500+ KB. Mitigations:

Code splitting where possible
Lazy-load heavy dependencies
Accept the trade-off (simplicity over optimization)

Trade-offs

Build complexity: Adding a new embed requires multiple steps:

Create React project
Configure Vite for IIFE output
Add build orchestration (Gradle/npm)
Register in root build system
Configure custom HTML tag name
Test in host page

A CLI tool (similar to create-react-app or Angular CLI) could automate much of this: generating project scaffolding, Vite config, build files, and registering the embed. Or at minimum, starter templates would reduce the manual setup significantly.

Performance: Each embed bootstraps independently. Multiple embeds on one page = multiple React instances, duplicate libraries. Not optimal.

Debugging challenges: When something breaks, the issue could be:

Embed code
Build configuration
Build orchestration copying files
CORS
Host page environment

Multiple layers make troubleshooting harder.

Dependency management: No shared dependencies between embeds. React updates require updating every embed, rebuilding everything, redeploying everything.

What It Enables

Independent deployment: Update one embed, deploy just that embed. The monolith doesn't care. Other embeds don't care.

Team scalability: Different teams own different embeds, work in parallel without coordination. No cross-team dependencies.

Technology freedom: Use Svelte for one embed, React for another, Vue for a third. The host page doesn't care, it's just a script tag.

Gradual migration: No complete rewrite needed. Carve out pieces, modernize as embeds, leave the rest. Zero risk incremental approach.

Legacy coexistence: Old JSP pages and new React embeds on the same page. Legacy toolbar with modern form. Everything works together.

When to Use This Pattern

This pattern works best when:

Modernizing legacy applications incrementally without full rewrites
Team independence is more valuable than shared dependencies
Technology flexibility matters (different frameworks for different embeds)
Deployment independence is critical
Simplicity is preferred over optimization

It's less suitable when:

All embeds share heavy dependencies (Module Federation better)
Performance is critical (duplicate libraries = overhead)
Single team owns everything (simpler patterns exist)
Host application can run orchestration logic (Single-SPA better)

The Technical Details (For Those Who Care)

If you want to see the actual implementation:

Java + Spring Boot + Gradle:

Repository: github.com/NazarUsik/embed-server
Full Gradle multi-project setup
Spring Boot static file serving
Example embeds: Counter (React), Todo (Vue), Dashboard (Angular)
Technical documentation

Node.js + Express + npm workspaces:

Repository: github.com/NazarUsik/embed-server-nodejs
Lighter weight, faster startup
npm workspaces for monorepo management
Same pattern, JavaScript tooling
Setup guide

The Core Pattern:

Build: Each embed bundles to single IIFE JavaScript file
Deploy: Embed server serves these files as static resources
Embed: Custom HTML tag + script tag in host page
Mount: Embed finds its tags and mounts React/Vue/Svelte

That's it. No fancy runtime orchestration. No complex dependency sharing. No module federation. Just HTML tags that know how to fill themselves with content.

Simple. Maybe too simple for "proper" micro-frontends, but it solves the legacy modernization problem effectively.

Comparison with Other Approaches

vs. Single-SPA:

Self-mounting: Simpler, no orchestration needed
Single-SPA: Better shared dependencies, more features, steeper learning curve

vs. Module Federation:

Self-mounting: Works with any host, including legacy pages that can't run orchestration
Module Federation: Better performance, shared dependencies, requires Webpack knowledge

vs. iFrames:

Self-mounting: Easier styling coordination, lighter weight
iFrames: Better isolation, but heavier and harder to style consistently

vs. Full rewrite:

Self-mounting: Incremental, zero risk, works alongside legacy
Full rewrite: Clean slate, but high risk, can't deliver features during rewrite

Wrapping Up

The self-mounting embed pattern bridges legacy and modern:

Custom HTML tags provide simple integration points
IIFE bundles prevent collisions
Static file serving handles delivery
Build orchestration coordinates multiple embeds

It enables gradual modernization without stopping feature delivery. The simplicity trades performance for independence and flexibility.

This foundation makes other patterns possible: runtime configuration, complex form systems, shared component libraries; all built on the same principle: HTML tags that know how to render themselves.

Author: Nazar Usik

GitHub: embed-server | embed-server-nodejs

Related: This enables the multi-layer config, declarative forms,
and component wrappers described in other articles.