Skip to content

Commit 48cd5e0

Browse files
konstantin-msftkonstantin-msft
authored
Migrate msal-react samples from CRA to Vite (#8423)
Migrate msal-react samples from CRA to Vite. Update migration guides.
1 parent a07373d commit 48cd5e0

File tree

31 files changed

+1856
-8360
lines changed

31 files changed

+1856
-8360
lines changed

‎lib/msal-browser/docs/redirect-bridge.md‎

Lines changed: 2 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,8 @@ export default defineConfig({
114114

115115
During development (`vite dev`), the redirect page is automatically served at `/redirect.html`. In production builds, Rollup will emit both `index.html` and `redirect.html` in the output directory.
116116

117+
> **Sample:** See the [react-router-sample](../../../samples/msal-react-samples/react-router-sample), [typescript-sample](../../../samples/msal-react-samples/typescript-sample), and [b2c-sample](../../../samples/msal-react-samples/b2c-sample).
118+
117119
## Webpack
118120

119121
Webpack requires a dedicated entry point and an `HtmlWebpackPlugin` instance for the redirect page.
@@ -253,117 +255,6 @@ No `next.config.js` changes are needed for either router — Next.js serves page
253255

254256
> **Sample:** See the [nextjs-sample](../../../samples/msal-react-samples/nextjs-sample) for a Pages Router example.
255257
256-
## Create React App (CRA)
257-
258-
The recommended approach for CRA is to use a **dedicated static HTML file** placed in the `public/` folder. CRA copies everything in `public/` to the build output as-is, so `public/redirect.html` is served at `/redirect.html` with no React bundle attached — exactly what the redirect bridge requires.
259-
260-
### Recommended: dedicated `public/redirect.html`
261-
262-
1. **Create `public/redirect.html`**:
263-
264-
```html
265-
<!DOCTYPE html>
266-
<html>
267-
<head>
268-
<meta charset="UTF-8">
269-
<title>Redirect</title>
270-
</head>
271-
<body>
272-
<p>Processing authentication...</p>
273-
<!--
274-
Ensure that msal-redirect-bridge.min.js (the UMD bundle) is hosted at this path,
275-
for example by copying it from the @azure/msal-browser package into your public/ folder.
276-
-->
277-
<script src="/msal-redirect-bridge.min.js"></script>
278-
<script>
279-
msalRedirectBridge.broadcastResponseToMainFrame().catch(function (error) {
280-
console.error("Error broadcasting response:", error);
281-
});
282-
</script>
283-
</body>
284-
</html>
285-
```
286-
287-
2. **Set `redirectUri`** in your MSAL configuration to point to this file:
288-
289-
```javascript
290-
const msalConfig = {
291-
auth: {
292-
clientId: "YOUR_CLIENT_ID",
293-
redirectUri: window.location.origin + "/redirect.html",
294-
},
295-
};
296-
```
297-
298-
This page is served as plain HTML — it does **not** load your React application bundle, React Router, or `MsalProvider`. No changes to `App.js` or routing are required.
299-
300-
> **Important:** The `public/redirect.html` example above uses the UMD bundle (`msal-redirect-bridge.min.js`) and the global `msalRedirectBridge` object. This makes the page usable in a wide range of browsers, including those that do not support native ES modules. If you prefer to use an ES module instead, you can replace the UMD `<script>` tag with a `<script type="module">` block that imports `broadcastResponseToMainFrame` from `@azure/msal-browser/redirect-bridge`, or you can use the SPA route approach described below.
301-
302-
### Alternative: SPA route (React Router)
303-
304-
> **Caveat:** This approach mounts the redirect URI inside the React Router SPA, so the **full application bundle** — including React, React Router, and all your app code — is downloaded and executed on the redirect page. For most apps the extra overhead is negligible, but it can slow down the authentication round-trip. If you use hash-based routing (`HashRouter`) you will also need to ensure the redirect URI hash is not consumed by the router before `broadcastResponseToMainFrame` runs.
305-
306-
If you prefer to keep everything inside the SPA, follow these steps to create a dedicated route that runs the bridge script and place it **outside** `MsalProvider`:
307-
308-
1. **Create `src/pages/Redirect.jsx`**:
309-
310-
```jsx
311-
import { useEffect } from "react";
312-
import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";
313-
314-
export function Redirect() {
315-
useEffect(() => {
316-
broadcastResponseToMainFrame().catch((error) => {
317-
console.error("Error broadcasting response to main frame:", error);
318-
});
319-
}, []);
320-
321-
return <p>Processing authentication...</p>;
322-
}
323-
```
324-
325-
2. **Create a layout component** that wraps child routes in `MsalProvider` (`src/components/MsalProviderLayout.jsx`):
326-
327-
```jsx
328-
import { Outlet } from "react-router-dom";
329-
import { MsalProvider } from "@azure/msal-react";
330-
331-
export function MsalProviderLayout({ instance }) {
332-
return (
333-
<MsalProvider instance={instance}>
334-
<Outlet />
335-
</MsalProvider>
336-
);
337-
}
338-
```
339-
340-
3. **Add the redirect route outside the layout** in your `App.js`:
341-
342-
```jsx
343-
import { Routes, Route } from "react-router-dom";
344-
import { MsalProviderLayout } from "./components/MsalProviderLayout";
345-
import { Redirect } from "./pages/Redirect";
346-
import { Home } from "./pages/Home";
347-
import { Profile } from "./pages/Profile";
348-
349-
function App({ msalInstance }) {
350-
return (
351-
<Routes>
352-
{/* Redirect route is NOT wrapped in MsalProvider */}
353-
<Route path="/redirect" element={<Redirect />} />
354-
355-
{/* All other routes share MsalProvider via the layout */}
356-
<Route element={<MsalProviderLayout instance={msalInstance} />}>
357-
<Route path="/" element={<Home />} />
358-
<Route path="/profile" element={<Profile />} />
359-
</Route>
360-
</Routes>
361-
);
362-
}
363-
```
364-
365-
> **Sample:** See the [react-router-sample](../../../samples/msal-react-samples/react-router-sample) and [typescript-sample](../../../samples/msal-react-samples/typescript-sample).
366-
367258
## Express.js / Node.js Backend
368259

369260
When using Express.js (or any Node.js backend serving static files), configure the server to serve the redirect page **without** COOP headers:

‎lib/msal-react/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ The `@azure/msal-react` package described by the code in this folder uses the [`
4040

4141
| MSAL React version | MSAL support status | Supported React versions |
4242
| --------------------- | ------------------- | ------------------------ |
43-
| MSAL React v5 (alpha) | Active development | 19 |
44-
| MSAL React v3 | Active development | 16, 17, 18, 19 |
43+
| MSAL React v5 | Active development | 19 |
44+
| MSAL React v3 | In maintenance | 16, 17, 18, 19 |
4545
| MSAL React v1, v2 | In maintenance | 16, 17, 18 |
4646

4747
**Note:** There have been no functional changes in the MSAL React v2 release.

‎lib/msal-react/docs/migration-guide-v4-v5.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ MSAL React v5 supports React 19.2.1 or greater. It no longer supports React 16,
2020

2121
## React 18 compatibility note
2222

23+
React 18 has reached end of life, which is why MSAL React v5 dropped support for it.
24+
2325
If your app is still on React 18, installing `@azure/msal-react@^5` may fail due to peer dependency constraints.
2426

2527
- Temporary install workaround: `npm install --legacy-peer-deps`
@@ -28,6 +30,72 @@ If your app is still on React 18, installing `@azure/msal-react@^5` may fail due
2830

2931
For production workloads, upgrade React to 19.2.1 or greater before moving to `@azure/msal-react@^5`.
3032

33+
## Migrating from Create React App (react-scripts)
34+
35+
Create React App is deprecated and `react-scripts` does not support React 19. If your app uses `react-scripts`, you **must** migrate to a different build tool before upgrading to `@azure/msal-react@^5`.
36+
37+
**Recommended: Migrate to [Vite](https://vite.dev/)**
38+
39+
1. Remove `react-scripts` and install Vite + the React plugin:
40+
```bash
41+
npm uninstall react-scripts
42+
npm install --save-dev vite @vitejs/plugin-react
43+
```
44+
45+
2. Add `"type": "module"` to `package.json`.
46+
47+
3. Move `public/index.html` to the project root as `index.html`, replace `%PUBLIC_URL%/` references with `/`, and add the entry point script tag:
48+
```html
49+
<!-- Before (CRA): no script tag needed, CRA injects it -->
50+
<!-- After (Vite): add before </body> -->
51+
<script type="module" src="/src/index.jsx"></script>
52+
```
53+
54+
4. Create a `vite.config.js` at project root:
55+
```js
56+
import { defineConfig } from "vite";
57+
import react from "@vitejs/plugin-react";
58+
import { resolve } from "path";
59+
60+
export default defineConfig({
61+
plugins: [react()],
62+
server: {
63+
port: 3000,
64+
},
65+
build: {
66+
rollupOptions: {
67+
input: {
68+
main: resolve(__dirname, "index.html"),
69+
redirect: resolve(__dirname, "public/redirect.html"),
70+
},
71+
},
72+
},
73+
});
74+
```
75+
76+
5. Update `package.json` scripts:
77+
```json
78+
"scripts": {
79+
"start": "vite",
80+
"build": "vite build",
81+
"preview": "vite preview"
82+
}
83+
```
84+
85+
6. Replace `process.env.REACT_APP_*` references with `import.meta.env.VITE_*` and rename environment variables accordingly (e.g. `REACT_APP_CLIENT_ID` → `VITE_CLIENT_ID`).
86+
87+
7. Remove CRA-specific environment variables (`SKIP_PREFLIGHT_CHECK`, `DISABLE_ESLINT_PLUGIN`) from `.env` files.
88+
89+
8. Upgrade React and install MSAL:
90+
```bash
91+
npm install react@^19.2.1 react-dom@^19.2.1
92+
npm install @azure/msal-browser@^5 @azure/msal-react@^5
93+
```
94+
95+
9. Set up the [redirect bridge](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/redirect-bridge.md#vite) for your Vite app.
96+
97+
> **Samples:** See the [react-router-sample](../../../samples/msal-react-samples/react-router-sample), [typescript-sample](../../../samples/msal-react-samples/typescript-sample), and [b2c-sample](../../../samples/msal-react-samples/b2c-sample) for complete Vite-based examples.
98+
3199
## Correct logout bug
32100
MSAL React v5 has fixed a bug affecting the `useMsalAuthentication` hook and `MsalAuthenticationTemplate`. Logging out now clears all state associated with the user.
33101

0 commit comments

Comments
 (0)