DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

Error Boundaries

Handle errors with error.tsx - catches errors in the child tree and shows fallback UI. Layouts stay visible.

Overview

Every layout and page is wrapped in an error boundary that resets on navigation. Add error.tsx in a folder for custom fallback UI. It is a special file - it does not create a URL. Nearest-wins applies.

error.tsx
export default function Error({ error, reset}) {
  return (
    <>
      An error occurred: {error.message}
      <button onClick={() => reset()}>Retry</button>
    </>
  );
}
Component hierarchy
<Layout>
  <ErrorBoundary fallback={<Error />}>
    <Page />
  </ErrorBoundary>
</Layout>
Error...
FilePurpose
src/app/error.tsxFallback for routes without a closer error file
src/app/dashboard/error.tsxDashboard segment only
src/app/blog/[slug]/error.tsxBlog post segment only
Layouts stay mounted. The error UI replaces the page (or segment) inside the boundary - not the whole app shell.

Creating an Error Boundary

Create error.tsx in any folder for that route and its children. The file default-exports a React component that receives error and reset.

app
layout.tsx
page.tsx
dashboard
layout.tsx
page.tsx
error.tsx
/
/dashboard
src/app/dashboard/error.tsx
export default function DashboardError({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div className="mx-auto max-w-2xl p-6">
      <div className="rounded-lg border border-neutral-200 p-6 dark:border-neutral-800">
        <h2 className="mb-2 text-xl font-bold text-black dark:text-white">
          Something went wrong
        </h2>
        <p className="mb-4 text-neutral-600 dark:text-neutral-400">
          {error.message}
        </p>
        <button
          onClick={reset}
          className="rounded-lg bg-black px-4 py-2 font-medium text-white dark:bg-white dark:text-black"
        >
          Try again
        </button>
      </div>
    </div>
  )
}

Error Props

The component receives two props from the boundary.

PropTypeDescription
errorErrorThrown Error object with message and stack
reset() => voidClears error state and re-renders children
src/app/dashboard/error.tsx
export default function DashboardError({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  console.error('Dashboard error:', error)

  return (
    <div>
      <h2>Something went wrong!</h2>
      <details className="mt-4 rounded border border-neutral-200 bg-neutral-50 p-4 dark:border-neutral-800 dark:bg-neutral-900">
        <summary className="cursor-pointer">Error details</summary>
        <pre className="mt-2 whitespace-pre-wrap text-xs">{error.stack}</pre>
      </details>
      <button
        onClick={reset}
        className="mt-4 rounded bg-black px-4 py-2 text-white dark:bg-white dark:text-black"
      >
        Try again
      </button>
    </div>
  )
}

Nested Error Boundaries

Place error.tsx in subdirectories. Each only catches errors in its subtree.

app
error.tsx
layout.tsx
page.tsx
blog
error.tsx
page.tsx
[slug]
page.tsx
dashboard
error.tsx
page.tsx
settings
error.tsx
page.tsx
/
/blog
/blog/:slug
/dashboard
/dashboard/settings
RouteError Boundary Used
/blog/hello-worldsrc/app/blog/error.tsx
/dashboardsrc/app/dashboard/error.tsx
/dashboard/settingssrc/app/dashboard/settings/error.tsx
/aboutsrc/app/error.tsx (global fallback)

Nearest Wins Resolution

The closest error.tsx to the route where the error occurred is used.

  1. Check the route's own folder for error.tsx
  2. If not found, walk up parent folders
  3. If still not found, use the built-in fallback

Error with Layout

Error UI is shown inside the layout hierarchy. Headers, sidebars, and nav stay visible when a child route errors.

app
layout.tsx
error.tsx
blog
layout.tsx
error.tsx
page.tsx
/blog
Error UI replaces only the page (or segment) - not the surrounding layout.

Built-in Fallback

If no error.tsx exists in scope, Bini.js uses a built-in fallback.

  • Development: Renders nothing so Vite / bini-overlay can show the error
  • Production: Generic "Something went wrong" UI with a retry button
  • Logging: Runtime errors dispatch a __bini_error__ CustomEvent on window for external overlays
Custom error UIs are recommended for production. Boundaries also reset when the pathname changes.

Complete Example

Special files do not create URLs. Pages do.

app
layout.tsx
error.tsx
page.tsx
blog
layout.tsx
error.tsx
page.tsx
dashboard
layout.tsx
error.tsx
page.tsx
/
/blog
/dashboard
FileRole
error.tsxSegment error boundary
layout.tsxWraps segment + children
page.tsxRoute content
loading.tsxSuspense fallback

Loading UI

Show a fallback while pages and layouts load.

Template

Wrap each page individually inside the layout chain.

Not Found

Handle unmatched URLs with a custom 404 page.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousLoading UI
NextTemplates

On this page

  • Overview
  • Creating an Error Boundary
  • Error Props
  • Nested Error Boundaries
  • Nearest Wins Resolution
  • Error with Layout
  • Built-in Fallback
  • Complete Example
Edit this page on GitHub

Error Boundaries

Handle errors with error.tsx - catches errors in the child tree and shows fallback UI. Layouts stay visible.

Overview

Every layout and page is wrapped in an error boundary that resets on navigation. Add error.tsx in a folder for custom fallback UI. It is a special file - it does not create a URL. Nearest-wins applies.

error.tsx
export default function Error({ error, reset}) {
  return (
    <>
      An error occurred: {error.message}
      <button onClick={() => reset()}>Retry</button>
    </>
  );
}
Component hierarchy
<Layout>
  <ErrorBoundary fallback={<Error />}>
    <Page />
  </ErrorBoundary>
</Layout>
Error...
FilePurpose
src/app/error.tsxFallback for routes without a closer error file
src/app/dashboard/error.tsxDashboard segment only
src/app/blog/[slug]/error.tsxBlog post segment only
Layouts stay mounted. The error UI replaces the page (or segment) inside the boundary - not the whole app shell.

Creating an Error Boundary

Create error.tsx in any folder for that route and its children. The file default-exports a React component that receives error and reset.

app
layout.tsx
page.tsx
dashboard
layout.tsx
page.tsx
error.tsx
/
/dashboard
src/app/dashboard/error.tsx
export default function DashboardError({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div className="mx-auto max-w-2xl p-6">
      <div className="rounded-lg border border-neutral-200 p-6 dark:border-neutral-800">
        <h2 className="mb-2 text-xl font-bold text-black dark:text-white">
          Something went wrong
        </h2>
        <p className="mb-4 text-neutral-600 dark:text-neutral-400">
          {error.message}
        </p>
        <button
          onClick={reset}
          className="rounded-lg bg-black px-4 py-2 font-medium text-white dark:bg-white dark:text-black"
        >
          Try again
        </button>
      </div>
    </div>
  )
}

Error Props

The component receives two props from the boundary.

PropTypeDescription
errorErrorThrown Error object with message and stack
reset() => voidClears error state and re-renders children
src/app/dashboard/error.tsx
export default function DashboardError({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  console.error('Dashboard error:', error)

  return (
    <div>
      <h2>Something went wrong!</h2>
      <details className="mt-4 rounded border border-neutral-200 bg-neutral-50 p-4 dark:border-neutral-800 dark:bg-neutral-900">
        <summary className="cursor-pointer">Error details</summary>
        <pre className="mt-2 whitespace-pre-wrap text-xs">{error.stack}</pre>
      </details>
      <button
        onClick={reset}
        className="mt-4 rounded bg-black px-4 py-2 text-white dark:bg-white dark:text-black"
      >
        Try again
      </button>
    </div>
  )
}

Nested Error Boundaries

Place error.tsx in subdirectories. Each only catches errors in its subtree.

app
error.tsx
layout.tsx
page.tsx
blog
error.tsx
page.tsx
[slug]
page.tsx
dashboard
error.tsx
page.tsx
settings
error.tsx
page.tsx
/
/blog
/blog/:slug
/dashboard
/dashboard/settings
RouteError Boundary Used
/blog/hello-worldsrc/app/blog/error.tsx
/dashboardsrc/app/dashboard/error.tsx
/dashboard/settingssrc/app/dashboard/settings/error.tsx
/aboutsrc/app/error.tsx (global fallback)

Nearest Wins Resolution

The closest error.tsx to the route where the error occurred is used.

  1. Check the route's own folder for error.tsx
  2. If not found, walk up parent folders
  3. If still not found, use the built-in fallback

Error with Layout

Error UI is shown inside the layout hierarchy. Headers, sidebars, and nav stay visible when a child route errors.

app
layout.tsx
error.tsx
blog
layout.tsx
error.tsx
page.tsx
/blog
Error UI replaces only the page (or segment) - not the surrounding layout.

Built-in Fallback

If no error.tsx exists in scope, Bini.js uses a built-in fallback.

  • Development: Renders nothing so Vite / bini-overlay can show the error
  • Production: Generic "Something went wrong" UI with a retry button
  • Logging: Runtime errors dispatch a __bini_error__ CustomEvent on window for external overlays
Custom error UIs are recommended for production. Boundaries also reset when the pathname changes.

Complete Example

Special files do not create URLs. Pages do.

app
layout.tsx
error.tsx
page.tsx
blog
layout.tsx
error.tsx
page.tsx
dashboard
layout.tsx
error.tsx
page.tsx
/
/blog
/dashboard
FileRole
error.tsxSegment error boundary
layout.tsxWraps segment + children
page.tsxRoute content
loading.tsxSuspense fallback

Loading UI

Show a fallback while pages and layouts load.

Template

Wrap each page individually inside the layout chain.

Not Found

Handle unmatched URLs with a custom 404 page.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousLoading UI
NextTemplates

On this page

  • Overview
  • Creating an Error Boundary
  • Error Props
  • Nested Error Boundaries
  • Nearest Wins Resolution
  • Error with Layout
  • Built-in Fallback
  • Complete Example
Edit this page on GitHub