Registry / storage / sentry-offline-transport-better-sqlite

sentry-offline-transport-better-sqlite

library1.1.2jsnpmunverified

Offline transport for Sentry Node.js that persists events to a local better-sqlite3 database when the network is unavailable, then flushes them on reconnection. Current version 1.1.2, stable, with infrequent releases. Key differentiator: uses synchronous better-sqlite3 for simpler setup compared to async alternatives like @sentry/utils's offline transport. Requires Node >=18 and better-sqlite3 as a peer dependency. Not for browser use.

storage

npm install sentry-offline-transport-better-sqlite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SENTRY-OFFLINE-TRA

sentry-offline-transport-better-sqlite

storagejavascriptv1.1.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import createOfflineTransport from 'sentry-offline-transport-better-sqlite'

✗ import { createOfflineTransport } from 'sentry-offline-transport-better-sqlite'

The package exports a single function as default export, not named.

createOfflineTransport

✓ import createOfflineTransport from 'sentry-offline-transport-better-sqlite'

✗ const createOfflineTransport = require('sentry-offline-transport-better-sqlite')

In CJS, you must use default import or require, but the module is ESM-first.

Sentry

✓ import * as Sentry from '@sentry/node'

✗ const Sentry = require('@sentry/node')

This is the Sentry SDK import, not from this package. Required as a peer dependency.

Initialize Sentry with offline transport using better-sqlite3 for persistent event queuing.

import * as Sentry from '@sentry/node'; import createOfflineTransport from 'sentry-offline-transport-better-sqlite'; Sentry.init({ dsn: process.env.SENTRY_DSN ?? '', transport: createOfflineTransport({ dbPath: './sentry-offline.db', maxQueueSize: 100, }), }); // Your app code here // On network failure, events are queued locally and sent when online.

Debug

Known issues

gotchaThe package uses synchronous database operations via better-sqlite3. This can block the event loop during disk I/O.

fix

Ensure the database path is on a fast local disk and avoid high-frequency events in production if event loop blocking is a concern.

affects: >=0.0.0

breakingThe package requires Node >=18 and is ESM-only. It cannot be required() in CommonJS directly without dynamic import.

fix

Use import syntax or dynamic import() in CJS projects. Set type: "module" in package.json or use .mjs extension.

affects: >=1.0.0

deprecatedThe option 'maxQueueSize' may be deprecated in future versions; check latest docs.

fix

Currently still supported. Monitor for updates.

affects: <=1.1.2

gotchaThe module uses better-sqlite3 as a peer dependency. If not installed, you'll get a runtime error when creating the transport.

fix

Run npm install better-sqlite3 alongside this package.

affects: >=0.0.0

gotchaThe offline transport does not automatically retry failed submissions beyond the first attempt after reconnection. Events that fail to send will remain queued.

fix

Implement manual flush or periodic retry logic using Sentry.flush().

affects: <=1.1.2

Errors

Common errors & fixes

Cannot find module 'better-sqlite3'

better-sqlite3 is not installed

fix

Run npm install better-sqlite3

ERR_REQUIRE_ESM: require() of ES Module

CommonJS require() on ESM package

fix

Use dynamic import: const createOfflineTransport = (await import('sentry-offline-transport-better-sqlite')).default;

TypeError: createOfflineTransport is not a function

Named import instead of default import

fix

Change import to: import createOfflineTransport from 'sentry-offline-transport-better-sqlite'

Sentry.TransportClass is not a constructor (or similar)

Incorrect usage of transport option; should pass a function, not an instance

fix

Pass the createOfflineTransport function (not its result) to the transport option: transport: createOfflineTransport

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

better-sqlite3requiredpeer dependency for SQLite persistence

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/RangerMauve/sentry-offline-transport-better-sqlite ↗

packagesentry-offline-transport-better-sqlite ↗

homepagehttps://github.com/RangerMauve/sentry-offline-transport-better-sqlite#readme ↗