@suspensive/react#

@suspensive/react provides declarative components and hooks that fill gaps in React's built-in Suspense, error boundary, and lazy primitives. Runtime exports: Suspense, ErrorBoundary, ErrorBoundaryGroup, Delay, ClientOnly, DefaultPropsProvider, DefaultProps, lazy, createLazy, reloadOnError, useErrorBoundary, useErrorBoundaryFallbackProps, useErrorBoundaryGroup, useIsClient. Type exports: SuspenseProps, ErrorBoundaryProps, ErrorBoundaryFallbackProps, ErrorBoundaryGroupProps, DelayProps, ClientOnlyProps. Requires React >= 18 (native useSyncExternalStore).

Every component (Suspense, ErrorBoundary, ErrorBoundaryGroup, Delay, ClientOnly) exposes a static .with(props, Component) HOC that wraps Component with that boundary.

CRITICAL: All Suspensive components are client components ('use client'). Never render them directly in a React Server Component — render-prop children are functions, which cannot cross the RSC serialization boundary. Put them inside a component marked 'use client'.

CRITICAL: These APIs were removed and must never be generated: the wrap builder (wrap.ErrorBoundary(...).Suspense(...).on(...), removed in v3 — use .with()), AsyncBoundary and the withSuspense/withDelay/withErrorBoundary/withErrorBoundaryGroup HOCs (removed in v2 — compose ErrorBoundary + Suspense or use .with()), Suspense.CSROnly (removed in v2 — use the clientOnly prop), and ErrorBoundaryGroup.Reset (removed in v2 — use ErrorBoundaryGroup.Consumer). Agents trained on older code still generate all of these. See migrate-to-v3.

CRITICAL: The component returned by .with() rejects extra static properties (router loaders etc.) at the type level. Attach statics with Object.assign(Suspense.with(props, Component), { loader }), not direct assignment.

Sub-Skills#

Quick Decision Tree#

Need to...
├─ catch render errors / filter by error type / reset boundaries
│    → error-handling (ErrorBoundary, shouldCatch, ErrorBoundaryGroup)
├─ show a loading fallback / avoid a 50ms spinner flash / set one default fallback
│    → loading-ux (Suspense, Delay, DefaultPropsProvider)
├─ skip SSR for a subtree / read browser APIs without hydration mismatch
│    → ssr-client-only (Suspense clientOnly, ClientOnly, useIsClient)
├─ code-split with preloading / survive stale-chunk errors after a deploy
│    → code-splitting (lazy, createLazy, reloadOnError)
└─ upgrade code that uses wrap / AsyncBoundary / withSuspense / Suspense.CSROnly
     → migrate-to-v3 (codemods, old→new API table)

Minimal Working Example#

'use client'
import { Delay, ErrorBoundary, Suspense } from '@suspensive/react'
import { UserProfile } from './UserProfile'

export const UserSection = () => (
  <ErrorBoundary
    fallback={({ error, reset }) => (
      <div>
        <p>{error.message}</p>
        <button onClick={reset}>Try again</button>
      </div>
    )}
  >
    <Suspense
      fallback={
        <Delay ms={200}>
          <div>Loading...</div>
        </Delay>
      }
    >
      <UserProfile />
    </Suspense>
  </ErrorBoundary>
)

The same tree with the .with() HOC pattern:

'use client'
import { ErrorBoundary, Suspense } from '@suspensive/react'
import { UserProfile } from './UserProfile'

export const UserSection = ErrorBoundary.with(
  { fallback: ({ error }) => <p>{error.message}</p> },
  Suspense.with({ fallback: <div>Loading...</div> }, () => <UserProfile />)
)

Common Mistakes#

HIGH Rendering Suspensive components in a Server Component#

Wrong:

// app/page.tsx — Server Component
import { Suspense } from '@suspensive/react'

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Content />
    </Suspense>
  )
}

Correct:

// app/page.tsx — Server Component
import { ContentSection } from './ContentSection'

export default function Page() {
  return <ContentSection />
}

// ContentSection.tsx
'use client'
import { Suspense } from '@suspensive/react'
import { Content } from './Content'

export const ContentSection = () => (
  <Suspense fallback={<div>Loading...</div>}>
    <Content />
  </Suspense>
)

All Suspensive components are client-only ('use client'), so using them directly in an RSC fails the build or errors at render.

Source: https://github.com/toss/suspensive/issues/1563

MEDIUM Attaching static properties to .with() result directly#

Wrong:

import { Suspense } from '@suspensive/react'

const Page = Suspense.with({ fallback: <div>Loading...</div> }, PageComponent)
Page.loader = loader // type error
export default Page

Correct:

import { Suspense } from '@suspensive/react'

export default Object.assign(Suspense.with({ fallback: <div>Loading...</div> }, PageComponent), { loader })

The component type returned by .with() rejects extra static properties, so router loaders and similar statics must be merged with Object.assign.

Source: https://github.com/toss/suspensive/issues/1665

Version#

Targets @suspensive/react v3.21.2. Requires React >= 18.0.