Skip to content

Commit 8111fbb

Browse files
WonSongWonSong
authored
v1.0.17 - dependency updates & AuthClient patch for msal-browser v5+ (#45)
1 parent 8a9f119 commit 8111fbb

160 files changed

Lines changed: 6190 additions & 23191 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/copilot-instructions.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Copilot Instructions — micro-frontend-react
2+
3+
## Project Overview
4+
Monorepo for the `@micro-frontend-react` npm packages enabling micro-frontend architecture on React applications. Host apps load micro-frontends at runtime via script injection and a global `window.__MICRO_FRONTENDS__` registry.
5+
6+
## Repository Structure
7+
```
8+
packages/micro-frontend-react/ → @micro-frontend-react/core (ComponentProvider, WebpackConfigs, Context)
9+
packages/micro-frontend-react-redux/ → @micro-frontend-react/redux (StoreBuilder, ReducerRegistry)
10+
packages/microsoft-employee-experience/ → @micro-frontend-react/employee-experience (AuthClient, Shell, telemetry, routing)
11+
samples/sample-react-host/ → Sample host app (core only)
12+
samples/sample-react-micro-frontend/ → Sample micro-frontend (core only)
13+
samples/sample-react-redux-host/ → Sample host app (with Redux)
14+
samples/sample-react-redux-micro-frontend/ → Sample micro-frontend (with Redux)
15+
samples/sample-employee-experience/ → EE sample app (standalone, internal registry)
16+
```
17+
18+
## Build System
19+
- **npm workspaces** for dependency management (`packages/*` and `samples/sample-react-*`; no lerna, no yarn)
20+
- **lage** for task orchestration (`npm run build` runs `lage build --no-cache`)
21+
- **TypeScript** compiled via `tsc` (not webpack) for library packages
22+
- **webpack 5** for sample apps and the generator example
23+
- Build order enforced by lage pipeline: core → redux → employee-experience
24+
25+
## Key Commands
26+
```
27+
npm install # Install all workspace dependencies
28+
npm run build # Build all library packages (lage)
29+
npm run serve # Serve sample-react-host + sample-react-micro-frontend
30+
npm run serve:redux # Serve sample-react-redux-host + sample-react-redux-micro-frontend
31+
npm run install:ee # Install generator example deps (uses internal .npmrc) + link local packages
32+
npm run serve:ee # Serve the EE generator example
33+
npm run clean # Clean all build artifacts
34+
npm run nuke # Full reset: delete node_modules + reinstall + clean
35+
npm version patch --workspaces --no-git-tag-version # Bump all package versions
36+
```
37+
38+
## Architecture Constraints
39+
40+
### UMD Externals Pattern
41+
React, react-router-dom, and styled-components are loaded as **UMD bundles from CDN** (`ee.azureedge.net`) and declared as webpack externals. This is fundamental to the micro-frontend architecture — host and micro-frontends share a single React instance via globals (`window.React`, `window.ReactDOM`, `window.ReactRouterDOM`, `window.styled`).
42+
43+
**Do not upgrade these beyond their UMD-available versions:**
44+
- `react` / `react-dom` / `react-is`: **18.3.1** (last version with official UMD builds; React 19 dropped UMD)
45+
- `react-router-dom`: **5.3.4** (v6+ dropped UMD; v5 API: `Switch`, `exact`, `render` prop, `withRouter`)
46+
- `styled-components`: **5.3.11** (v6 dropped UMD)
47+
48+
### Peer Dependencies
49+
Library packages declare peer deps with `>=` lower bounds (no upper bounds). When modifying peer deps, ensure the range covers what consumers actually use.
50+
51+
### Employee Experience Sample (EE)
52+
The `samples/sample-employee-experience/` project is **not** in npm workspaces because it depends on internal Microsoft packages (`@coherence-design-system`, `@m365-admin`) from private registries configured in its `.npmrc`. It links to the local `employee-experience` build via `npm link` (handled by `npm run install:ee`).
53+
54+
## TypeScript Configuration
55+
- Library packages use `moduleResolution: "bundler"` (required for `@redux-devtools/extension` v4)
56+
- No `typeRoots` — TypeScript's default resolution handles hoisted `@types` correctly in workspaces and for published consumers
57+
- `skipLibCheck: true` is set on all packages
58+
- `strict: true` on all packages
59+
60+
## Code Patterns
61+
62+
### ComponentProvider
63+
Core mechanism for loading micro-frontends. Injects a `<script>` tag, waits for the UMD bundle to register on `window.__MICRO_FRONTENDS__[fileName][componentName]`, then renders the component. Do not change the loading mechanism without a major version bump.
64+
65+
### AuthClient (employee-experience)
66+
Uses `@azure/msal-browser` v5. The `PublicClientApplication` must be initialized async (`await instance.initialize()`) before calling any API methods including `handleRedirectPromise()`.
67+
68+
### StoreBuilder (redux)
69+
Uses `redux-persist` with a `PersistConfig<T>` generic. The dynamic reducer persist config requires an `as any` cast due to type incompatibility between the generic and `combineReducers` return type.
70+
71+
## Version Constraints
72+
73+
### Pinned Dependencies (UMD requirement)
74+
The micro-frontend architecture loads shared dependencies as UMD bundles from CDN (`ee.azureedge.net`). These packages are pinned to their last UMD-available versions:
75+
76+
| Package | Max Version | Why |
77+
|---------|------------|-----|
78+
| `react` / `react-dom` / `react-is` | 18.3.1 | React 19 removed official UMD builds |
79+
| `react-router-dom` | 5.3.4 | v6+ removed UMD; uses v5 API (`Switch`, `exact`, `render` prop, `withRouter`) |
80+
| `styled-components` | 5.3.11 | v6 removed UMD builds |
81+
82+
React 18 active support ended Dec 2024 (security-only). react-router-dom v5 and styled-components v5 are no longer actively maintained. Do not upgrade these without migrating away from the UMD external pattern.
83+
84+
### Planned v2.0 — Module Federation
85+
v2.0 will replace UMD script injection with **webpack Module Federation**:
86+
- Unblocks React 19+, react-router-dom v7+, styled-components v6+
87+
- Shares deps via webpack container API (`singleton: true`) instead of CDN globals
88+
- Supports dynamic remotes (micro-frontend URLs from backend APIs at runtime)
89+
- Replaces `window.__MICRO_FRONTENDS__` with federated module imports
90+
- `ComponentProvider` loading mechanism will be rewritten
91+
- `IComponentConfig` will change from `{ script, name }` to a federated remote format
92+
- **Breaking change** for all consumers
93+
94+
## When Making Changes
95+
1. Always run `npm run build` after changes — lage handles build ordering
96+
2. After modifying package versions, update all internal cross-references (grep for `@micro-frontend-react/` in package.json files)
97+
3. Test samples with `npm run serve` and `npm run serve:redux` to verify runtime behavior
98+
4. The webpack `generateDevServerSettings` uses `server: 'https' | 'http'` (webpack-dev-server v5 API), not the deprecated `https: boolean`
99+
5. Do not add `react-router-dom` v6/v7 APIs (`Routes`, `element` prop, `useNavigate`) — the project uses v5 APIs throughout

‎README.md‎

Lines changed: 110 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,113 @@
1-
# Micro-Frontend!
2-
3-
This is an open source library that shares a set of utilities that can be used to support Micro-Frontend architecture in your React.js applications.
4-
5-
While the proper documentation is being prepared, please see the following samples:
6-
7-
## React.js
8-
9-
* [Host application](https://github.com/microsoft/microfrontend/blob/main/samples/sample-react-host/src/App.tsx)
10-
* The host application provides shared "Context"
11-
* The host application loads Micro-Frontend applications using or `ComponentProvider` with runtime configuration
12-
``` tsx
13-
// Load a micro-frontend anywhere on the screen
14-
<ComponentProvider
15-
config={{
16-
script: 'http://localhost:8000/bundles/micro-frontend-app.js',
17-
name: 'MicroFrontendApp',
18-
}}
19-
/>
20-
```
21-
* [Micro-Frontend application](https://github.com/microsoft/microfrontend/blob/main/samples/sample-react-micro-frontend/src/MicroFrontendApp.tsx)
22-
* Micro-Frontends are components that are developed and deployed in isolation
23-
* Micro-Frontends will receive receive the "Context" when mounted
24-
25-
## React.js with Redux
26-
* [Host application with Redux](https://github.com/microsoft/micro-frontend/blob/main/samples/sample-react-redux-host/src/App.tsx)
27-
* Setup host application with various redux extensions such as redux-sagas, redux-logger, redux-persist
28-
* Host's "Context" now includes utilities for Redux operations
29-
* [Micro-Frontend application with Redux](https://github.com/microsoft/micro-frontend/blob/main/samples/sample-react-redux-micro-frontend/src/MicroFrontendApp.tsx)
30-
* Retrieve data from host application's Redux store
31-
* Register new reducer and saga to the host application's Redux store
1+
# Micro-Frontend React
2+
3+
An open source library providing utilities to support micro-frontend architecture in React.js applications.
4+
5+
## Packages
6+
7+
| Package | Description |
8+
|---------|-------------|
9+
| `@micro-frontend-react/core` | ComponentProvider, WebpackConfigs, Context |
10+
| `@micro-frontend-react/redux` | StoreBuilder, ReducerRegistry, Redux integration |
11+
| `@micro-frontend-react/employee-experience` | AuthClient, Shell, telemetry, routing (Microsoft EE extension) |
12+
13+
## Prerequisites
14+
15+
- Node.js 18+
16+
- npm 9+
17+
18+
## Getting Started
19+
20+
```bash
21+
# Install dependencies (uses npm workspaces)
22+
npm install
23+
24+
# Build all packages
25+
npm run build
26+
27+
# Serve the basic sample (host on :9000, micro-frontend on :8000)
28+
npm run serve
29+
30+
# Serve the Redux sample
31+
npm run serve:redux
32+
```
33+
34+
### Employee Experience Sample
35+
36+
The EE sample uses internal Microsoft package registries. It is not part of npm workspaces.
37+
38+
```bash
39+
# Install dependencies (uses .npmrc for internal registries) and link local packages
40+
npm run install:ee
41+
42+
# Serve the EE example
43+
npm run serve:ee
44+
```
45+
46+
## How It Works
47+
48+
Host applications load micro-frontends at runtime using `ComponentProvider`:
49+
50+
```tsx
51+
<ComponentProvider
52+
config={{
53+
script: 'http://localhost:8000/bundles/micro-frontend-app.js',
54+
name: 'MicroFrontendApp',
55+
}}
56+
/>
57+
```
58+
59+
Micro-frontends are webpack UMD bundles that register on `window.__MICRO_FRONTENDS__`. Shared dependencies (React, react-router-dom, styled-components) are loaded once from CDN as webpack externals, ensuring a single instance across all micro-frontends.
60+
61+
## Samples
62+
63+
### React.js
64+
* [Host application](samples/sample-react-host/src/App.tsx) — provides shared Context and loads micro-frontends via `ComponentProvider`
65+
* [Micro-Frontend application](samples/sample-react-micro-frontend/src/MicroFrontendApp.tsx) — developed and deployed in isolation, receives Context when mounted
66+
67+
### React.js with Redux
68+
* [Host application with Redux](samples/sample-react-redux-host/src/App.tsx) — host with redux-sagas, redux-logger, redux-persist
69+
* [Micro-Frontend with Redux](samples/sample-react-redux-micro-frontend/src/MicroFrontendApp.tsx) — reads from host Redux store, registers reducers and sagas dynamically
70+
71+
## Version Constraints & Roadmap
72+
73+
### Current Limitations (v1.x)
74+
75+
The micro-frontend architecture relies on UMD bundles loaded from CDN as webpack externals. This constrains several dependencies to their last UMD-available versions:
76+
77+
| Package | Pinned Version | Reason |
78+
|---------|---------------|--------|
79+
| `react` / `react-dom` / `react-is` | 18.3.1 | React 19 removed official UMD builds |
80+
| `react-router-dom` | 5.3.4 | v6+ removed UMD builds; v5 API (`Switch`, `exact`, `render` prop, `withRouter`) |
81+
| `styled-components` | 5.3.11 | v6 removed UMD builds |
82+
83+
React 18 is in security-only support (active support ended Dec 2024). react-router-dom v5 and styled-components v5 are no longer actively maintained.
84+
85+
These libraries cannot be upgraded without replacing the UMD/CDN external loading pattern.
86+
87+
### Planned v2.0 — Module Federation
88+
89+
v2.0 will migrate from UMD script injection to **webpack Module Federation**, which:
90+
- Removes the UMD/CDN dependency, unblocking React 19+, react-router-dom v7+, styled-components v6+
91+
- Shares dependencies at runtime via webpack's container API (`singleton: true`) instead of global variables
92+
- Supports dynamic remotes — micro-frontend URLs resolved at runtime from backend APIs (no build-time configuration required)
93+
- Replaces `window.__MICRO_FRONTENDS__` global registry with federated module imports
94+
- Requires a rewrite of `ComponentProvider`'s script loading mechanism
95+
96+
**v2.0 is a breaking change** for consumers. The `IComponentConfig` interface will change from `{ script, name }` to a federated remote format, and consumers will need to add `ModuleFederationPlugin` to their webpack configs with shared dependency declarations.
97+
98+
## Scripts
99+
100+
| Command | Description |
101+
|---------|-------------|
102+
| `npm install` | Install all workspace dependencies |
103+
| `npm run build` | Build all library packages via lage |
104+
| `npm run serve` | Serve basic sample apps |
105+
| `npm run serve:redux` | Serve Redux sample apps |
106+
| `npm run install:ee` | Install EE generator example + link local packages |
107+
| `npm run serve:ee` | Serve EE generator example |
108+
| `npm run clean` | Clean build artifacts |
109+
| `npm run nuke` | Full reset (delete node_modules, reinstall, clean) |
110+
| `npm version patch --workspaces --no-git-tag-version` | Bump all package versions |
32111

33112
## Contributing
34113

‎generators/microsoft-employee-experience-generator/.gitattributes‎

Lines changed: 0 additions & 63 deletions
This file was deleted.

0 commit comments

Comments
 (0)