Skip to content

Commit e938e90

Browse files
EhespEhesp
committed
-
1 parent f06977c commit e938e90

File tree

1 file changed

+207
-0
lines changed

1 file changed

+207
-0
lines changed

‎MIGRATION.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Migration Guide
2+
3+
## Overview
4+
5+
FirebaseUI for Web has been completely rewritten from the ground up. The previous version (v6) was a single JavaScript package that provided a monolithic authentication UI solution. The new version (v7) represents a modern, modular architecture that separates concerns and provides better flexibility for developers.
6+
7+
### Architecture Changes
8+
9+
**Previous Version (v6):**
10+
- Single JavaScript package (`firebaseui`) that handled both authentication logic and UI rendering
11+
- Tightly coupled to DOM manipulation and jQuery-like patterns
12+
- Limited customization options
13+
- Framework-agnostic but with a rigid structure
14+
15+
**New Version (v7):**
16+
- **Framework-agnostic core package** (`@invertase/firebaseui-core`): Contains all authentication logic, state management, behaviors, and utilities without any UI dependencies
17+
- **Framework-specific packages**: Separate packages for React (`@invertase/firebaseui-react`), Angular (`@invertase/firebaseui-angular`), and Shadcn components
18+
- **Supporting packages**: Separate packages for styles (`@invertase/firebaseui-styles`) and translations (`@invertase/firebaseui-translations`)
19+
- **Composable architecture**: Components are designed to be composed together, allowing for greater flexibility
20+
- **Modern patterns**: Uses reactive stores (nanostores), TypeScript throughout, and modern framework patterns
21+
22+
### Migration Path
23+
24+
**Important:** There is no direct migration path from v6 to v7. This is a complete rewrite with a fundamentally different architecture and API. You cannot simply update the package version and expect your existing code to work.
25+
26+
Instead, you will need to:
27+
1. Remove the old `firebaseui` package
28+
2. Install the appropriate new package(s) for your framework
29+
3. Rewrite your authentication UI components using the new API
30+
4. Update your configuration and styling approach
31+
32+
### What This Guide Covers
33+
34+
This migration guide maps features and concepts from the old [v6 version](https://github.com/firebase/firebaseui-web/tree/v6) to the new v7 rewrite, helping you understand:
35+
- How authentication methods translate between versions
36+
- How configuration options map to the new behaviors system
37+
- How UI customization works in the new architecture
38+
- How to achieve similar functionality with the new component-based approach
39+
40+
## Migrating
41+
42+
### 1. Installing Packages
43+
44+
First, remove the old `firebaseui` package and install the appropriate new package(s) for your framework:
45+
46+
<details>
47+
<summary>React</summary>
48+
49+
Remove the old package:
50+
```bash
51+
npm uninstall firebaseui
52+
```
53+
54+
Install the new React package:
55+
```bash
56+
npm install @invertase/firebaseui-react
57+
```
58+
59+
The package automatically includes the core package as a dependency, so you don't need to install `@invertase/firebaseui-core` separately.
60+
</details>
61+
62+
<details>
63+
<summary>Angular</summary>
64+
65+
Remove the old package:
66+
```bash
67+
npm uninstall firebaseui
68+
```
69+
70+
Install the new Angular package:
71+
```bash
72+
npm install @invertase/firebaseui-angular
73+
```
74+
75+
**Note:** The Angular package requires [AngularFire](https://github.com/angular/angularfire) to be installed and configured first.
76+
</details>
77+
78+
<details>
79+
<summary>Shadcn</summary>
80+
81+
Remove the old package:
82+
```bash
83+
npm uninstall firebaseui
84+
```
85+
86+
Ensure you have [installed and setup](https://ui.shadcn.com/docs/installation) Shadcn in your project first.
87+
88+
Add the Firebase UI registry to your `components.json`:
89+
```json
90+
{
91+
...
92+
"registries": {
93+
"@firebase": "https://fir-ui-shadcn-registry.web.app/r/{name}.json"
94+
}
95+
}
96+
```
97+
98+
Then add components as needed:
99+
```bash
100+
npx shadcn@latest add @firebase/sign-in-auth-screen
101+
```
102+
103+
This will automatically install all required dependencies.
104+
</details>
105+
106+
### 2. Initialization
107+
108+
The initialization process is fundamentally different between v6 and v7.
109+
110+
**Old Way (v6):**
111+
```javascript
112+
// Initialize the FirebaseUI Widget using Firebase.
113+
var ui = new firebaseui.auth.AuthUI(firebase.auth());
114+
115+
// The start method will wait until the DOM is loaded.
116+
ui.start('#firebaseui-auth-container', uiConfig);
117+
```
118+
119+
**New Way (v7):**
120+
121+
<details>
122+
<summary>React</summary>
123+
124+
```tsx
125+
import { initializeApp } from 'firebase/app';
126+
import { initializeUI } from '@invertase/firebaseui-core';
127+
import { FirebaseUIProvider } from '@invertase/firebaseui-react';
128+
129+
const app = initializeApp({ ... });
130+
131+
const ui = initializeUI({
132+
app,
133+
// behaviors and other configuration go here
134+
});
135+
136+
function App() {
137+
return (
138+
<FirebaseUIProvider ui={ui}>
139+
{/* Your app components */}
140+
</FirebaseUIProvider>
141+
);
142+
}
143+
```
144+
</details>
145+
146+
<details>
147+
<summary>Angular</summary>
148+
149+
```ts
150+
import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
151+
import { initializeUI } from '@invertase/firebaseui-core';
152+
153+
export const appConfig: ApplicationConfig = {
154+
providers: [
155+
provideFirebaseApp(() => initializeApp({ ... })),
156+
provideFirebaseUI((apps) => initializeUI({
157+
app: apps[0],
158+
// behaviors and other configuration go here
159+
})),
160+
]
161+
};
162+
```
163+
</details>
164+
165+
<details>
166+
<summary>Shadcn</summary>
167+
168+
```tsx
169+
import { initializeApp } from 'firebase/app';
170+
import { initializeUI } from '@invertase/firebaseui-core';
171+
import { FirebaseUIProvider } from '@invertase/firebaseui-react';
172+
173+
const app = initializeApp({ ... });
174+
175+
const ui = initializeUI({
176+
app,
177+
// behaviors and other configuration go here
178+
});
179+
180+
function App() {
181+
return (
182+
<FirebaseUIProvider ui={ui}>
183+
{/* Your app components */}
184+
</FirebaseUIProvider>
185+
);
186+
}
187+
```
188+
</details>
189+
190+
### 3. Configuration Options Migration
191+
192+
The following table maps v6 configuration options to their v7 equivalents:
193+
194+
| v6 Option | Required | Migration Guide |
195+
|----------|:--------:|------------------|
196+
| `autoUpgradeAnonymousUsers` | No | **Use the `autoUpgradeAnonymousUsers` behavior.**<br/><br/>```ts<br/>import { autoUpgradeAnonymousUsers } from '@invertase/firebaseui-core';<br/><br/>const ui = initializeUI({<br/> app,<br/> behaviors: [autoUpgradeAnonymousUsers({<br/> async onUpgrade(ui, oldUserId, credential) {<br/> // Handle account merge logic<br/> }<br/> })],<br/>});<br/>```<br/><br/>The `onUpgrade` callback replaces the `signInFailure` callback for handling merge conflicts. |
197+
| `callbacks` | No | **Use component props instead.**<br/><br/>v6 callbacks like `signInSuccessWithAuthResult`, `signInFailure`, etc. are replaced by component event handlers:<br/><br/>- `onSignIn={(user) => { ... }}` on screen components<br/>- `onSignUp={(user) => { ... }}` on screen components<br/>- `onForgotPasswordClick={() => { ... }}` on form components<br/><br/>These are passed directly to the components you use, giving you more control over the flow. |
198+
| `credentialHelper` | No | **Not directly supported.**<br/><br/>The credential helper (Account Chooser) feature from v6 is not available in v7. If you need similar functionality, you'll need to implement it yourself using Firebase Auth's account linking features. |
199+
| `queryParameterForSignInSuccessUrl` | No | **Handle in your routing logic.**<br/><br/>v7 doesn't have built-in URL parameter handling. Instead, handle redirects in your `onSignIn` callback:<br/><br/>```tsx<br/><SignInAuthScreen onSignIn={(user) => {<br/> const urlParams = new URLSearchParams(window.location.search);<br/> const redirectUrl = urlParams.get('signInSuccessUrl') || '/dashboard';<br/> window.location.href = redirectUrl;<br/>}} /><br/>``` |
200+
| `queryParameterForWidgetMode` | No | **Not applicable.**<br/><br/>v7 doesn't use widget modes. Instead, you explicitly render the components you need (e.g., `<SignInAuthScreen />`, `<SignUpAuthScreen />`, etc.) in your application. |
201+
| `signInFlow` | No | **Use provider strategy behaviors.**<br/><br/>Replace `signInFlow: 'redirect'` with:<br/>```ts<br/>import { providerRedirectStrategy } from '@invertase/firebaseui-core';<br/><br/>behaviors: [providerRedirectStrategy()]<br/>```<br/><br/>Replace `signInFlow: 'popup'` with:<br/>```ts<br/>import { providerPopupStrategy } from '@invertase/firebaseui-core';<br/><br/>behaviors: [providerPopupStrategy()]<br/>```<br/><br/>**Note:** `popup` is the default strategy in v7. |
202+
| `immediateFederatedRedirect` | No | **Control via component rendering.**<br/><br/>v7 doesn't have this option. Instead, you control whether to show OAuth buttons or redirect immediately by conditionally rendering components or using your routing logic. For example:<br/><br/>```tsx<br/>{singleProvider ? (<br/> <Navigate to="/oauth-redirect" /><br/>) : (<br/> <OAuthScreen onSignIn={handleSignIn} /><br/>)}<br/>``` |
203+
| `signInOptions` | Yes | **Use OAuth button components directly.**<br/><br/>v6's `signInOptions` array is replaced by explicitly rendering the OAuth provider buttons you want:<br/><br/>```tsx<br/>import { <br/> GoogleSignInButton,<br/> FacebookSignInButton,<br/> AppleSignInButton<br/>} from '@invertase/firebaseui-react';<br/><br/><OAuthScreen onSignIn={handleSignIn}><br/> <GoogleSignInButton onSignIn={handleSignIn} /><br/> <FacebookSignInButton onSignIn={handleSignIn} /><br/> <AppleSignInButton onSignIn={handleSignIn} /><br/></OAuthScreen><br/>```<br/><br/>The order you place the buttons determines their display order. |
204+
| `signInSuccessUrl` | No* | **Handle in `onSignIn` callback.**<br/><br/>Instead of a configuration option, handle redirects in your component's `onSignIn` callback:<br/><br/>```tsx<br/><SignInAuthScreen onSignIn={(user) => {<br/> window.location.href = '/dashboard';<br/>}} /><br/>```<br/><br/>*Required in v6 when `signInSuccessWithAuthResult` callback is not used or returns `true`. |
205+
| `tosUrl` | Yes | **Pass via `policies` prop.**<br/><br/>**React:**<br/>```tsx<br/><FirebaseUIProvider <br/> ui={ui} <br/> policies={{<br/> termsOfServiceUrl: 'https://example.com/tos',<br/> privacyPolicyUrl: 'https://example.com/privacy'<br/> }}<br/>><br/>```<br/><br/>**Angular:**<br/>```ts<br/>provideFirebaseUIPolicies(() => ({<br/> termsOfServiceUrl: 'https://example.com/tos',<br/> privacyPolicyUrl: 'https://example.com/privacy'<br/>}))<br/>```<br/><br/>The policies are automatically rendered in auth forms and screens. |
206+
| `privacyPolicyUrl` | Yes | **Pass via `policies` prop.**<br/><br/>See `tosUrl` above - both URLs are passed together in the `policies` object. |
207+
| `adminRestrictedOperation` | No | **Handle in your UI logic.**<br/><br/>v7 doesn't have built-in support for this GCIP-specific feature. You'll need to:<br/><br/>1. Check if sign-up is disabled in your Firebase project settings<br/>2. Handle the `auth/admin-restricted-operation` error in your error handling<br/>3. Display appropriate messaging to users when sign-up attempts are blocked<br/><br/>You can check for this error in your `onSignUp` or form error handlers and display custom UI accordingly. |

0 commit comments

Comments
 (0)