AddThisFeature

SSR-Safe Browser APIs

Stop server-rendered pages breaking or flickering on browser-only APIs.

moderate Developer Experience

What it adds

Wrappers around storage, clipboard, media queries, and viewport measurement that behave predictably where no browser exists.

What your agent is told to do

5
  1. 1

    Find every direct reach for a browser global in code that also runs on the server — stored preferences, clipboard writes, viewport width, dark-mode and reduced-motion queries, network status — and route them through a small set of shared accessors.

  2. 2

    Give each accessor a deterministic value to return when there is no browser, and choose that value to match what the majority of users will resolve to, so the correction after mount is invisible for most and small for the rest.

  3. 3

    Report availability explicitly alongside the value, so a caller can distinguish not yet known from genuinely unavailable and render a neutral state rather than guessing.

  4. 4

    Return a refusal a caller can act on when an API exists but is blocked — storage disabled in a private window, clipboard denied, a permission never granted — instead of throwing from inside a render.

  5. 5

    Do not solve the visible flash by rendering nothing until mount. A blank sidebar or a missing header is a worse first paint than a briefly imperfect one, and it costs the page its server-rendered content.

Edge cases it handles

7
  • Every accessor needs one documented server-side default, and it must be the same on every request. A value that differs between the server render and the first client render produces a mismatch, and a value that differs between two server renders makes the page uncacheable.
  • Reading a stored theme or a media query only after mount swaps the layout in front of the user. Reserve the space, keep the first paint stable, and apply the corrected value without moving anything around it.
  • Storage throws rather than returning empty when it is disabled or the quota is full, and clipboard and notification permissions can be denied outright. Every wrapper must treat refusal as an ordinary outcome and let the caller fall back.
  • The wrappers must be trivial to replace in tests, because assertions about a component's behaviour at a narrow viewport or with storage unavailable should not require driving a real browser.
  • Media query and resize listeners registered by these wrappers must be removed when their caller goes away, or a long session accumulates listeners that fire against unmounted views.
  • Viewport height on mobile changes as browser chrome and the on-screen keyboard appear, so a measurement taken once at mount is wrong within seconds.
  • The same accessor may be called from many components at once, so it should share one underlying listener and one cached value rather than opening a subscription per caller.

Definition of done

8
  • No component reaches for a browser global directly on a path that also renders on the server.
  • Each accessor returns one documented, deterministic value when no browser is present.
  • Nothing on the page moves or is replaced when the real client value arrives after mount.
  • Blocked storage, clipboard, and permission APIs return a handled refusal rather than throwing.
  • Each accessor can be stubbed in a test without a browser environment.
  • Listeners registered by the wrappers are removed with their callers and shared between concurrent ones.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.