FirebaseUI for Web

The v7 architecture separates authentication logic from UI rendering, allowing for better flexibility and framework integration. Unlike v6, which was a single monolithic package, v7 uses a composable system of specialized packages:

• @firebase-oss/ui-core: The framework-agnostic core containing all authentication logic, state management, behaviors, and utilities. It has no UI dependencies.
• Framework-specific packages: Dedicated packages for specific UI implementations:
  • @firebase-oss/ui-react for React applications.
  • @firebase-oss/ui-angular for Angular applications.
  • @firebase-oss/ui-shadcn for Shadcn components.
• @firebase-oss/ui-styles: A separate package dedicated to styling.
• @firebase-oss/ui-translations: A separate package for translations.

This architecture uses modern patterns such as TypeScript and reactive stores (nanostores).

To migrate to the Shadcn implementation of Firebase UI:

1. Uninstall the old package:

   npm uninstall firebaseui

2. Ensure Shadcn is installed and set up in your project.
3. Add the Firebase UI registry to your components.json:

   {
     "registries": {
       "@firebase": "https://firebaseopensource.com/r/{name}.json"
     }
   }

4. Add components using the Shadcn CLI:

   npx shadcn@latest add @firebase/sign-in-auth-screen

UI examples (react, shadcn, nextjs, nextjs-ssr, angular) are verified using Playwright smoke tests. These tests focus on rendered UI elements rather than exact URL matching.

Smoke Test Scope

• Deep-link to the sign-in-with-handlers screen.
• Assert form rendering.
• Assert that empty submissions trigger validation.
• Assert that the 'forgot-password' control navigates to a rendered forgot-password screen.

Execution Details

• Environment: Tests run against dev servers, which automatically connect to the Auth emulator in development mode.
• Commands:
  • pnpm test:e2e: Runs the entire suite.
  • pnpm test:e2e:<example>: Runs tests for a specific project.
• Note: OAuth, phone/MFA, and real sign-in flows are currently out of the MVP scope for smoke testing.

To attach legal policy links to the authentication UI in React or Shadcn, wrap your application (or the relevant component tree) with the FirebaseUIProvider and pass a policies object containing termsOfServiceUrl and privacyPolicyUrl.

import { FirebaseUIProvider } from '@firebase-oss/ui-react';

<FirebaseUIProvider
  ui={ui}
  policies={{
    termsOfServiceUrl: 'https://example.com/terms',
    privacyPolicyUrl: 'https://example.com/privacy',
  }}
>
  {children}
</FirebaseUIProvider>;

You can override CSS variables with preset colors by importing specific theme files into your CSS. Themes should be imported after the base Tailwind and FirebaseUI styles.

@import "tailwindcss";
@import "@firebase-oss/ui-styles/tailwind";
@import "@firebase-oss/ui-styles/themes/brualist";

To migrate an Angular project from firebaseui (v6) to @firebase-oss/ui-angular (v7):

1. Uninstall the old package:

   npm uninstall firebaseui

2. Install the new Angular packages (requires AngularFire to be configured first):

   npm install @angular/fire @firebase-oss/ui-angular@beta @firebase-oss/ui-core@beta @firebase-oss/ui-styles@beta

3. Update initialization using provideFirebaseUI in your ApplicationConfig.

import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
import { initializeUI } from '@firebase-oss/ui-core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirebaseApp(() => initializeApp({ ... })),
    provideFirebaseUI((apps) => initializeUI({
      app: apps[0],
      // behaviors and other configuration go here
    })),
  ];
};

To quickly access the Sign-in Auth Screen with Handlers across all UI examples, use the following deep-link path:

/screens/sign-in-auth-screen-w-handlers

Note: For Next.js examples, ensure you include the trailing slash: /screens/sign-in-auth-screen-w-handlers/.

The @firebase/shadcn package allows you to use Firebase UI for Web logic while using your own Shadcn UI components. To use this, you must add the @firebase registry namespace to your components.json file so that the Shadcn CLI knows where to fetch the component definitions.

{
  // ...
  "registries": {
    "@firebase": "https://firebaseopensource.com/r/{name}.json"
  }
}

The root pnpm build command does not compile examples/custom-auth-server. If you modify examples/custom-auth-server or its dependencies, you must build it explicitly to ensure E2E tests pass. You can either run the specific build command or rely on pnpm test:e2e which handles the build automatically.

pnpm --filter custom-auth-server run build

You can run the end-to-end smoke tests for all monorepo examples using the serial runner, or target a specific example for debugging. The runner manages dev servers and the Firebase Auth emulator automatically.

Run all examples (Serial): pnpm test:e2e

Run a specific example (Debug): pnpm test:e2e:<example> (e.g., pnpm test:e2e:react)

Note on Execution:

• The runner builds packages once before starting.
• It starts a shared Auth emulator on port :9099 if not already running.
• It runs tests serially (workers: 1) to ensure only one dev server is active at a time.

Once your packages are built and the emulator is running, start an example app in a separate terminal to test your changes:

• React (Recommended): pnpm --filter=react run dev
• Next.js (Static): pnpm --filter=nextjs run dev
• Next.js (SSR): pnpm --filter=nextjs-ssr run dev
• Angular: pnpm --filter=angular-example run start
• Shadcn: pnpm --filter=shadcn run dev