@uniflowed/router 0.0.0-alpha.14 → 0.0.0-alpha.15

package/client.js

@@ -18,6 +18,37 @@
 // Development only, and dynamically imported so a production bundle has no path
 // to it. See ubugeeei-prod/uf#508.
 //
+// # And whether React DevTools can see the page at all
+//
+// The other question only this module is in a position to ask.
+// `@uniflowed/vite` installs the hook DevTools attaches through, above every
+// module in the document; whether that worked *on this page* is a fact about a
+// running browser, and the line after hydration is where it can be read.
+// `internal/devtools.js` has the two findings and sends them to the same
+// terminal the hydration report goes to. See ubugeeei-prod/uf#503.
+//
+// # Strict Mode, in development, by default
+//
+// `uf dev` generates `strictMode: true` into `virtual:uf/client` and `uf build`
+// does not, so a development render is doubled and a visitor's is not. That is
+// React's own check for the thing it cannot check any other way: a component
+// whose render is not pure, and an effect whose cleanup does not undo its
+// setup, both behave correctly until the one production render that interleaves
+// with something — and Strict Mode makes them behave incorrectly at once, on
+// the machine of the person writing them.
+//
+// The wrapper is the argument to `hydrateRoot` rather than something inside
+// `<App>`, and that is load-bearing rather than tidy. React decides whether to
+// double-invoke a mount's effects at the *topmost fiber it is placing*: if that
+// fiber is not itself in Strict Mode, React stops there and never looks inside
+// it. A `<StrictMode>` further down still doubles the renders under it — that
+// comes from the fiber's own mode — and doubles no effect at all, so it would
+// have bought the half of the check that is easy to notice and silently lost
+// the half that finds the bug. It renders no element, so the hydrated tree is
+// unchanged and the markup comparison above is unaffected.
+// `app.react.strictMode: false` in `uf.config.js` turns it off. See
+// ubugeeei-prod/uf#516.
+//
 // # A route can decline to be hydrated
 //
 // uf's server-component analysis decides which routes have a `"use client"`
@@ -29,7 +60,7 @@
 // See ubugeeei-prod/uf#350.
 
 import * as React from "react";
-import { startTransition } from "react";
+import { StrictMode, startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 
 import {
@@ -54,6 +85,7 @@ export async function hydrate(options: {|
   readonly routes: RouteTable["routes"],
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
+  readonly strictMode?: boolean,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -95,11 +127,28 @@ export async function hydrate(options: {|
     recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
   }
 
+  // `<StrictMode>` renders no element of its own, so the tree React hydrates
+  // against the server's markup is the same tree either way and the flag can
+  // be a development-only difference without being a hydration difference.
+  const tree = <App url={url} initial={resolved} />;
+
   startTransition(() => {
     hydrateRoot(
       container,
-      <App url={url} initial={resolved} />,
+      options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
       recovery == null ? undefined : { onRecoverableError: recovery },
     );
   });
+
+  // And, in development only, whether the panel a developer is about to open
+  // can see any of that. `react-dom` announced itself while it was being
+  // imported — long before this line — so the answer is already settled and
+  // this only reads it. Behind the same `import.meta.hot` gate as the
+  // hydration reporter, dynamically imported for the same reason: a production
+  // bundle has no path to the module rather than merely no reason to run it.
+  // See `./internal/devtools.js` and ubugeeei-prod/uf#503.
+  if (import.meta.hot != null) {
+    const { reportDevtools } = await import("./internal/devtools.js");
+    reportDevtools(window);
+  }
 }

package/internal/devtools.js

@@ -0,0 +1,131 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: whether React DevTools can actually attach
+// to the page this browser just hydrated.
+//
+// `@uniflowed/vite` installs the hook DevTools attaches through, as a classic
+// script above every module — see `packages/vite/internal/devtools.js`, which
+// has the argument. That is uf saying what it intends. This is the half that
+// checks it happened, and the two are not the same claim: the preamble is
+// injected by a `transformIndexHtml` hook, into a document a project's own Vite
+// plugins also write to, and the thing that has to be true is an *ordering* —
+// the hook exists before `react-dom` is evaluated — which no amount of reading
+// the injector can establish about a particular page.
+//
+// It runs once, after hydration, in development only, and says nothing at all
+// when there is nothing wrong. See ubugeeei-prod/uf#503.
+//
+// # Why it reports rather than throws
+//
+// Nothing here is a reason to stop a page. DevTools not attaching costs a
+// developer a panel, and a framework that refused to render over it would have
+// turned a missing convenience into an outage. So the two findings go to the
+// terminal on the same channel as every other browser-side diagnostic — see
+// `./diagnostics.js` — and the page carries on.
+//
+// # The two findings, and why they are the two
+//
+// A third condition — React's *development* build, which is what gives the
+// panel props, hooks and source positions — is not checked here because a
+// browser cannot tell the difference from the outside, and because uf owns it
+// end to end: `mode` is `development` and `uf transform` is called with
+// `development: true`, both asserted in `tests/library/devtools.test.js`
+// against the plugin rather than against a page. What is left is what only a
+// running page knows.
+//
+//   1. **There is no hook.** Something ran before `react-dom` and there was
+//      nothing for it to register with, or the preamble did not reach this
+//      document. Either way no renderer was announced and the panel will say
+//      the page is not using React.
+//   2. **There is more than one renderer.** Two copies of `react-dom` each
+//      injected, and DevTools shows the tree of whichever it heard from — which
+//      is the shape of the "multiple renderers concurrently rendering the same
+//      context provider" report, and a component tree that is missing half the
+//      page for a reason nothing on screen explains.
+
+import { reportDiagnostic } from "./diagnostics.js";
+
+/**
+ * The global React registers itself with.
+ *
+ * The same string as `DEVTOOLS_HOOK` in `@uniflowed/vite`'s
+ * `internal/devtools.js`, written out again rather than imported for the reason
+ * that file's neighbour `internal/diagnostics.js` gives about the endpoint
+ * paths: `@uniflowed/vite` is loaded by Vite before any Flow transform exists
+ * and this module is Flow, so the import cannot go either way.
+ * `tests/library/devtools.test.js` asserts the two spellings agree, which is
+ * what makes a duplicated constant honest.
+ */
+export const DEVTOOLS_HOOK: string = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+
+/** The part of a page this module reads. */
+type HookWindow = {
+  [key: string]: mixed,
+  ...
+};
+
+/**
+ * What is wrong with this page's DevTools hook, as a diagnostic, or `null`.
+ *
+ * Separated from the reporting so that a test can ask the question without a
+ * channel to answer on, and because the wording is the part worth pinning: a
+ * reader who sees this in a terminal has to be able to act on it without
+ * reading this file.
+ */
+export function devtoolsProblem(win: HookWindow): {|
+  readonly message: string,
+  readonly detail: $ReadOnlyArray<string>,
+|} | null {
+  const hook = win[DEVTOOLS_HOOK];
+  if (hook == null || typeof hook !== "object") {
+    return {
+      message: `React DevTools cannot attach: nothing installed \`${DEVTOOLS_HOOK}\` before react-dom ran`,
+      detail: [
+        "React registers itself with that global while `react-dom` is evaluated, once and never again.",
+        "`uf dev` injects the hook as a classic script at the top of the head; a plugin that replaces",
+        "`transformIndexHtml`'s output, or a document that does not go through it, takes it away.",
+      ],
+    };
+  }
+
+  // `renderers` is a Map React puts its renderer in, keyed by the id `inject`
+  // handed back. Anything else there is a hook uf did not install and DevTools
+  // did not either, and guessing at its shape would report a problem that is
+  // really this module not recognising one.
+  const renderers = (hook: $FlowFixMe).renderers;
+  const count = renderers instanceof Map ? renderers.size : null;
+  if (count != null && count > 1) {
+    return {
+      message: `React DevTools has ${count} renderers on this page and will show one of them`,
+      detail: [
+        "Two copies of `react-dom` are loaded, so half the component tree is in a tree the panel cannot see.",
+        '`resolve.dedupe: ["react", "react-dom"]` is what usually prevents it; a linked package with its',
+        "own `react-dom` in `node_modules` is what usually causes it.",
+      ],
+    };
+  }
+  return null;
+}
+
+/**
+ * Report the problem, if there is one, to the terminal running `uf dev`.
+ *
+ * Throws nothing and returns nothing, and the guard is around the whole body
+ * rather than around the reading: this is called from the line after a
+ * successful hydration, so every failure available to it — a hook object whose
+ * property getter throws, a host with no `fetch` to report through — is a
+ * development convenience failing, and a development convenience that can take
+ * a working page down is worse than no convenience at all.
+ */
+export function reportDevtools(win: HookWindow): void {
+  try {
+    const problem = devtoolsProblem(win);
+    if (problem == null) {
+      return;
+    }
+    reportDiagnostic({ severity: "warn", message: problem.message, detail: problem.detail });
+  } catch {
+    // Deliberately silent. There is no second channel to complain on, and the
+    // thing being reported was never worth interrupting anybody for.
+  }
+}

package/internal/diagnostics.js

@@ -39,9 +39,9 @@
 // `uf dev` serves this path and nothing else does: a built application has no
 // `/__uf/` anything, so a call in production posts to a path that answers 404
 // and the rejected promise is swallowed here. That is a fallback rather than a
-// design — the only caller is behind `import.meta.hot` in `../client.js`, so a
-// production bundle has no path to this module rather than merely no answer
-// from it.
+// design — both callers are behind `import.meta.hot` in `../client.js`, the
+// hydration report and the DevTools check, so a production bundle has no path
+// to this module rather than merely no answer from it.
 //
 // Nothing here opens a connection until it is called, importing it does nothing
 // at all, and what it sends goes to the page's own origin as a path rather than

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.14",
+  "version": "0.0.0-alpha.15",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.14",
-    "@uniflowed/server": "0.0.0-alpha.14"
+    "@uniflowed/hooks": "0.0.0-alpha.15",
+    "@uniflowed/server": "0.0.0-alpha.15"
   }
 }