Connect Nuxt to Bugsink
Nuxt runs application code in the browser and in its Nitro server. Bugsink can capture failures from both sides, including the request for a failed API route, and use production source maps to show the original Vue and TypeScript code.
This guide adds the Nuxt SDK, sends a deliberate browser error and server API error, and uploads the production source maps for both builds. To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the Nuxt SDK
Install the open-source Sentry SDK for Nuxt. Bugsink accepts the SDK’s event protocol, so browser and Nitro errors can go directly to your Bugsink project:
npm install @sentry/nuxtnpm install @sentry/nuxt
Add the Nuxt module
Register the SDK module in nuxt.config.ts. Keep hidden source maps for the
client and server builds: they are available for upload but are not published
alongside the application bundles.
The release operations are disabled because debug-ID source maps do not need a release in Bugsink. The DSN is exposed through Nuxt’s public runtime config so the browser configuration can read it:
export default defineNuxtConfig({ compatibilityDate: "2026-11-01", devtools: { enabled: false }, modules: ["@sentry/nuxt/module"], sourcemap: { client: "hidden", server: "hidden", }, sentry: { telemetry: false, release: { name: "", create: false, inject: false, }, }, runtimeConfig: { public: { sentryDsn: process.env.NUXT_PUBLIC_SENTRY_DSN, }, }, });export default defineNuxtConfig({ compatibilityDate: "2026-11-01", devtools: { enabled: false }, modules: ["@sentry/nuxt/module"], sourcemap: { client: "hidden", server: "hidden", }, sentry: { telemetry: false, release: { name: "", create: false, inject: false, }, }, runtimeConfig: { public: { sentryDsn: process.env.NUXT_PUBLIC_SENTRY_DSN, }, }, });
Initialize the browser and server SDKs
Create sentry.client.config.ts in the project root. Nuxt loads it before the
browser application, allowing the SDK to capture Vue errors, uncaught errors,
and unhandled promise rejections:
import * as Sentry from "@sentry/nuxt"; const config = useRuntimeConfig(); Sentry.init({ dsn: config.public.sentryDsn, });import * as Sentry from "@sentry/nuxt"; const config = useRuntimeConfig(); Sentry.init({ dsn: config.public.sentryDsn, });
Create sentry.server.config.ts beside it. The Nitro process reads its DSN
from the server environment, so it does not need to expose the value through
the browser runtime config:
import * as Sentry from "@sentry/nuxt"; Sentry.init({ dsn: process.env.SENTRY_DSN, });import * as Sentry from "@sentry/nuxt"; Sentry.init({ dsn: process.env.SENTRY_DSN, });
Upload the production source maps
Source maps turn minified production frames back into the Vue components and TypeScript modules you edit. The Nuxt plugins generate maps and inject debug IDs into the browser and Nitro bundles, but their automatic uploader is not currently compatible with Bugsink. The explicit upload below is the tested route; the exact boundary is described under Limitations.
Preserve the plugin’s debug IDs
The generated bundles already contain the IDs that the SDK will put on events.
Before upload, copy each existing ID into its corresponding map. Add this small
post-build script as scripts/stamp-source-maps.mjs:
import { readdir, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; const outputDirectory = fileURLToPath(new URL("../.output/", import.meta.url)); const debugIdPattern = /sentry-dbid-([0-9a-f-]{36})/i; let stamped = 0; async function visit(directory) { for (const entry of await readdir(directory, { withFileTypes: true })) { const path = join(directory, entry.name); if (entry.isDirectory()) { await visit(path); continue; } if (!entry.name.endsWith(".js") && !entry.name.endsWith(".mjs")) { continue; } let bundle = await readFile(path, "utf8"); const match = bundle.match(debugIdPattern); if (!match) continue; const mapPath = `${path}.map`; let sourceMap; try { sourceMap = JSON.parse(await readFile(mapPath, "utf8")); } catch (error) { if (error.code === "ENOENT") continue; throw error; } const debugId = match[1]; if (!bundle.includes("//# debugId=")) { bundle += `\n//# debugId=${debugId}`; await writeFile(path, bundle); } sourceMap.debug_id = debugId; sourceMap.debugId = debugId; await writeFile(mapPath, JSON.stringify(sourceMap)); stamped += 1; } } await visit(outputDirectory); if (stamped === 0) { throw new Error("Nuxt produced no source maps with Sentry debug IDs"); } console.log(`Prepared ${stamped} Nuxt source maps for upload`);import { readdir, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; const outputDirectory = fileURLToPath(new URL("../.output/", import.meta.url)); const debugIdPattern = /sentry-dbid-([0-9a-f-]{36})/i; let stamped = 0; async function visit(directory) { for (const entry of await readdir(directory, { withFileTypes: true })) { const path = join(directory, entry.name); if (entry.isDirectory()) { await visit(path); continue; } if (!entry.name.endsWith(".js") && !entry.name.endsWith(".mjs")) { continue; } let bundle = await readFile(path, "utf8"); const match = bundle.match(debugIdPattern); if (!match) continue; const mapPath = `${path}.map`; let sourceMap; try { sourceMap = JSON.parse(await readFile(mapPath, "utf8")); } catch (error) { if (error.code === "ENOENT") continue; throw error; } const debugId = match[1]; if (!bundle.includes("//# debugId=")) { bundle += `\n//# debugId=${debugId}`; await writeFile(path, bundle); } sourceMap.debug_id = debugId; sourceMap.debugId = debugId; await writeFile(mapPath, JSON.stringify(sourceMap)); stamped += 1; } } await visit(outputDirectory); if (stamped === 0) { throw new Error("Nuxt produced no source maps with Sentry debug IDs"); } console.log(`Prepared ${stamped} Nuxt source maps for upload`);
Run it after nuxt build; this guide uses the postbuild script shown above.
Do not run sentry-cli sourcemaps inject over this output, because that would
replace the relationship established by the Nuxt plugins with different IDs.
Build and upload
Create a project-bound Bugsink token with the debug-files:upload capability.
Build with both DSN variables, but keep the upload token out of the build
command so the incompatible automatic uploader does not run:
NUXT_PUBLIC_SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm run buildNUXT_PUBLIC_SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm run build
Upload the completed browser and Nitro output with sentry-cli. The org
value is a compatibility placeholder; Bugsink uses the project slug and the
project-bound token to select the destination:
SENTRY_AUTH_TOKEN=your-project-token \ npx --yes @sentry/cli@3.8.2 \ --url https://bugsink.example \ sourcemaps --org bugsink --project your-project-slug upload \ .output/public/_nuxt .output/server/chunksSENTRY_AUTH_TOKEN=your-project-token \ npx --yes @sentry/cli@3.8.2 \ --url https://bugsink.example \ sourcemaps --org bugsink --project your-project-slug upload \ .output/public/_nuxt .output/server/chunks
Upload the maps for every production build before that build can receive traffic.
See a browser error in Bugsink
Start the production server with its server-side DSN:
PORT=3000 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm startPORT=3000 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm start
This page calls ordinary inventory code from a Vue click handler. The inventory
module raises ProductNotFound when the requested quantity is unavailable:
class ProductNotFound extends Error {} export function reserveProduct(sku: string, quantity: number) { const available = 0; if (quantity > available) { throw new ProductNotFound( `Cannot reserve ${quantity} unit of ${sku}: only ${available} remain [nuxt-browser]`, ); } }class ProductNotFound extends Error {} export function reserveProduct(sku: string, quantity: number) { const available = 0; if (quantity > available) { throw new ProductNotFound( `Cannot reserve ${quantity} unit of ${sku}: only ${available} remain [nuxt-browser]`, ); } }
Open http://127.0.0.1:3000/ and click Reserve desk lamp. The SDK reports
the unhandled Vue error in the background.
See the original browser source
Open the new issue in Bugsink. The uploaded map translates the production browser chunk back to the inventory module and shows the exact TypeScript line that raised the error.
Error
That’s it: browser failures from the production Nuxt build now reach Bugsink with their original source.
Capture Nitro API errors
The server SDK reports unhandled API failures through Nitro’s normal request
lifecycle. This route raises ProductNotFound for an unknown product; it does
not contain a Bugsink-specific capture call:
class ProductNotFound extends Error {} export default defineEventHandler((event) => { const sku = getRouterParam(event, "sku"); const products = new Map([["desk-lamp", { name: "Desk lamp", available: 0 }]]); const product = sku ? products.get(sku) : undefined; if (!product) { throw new ProductNotFound( `Product ${sku} is not in inventory [nuxt-server]`, ); } return product; });class ProductNotFound extends Error {} export default defineEventHandler((event) => { const sku = getRouterParam(event, "sku"); const products = new Map([["desk-lamp", { name: "Desk lamp", available: 0 }]]); const product = sku ? products.get(sku) : undefined; if (!product) { throw new ProductNotFound( `Product ${sku} is not in inventory [nuxt-server]`, ); } return product; });
Request http://127.0.0.1:3000/api/products/missing. Nuxt keeps its normal 500
response, while the SDK reports the exception and concrete request to Bugsink.
See the original server source
Open the server issue in Bugsink. It contains the GET request and resolves
the Nitro bundle back to the parameterized route file.
Error
Server API failures now reach the same Bugsink project with the request and their original route source.
Limitations
The @sentry/nuxt 11.15.0 Vite and Rollup plugins generate usable source maps
and inject matching debug IDs, but their automatic upload path currently fails
with SentryError: Invalid URL. The production build still exits successfully,
so do not rely on its exit status to prove that maps were uploaded. Keep the
token out of npm run build and use the explicit sentry-cli upload above.
This compatibility path is tracked with the broader source-map work in Bugsink
issues #109 and
#157.
The tested Nitro event uses its concrete request path as the transaction name;
it does not replace missing with the [sku] route parameter. The request and
original parameterized source filename are still present in Bugsink.
For handled errors, logging, tags, structured context, and other SDK options, continue with the broader JavaScript guide.
