Where the check happens

In a complex React application, it’s easy to pass the wrong props to a provider, especially when the provider list is long. Because ComposeProvider is a generic wrapper, it could technically render a provider with missing or incorrect props without any immediate warning—only for the app to crash at runtime.

To prevent this, @evanion/compose moves the validation to compile time using advanced TypeScript generics.

Validating Providers at Different Stages

Depending on how you define your provider entries, the compiler checks the props at different times. Consider three providers: CartProvider (no props), ThemeProvider (requires theme), and CurrencyProvider (requires currency).

const markup = renderToStaticMarkup(
  <ComposeProvider
    providers={[
      // A bare component, for a provider whose props are all optional.
      CartProvider,
      // A `provider()` call, checked where it is written.
      provider(ThemeProvider, { theme: 'dark' }),
      // A tuple, checked where the array reaches `ComposeProvider`.
      [CurrencyProvider, { currency: 'SEK' }],
    ]}
  >
    <p>Brass: Birmingham</p>
  </ComposeProvider>,
);
 
markup; // -> '<div id="cart"><div id="dark"><div id="SEK"><p>Brass: Birmingham</p></div></div></div>'

The checks differ by entry type:

1. provider() calls: This helper checks props at the call site. You get autocomplete and immediate errors as you type, making it the preferred way to define tuples.
2. Bare components: Used for providers with all-optional props (like CartProvider). If a bare component is used but requires mandatory props, the compiler will flag it.
3. Hand-written tuples: If you write [Component, Props] manually, the check is deferred until the array is passed to ComposeProvider.

Type Safety for Inline Arrays

When you write your provider array inline within the providers prop, ComposeProvider uses a TypeScript const type parameter to ensure every entry is checked against its own component.

If you provide an incorrect prop for ThemeProvider, the compiler identifies exactly which entry in the array is failing.

const markup = renderToStaticMarkup(
  <ComposeProvider
    providers={[
      ThemeProvider,
Type '({ theme, children, }: React.PropsWithChildren<{ theme: "light" | "dark"; }>) => React.JSX.Element' is not assignable to type '(({ theme, children, }: PropsWithChildren<{ theme: "light" | "dark"; }>) => Element) & ComposeError<"this component requires props — use provider(Component, props) or a [Component, props] tuple">'.
  Type '({ theme, children, }: React.PropsWithChildren<{ theme: "light" | "dark"; }>) => React.JSX.Element' is not assignable to type 'ComposeError<"this component requires props — use provider(Component, props) or a [Component, props] tuple">'.
      [ThemeProvider, {}],
Property 'theme' is missing in type '{}' but required in type 'PropsWithoutChildren<({ theme, children, }: PropsWithChildren<{ theme: "light" | "dark"; }>) => Element>'.
      [ThemeProvider, { theme: 'blue' }],
Type 'string' is not assignable to type 'never'.
      [ThemeProvider, { theme: 'dark', accent: 'green' }],
Type '[({ theme, children, }: PropsWithChildren<{ theme: "light" | "dark"; }>) => Element, { theme: "dark"; accent: "green"; }]' is not assignable to type 'readonly [({ theme, children, }: PropsWithChildren<{ theme: "light" | "dark"; }>) => Element, { readonly theme: "dark"; readonly accent: "green"; }] & ComposeError<"unknown prop 'accent'">'.
  Property '"ComposeError: unknown prop 'accent'"' is missing in type '[({ theme, children, }: PropsWithChildren<{ theme: "light" | "dark"; }>) => Element, { theme: "dark"; accent: "green"; }]' but required in type 'ComposeError<"unknown prop 'accent'">'.
    ]}
  >
    <p>Brass: Birmingham</p>
  </ComposeProvider>,
);
 
markup; // -> '<div><div><div id="blue"><div id="dark"><p>Brass: Birmingham</p></div></div></div></div>'

The compiler can detect multiple types of errors:

Debugging Compose Errors

To make these complex TypeScript failures readable, @evanion/compose wraps them in a ComposeError type. When a check fails, the expected type of the entry becomes ComposeError<"message">, except for a missing or mistyped prop value, where it becomes the shape the entry should have had.

Since no value can match this type, the entry fails to compile, and the message is displayed directly in the TypeScript output.

Solving the “Type ‘string’ is not assignable to type ‘never’” Error

You may encounter a confusing error like Type 'string' is not assignable to type 'never' when providing a value outside the allowed literals (e.g., 'blue' when only 'light' or 'dark' are accepted).

This happens because TypeScript intersects your provided type with the correct type; since they don’t overlap, the result is never.

The Fix: Use the provider() helper. It avoids this intersection and reports the error at the call site with a much clearer message: Type '"blue"' is not assignable to type '"light" | "dark"'.

Maintain Checks in Separate Constants

In real applications, provider arrays are often moved to a const or a config file to keep the JSX clean. Keeping the check explains how to maintain these compile-time checks when the array is moved out of the JSX.