example/: kitchen-sink demo cannot be installed, and its Suspense path cannot run

[tyler-reitz]

Two pre-existing defects in example/, both surfaced by @armando-navarro while reviewing #781 and both verified against main. Neither was caused by that PR and neither was fixed by it, so they are filed here rather than left in a review thread on a merged PR.

They are filed together because the fix for the second requires the first: there is no way to check that the Suspense path runs without being able to install the demo.

1. The demo cannot be installed as checked out

example/package.json depends on:

"reactfire": "file:../reactfire-4.0.1.tgz"

That tarball is not in the repository, so npm install inside example/ fails from a clean checkout. Whatever produced it was never committed and no script regenerates it.

Worth deciding rather than patching blindly: the fix could be a file:.. reference to the workspace, a documented npm pack step, or a published version range. They differ in whether the demo is meant to exercise the local working tree or the last release.

2. The Suspense path cannot run, on either the old instructions or the new ones

example/index.tsx ships a commented-out Suspense variant. #781 corrected the comment to say the path does not run as checked in, which is accurate, but the underlying reason is worth recording.

example/package.json pins the runtime to React 17 while the types are already on 18:

"react": "^17.0.0",
"react-dom": "^17.0.0",
"@types/react": "^18.0.15",
"@types/react-dom": "^18.0.6",
"typescript": "^4.7.4"

That skew produces two distinct failures.

• example/index.tsx:45, the commented ReactDOM.createRoot(rootElement). On react-dom 17 this is undefined at runtime, and under @types/react-dom@18 it is also a type error, because createRoot is declared in client.d.ts and not on the root entry. The example's build is tsc && vite build, so uncommenting it breaks the build as well as the app.
• example/withSuspense/Firestore.tsx:2, which imports useTransition (used at :87). This one type-checks cleanly because @types/react is already 18, and fails only at runtime on React 17. It is the more dangerous of the two for exactly that reason.

Those are the only React 18 APIs anywhere under example/, which bounds the work:

example/index.tsx:45:                    // ReactDOM.createRoot(rootElement).render(
example/withSuspense/Firestore.tsx:2:    import { useState, useTransition } from 'react';
example/withSuspense/Firestore.tsx:87:   const [isPending, startTransition] = useTransition();

The instructions that #781 replaced did not work either. Verified on react@experimental: createRoot, unstable_createRoot and render are all undefined on the root react-dom entry. So this is long-standing, and #781 regressed nothing.

What the fix involves

1. Bump react and react-dom to 18 in example/package.json, and the lockfile.
2. Import createRoot from react-dom/client, not the root entry. It is not on the root entry under @types/react-dom@18 either, so the currently commented specifier would still be wrong after the bump.
3. Word the comment as replacing the existing ReactDOM.render call, not uncommenting alongside it. Leaving both produces React 18's You are calling ReactDOMClient.createRoot() on a container that was previously passed to ReactDOM.render() warning.
4. Rename ConcurrentModeApp / NonConcurrentModeApp. "Concurrent mode" has not been the name for this since React 18 shipped, and docs(example): drop the concurrent mode framing from the demo entry #781 removed that framing from the surrounding prose but deliberately left the identifiers, since renaming them is not a comments-only change.

#781 also deliberately left the commented ReactDOM.createRoot specifier uncorrected. Fixing it in isolation would make the block look runnable, which is the opposite of what the caveat it sits under is for. It should be corrected as part of the bump, not before.

Not a ReactFire bug

Worth stating explicitly so this is not mistaken for a library problem: ReactFire itself works fine on React 17. @armando-navarro ran useObservable with suspense: true under the legacy render path and it suspends, resolves and keeps updating. The React 18 requirement belongs to the demo, not to the library.

Refs #781.