In firebase_auth, how do authStateChanges, idTokenChanges and userChanges differ, and which one should drive sign-in versus home routing?

## Three streams, one `User?` `firebase_auth` exposes the signed-in user as a nullable `User`. Besides the `currentUser` getter — a one-off snapshot — `FirebaseAuth.instance` offers three methods that each return a `Stream<User?>`. All three emit **immediately after a listener subscribes** (once the auth state has been initialized) and then again on later changes. They differ only in *which* changes wake them up. | Event | `authStateChanges()` | `idTokenChanges()` | `userChanges()` | |---|---|---|---| | Right after a listener registers | yes | yes | yes | | A user signs in | yes | yes | yes | | The current user signs out | yes | yes | yes | | The current user's ID token changes (refresh) | no | yes | yes | | `reload()`, `unlink()`, `updatePassword()`, `updatePhoneNumber()`, `updateProfile()` on the current user | no | no | yes | The `userChanges()` doc comment in the pinned source calls it "a superset of both `authStateChanges` and `idTokenChanges`": it exists so an app can follow profile edits — a new display name, a newly linked or unlinked provider — without calling `reload()` and re-reading the user by hand. (The FlutterFire guide still lists `updateEmail()` in this set; that method is gone from the current `User` class, which offers `verifyBeforeUpdateEmail()` instead.) ## Which one should drive routing In a recipe-sharing app the top-level question is binary: is anyone signed in? If yes, show the recipe feed; if no, show the sign-in screen. That is exactly the question `authStateChanges()` answers, and it answers *only* that question. - **`authStateChanges()`** — the default for routing. It fires on sign-in and sign-out, so a route decision is re-evaluated only when the answer can actually change. - **`idTokenChanges()`** — for code that must react when the token itself changes: re-attaching a fresh token to an API client, or noticing new custom claims after a refresh. - **`userChanges()`** — for screens that display profile data, such as the account page showing the cook's display name and photo. Routing on `userChanges()` is not *wrong* — the null/non-null answer is the same — but every profile edit and every token refresh now re-runs the routing logic. In a router that rebuilds its page stack on each event, that means needless rebuilds and, in the worst case, a user dropped back to the home route while editing their profile. ## What none of them report The FlutterFire guide is explicit about the gaps: - Changes made **server-side with the Admin SDK** (a profile update) do not fire any of the three streams. The client sees them after `currentUser!.reload()`. - A user **disabled or deleted in the console** keeps appearing signed in on the device until something forces a round trip; `reload()` then throws a `FirebaseAuthException` with `user-disabled` or `user-not-found`, which the app should catch and treat as a sign-out. - Custom-claim changes reach `idTokenChanges()` only when a new ID token is issued — at the next sign-in, the next natural refresh, or a forced refresh with `getIdTokenResult(true)`. ## Matching each consumer to a signal A useful habit in an interview answer is to name the consumer first and pick the signal second: 1. **The sign-in versus recipe-feed gate** subscribes to `authStateChanges()`. 2. **An API client or socket that holds a token** subscribes to `idTokenChanges()`, so it can re-authenticate when the token rotates. 3. **The account screen** showing name, photo and linked providers subscribes to `userChanges()`. 4. **A one-off read after startup**, such as taking the `uid` to build a query, uses the `currentUser` snapshot. Each consumer then wakes up only for events that change its own output. ## Mechanics worth knowing 1. Each call to one of these methods returns a **new** broadcast `Stream` object in the pinned `firebase_auth` source. Create the stream once — in a field, a provider or a service — rather than calling `authStateChanges()` on every rebuild, or each rebuild resubscribes. 2. The events carry `User?`, not `UserCredential`; the credential only comes back from the sign-in call itself. 3. `null` means signed out. There is no separate "loading" event: until the first event arrives, your app is in the loading state and should render something neutral, such as a splash. ```dart import 'package:firebase_auth/firebase_auth.dart'; enum Gate { signedOut, signedIn } // Created once, e.g. in a service, and shared by the router. final Stream<Gate> gateStream = FirebaseAuth.instance .authStateChanges() .map((User? user) => user == null ? Gate.signedOut : Gate.signedIn) .distinct(); ``` Mapping to a two-value enum with `distinct()` makes the routing input as narrow as the decision it drives, whichever stream sits underneath.