Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Resources, Suspense and Async

Error Boundaries and Lazy Loading

Catch rendering and resource errors with ErrorBoundary and reset them, then split your bundle with lazy components and dynamic imports in SolidJS.

Two things go wrong in real apps: errors, because networks fail and data is not what you expected, and size, because shipping every screen to every visitor makes the first load slow. Solid has a small tool for each: ErrorBoundary contains failures, and lazy loads a component only when it is needed. Both cooperate with Suspense.

ErrorBoundary

If a component throws while rendering, or a resource it reads is in the errored state, the error travels up the tree. Without a catcher, the whole app breaks. ErrorBoundary is the catcher:

JSX
<ErrorBoundary fallback={(err, reset) => (
  <div>
    <p>Something went wrong: {err.message}</p>
    <button onClick={reset}>Try again</button>
  </div>
)}>
  <Profile />
</ErrorBoundary>

The fallback can be plain JSX or a function. As a function it receives the error and a reset function. Calling reset() re-renders the children, which is how a "try again" button works; because the children are created again, a resource inside them fetches again.

Catch a failing resource

The first two attempts fail and show the fallback; the third succeeds. Notice the order: Suspense sits inside the boundary, so loading and failure are handled by different components.

What ErrorBoundary does not catch

An error boundary only catches errors thrown during rendering and reactive computations below it. It does not catch:

  • errors inside event handlers (onClick), which behave like normal JavaScript errors,
  • errors in setTimeout or other callbacks you started yourself,
  • rejected promises that nothing reads (a bare fetch(...) with no .catch).

For those, use try/catch or .catch yourself. A common pattern is to catch in the handler and set an error signal that the UI shows.

JSX
<button onClick={async () => {
  try { await save(); }
  catch (e) { setMessage("Could not save: " + e.message); }
}}>Save</button>

Where to put boundaries

One boundary around the whole app is a safety net. Boundaries around independent widgets (a chart, a comments list) are better: one broken widget does not take the page down.

Lazy loading with lazy()

lazy wraps a dynamic import(). The component's code is downloaded the first time it is rendered, not at page load.

JSX
import { lazy, Suspense } from "solid-js";

const Settings = lazy(() => import("./Settings"));

function App() {
  return (
    <Suspense fallback={<p>Loading settings...</p>}>
      <Settings />
    </Suspense>
  );
}

Three facts to remember:

  1. The module must default export the component.
  2. A lazy component suspends while its code downloads, so it needs a Suspense above it (the router adds one for route components).
  3. Bundlers (Vite) turn each import() into a separate file, so the code split happens automatically.

Lazy components are most valuable at route level (each page in its own chunk) and for heavy, rarely used UI: a rich-text editor, a chart library, a modal that few users open.

A lazy component (simulated import)

The first toggle shows the "Downloading" fallback for a second. Toggle off and on again: the chart appears instantly, because the module was already loaded (the counter stays at 1).

Preloading

lazy components have a .preload() method that starts the download without rendering. You can call it on hover so the click feels instant:

JSX
<button onMouseEnter={() => Settings.preload()} onClick={() => setOpen(true)}>
  Settings
</button>

Putting it together

A robust section of UI usually nests all three: the boundary on the outside, Suspense inside it, and lazy or resource-reading components inside that.

JSX
<ErrorBoundary fallback={(e, reset) => <Failed error={e} retry={reset} />}>
  <Suspense fallback={<Skeleton />}>
    <LazyDashboard />
  </Suspense>
</ErrorBoundary>

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the second argument of an ErrorBoundary fallback function do?

    reset() clears the caught error and re-renders the children, which powers a 'try again' button.
  2. 2. Which error is NOT caught by an ErrorBoundary?

    Event handlers run outside the reactive render flow, so use try/catch there.
  3. 3. What must a module expose to be loaded with lazy()?

    lazy expects the dynamic import to resolve to a module whose default export is the component.
  4. 4. Why does a lazy component need a Suspense above it?

    The download counts as loading, so the nearest Suspense shows the fallback until the code arrives.

Summary

  • ErrorBoundary catches render-time and reactive errors; its fallback gets (error, reset).
  • It does not catch errors in event handlers or free-standing promises: handle those yourself.
  • lazy(() => import(...)) splits code; the module needs a default export and a Suspense above.
  • Call .preload() on hover or idle to hide the download delay.
  • Nest ErrorBoundary outside Suspense around independent sections.

Next: Async Patterns: Debounce, Optimistic Updates and Cancellation