· By John Kavanagh

Testing a Packed React Library in Its Real Consumers

Photograph of stacked cardboard produce boxes and a wooden crate at a street market.
Image by Eric Prouzet, licensed from Unsplash.

The component works in Storybook. The TypeScript build passes. Someone installs the package in another application, and the first click produces an invalid Hook call.

It is tempting to start rearranging the Hook. Sometimes the Hook is entirely innocent. The package has brought its own React to an application which already had one, and the two copies are now conducting separate meetings.

My design‑system guide covers the wider route from design decisions to a versioned component package. Here I want to look at one narrower release check: install the exact packed artefact in a separate application before asking another team to do it.

A workspace can make the source convenient to use whilst hiding what the package actually ships. Those are different things to test.


Start Outside the Producer's Comfortable Surroundings

My example is a small counter with a Hook, a declaration file, and an explicitly imported stylesheet. It has consumers using matched React and React DOM versions from the 18.3 and 19.0 lines. They don't import the library's source directory or use a workspace alias.

The producer creates local tarballs with yarn pack. Each consumer installs a tarball through a file dependency into its own dependency tree. No package is published to a registry.

That extra boundary is the point. A source alias can bypass the package's export map. A development project can see a declaration file which the packing rules leave behind. A shared dependency tree can also make a React import resolve differently from an independent installation.

I keep the consumers small because their job is to test the package contract. Adding the entire product application would make a failure more realistic, perhaps, but considerably less helpful to diagnose.


Inspect the Files People Receive

Before rendering anything, inspect the tarball's file list. For this package I expect the JavaScript entry point, its declarations, the stylesheet, the manifest, and the licence. I don't expect the producer's installed dependencies or its test output.

The package exposes a deliberately narrow surface:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./style.css": "./dist/style.css"
  },
  "peerDependencies": {
    "react": "^18.3.0 || ^19.0.0"
  }
}

This is an ESM package. It doesn't promise a CommonJS entry point, and the test doesn't quietly assume one. A real library which promises both needs consumer checks for both.

My missing‑declarations variant makes the distinction visible. The producer's TypeScript source still checks successfully, and the packed JavaScript exists. The consumer then fails to compile the public import because the declared type file is absent. Looking at a successful producer build would have missed the part the reader actually needs.


Check the React Instance, Not Just Its Version Label

React's invalid Hook call guidance distinguishes incorrect Hook usage, incompatible renderer versions, and duplicate React. A warning alone doesn't establish which one happened.

The working library leaves React external to its bundle, including the JSX runtime subpath. The accidentally bundled variant includes React's implementation inside its generated JavaScript. Both variants can still carry the same peer dependency declaration. Metadata does not reach into an already‑built file and remove a second runtime.

My diagnostic export exposes the library's useState reference solely for the test. The working package and the consumer see the same function object. The bundled variant sees a different one, even in the React 18 consumer where the version numbers agree. Rendering its Hook‑using component then fails.

That combination is more useful than matching a particular warning sentence. It establishes separate module identity and demonstrates the consequence at render time. The exact wording of React's diagnostic can change without making the duplicate copy acceptable.

I also inspect the builder's module graph. The good library bundle contains no React implementation; the complete consumer bundle resolves React from that consumer's own installation. Checking only the producer's dependency list wouldn't establish either fact.


Treat the Peer Range as a Support Decision

A peer range describes which host versions the library claims to work with. I would expect the advertised range to have a deliberate relationship with the consumer matrix, rather than being whatever makes the installer stop complaining.

That does not mean testing every possible patch on every build. It means choosing representative versions, recording them, and testing the boundaries which matter to the component's implementation. A library using a React 19‑only API should not claim React 18 support merely because its simplest button happens to render there.

My unsupported‑peer variant declares React 17 whilst the consumers use 18 or 19. The installer diagnostic is retained separately from the render result. Whether an installer warns, refuses, or continues depends on the package manager and its configuration. A completed installation is therefore not my compatibility gate.

The release decision should combine the declared promise with actual checks. Widening the range to silence a warning without running the newly admitted consumer just moves the uncertainty downstream.


Compile the Allowed Imports and Reject the Others

The consumer's type check uses a resolver which understands package exports. It imports the supported root entry point, then separately attempts an internal subpath which the package does not expose.

The public import must compile. The private import must fail. That second assertion protects the boundary: an accidental source alias could make an unsupported path work during development and encourage another team to depend on it.

TypeScript's module reference explains how the resolver reads the export map. Keep the test's resolver aligned with the consumers you support. Passing one bundler‑oriented configuration does not prove every Node, CommonJS, and older TypeScript configuration can use the package.


Make the Stylesheet Part of the Test

A component which renders without throwing can still be an incomplete delivery. In my example the consumer imports the public CSS subpath, builds the application, and opens it in a browser.

The browser check verifies the counter's computed background colour, moves focus to its native button, and increments it with the keyboard. This proves that the packed stylesheet arrived and that the installed component can update its Hook state in a real consumer.

It is a deliberately modest assertion. It doesn't certify the component's full accessibility, every reset stylesheet, or every browser engine. Those need their own coverage. My Storybook article explains the broader component‑state review; the packed‑consumer check adds a delivery boundary to that work.

My consumer‑contract lab includes the working package, three deliberately broken variants, independent installs, and the positive and negative checks. Keep the final package hash with those results. If you rebuild the artefact after testing it, you have a new artefact to account for.

I still want the workspace to be pleasant to develop in. Before releasing, I also want to see the package survive leaving it.

Postscript

November 2026: I've added a React 19.3.1 consumer alongside the React 18.3.1 and 19.0.0 examples. My lab now records the installed package paths, module graph, type‑check failures, and browser interaction for each. The companion uses current build tools, with their exact versions in the README; I've kept the original React versions available for comparison.

Downloadable Resource

  • React Library Consumer Contract

    Pack a Hook‑using component and test independent React consumers against duplicate React, missing declarations, export boundaries, CSS, and peer warnings.

    Download ZIP

Have a complex web platform issue?

Tell me what is blocked, what has changed, and what needs to be true after the fix. I'll come back with a practical next step.