Suspensive Documentation

Suspensive is a library designed to fill the functional gaps in React's core async rendering primitives (Suspense, Error Boundary, and lazy). It provides declarative components and hooks to handle real-world application requirements such as skipping SSR for specific boundaries, preventing loading spinner flashes, managing hydration mismatches, and coordinating error handling across multiple boundaries.

Beyond React, Suspensive provides specialized integrations for:

• TanStack Query (@suspensive/react-query): Simplifies Suspense integration, SSR prefetching, and error handling during hydration.
• Jotai (@suspensive/jotai): Makes atom-based state management compatible with Suspense and other data-fetching layers.
• React Core (@suspensive/react): Enhances Suspense, ErrorBoundary, and lazy with features like clientOnly boundaries, error filtering, and preloading.

Suspensive is a collection of declarative React components and hooks designed to bridge the practical gaps in React's native features like Suspense, Error Boundaries, and lazy.

Core Philosophy: Declare boundaries (error handling, loading states) and data-fetching (queries, mutations) as JSX at the same depth using render props. This allows your functional components to focus exclusively on the "success case," as the surrounding Suspensive components handle the loading and error states.

@suspensive/react provides declarative components and hooks to enhance React's built-in Suspense, error boundary, and lazy primitives. It is designed for React 18+ and focuses on improving loading UX, error handling, SSR/client-only rendering, and code-splitting.

Core Runtime Exports:

• Boundaries: Suspense, ErrorBoundary, ErrorBoundaryGroup
• UX/SSR: Delay, ClientOnly, useIsClient
• Error Handling: useErrorBoundary, useErrorBoundaryFallbackProps
• Code Splitting: lazy, createLazy, reloadOnError
• Configuration: DefaultPropsProvider, DefaultProps
• Pattern: All boundary components expose a .with(props, Component) HOC pattern.

Suspensive's lazy implementation extends standard lazy loading with two critical production features:

1. Preloading: Use the .load() method to preload chunks before they are needed.
2. Recovery: It provides automatic retry logic if a chunk fails to load (e.g., due to network issues).

Prefetch APIs (usePrefetchQuery, usePrefetchInfiniteQuery, PrefetchQuery, and PrefetchInfiniteQuery) fire a fetch during the render phase—before a Suspense boundary below them suspends. This warms the cache so that subsequent suspense queries find the data immediately instead of starting a new request.

Key characteristics:

• They return nothing.
• They never suspend.
• They never throw errors (errors surface later through the suspense query that reads the cache).
• You must use the exact same queryOptions (including queryKey) for both the prefetch and the suspense query to ensure a cache hit.

@suspensive/jotai provides three render-prop components that wrap Jotai hooks. This allows you to read or write atoms inline within JSX (e.g., inside loops or conditionals) without needing to extract a new component just to use a hook.

Key Characteristics:

• Client-only: All components are 'use client' and cannot cross the React Server Components (RSC) serialization boundary.
• Suspense Integration: Async atoms (or writing a Promise via SetAtom) will trigger the nearest parent Suspense boundary. A Suspense boundary must exist above these components to prevent blanking the UI.
• Props: Each component accepts an atom prop and an optional options prop (which is forwarded to the underlying Jotai hook, such as { store }).

The components provided by @suspensive/jotai (specifically <Atom/>, <AtomValue/>, and <SetAtom/>) are compatible with the existing Jotai extension ecosystem. This means atoms created via extensions like tRPC, Query (e.g., jotai-tanstack-query), or Cache work out of the box without requiring additional wrappers.

import { AtomValue } from '@suspensive/jotai'
import { Suspense, ErrorBoundary } from '@suspensive/react'
import { userQueryAtom } from '~/queries' // Example: atom from jotai-tanstack-query

const MyPage = () => (
  <ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
    <Suspense fallback={'pending...'}>
      <AtomValue atom={userQueryAtom}>
        {({ data: user }) => <UserProfile key={user.id} {...user} />}
      </AtomValue>
    </Suspense>
  </ErrorBoundary>
)