{"id":46337,"library":"sentry-offline-transport-better-sqlite","title":"Sentry Offline Transport (better-sqlite)","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/RangerMauve/sentry-offline-transport-better-sqlite","tags":["javascript","sentry","sqlite.","logs","offline"],"install":[{"cmd":"npm install sentry-offline-transport-better-sqlite","lang":"bash","label":"npm"},{"cmd":"yarn add sentry-offline-transport-better-sqlite","lang":"bash","label":"yarn"},{"cmd":"pnpm add sentry-offline-transport-better-sqlite","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for SQLite persistence","package":"better-sqlite3","optional":false}],"imports":[{"note":"The package exports a single function as default export, not named.","wrong":"import { createOfflineTransport } from 'sentry-offline-transport-better-sqlite'","symbol":"default","correct":"import createOfflineTransport from 'sentry-offline-transport-better-sqlite'"},{"note":"In CJS, you must use default import or require, but the module is ESM-first.","wrong":"const createOfflineTransport = require('sentry-offline-transport-better-sqlite')","symbol":"createOfflineTransport","correct":"import createOfflineTransport from 'sentry-offline-transport-better-sqlite'"},{"note":"This is the Sentry SDK import, not from this package. Required as a peer dependency.","wrong":"const Sentry = require('@sentry/node')","symbol":"Sentry","correct":"import * as Sentry from '@sentry/node'"}],"quickstart":{"code":"import * as Sentry from '@sentry/node';\nimport createOfflineTransport from 'sentry-offline-transport-better-sqlite';\n\nSentry.init({\n  dsn: process.env.SENTRY_DSN ?? '',\n  transport: createOfflineTransport({\n    dbPath: './sentry-offline.db',\n    maxQueueSize: 100,\n  }),\n});\n\n// Your app code here\n// On network failure, events are queued locally and sent when online.","lang":"typescript","description":"Initialize Sentry with offline transport using better-sqlite3 for persistent event queuing."},"warnings":[{"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.","message":"The package uses synchronous database operations via better-sqlite3. This can block the event loop during disk I/O.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use import syntax or dynamic import() in CJS projects. Set type: \"module\" in package.json or use .mjs extension.","message":"The package requires Node >=18 and is ESM-only. It cannot be required() in CommonJS directly without dynamic import.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Currently still supported. Monitor for updates.","message":"The option 'maxQueueSize' may be deprecated in future versions; check latest docs.","severity":"deprecated","affected_versions":"<=1.1.2"},{"fix":"Run npm install better-sqlite3 alongside this package.","message":"The module uses better-sqlite3 as a peer dependency. If not installed, you'll get a runtime error when creating the transport.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Implement manual flush or periodic retry logic using Sentry.flush().","message":"The offline transport does not automatically retry failed submissions beyond the first attempt after reconnection. Events that fail to send will remain queued.","severity":"gotcha","affected_versions":"<=1.1.2"}],"env_vars":null,"search_vec":"'1.1.2':34 '18':60 'altern':52 'async':51 'better':5,19,44,63 'better-sqlit':4 'better-sqlite3':18,43,62 'browser':71 'compar':49 'current':32 'databas':21 'depend':68 'differenti':40 'event':14 'flush':28 'infrequ':37 'javascript':73 'key':39 'like':53 'local':17 'log':76 'network':24 'node':59 'node.js':11 'offlin':2,7,56,77 'peer':67 'persist':13 'reconnect':31 'releas':38 'requir':58 'sentri':1,10,74 'sentry/utils':54 'setup':48 'simpler':47 'sqlite':6,75 'sqlite3':20,45,64 'stabl':35 'synchron':42 'transport':3,8,57 'unavail':26 'use':41,72 'version':33","created_at":"2026-06-07T12:59:26.088782+00:00","updated_at":"2026-06-07T12:59:26.088782+00:00","problems":[{"fix":"Run npm install better-sqlite3","cause":"better-sqlite3 is not installed","error":"Cannot find module 'better-sqlite3'"},{"fix":"Use dynamic import: const createOfflineTransport = (await import('sentry-offline-transport-better-sqlite')).default;","cause":"CommonJS require() on ESM package","error":"ERR_REQUIRE_ESM: require() of ES Module"},{"fix":"Change import to: import createOfflineTransport from 'sentry-offline-transport-better-sqlite'","cause":"Named import instead of default import","error":"TypeError: createOfflineTransport is not a function"},{"fix":"Pass the createOfflineTransport function (not its result) to the transport option: transport: createOfflineTransport","cause":"Incorrect usage of transport option; should pass a function, not an instance","error":"Sentry.TransportClass is not a constructor (or similar)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/RangerMauve/sentry-offline-transport-better-sqlite#readme","github":"https://github.com/RangerMauve/sentry-offline-transport-better-sqlite","docs":null,"changelog":null,"pypi":null,"npm":"sentry-offline-transport-better-sqlite","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}