feat(react): add runtime tagNameTransformer for microfrontends

Elliott Davies · Elliott Davies · commit 1ea8aa59e216 · 2025-08-19T09:53:17.000+01:00
- Add global tagNameTransformer with setTagNameTransformer API - Transform tag names at component creation time for zero build overhead - Support dynamic transformation based on environment/team configuration - Add comprehensive test coverage for runtime transformation logic - Update documentation with detailed usage examples and migration strategies - Maintain backward compatibility with existing components Enables multiple versions of Stencil components to coexist in MFE environments through runtime tag name transformation. Based on PR stenciljs#635 with improvements: - Better TypeScript types and documentation - Comprehensive test coverage - Clear transformer lifecycle management - Enhanced error handling and edge cases Resolves: stenciljs#420
diff --git a/packages/react/README.md b/packages/react/README.md
@@ -78,6 +78,120 @@ npm install typescript@5 --save-dev
 
 That's it! You can now import and use your Stencil components as React components in your React application or library.
 
+## Advanced Usage
+
+### Runtime Tag Name Transformation for Microfrontends
+
+The React output target supports **runtime tag name transformation** for microfrontend environments where multiple teams need to use different versions of the same components without conflicts.
+
+#### **Setup**
+
+Configure your Stencil build normally (no special configuration needed):
+
+```ts
+import { Config } from '@stencil/core';
+import { reactOutputTarget } from '@stencil/react-output-target';
+
+export const config: Config = {
+  outputTargets: [
+    reactOutputTarget({
+      outDir: '../my-react-library/src/components',
+    }),
+    { type: 'dist-custom-elements' },
+  ],
+};
+```
+
+#### **Usage in MFE Applications**
+
+Each microfrontend can configure tag name transformation at runtime:
+
+```tsx
+// In your MFE application entry point
+import { setTagNameTransformer } from '@my-design-system/react';
+
+// Team Alpha: Add team prefix
+setTagNameTransformer((tagName) => `alpha-${tagName}`);
+
+// Team Beta: Add team prefix  
+setTagNameTransformer((tagName) => `beta-${tagName}`);
+
+// Version-specific transformation
+setTagNameTransformer((tagName) => `${tagName}-v2`);
+
+// Environment-specific transformation
+setTagNameTransformer((tagName) => `${tagName}-${process.env.NODE_ENV}`);
+```
+
+#### **Component Usage (Same API for All Teams)**
+
+```tsx
+import { MyButton, MyTabs, MyTab } from '@my-design-system/react';
+
+function App() {
+  return (
+    <div>
+      <MyButton>Click me</MyButton>
+      <MyTabs>
+        <MyTab>Tab 1</MyTab>
+        <MyTab>Tab 2</MyTab>
+      </MyTabs>
+    </div>
+  );
+}
+
+// Renders different DOM based on transformer:
+// Team Alpha: <alpha-my-button>, <alpha-my-tabs>, <alpha-my-tab>
+// Team Beta:  <beta-my-button>, <beta-my-tabs>, <beta-my-tab>
+// Version 2:  <my-button-v2>, <my-tabs-v2>, <my-tab-v2>
+```
+
+#### **Advanced Transformation Logic**
+
+```tsx
+import { setTagNameTransformer, clearTagNameTransformer } from '@my-design-system/react';
+
+// Conditional transformation
+setTagNameTransformer((tagName) => {
+  if (tagName.startsWith('my-')) {
+    return `admiral-${tagName.substring(3)}-v2`;
+  }
+  return tagName;
+});
+
+// Clear transformation (useful for testing)
+clearTagNameTransformer();
+
+// Complex team-based logic
+const teamConfig = {
+  alpha: (tagName: string) => `alpha-${tagName}`,
+  beta: (tagName: string) => `beta-${tagName}`,
+  gamma: (tagName: string) => `${tagName}-v2`,
+};
+
+setTagNameTransformer(teamConfig[process.env.TEAM_NAME] || ((name) => name));
+```
+
+#### **Benefits**
+
+✅ **Single Build Pipeline**: Design system team maintains one build
+✅ **Runtime Flexibility**: Teams can change transformations without rebuilds  
+✅ **Simple Distribution**: One NPM package for all teams
+✅ **Zero Configuration**: No build-time setup required
+✅ **Dynamic Control**: Can change transformations based on environment/conditions
+
+#### **Migration Strategy**
+
+```tsx
+// Gradual migration approach
+if (process.env.ENABLE_NEW_COMPONENTS === 'true') {
+  setTagNameTransformer((tagName) => `${tagName}-v2`);
+}
+// Otherwise uses original tag names
+```
+
+> **Note:** Tag name transformation only affects the DOM tag names used by custom elements. React component names and import paths remain unchanged, ensuring a consistent developer experience across all teams.
+
 ## Output Target Options
 
 | Property                | Description                                                                                                                                                                                                                                                                    |
diff --git a/packages/react/src/runtime/create-component.test.ts b/packages/react/src/runtime/create-component.test.ts
@@ -1,9 +1,25 @@
 import React from 'react';
-import { vi, describe, it, expect } from 'vitest';
+import { vi, describe, it, expect, beforeEach } from 'vitest';
 
 import { createComponent } from './create-component';
+import { setTagNameTransformer, clearTagNameTransformer } from './tagNameTransformer';
+
+// Mock @lit/react
+vi.mock('@lit/react', () => ({
+  createComponent: vi.fn((options) => {
+    // Return a mock React component that we can inspect
+    const MockComponent = () => React.createElement('div', { 'data-tagname': options.tagName });
+    MockComponent.displayName = `MockComponent(${options.tagName})`;
+    return MockComponent;
+  }),
+}));
 
 describe('createComponent', () => {
+  beforeEach(() => {
+    clearTagNameTransformer();
+    vi.clearAllMocks();
+  });
+
   it('should call defineCustomElement if it is defined', () => {
     const defineCustomElement = vi.fn();
 
@@ -18,4 +34,93 @@ describe('createComponent', () => {
 
     expect(defineCustomElement).toHaveBeenCalled();
   });
+
+  it('should use original tag name when no transformer is set', () => {
+    const { createComponent: mockCreateComponent } = require('@lit/react');
+    
+    createComponent({
+      defineCustomElement: vi.fn(),
+      tagName: 'my-component',
+      elementClass: class Foo {} as any,
+      react: React,
+      events: {},
+      displayName: 'MyComponent',
+    });
+
+    expect(mockCreateComponent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tagName: 'my-component',
+      })
+    );
+  });
+
+  it('should transform tag name when transformer is set', () => {
+    const { createComponent: mockCreateComponent } = require('@lit/react');
+    
+    setTagNameTransformer((tagName) => `${tagName}-v2`);
+    
+    createComponent({
+      defineCustomElement: vi.fn(),
+      tagName: 'my-component',
+      elementClass: class Foo {} as any,
+      react: React,
+      events: {},
+      displayName: 'MyComponent',
+    });
+
+    expect(mockCreateComponent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tagName: 'my-component-v2',
+      })
+    );
+  });
+
+  it('should apply team prefix transformation', () => {
+    const { createComponent: mockCreateComponent } = require('@lit/react');
+    
+    setTagNameTransformer((tagName) => `alpha-${tagName}`);
+    
+    createComponent({
+      defineCustomElement: vi.fn(),
+      tagName: 'my-button',
+      elementClass: class Foo {} as any,
+      react: React,
+      events: {},
+      displayName: 'MyButton',
+    });
+
+    expect(mockCreateComponent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tagName: 'alpha-my-button',
+      })
+    );
+  });
+
+  it('should preserve all other options while transforming tag name', () => {
+    const { createComponent: mockCreateComponent } = require('@lit/react');
+    const defineCustomElement = vi.fn();
+    const elementClass = class TestElement {} as any;
+    const events = { onClick: 'click' };
+    
+    setTagNameTransformer((tagName) => `${tagName}-transformed`);
+    
+    createComponent({
+      defineCustomElement,
+      tagName: 'my-component',
+      elementClass,
+      react: React,
+      events,
+      displayName: 'MyComponent',
+    });
+
+    expect(mockCreateComponent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tagName: 'my-component-transformed',
+        elementClass,
+        react: React,
+        events,
+        displayName: 'MyComponent',
+      })
+    );
+  });
 });
diff --git a/packages/react/src/runtime/create-component.ts b/packages/react/src/runtime/create-component.ts
@@ -1,6 +1,8 @@
 import type { EventName, Options } from '@lit/react';
 import { createComponent as createComponentWrapper } from '@lit/react';
 
+import { transformTagName } from './tagNameTransformer.js';
+
 // A key value map matching React prop names to event names.
 type EventNames = Record<string, EventName | string>;
 
@@ -25,5 +27,12 @@ export const createComponent = <I extends HTMLElement, E extends EventNames = {}
   if (typeof defineCustomElement !== 'undefined') {
     defineCustomElement();
   }
-  return createComponentWrapper<I, E>(options) as unknown as StencilReactComponent<I, E>;
+
+  // Apply tag name transformation if a transformer is set
+  const transformedOptions = {
+    ...options,
+    tagName: transformTagName(options.tagName),
+  };
+
+  return createComponentWrapper<I, E>(transformedOptions) as unknown as StencilReactComponent<I, E>;
 };
diff --git a/packages/react/src/runtime/index.ts b/packages/react/src/runtime/index.ts
@@ -1,2 +1,7 @@
 export type { EventName, Options } from '@lit/react';
 export { createComponent, type StencilReactComponent } from './create-component.js';
+export { 
+  setTagNameTransformer, 
+  clearTagNameTransformer, 
+  type TagNameTransformer 
+} from './tagNameTransformer.js';
diff --git a/packages/react/src/runtime/tagNameTransformer.test.ts b/packages/react/src/runtime/tagNameTransformer.test.ts
@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { 
+  setTagNameTransformer, 
+  clearTagNameTransformer, 
+  getTagNameTransformer,
+  transformTagName,
+  type TagNameTransformer 
+} from './tagNameTransformer.js';
+
+describe('tagNameTransformer', () => {
+  beforeEach(() => {
+    // Clear transformer before each test
+    clearTagNameTransformer();
+  });
+
+  describe('setTagNameTransformer', () => {
+    it('should set a global tag name transformer', () => {
+      const transformer: TagNameTransformer = (tagName) => `${tagName}-v2`;
+      
+      setTagNameTransformer(transformer);
+      
+      expect(getTagNameTransformer()).toBe(transformer);
+    });
+
+    it('should replace previous transformer when called multiple times', () => {
+      const transformer1: TagNameTransformer = (tagName) => `${tagName}-v1`;
+      const transformer2: TagNameTransformer = (tagName) => `${tagName}-v2`;
+      
+      setTagNameTransformer(transformer1);
+      setTagNameTransformer(transformer2);
+      
+      expect(getTagNameTransformer()).toBe(transformer2);
+    });
+  });
+
+  describe('clearTagNameTransformer', () => {
+    it('should clear the current transformer', () => {
+      const transformer: TagNameTransformer = (tagName) => `${tagName}-v2`;
+      
+      setTagNameTransformer(transformer);
+      clearTagNameTransformer();
+      
+      expect(getTagNameTransformer()).toBeUndefined();
+    });
+  });
+
+  describe('transformTagName', () => {
+    it('should return original tag name when no transformer is set', () => {
+      const tagName = 'my-component';
+      
+      const result = transformTagName(tagName);
+      
+      expect(result).toBe('my-component');
+    });
+
+    it('should apply transformation when transformer is set', () => {
+      const transformer: TagNameTransformer = (tagName) => `${tagName}-v2`;
+      setTagNameTransformer(transformer);
+      
+      const result = transformTagName('my-component');
+      
+      expect(result).toBe('my-component-v2');
+    });
+
+    it('should apply version suffix transformation', () => {
+      setTagNameTransformer((tagName) => `${tagName}-v2`);
+      
+      expect(transformTagName('my-button')).toBe('my-button-v2');
+      expect(transformTagName('my-tabs')).toBe('my-tabs-v2');
+      expect(transformTagName('my-input')).toBe('my-input-v2');
+    });
+
+    it('should apply team prefix transformation', () => {
+      setTagNameTransformer((tagName) => `alpha-${tagName}`);
+      
+      expect(transformTagName('my-button')).toBe('alpha-my-button');
+      expect(transformTagName('my-tabs')).toBe('alpha-my-tabs');
+      expect(transformTagName('my-input')).toBe('alpha-my-input');
+    });
+
+    it('should apply complex transformation logic', () => {
+      setTagNameTransformer((tagName) => {
+        if (tagName.startsWith('my-')) {
+          return `admiral-${tagName.substring(3)}-v2`;
+        }
+        return tagName;
+      });
+      
+      expect(transformTagName('my-button')).toBe('admiral-button-v2');
+      expect(transformTagName('my-tabs')).toBe('admiral-tabs-v2');
+      expect(transformTagName('other-component')).toBe('other-component');
+    });
+
+    it('should handle environment-specific transformations', () => {
+      const originalEnv = process.env.NODE_ENV;
+      
+      try {
+        process.env.NODE_ENV = 'development';
+        setTagNameTransformer((tagName) => `${tagName}-${process.env.NODE_ENV}`);
+        
+        expect(transformTagName('my-button')).toBe('my-button-development');
+        
+        process.env.NODE_ENV = 'production';
+        expect(transformTagName('my-button')).toBe('my-button-production');
+      } finally {
+        process.env.NODE_ENV = originalEnv;
+      }
+    });
+
+    it('should handle empty and special tag names', () => {
+      setTagNameTransformer((tagName) => `prefix-${tagName}`);
+      
+      expect(transformTagName('')).toBe('prefix-');
+      expect(transformTagName('a')).toBe('prefix-a');
+      expect(transformTagName('component-with-many-dashes')).toBe('prefix-component-with-many-dashes');
+    });
+  });
+});
