SKILL.md

React Micro-Frontend Patterns

The Pattern

Problem: You have multiple independently-built UI bundles that must share React at runtime, a form system driven by server-side schemas that change dynamically, and state that needs to persist in the browser and sync across tabs.

Approach: Import maps with Vite's rollupOptions.external for shared React, a useFrecency hook with exponential decay scoring, schema-to-React rendering with action-triggered schema refinement, and Zustand stores with localStorage sync.

Pattern proven in production across multiple React frontends and web services.

Key Design Decisions

1. Import map + `rollupOptions.external` for shared React

When multiple independently-built bundles run on the same page, each gets its own copy of React. This causes the "dual React instance" bug: hooks break because the React instance that rendered the component is different from the one providing useState.

The fix: externalize React in every bundle's Vite config and provide it via an import map in the HTML:

<!-- index.html -->
<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/[email protected]",
    "react-dom": "https://esm.sh/[email protected]",
    "react-dom/client": "https://esm.sh/[email protected]/client",
    "react/jsx-runtime": "https://esm.sh/[email protected]/jsx-runtime"
  }
}
</script>

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      external: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime'],
    },
  },
})

2. The Vite dev-mode problem

Vite's dev server ignores browser import maps — it pre-bundles CJS modules and serves them from /.vite/deps/. This means dynamically-loaded bundles that use bare import React from 'react' will resolve via the import map to a different React instance than the host app.

Solutions: Use @vitejs/plugin-react with careful configuration, or write a custom Vite plugin that serves shim modules redirecting bare specifiers to Vite's pre-bundled paths during dev. This is inherently complex — consult your Vite config documentation for the specifics of your setup.

// hooks/useFrecency.ts const DECAY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000 // 1-week half-life const STORAGE_KEY = 'frecency-data' const _suggestionCache = new Map<string, string[]>() // module-level perf cache interface FrecencyEntry { score: number lastUsed: number // timestamp ms } function computeScore(entry: FrecencyEntry, now: number): number { const ageFraction = (now - entry.lastUsed) / DECAY_HALF_LIFE_MS return entry.score * Math.pow(0.5, ageFraction) } function useFrecency(namespace: string) { const [entries, setEntries] = useState<Record<string, FrecencyEntry>>(() => { const stored = localStorage.getItem(`${STORAGE_KEY}:${namespace}`) return stored ? JSON.parse(stored) : {} }) const getSuggestions = useCallback((fieldKey: string, allValues: string[]) => { const cacheKey = `${namespace}:${fieldKey}` if (_suggestionCache.has(cacheKey)) return _suggestionCache.get(cacheKey)! const now = Date.now() const sorted = [...allValues].sort((a, b) => { const sa = entries[a] ? computeScore(entries[a], now) : 0 const sb = entries[b] ? computeScore(entries[b], now) : 0 return sb - sa }) _suggestionCache.set(cacheKey, sorted) return sorted }, [namespace, entries]) const recordValue = useCallback((fieldKey: string, value: string) => { _suggestionCache.clear() setEntries(prev => { const now = Date.now() const existing = prev[value] ?? { score: 0, lastUsed: now } const updated = { ...prev, [value]: { score: existing.score + 1, lastUsed: now } } localStorage.setItem(`${STORAGE_KEY}:${namespace}`, JSON.stringify(updated)) return updated }) }, [namespace]) const recordAll = useCallback((formData: Record<string, string>) => { _suggestionCache.clear() setEntries(prev => { const now = Date.now() const updated = { ...prev } for (const value of Object.values(formData)) { if (value) { const existing = updated[value] ?? { score: 0, lastUsed: now } updated[value] = { score: existing.score + 1, lastUsed: now } } } localStorage.setItem(`${STORAGE_KEY}:${namespace}`, JSON.stringify(updated)) return updated }) }, [namespace]) return { getSuggestions, recordValue, recordAll } }

react-microfrontend-patterns

Summary

SKILL.md

React Micro-Frontend Patterns

The Pattern

Key Design Decisions

1. Import map + `rollupOptions.external` for shared React

2. The Vite dev-mode problem

3. useFrecency hook: group-by-suffix, exponential decay scoring

4. Zustand store with localStorage sync and Map-based collections

Template / Starter Code

Gotchas & Lessons Learned

Related skills

react-microfrontend-patterns

Summary

React Micro-Frontend Patterns

The Pattern

Key Design Decisions

1. Import map + rollupOptions.external for shared React

2. The Vite dev-mode problem

3. useFrecency hook: group-by-suffix, exponential decay scoring

4. Zustand store with localStorage sync and Map-based collections

Template / Starter Code

Gotchas & Lessons Learned

Related skills

1. Import map + `rollupOptions.external` for shared React