toss/suspensive

What is Suspensive?

React gives you Suspense, lazy, and an interface to build Error Boundaries — but using them in real applications reveals gaps. Suspensive fills those gaps with declarative components and hooks.

import { Delay, ErrorBoundary, ErrorBoundaryGroup, Suspense } from '@suspensive/react'

const Page = () => (
  <ErrorBoundaryGroup>
    <ErrorBoundaryGroup.Consumer>
      {({ reset }) => <button onClick={reset}>Reset All</button>}
    </ErrorBoundaryGroup.Consumer>
    <ErrorBoundary
      shouldCatch={NetworkError}
      fallback={({ error, reset }) => <ErrorUI error={error} onRetry={reset} />}
    >
      <Suspense
        clientOnly
        fallback={
          <Delay ms={200}>
            {({ isDelayed }) => <Spinner style={{ opacity: isDelayed ? 1 : 0, transition: 'opacity 200ms' }} />}
          </Delay>
        }
      >
        <Content />
      </Suspense>
    </ErrorBoundary>
  </ErrorBoundaryGroup>
)

• shouldCatch — catch only specific error types, let others propagate
• ErrorBoundaryGroup — reset multiple error boundaries at once, no prop drilling
• clientOnly — skip SSR for a Suspense boundary (fallback on server, children on client)
• Delay — prevent flash-of-loading-state with render props for smooth fade-in
• reset — built into the fallback props, no external state needed

Packages

Package	Description	Version
@suspensive/react	Suspense, ErrorBoundary, ErrorBoundaryGroup, Delay, ClientOnly
@suspensive/react-query	SuspenseQuery, SuspenseInfiniteQuery, Mutation, PrefetchQuery
@suspensive/jotai	Atom, AtomValue, SetAtom for Jotai integration
@suspensive/codemods	Automated migration codemods

Key Features

• <ErrorBoundary/> with shouldCatch — catch only the errors you want (comparison with react-error-boundary)
• <ErrorBoundaryGroup/> — reset multiple error boundaries at once, no prop drilling
• <Suspense/> with clientOnly — declaratively skip SSR for a boundary when you need client-only rendering
• <SuspenseQuery/> — declarative data fetching as JSX, no hook constraints
• <Delay/> — prevent flash-of-loading-state UX issues
• <DefaultPropsProvider/> — set global default fallbacks for all components

Getting Started

npm install @suspensive/react

Visit suspensive.org for full documentation.

English | 한국어

Contributors

Read our Contributing Guide to familiarize yourself with Suspensive's development process, how to suggest bug fixes and improvements, and the steps for building and testing your changes.

MIT © Viva Republica, Inc. See LICENSE for details.