A store created at module scope works in the browser but leaks data between users when the tree is rendered on a server; why?

## What module scope actually means A value created at the top level of a module is created once — the first time that module is loaded into a process — and lives as long as the process does. Not per user, not per page, not per test: per **process**. Everything about the singleton problem follows from that sentence, plus the fact that a browser and a server mean very different things by the word. ## Why the browser hides the problem In a browser the code runs in a process belonging to one document, driving one screen for one person. Process-wide and user-wide are the same thing there, so a module-level store does exactly what its author wanted: one instance, reachable from anywhere, alive for the session. A client-side navigation does not reload modules, so the store survives route changes too — usually desirable, and the reason the pattern feels safe. ## What a server does with the same code A server process handles **many requests, often concurrently and interleaved**. The module loads once; every request rendering the tree reaches the same store. The consequences, roughly in the order teams discover them: - **Bleed between users.** One request writes the signed-in person into the store; another request rendering at the same moment reads it and renders someone else's name. This is the failure that matters: a data-exposure bug, not a cosmetic one. - **Persistence across requests.** Whatever the previous request left behind is the starting state of the next, so a fresh visitor's first render can show stale data. - **Interleaving.** Because a render can pause and resume, two requests' writes alternate inside one store, producing states neither request intended. - **A clear at the start of a request makes it worse.** It looks like isolation and is really a write that wipes a concurrent request's in-flight data. ## Tests have the same shape A test file importing a module-level store shares it with every other test in that process. The symptoms are familiar: a case that passes alone and fails in the suite, an order-dependent failure, a value leaking from one case into the next. A reset between tests is the same partial fix as clearing per request — it holds while tests run strictly one at a time in one process, and stops holding the moment the runner parallelises or reuses workers. ## The fix: one instance per unit of work Stop exporting an instance. Export a **factory** that creates one. | Packaging | Instances | Isolation | Where it is right | |---|---|---|---| | module-level instance | one per process | none | a browser-only app with no server rendering | | factory, one per request | one per request | complete | any tree rendered on a server | | factory, one per test | one per test | complete | every test suite | The tree then needs a way to find the instance belonging to its own render. That is the ancestor-provides-a-value channel: create the store where the request is handled, provide it at the root of that render, and have components read it from their ancestors instead of importing it. The same seam hands every test a store it owns, which is usually the point at which the tests get shorter. ## Handing state to the client If the server rendered markup from a store, the browser's first render has to agree with that markup, so the data the server used travels with the response and seeds the client's own instance. The client then creates its store — one per document, the case where per-process genuinely is per person — and carries on from there. ## How to detect it before a user does 1. Render two different requests in one process, with different data, and assert each output separately. A shared store fails this immediately. 2. Render the same request twice in one process and assert the second output equals the first. A store that accumulated state fails here. 3. Run the suite with ordering randomised, and again with more than one worker. 4. List every piece of state created at module scope and ask of each: would this be correct if two people's renders were in flight at the same time? ## The honest exception A module-level instance is fine for state that genuinely is per process and carries nothing about a person: a registry of component or feature definitions, parsed configuration, a counter used only to generate local identifiers. The test is not "is it convenient to import" but "would two concurrent renders for two different people both be correct sharing this". When the answer is no, it belongs to the request.