react-swc-suspense-tracker

A development tool that helps you track which React Suspense and Error boundaries handle thrown promises and errors, making it easier to debug your React applications that use Suspense for data fetching and Error boundaries for error handling.

The Problem

React Suspense uses thrown Promises to pause rendering until data is ready, and Error boundaries catch thrown errors to handle failures gracefully. However, there's no public API to identify which boundary catches a suspension or error. This makes debugging difficult when you have multiple nested boundaries and need to understand the flow of suspensions and errors in your app.

The Solution

This package provides:

• SWC Plugin: Automatically replaces Suspense and ErrorBoundary imports to use trackable versions
• Development Hooks: Utilities to detect missing boundaries and debug suspension/error flow

Installation

1npm install --save-dev react-swc-suspense-tracker

Usage

Next.js Setup

Add the plugin to your next.config.js:

1module.exports = {
2  experimental: {
3    swcPlugins: [
4      [
5        "react-swc-suspense-tracker/swc",
6        {
7          // Optional: track custom boundary components
8          boundaries: [
9            { component: "ErrorBoundary", from: "react-error-boundary" }
10          ]
11        }
12      ],
13    ],
14  },
15};

*Note: The plugin is enabled by default in development mode and disabled in production builds. You can override this behavior by setting the enabled option.

Plugin Options

Option	Type	Default	Description
enabled	boolean	true on development false in production	Enable/disable the plugin transformation
boundaries	Array<{component: string, from: string}>	[]	Additional boundary components to track (e.g., custom Error boundaries)

Using with SWC directly

Add to your .swcrc:

1{
2  "jsc": {
3    "experimental": {
4      "plugins": [
5        [
6          "react-swc-suspense-tracker/swc",
7          {
8            "boundaries": [
9              { "component": "ErrorBoundary", "from": "react-error-boundary" }
10            ]
11          }
12        ]
13      ]
14    }
15  }
16}

Debugging Suspense Boundaries

The following example shows how you can debug specific hooks that might suspend.

Note: By default suspenseInfo will always be null in production mode. To change that you have to set the enabled option to true in the SWC plugin configuration.

1import { useQuery } from 'react-query';
2import { wrapSuspendableHook } from 'react-swc-suspense-tracker';
3
4const useQueryWithDebug = process.env.NODE_ENV === 'production'
5 ? useQuery
6 : wrapSuspendableHook(
7  useQuery,
8  (suspenseBoundaries, queryKey) => {
9    if (suspenseBoundaries.length === 0) {
10     console.warn(`Suspense triggered by ${queryKey} but no Suspense boundary found`);
11    } else {
12     console.info(`Suspense triggered by ${queryKey} for boundary: ${suspenseBoundaries[0]}`);
13    }
14  }
15);
16
17function MyComponent() {
18  const { data } = useQueryWithDebug('my-query-key', fetchData);
19  return <div>{data}</div>;
20}

Throwing Errors for Missing Suspense Boundaries

If you want to ensure that your component is wrapped in a Suspense boundary, you can use the useThrowIfSuspenseMissing hook. This will throw an error in development if the component might suspend but has no Suspense boundary above it.

1import { useThrowIfSuspenseMissing } from "react-swc-suspense-tracker";
2
3function MyComponent() {
4  // This will throw an error in development if no Suspense boundary is found
5  useThrowIfSuspenseMissing();
6
7  const data = useSomeDataHook(); // This might suspend
8  return <div>{data}</div>;
9}

Result:

What the SWC Plugin does

The plugin automatically transforms:

1// Before transformation
2import { Suspense } from "react";
3<Suspense fallback={<Loading />}>
4  <MyComponent />
5</Suspense>
6
7// After transformation
8import { Suspense } from "react";
9import { BoundaryTrackerSWC } from "react-swc-suspense-tracker/context";
10<BoundaryTrackerSWC Component={Suspense} fallback={<Loading />} id="my/file.tsx:123">
11  <MyComponent />
12</BoundaryTrackerSWC>

Custom logger

For custom logging or logging in production you can use the useSuspenseOwner hook to get the ID of the nearest Suspense boundary:

1import { 
2  useSuspenseOwner,
3} from "react-swc-suspense-tracker";
4function MyComponent() {
5  const suspenseOwner = useSuspenseOwner();
6  
7  // Log the Suspense boundary ID
8  console.log("Closest Suspense boundary ID:", suspenseOwner);
9
10  const data = useSomeDataHook(); // This might suspend
11  return <div>{data}</div>;
12}

API Reference

Hooks

useSuspenseOwner(): string | null

Returns the ID of the nearest Suspense boundary above this component. The ID format is "file.tsx:line" if set by the SWC plugin, or a custom string if set manually.

Returns null if no Suspense boundary is found.

useBoundaryStack(): Array<[string, ComponentType]>

Returns information about all boundary components above this component as an array of [boundaryId, BoundaryComponent] tuples, ordered from outermost to innermost boundary.

Returns empty array if no boundaries are found.

useThrowIfSuspenseMissing(skip?: boolean): void

Throws an error in development if this component might suspend but has no Suspense boundary above it - NOOP in production builds

Parameters:

• skip (optional): If true, skips the check. Defaults to false.

Throws: Error with message explaining the missing Suspense boundary.

wrapSuspendableHook<T>(hook: T, onSuspense: (suspenseBoundaries: string[], ...args: Parameters<T>) => void): T

Wraps a hook to catch Suspense errors and call the provided onSuspense function with the current Suspense boundary information.

Parameters:

• hook: The hook function to wrap
• onSuspense: Function called when the hook suspends, receives array of Suspense boundary IDs

Returns: A wrapped version of the hook with the same signature.

Development vs Production

This package is designed for development use only. The SWC plugin should be disabled in production builds to avoid the additional runtime overhead.

Build

Get the Rust toolchain and the right target:

1rustup target add wasm32-wasip1
2npm run build

The compiled Wasm module will be available as react_swc_suspense_tracker.wasm.

License

MIT