[Deep Dive #44] Scenario-Bound APIs - discussion
Deep Dive #44 argues for scenario-bound APIs: instead of a single 'generic' reference, you index the API surface by the kinds of problems teams actually have.
It calls out separate clusters like router APIs (multiple systems), file-routed metadata and image/font APIs, server component APIs, and state hooks as their own navigable routes.
Do you prefer one big reference page, or scenario-bound entry points that link to the same primitives? For router APIs with multiple systems, how do you prevent teams from mixing mental models in the same screen? When APIs are file-routed (metadata, images/fonts), do you treat that as part of routing vocabulary or part of the component surface?
Comments (10)
Back to latestScenario-bound indexing is a huge UX improvement. People don't think 'I need useX', they think 'I need to load data on a route'.
Related: API Reference.
Router APIs with multiple systems are manageable if you treat the router choice as a route-level posture.
In other words: you don't 'pick per component', you pick per route tree and render a marker.
File-routed metadata APIs are great because they force the 'route owns the document surface' idea.
It is basically routing vocabulary in disguise.
I like scenario-bound docs when they still link back to the same primitives. Otherwise you get duplicate references that drift.
The deep dive reads like it wants one truth, many entry points.
Server component APIs being their own cluster is smart. It prevents people from treating them like regular hooks and then getting surprised by boundaries.
If the docs are scenario-bound, the app architecture tends to become scenario-bound too (in a good way).
State hooks as a scenario is funny because it implies 'state' is a problem category, not a primitive category.
But that's accurate. People reach for state to solve routing, caching, orchestration, and only sometimes actual local state.
We got the most mileage out of making the scenario itself renderable. If the docs say "this hook solves the 'route scenario'", the route should be able to print the scenario name and the chosen posture.
tsx
import { useRouteState } from "react";
export function ScenarioEvidence({ name }: { name: string }) {
const route = useRouteState();
return <small data-scenario={name} data-posture={route.read("posture")} />;
}Counterpoint: scenario-bound entry points can become a maze. People bounce between 5 pages to learn one primitive.
I still want a single reference page, but with scenario sections and deep links into the same anchors.
Same. I think the "one truth, many entry points" line in the thread is the right posture.
If scenario pages are just curated routes into the same anchors, drift is much less likely.
On the router mental model mixing: we solved it by banning cross-router imports at the leaf level.
File router touches happen in the shell; component router touches happen inside the switchyard. Leaves get a deep prop object with the "current route contract" and nothing else.
The most practical scenario-bound split for us was: "Data Fetching" vs "Caching" vs "Rendering" as separate entries, even if they share hooks.
It stopped people from using caching primitives as fetch primitives and vice versa.
Related: Data Fetching and Caching.