Suspensive
Suspensive is a comprehensive collection of libraries designed to simplify and enhance the use of React Suspense. Suspensive contains several packages that provide components, hooks, and utilities to streamline the implementation of suspense-based features, error handling, and integrations with popular data fetching libraries.
Purpose
The Suspensive libraries address common challenges developers face when working with React Suspense, such as:
- Managing loading states and timing
- Implementing robust error boundaries
- Integrating suspense with data fetching libraries
- Coordinating multiple suspense and error boundaries
- Creating viewport-aware components with suspense capabilities
By providing a unified, declarative API for these concerns, Suspensive helps developers create more resilient and better-structured React applications with significantly less boilerplate code.
Core Packages
Package Responsibilities
| Package | Description | Key Features |
|---|---|---|
| @suspensive/react | Core suspense components | ErrorBoundary, Suspense, Delay, ErrorBoundaryGroup |
| @suspensive/react-dom | DOM-specific components | InView |
| @suspensive/react-query | TanStack Query integration | SuspenseQuery, SuspenseInfiniteQuery, Version detection |
| @suspensive/jotai | Jotai integration | useAtomValue, useAtom, useSetAtom |
| @suspensive/codemods | Migration utilities | Automated code transformations |
Architecture and Component Relationships
The Suspensive ecosystem is built on a foundation of core components from @suspensive/react, which are then extended and specialized by other packages:
Version Support and Compatibility
Suspensive is designed to work with:
- React 18 and React 19
- TanStack Query v4 and v5
- Jotai v2
The library automatically adapts to the installed versions of these dependencies, providing a seamless developer experience regardless of which specific versions are being used in a project.
Data Flow Pattern
A central pattern in Suspensive is the handling of asynchronous states through React Suspense. Here’s how data flows through the system when using components like SuspenseQuery:
Key Benefits
- Declarative Error Handling: Replace try/catch blocks with component-based error boundaries
- Simplified Data Fetching: Integrate seamlessly with TanStack Query using suspense
- Coordinated Error Management: Group and reset multiple error boundaries together
- Controlled Loading States: Fine-tune loading indicators with timing controls
- Viewport Awareness: Trigger loading or animations based on viewport visibility