the-platform: React Hooks and Suspense Components for Browser APIs

What the-platform Solves and Who It Is For

Browser APIs are imperative. Reading window.innerWidth means attaching a resize listener, storing the value in component state, and removing the listener on unmount. Reading the network status means listening for online and offline events and tracking when the connection dropped. the-platform turns each of those into a Hook that returns the current value and keeps it in sync, or into a component that suspends until a resource is ready.

The target user is a React developer on React 16.8 or later who wants the browser's own APIs rather than a third-party service. The README lists nine Hooks (useDeviceMotion, useDeviceOrientation, useGeoPosition, useNetworkStatus, useMedia, useScript, useStylesheet, useWindowScrollPosition, useWindowSize) and six components (Img, Script, Video, Audio, Preload, Stylesheet). The package description in package.json calls them "React Hooks and Suspense-ready Components for Web API's and elements." It is a convenience layer, not a framework: there is no state container, no router, no data fetching client.

How the Hooks and Suspense Components Work

Each Hook is a thin adapter over one browser API. useWindowSize returns an object whose width and height come from window.innerWidth and window.innerHeight, according to the README. useWindowScrollPosition returns x and y read from window.pageXOffset and window.pageYOffset. useNetworkStatus returns isOnline, a boolean, plus an optional offlineAt Date recording when the connection was lost. useMedia takes either a media query string or an object and returns a match boolean; object queries are parsed by json2mq, which is the only runtime dependency in package.json.

The Suspense path is different. useGeoPosition, useScript and useStylesheet are documented as throwing a promise, which means they must be rendered inside a React.Suspense boundary. The components follow the same pattern: Img, Script, Video and Audio accept a src prop plus anything else you would pass to the underlying HTML element, and they suspend until the resource loads. Script goes further with a children render prop that the README says will only execute after the script has loaded, which is how the documented Stripe example reaches window.Stripe. React.Suspense in the examples is given maxDuration={300} and a fallback string, so the boundary shows the fallback while the resource is pending.

That design ties the package to the experimental Suspense semantics of its era. The peer dependencies in package.json are react >=16.6.0, react-dom >=16.6.0 and react-cache ^2.0.0-alpha.1. react-cache never shipped as a stable release, so any project installing the-platform today inherits an alpha dependency from 2018.

Installing the-platform and Loading Stripe with Script

The README gives two install commands. Either one adds the package to your project, and the note above them states that React 16.8 or later is required for Hooks.

npm i the-platform --save

yarn add the-platform

For a first real use, the README's Script example loads Stripe.js and reads the global it defines. The children render prop runs only after the script has loaded, so window.Stripe is available inside it. Wrap the component in React.Suspense with a fallback, because Script suspends while the network request is in flight.

import React from 'react';
import { Script } from 'the-platform';

function App() {
  return (
    <div>
      <h1>Load Stripe.js Async</h1>
      <React.Suspense maxDuration={300} fallback={'loading...'}>
        <Script src="https://js.stripe.com/v3/" async>
          {() => console.log(window.Stripe) || null}
        </Script>
      </React.Suspense>
    </div>
  );
}

export default App;

After the script loads, the console logs the Stripe object and the fallback text is replaced by the rendered children. The same shape applies to Video and Audio, which take a src prop and pass the rest through to the underlying element. The repository also ships an example/ directory with App.js, index.js, index.html and its own package.json, which is the fastest way to see the components wired together without writing the harness yourself.

Where the-platform Breaks Down

The strongest limitation is time. The last push to the repository was on 2019-04-08, and the most recent release listed is v0.10.1 on the same date. React's Suspense behaviour changed substantially after that point, and the package's peer dependency on react-cache ^2.0.0-alpha.1 points at a package that was never stabilised. Installing the-platform into a React 18 or 19 application means accepting a dependency tree that was never tested against those versions.

There are smaller failure modes too. useGeoPosition throws a promise and therefore requires a Suspense boundary plus the browser's permission prompt; the README documents the hook and its PositionOptions argument but does not describe what happens when the user denies the request. useDeviceMotion and useDeviceOrientation depend on DeviceMotionEvent and DeviceOrientationEvent, which browsers gate behind permissions and, in some cases, HTTPS. useNetworkStatus reports what the browser exposes through online and offline events, which is not the same as your API being reachable.

It is also the wrong tool when you need a maintained abstraction. If you want media loading with retries, caching or analytics, or a geolocation library that handles permission states and timeouts, the-platform gives you the raw event and stops there. The README does not document rollback, error boundaries for the suspended resources, or server-side rendering behaviour for any of the Hooks.

the-platform Compared with Writing the Hooks Yourself

The honest alternative is a local hook. A useWindowSize you write yourself is roughly a useState plus a useEffect that adds a resize listener and removes it on cleanup, and it lives in your repository where you can change it the day a browser API shifts. the-platform's value is that the same pattern is already written, typed and tested across nine Hooks and six components, so you do not repeat the listener-and-cleanup boilerplate in every project.

The trade-off is control. A local hook can debounce the resize handler, read from a ResizeObserver instead of the resize event, or return a default during server rendering. the-platform's implementation is in src/ and you can read it, but you cannot change it without forking. For a project that uses one or two of these APIs, a local hook is less code than a dependency plus its peer requirements. For a project that wants most of the list, the-platform saves real duplication. The tests/ directory in the repository shows what the maintainers considered worth covering, and reading it before adopting tells you more about the package's edges than the README does.

Licence and the Cost of Keeping It Installed

the-platform is MIT licensed, and the LICENSE file sits at the top level of the repository. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive arrangement and it does not oblige you to publish your own source. It also means there is no vendor to hold accountable: the licence grants rights over the code as it exists, not a commitment to fix it.

Upgrade cost is the real expense. The package version in package.json is 0.10.1 and the peer dependencies require react-cache ^2.0.0-alpha.1, so an upgrade of React is not a matter of bumping one number. The build pipeline in package.json runs Babel over src/ with the .ts and .tsx extensions and then tsc, and the published entry points are index.js and index.d.ts. If you fork to patch a hook, you inherit that build. Pinning the-platform to an exact version in your lockfile is the cheapest way to keep the dependency stable while you decide whether the Hooks you use are worth maintaining yourself.

Editorial conclusion

Adopt the-platform only on React 16.8 or 17 projects that already use Suspense for data loading and want small, typed wrappers around browser APIs instead of writing the same event listeners by hand. Do not adopt it on React 18 or 19, and do not expect fixes: the last push to the repository was on 2019-04-08 and the peer dependencies still point at react-cache 2.0.0-alpha.1. Before installing, read src/ for the specific hook you need, confirm that its event listener and cleanup path still matches the browser API you are targeting, and pin the version in package.json rather than relying on a caret range.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes