How to override components?

Milan Herda, 07/2024

The Problem

1. Design based on

the current portal

2. Different components for the same functionality

3. Different set of features

Let's start with an obvious approach

'use client';

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';
import SearchForm from '@local/ui/search/SearchForm';
import useHostname from '@local/router/infrastructure/react/useHostname';

export default function Homepage() {
    const hostname = useHostname();
  
    let HeroBanner = DefaultHeroBanner;
  
    if (hostname === 'prace.cz') {
        HeroBanner = HeroBannerPrace;
    } else if (hostname === 'jobs.cz') {
        HeroBanner = HeroBannerJobs;
    }
 
    return (
        <>
            <HeroBanner />
            <SearchForm />
            <>
        </>
    );
}

SOLID principles to the rescue

Single Responsibility Principle

'use client';

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';
import SearchForm from '@local/ui/search/SearchForm';
import useHostname from '@local/router/infrastructure/react/useHostname';

export default function Homepage() {
    const hostname = useHostname();
  
    let HeroBanner = DefaultHeroBanner;
  
    if (hostname === 'prace.cz') {
        HeroBanner = HeroBannerPrace;
    } else if (hostname === 'jobs.cz') {
        HeroBanner = HeroBannerJobs;
    }
 
    return (
        <>
            <HeroBanner />
            <SearchForm />
            <>
        </>
    );
}

Single Responsibility Principle

'use client';

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';
import SearchForm from '@local/ui/search/SearchForm';
import useHostname from '@local/router/infrastructure/react/useHostname';

export default function Homepage() {
    const hostname = useHostname();
  
    const HeroBanner = resolveHeroBanner(hostname)
  
    return (
        <>
            <HeroBanner />
            <SearchForm />
            <>
        </>
    );
}

function resolveHeroBanner(hostname: string) {
    let HeroBanner = DefaultHeroBanner;
  
    if (hostname === 'prace.cz') {
        HeroBanner = HeroBannerPrace;
    } else if (hostname === 'jobs.cz') {
        HeroBanner = HeroBannerJobs;
    }
 
    return HeroBanner;
}

Single Responsibility Principle

'use client';

import SearchForm from '@local/ui/search/SearchForm';
import useHostname from '@local/router/infrastructure/react/useHostname';
import resolveHeroBanner from '@local/resolver/application/resolveBanner';

export default function Homepage() {
    const hostname = useHostname();
  
    const HeroBanner = resolveHeroBanner(hostname)
  
    return (
        <>
            <HeroBanner />
            <SearchForm />
        </>
    );
}

Single Responsibility Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

export default function resolveHeroBanner(hostname: string) {
    let HeroBanner = DefaultHeroBanner;
  
    if (hostname === 'prace.cz') {
        HeroBanner = HeroBannerPrace;
    } else if (hostname === 'jobs.cz') {
        HeroBanner = HeroBannerJobs;
    }
 
    return HeroBanner;
}

Open-Closed Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

export default function resolveHeroBanner(hostname: string) {
    let HeroBanner = DefaultHeroBanner;
  
    if (hostname === 'prace.cz') {
        HeroBanner = HeroBannerPrace;
    } else if (hostname === 'jobs.cz') {
        HeroBanner = HeroBannerJobs;
    }
 
    return HeroBanner;
}

Open-Closed Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

const componentsRegistry = {
    'prace.cz': HeroBannerPrace,
    'jobs.cz': HeroBannerJobs,
};

export default function resolveHeroBanner(hostname: string) {
    if (componentsRegistry[hostname]) {
        return componentsRegistry[hostname];
    }
  
    return DefaultHeroBanner;
}

Open-Closed Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

const componentsRegistry = {
    'default': DefaultHeroBanner,
    'prace.cz': HeroBannerPrace,
    'jobs.cz': HeroBannerJobs,
};

export default function resolveHeroBanner(hostname: string) {
    if (componentsRegistry[hostname]) {
        return componentsRegistry[hostname];
    }
  
    return componentsRegistry.default ?? () => null;
}

Open-Closed Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

const componentsRegistry = {
    'default': DefaultHeroBanner,
    'prace.cz': HeroBannerPrace,
    'jobs.cz': HeroBannerJobs,
};

export default function resolveComponent(hostname: string, componentName: string) {
    if (componentsRegistry[hostname]) {
        return componentsRegistry[hostname];
    }
  
    return componentsRegistry.default ?? () => null;
}

Open-Closed Principle

import HeroBannerPrace from '@prace/ui/HeroBanner';
import HeroBannerJobs from '@jobs/ui/Homepage/HeroBanner';
import DefaultHeroBanner from '@local/ui/hero/HeroBanner';

const componentsRegistry = {
    'default': {
        HeroBanner: DefaultHeroBanner,
    },
    'prace.cz': {
        HeroBanner: HeroBannerPrace,
    },
    'jobs.cz': {
        HeroBanner: HeroBannerJobs,
    },
};

export default function resolveComponent(hostname: string, componentName: string) {
    if (componentsRegistry[hostname]?.[componentName]) {
        return componentsRegistry[hostname][componentName];
    }
  
    return componentsRegistry.default[componentName] ?? () => null;
}

Open-Closed Principle

import componentsRegistry from '@local/configuration/componentsRegistry';

export default function resolveComponent(hostname: string, componentName: string) {
    if (componentsRegistry[hostname]?.[componentName]) {
        return componentsRegistry[hostname][componentName];
    }
  
    return componentsRegistry.default[componentName] ?? () => null;
}

Things left to solve

  • we want to be able resolve also services and parameters, not only components
  • TypeScript types
  • registry imports all components/services for all supported domains
    • we need registry to be domain-specific
    • support for lazy loading
    • split server components and client components
    • all of this will end with the requirement for some form of configuration file
  • resolver should be available also in other packages

a Service Container

My approach to the problems was to use

ServiceContainer

  • object encapsulating the registry of services (and parameters)
  • providing access methods to these services (getService, getParameter, getComponent etc...)
  • usable as a Dependency Injection Container (good pattern) or Service Locator (antipattern in most languages)

Implementation

To minimize the work of programmers:

  • they can add/edit service in a configuration file and
    • registers and containers for each domain will be generated automatically
    • server-side and client containers will be generated automatically
    • types will be generated automatically (yet TBD)

Configuration & Generation

Configuration

// apps/container-experiment/config/*

{
	"components": {
		"Demo/Banner": "@local/ui/Banner",
		"Demo/ServerComponent": [
			"@local/ui/server/ServerComponent",
			{
				"isServer": true
			}
		],
		"Demo/ClientComponent": [
			"@local/ui/client/ClientComponent",
			{
				"isLazy": true
			}
		]
	},
    "services": {},
    "parameters": {
        "searchEngine": "algolia",
        "isUserAccountAvailable": false,
    }
}

Generate container from configuration files

// apps/container-experiment/bin/generate-container.sh

#!/bin/bash

PREV_DIR=`pwd`

__DIR__=`dirname ${BASH_SOURCE[0]}`

LOCAL_ENV_FILE=$__DIR__/../.env.local

if [ -f $LOCAL_ENV_FILE ]; then
	source $LOCAL_ENV_FILE
fi

if [ -z "$DOMAIN" ]; then
	DOMAIN=default
fi

cd $__DIR__/..

echo "Generating containers for $DOMAIN"
yarn container-generator \
	--confDir ./config/$DOMAIN/ \
	--verbose \
	--serverFile=./src/container/serverContainer.ts \
	--clientFile=./src/container/clientContainer.ts

cd $PREV_DIR

Generate container from configuration files

// apps/container-experiment/package.json

{
	"scripts": {
		"dev": "yarn generate:container && next dev",
		"build": "yarn generate:container && next build",
		"generate:container": "bash bin/generate-container.sh"
	},
	"dependencies": {
		"@almacareer/cyborg.container": "workspace:^"
	}
}

TODO

  • composing of configuration files in a way where domain-specific files define only overrrides and everything else is taken from default

Generate container from configuration files

// libs/container/src/containerGenerator/index.ts

import commandLineArgs from 'command-line-args';
import chalk from 'chalk';
import { writeFile } from 'node:fs/promises';
import { generateClientContainerCode, generateServerContainerCode } from './generator/generateContainerCode';
import parseConfiguration from './parser/parseConfiguration';
import composeConfiguration from './composer/composeConfiguration';
import findConfigurationFiles from './composer/findConfigurationFiles';

const options = commandLineArgs([
	{ name: 'confDir', alias: 'c', type: String, defaultValue: './config' },
	{ name: 'serverFile', type: String, defaultValue: 'serverContainer.ts' },
	{ name: 'clientFile', type: String, defaultValue: 'clientContainer.ts' },
	{ name: 'localConfig', alias: 'l', type: String, defaultValue: './local.services.json' },
	{ name: 'verbose', alias: 'v', type: Boolean },
]);

const { confDir, serverFile, clientFile, localConfig } = options;

const files = await findConfigurationFiles(confDir, localConfig);

const configuration = composeConfiguration(files);

const parsedConfiguration = parseConfiguration(configuration.services);
const serverCode = generateServerContainerCode(parsedConfiguration);
const clientCode = generateClientContainerCode(parsedConfiguration);

await writeFile(serverFile, serverCode);
await writeFile(clientFile, clientCode);

Container

Container: types

// libs/container/src/container/application/types.ts

export interface MutableServiceContainer {
	setService: <T>(serviceName: string, service: T) => MutableServiceContainer;
}

export interface ServiceLocator {
	getService: <T>(serviceName: string) => T | undefined;
}

interface DependencyInjectionContainer extends ServiceLocator, MutableServiceContainer {}

export interface DependencyInjectionContainerProxy extends DependencyInjectionContainer {
	wrapContainer: (container: DependencyInjectionContainer) => DependencyInjectionContainerProxy;
}

export default DependencyInjectionContainer;

✏️ TODO:

set/getComponent & set/getParameter methods

Container: context

// libs/container/src/container/infrastructure/react/client/ServiceContainerContext.tsx

import React, { createContext, PropsWithChildren, useContext } from 'react';
import createContainer from '@local/container/application/createContainer';
import DependencyInjectionContainer from '@local/container/application/types';

interface ServiceContainerContextType {
	container: DependencyInjectionContainer;
}

const defaultValue: ServiceContainerContextType = {
	container: createContainer(),
};

const ServiceContainerContext = createContext(defaultValue);

export function ServiceContainerProvider({
	container,
	children,
}: PropsWithChildren<{ container: DependencyInjectionContainer }>) {
	return (
        <ServiceContainerContext.Provider value={{ container }}>
            {children}
        </ServiceContainerContext.Provider>
    );
}

export default ServiceContainerContext;

Container: proxy

import 'server-only';
import createContainer from '@local/container/application/createContainer';
import DependencyInjectionContainer, { DependencyInjectionContainerProxy } from '@local/container/application/types';

export function createProxyContainer(): DependencyInjectionContainerProxy {
	let wrappedContainer: DependencyInjectionContainer = createContainer();

	return {
		setService(serviceName, service) {
			wrappedContainer.setService(serviceName, service);

			return this;
		},
		getService(serviceName) {
			return wrappedContainer.getService(serviceName);
		},
		wrapContainer(container) {
			wrappedContainer = container;

			return this;
		},
	};
}

const container: DependencyInjectionContainerProxy = createProxyContainer();

export default container;

Why do we need proxy?

App with container

Library

App with real container

Library

Container(proxy)

Generated Server Container

// apps/container-experiment/src/container/serverContainer.ts

import 'server-only';
import DependencyInjectionContainer from '@almacareer/cyborg.container/container/application/types';
import containerProxy from '@almacareer/cyborg.container/container/infrastructure/react/server';

export function createContainer(): DependencyInjectionContainer {
    // ...
}

const container = containerProxy.wrapContainer(createContainer());

export default container;

Generated Client Container

import DependencyInjectionContainer from '@almacareer/cyborg.container/container/application/types';
import DemoBannerc331b7bc7ac84527bf8f4f9d2ae1d20e from '@local/ui/Banner';

export function createContainer(): DependencyInjectionContainer {
	const services: Record<string, any> = {
		'Demo/Banner': DemoBannerc331b7bc7ac84527bf8f4f9d2ae1d20e,
	};

	const lazyLoadedServices: Record<string, boolean> = {};

	const container: DependencyInjectionContainer = {
		setService(serviceName, service) {
			services[serviceName] = service;

			return this;
		},
		getService(serviceName) {
			switch (serviceName) {
                // ...

				default:
					return services[serviceName];
			}
		},
	};

	return container;
}

const container = createContainer();

export default container;

Generated Client Container

import DependencyInjectionContainer from '@almacareer/cyborg.container/container/application/types';
import dynamic from 'next/dynamic';
import DemoBannerc331b7bc7ac84527bf8f4f9d2ae1d20e from '@local/ui/Banner';

export function createContainer(): DependencyInjectionContainer {
	//...
	const lazyLoadedServices: Record<string, boolean> = {};

	const container: DependencyInjectionContainer = {
		setService(serviceName, service) { /*...*/ },
		getService(serviceName) {
			switch (serviceName) {
				case 'Demo/ClientComponent':
					if (!lazyLoadedServices[serviceName]) {
						const service = dynamic(() => import('@local/ui/client/ClientComponent'));
						services[serviceName] = service;
						lazyLoadedServices[serviceName] = true;
					}

					return services[serviceName];

				default:
					return services[serviceName];
			}
		},
	};

	return container;
}

const container = createContainer();

export default container;

layout.tsx

// apps/container-experiment/src/app/layout.tsx

export default function RootLayout({
	children,
}: Readonly<{
	children: React.ReactNode;
}>) {
	return (
		<html lang="en">
			<head>
				<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@1.0.0/css/bulma.min.css" />
			</head>
			<body>
				<ContainerProvider>
					<Navigation />
					<main className="px-2 pt-2">{children}</main>
				</ContainerProvider>
			</body>
		</html>
	);
}

ContainerProvider.tsx

// apps/container-experiment/src/container/ui/ContainerProvider.tsx

'use client';

import { PropsWithChildren } from 'react';
import {
    ServiceContainerProvider
} from '@almacareer/cyborg.container/container/infrastructure/react/client/ServiceContainerContext';
import container from '@local/container/clientContainer';

export default function ContainerProvider({ children }: PropsWithChildren) {
	return (
        <ServiceContainerProvider container={container}>
			{children}
		</ServiceContainerProvider>
	);
}

Usage

From application, server-side

// apps/container-experiment/src/../SomeComponent.tsx

import container from '@local/container/serverContainer';
import { ComponentType } from 'react';

export default function SomeComponent() {
	const ServerComponent = container.getService<ComponentType>('Demo/ServerComponent');
	const ClientComponent = container.getService<ComponentType>('Demo/ClientComponent');

	return (
		<>
			<div>
				<div>
					{ServerComponent ? <ServerComponent /> : null}
				</div>
				<div>
					{ClientComponent ? <ClientComponent /> : null}
				</div>
			</div>
		</>
	);
}

From library, server-side

// libs/search/src/ui/List.tsx

import React, { ComponentType } from 'react';
import container from '@almacareer/cyborg.container/container/infrastructure/react/server';
import Item from './Item';

function NullComponent() {
	return null;
}

export default function List() {
	const items = ['Programmer', 'Product Manager', 'Delivery Manager', 'CEO', 'UX designer'];

	const HotOffers = container.getService<ComponentType>('Search/HotOffers') ?? NullComponent;

	return (
		<div>
			<HotOffers />
			<div className="message is-info">
				<div className="message-body">
					This list comes from package <code>@almacareer/cyborg.search</code> and it is server component.
				</div>
			</div>
			{items.map((item) => {
				return <Item key={`item-${item}`} title={item} />;
			})}
		</div>
	);
}

From application, client-side

// apps/container-experiment/src/../SomeComponent.tsx

'use client';

import { ComponentType } from 'react';
import { 
  useService
} from '@almacareer/cyborg.container/container/infrastructure/react/client/ServiceContainerContext';


export default function ClientPage() {
	const ClientComponent = useService<ComponentType>('Demo/ClientComponent');

	return (
		<>
			<div>
				{ClientComponent ? <ClientComponent /> : null}
			</div>
		</>
	);
}

From library, client-side

// libs/search/src/ui/HotOffers.tsx

'use client';

import React from 'react';
import Item from './Item';
import { 
    useService
} from '@almacareer/cyborg.container/container/infrastructure/react/client/ServiceContainerContext';

export default function HotOffers() {
	const items = ['Hot offer 1', 'Hot offer 2'];
	const ClientComponent = useService<ComponentType>('Demo/ClientComponent') ?? NullComponent;

	return (
		<div>
			<div className="message is-info">
				<div className="message-body">
					This Hot Offers list comes from package <code>@almacareer/cyborg.search</code>
					and it is client component
				</div>
			</div>
			{items.map((item) => {
				return <Item key={`item-${item}`} title={item} bgVariant="danger" />;
			})}
            <ClientComponent />
		</div>
	);
}
From Import Usage
application, server @local/serverContainer container.getService
library, server @container/server container.getService
application, server @container/Context useService
library, client @container/Context useService

Summary

Implications

  • programmers must know their server/client context
  • server-only services must be tagged in configuration
  • configuration is explicit
    • in order to override a component, we need to  change the configuration (json files)
    • while it is easy to make a typo, it is hard to accidentally override something we are not aware of
  • generated container can tell programmers, what component are being used

TODOs:

  • distinct between services, components and parameters in a registry (custom methods)
  • always use "default" services folder and domain-specific folders will provide only overrides
  • find a way to serve multiple domains on one running instance
    • generate a container for each one
    • add a switching layer
  • generate types from configuration

Questions?