Connect Remix to Bugsink

Remix runs application code in the browser and on the server. Bugsink can capture failures from both sides, including the route and request that led to them.

This guide initializes the open-source Sentry SDK for Remix, connects its server and browser lifecycles, and uploads production source maps. To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the Remix SDK

Install the framework SDK in the application. Bugsink accepts the Sentry event protocol, so this SDK can send Remix errors directly to your Bugsink project:

npm install @sentry/remix

Initialize the server SDK

Create instrument.server.mjs beside package.json. autoInstrumentRemix wraps Remix’s server runtime so loader and action failures are captured with their route and request context:

import * as Sentry from "@sentry/remix";


Sentry.init({
  dsn: process.env.SENTRY_DSN,
  autoInstrumentRemix: true,
});

Load this file before Remix starts. NODE_OPTIONS makes Node import it early enough for the SDK to instrument the framework:

SENTRY_DSN=https://key@bugsink.example/1 \
NODE_OPTIONS=--import=./instrument.server.mjs \
npm start

Connect the server error handler

Export sentryHandleError from app/entry.server.jsx. Remix calls this hook for server rendering failures in addition to the loader and action coverage provided by automatic instrumentation:

import * as Sentry from "@sentry/remix";

export const handleError = Sentry.sentryHandleError;

Initialize the browser SDK

Initialize the same project from app/entry.client.jsx. A DSN identifies the destination project and is safe to include in browser code; Vite exposes the value at build time through its VITE_ prefix:

import { RemixBrowser } from "@remix-run/react";
import * as Sentry from "@sentry/remix";
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";


Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
});

startTransition(() => {
  hydrateRoot(document, <StrictMode><RemixBrowser /></StrictMode>);
});

Capture errors rendered by a route boundary

Remix sends route rendering errors to the nearest ErrorBoundary. Call captureRemixErrorBoundaryError there so the browser failure reaches Bugsink before the boundary renders its fallback interface:

import { captureRemixErrorBoundaryError } from "@sentry/remix";
import { useRouteError } from "@remix-run/react";


export default function BrokenInventoryPanel() {
  throw new Error("Inventory panel could not render [remix-browser]");
}

export function ErrorBoundary() {
  captureRemixErrorBoundaryError(useRouteError());
  return <h1>Inventory is temporarily unavailable</h1>;
}

Use the same call in each route boundary that should report its error. Errors which reach the root boundary still need the call there; defining a boundary changes normal Remix rendering rather than bypassing it.

Upload production source maps

Production builds bundle and minify browser code. Source maps let Bugsink show the original route file and line instead of only a generated JavaScript frame.

Create hidden maps during the build

Enable hidden maps in vite.config.js. Hidden maps are emitted without a browser-visible reference, leaving them available to the release process:

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";


export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [remix()],
});

Build with the browser DSN that belongs to the destination project:

VITE_SENTRY_DSN=https://key@bugsink.example/1 npm run build

Inject debug IDs and upload the maps

Create a project-bound Bugsink token with the debug-files:upload capability. Keep the token in the release environment; unlike the DSN, it must never be included in the browser bundle:

npx --yes @sentry/cli sourcemaps inject build
SENTRY_AUTH_TOKEN=your-project-token \
npx --yes @sentry/cli \
  --url https://bugsink.example \
  sourcemaps --org bugsink --project your-project-slug upload build
find build/client -name '*.map' -delete

Bugsink has no organization object, so --org is only a compatibility value. Upload the maps before this build can receive production traffic, then remove them from the deployable output as shown above.

Check a server loader

Loader failures are reported automatically. This route deliberately requests an inventory item that does not exist:

export async function loader({ params }) {
  const products = new Map([["desk-lamp", { name: "Desk lamp", available: 0 }]]);
  const product = products.get(params.sku);

  if (!product) {
    throw new ProductNotFound(`Product ${params.sku} is not in inventory [remix-server]`);
  }
  return product;
}

Start the production server with instrument.server.mjs preloaded, then open http://127.0.0.1:3000/products/missing. Remix follows its normal error path and the SDK reports the failed loader in the background.

In Bugsink, the issue includes the concrete request and the original loader line rather than only a framework stack.

Bugsink preview

Server loader failures now reach Bugsink with their route and request context.

Check a browser route error

Open the application and follow the Open a broken inventory panel link. The route boundary renders its fallback page while sending the original error to Bugsink.

The uploaded map translates the production bundle back to the route component and exact statement that threw.

Bugsink preview

That’s it: server and browser errors from the production Remix application now arrive in Bugsink, and browser stacktraces point back to their original source.

Limitations

Remix 2.17.5 is the newest Remix 2 package set in the npm registry, but npm audit --omit=dev currently reports known vulnerabilities in its production dependency tree. Review those advisories and the React Router migration path before choosing Remix 2 for a new production application.

With Remix 2.17.5 and @sentry/remix 11.15.0, one error handled by a route ErrorBoundary produced two matching browser events in the reproduced production flow. Both events contained the same mapped application frame.

The CLI also uploads the server bundle’s map, but this SDK version does not put its debug ID in the captured server event. Node still provides the original loader source and context locally, as the server result above shows.

For SDK-wide capture options and other browser and server frameworks, return to the JavaScript guide.