@starko-one/sdk 0.0.0-stage → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +124 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-B5IHeINe.d.ts +558 -0
  6. package/dist/api-DR4HazCu.d.cts +558 -0
  7. package/dist/browser/index.cjs +168 -0
  8. package/dist/browser/index.d.cts +131 -0
  9. package/dist/browser/index.d.ts +131 -0
  10. package/dist/browser/index.js +7 -0
  11. package/dist/build/rollup.cjs +22 -0
  12. package/dist/build/rollup.d.cts +34 -0
  13. package/dist/build/rollup.d.ts +34 -0
  14. package/dist/build/rollup.js +3 -0
  15. package/dist/build/vite.cjs +51 -0
  16. package/dist/build/vite.d.cts +23 -0
  17. package/dist/build/vite.d.ts +23 -0
  18. package/dist/build/vite.js +46 -0
  19. package/dist/build/webpack.cjs +18 -0
  20. package/dist/build/webpack.d.cts +39 -0
  21. package/dist/build/webpack.d.ts +39 -0
  22. package/dist/build/webpack.js +3 -0
  23. package/dist/chunk-7HYGODU6.cjs +583 -0
  24. package/dist/chunk-A5M4NOVT.js +413 -0
  25. package/dist/chunk-A7MYYWMP.cjs +15 -0
  26. package/dist/chunk-BAQA47FM.js +1113 -0
  27. package/dist/chunk-CM7HM6CC.js +563 -0
  28. package/dist/chunk-DFYNIWUN.js +608 -0
  29. package/dist/chunk-DMVVCGKO.cjs +96 -0
  30. package/dist/chunk-FARGXYJ4.cjs +56 -0
  31. package/dist/chunk-G3MYIAX2.js +1226 -0
  32. package/dist/chunk-G4NAVZQ4.js +249 -0
  33. package/dist/chunk-GH7RYPKS.js +96 -0
  34. package/dist/chunk-HADYYQNL.cjs +134 -0
  35. package/dist/chunk-HOQPAB4X.js +178 -0
  36. package/dist/chunk-J5RU73SW.js +214 -0
  37. package/dist/chunk-JNAJ3YZB.cjs +223 -0
  38. package/dist/chunk-KN7H22EQ.cjs +659 -0
  39. package/dist/chunk-LDQ4I7FZ.cjs +1151 -0
  40. package/dist/chunk-NPGESRVQ.js +1212 -0
  41. package/dist/chunk-OPWM5V7A.cjs +258 -0
  42. package/dist/chunk-PYYWPIFL.cjs +1230 -0
  43. package/dist/chunk-R7JLZ4WO.cjs +115 -0
  44. package/dist/chunk-SC6VQSES.js +213 -0
  45. package/dist/chunk-TPSJGLR3.cjs +220 -0
  46. package/dist/chunk-UKBY6HPC.js +131 -0
  47. package/dist/chunk-VRSEHRBX.cjs +185 -0
  48. package/dist/chunk-X74AONZA.js +90 -0
  49. package/dist/chunk-XW3I5CJN.js +12 -0
  50. package/dist/chunk-XW56FKKJ.js +53 -0
  51. package/dist/chunk-Z3G5SW7R.cjs +1251 -0
  52. package/dist/chunk-ZVMAN7OO.cjs +431 -0
  53. package/dist/cli/index.cjs +1487 -0
  54. package/dist/common-ARWXbeS3.d.ts +36 -0
  55. package/dist/common-CwIFh2hK.d.cts +36 -0
  56. package/dist/dedupe-eHBIfUUD.d.cts +13 -0
  57. package/dist/dedupe-fw8aNtt4.d.ts +13 -0
  58. package/dist/handler-DTZ4Rzcf.d.ts +82 -0
  59. package/dist/handler-_00lctTI.d.cts +82 -0
  60. package/dist/index.cjs +277 -0
  61. package/dist/index.d.cts +187 -0
  62. package/dist/index.d.ts +187 -0
  63. package/dist/index.js +4 -0
  64. package/dist/next/client.cjs +113 -0
  65. package/dist/next/client.d.cts +26 -0
  66. package/dist/next/client.d.ts +26 -0
  67. package/dist/next/client.js +41 -0
  68. package/dist/next/config.cjs +275 -0
  69. package/dist/next/config.d.cts +193 -0
  70. package/dist/next/config.d.ts +193 -0
  71. package/dist/next/config.js +261 -0
  72. package/dist/next/index.cjs +148 -0
  73. package/dist/next/index.d.cts +32 -0
  74. package/dist/next/index.d.ts +32 -0
  75. package/dist/next/index.js +59 -0
  76. package/dist/node/index.cjs +257 -0
  77. package/dist/node/index.d.cts +145 -0
  78. package/dist/node/index.d.ts +145 -0
  79. package/dist/node/index.js +83 -0
  80. package/dist/options-0BhybO54.d.cts +47 -0
  81. package/dist/options-0BhybO54.d.ts +47 -0
  82. package/dist/react/index.cjs +107 -0
  83. package/dist/react/index.d.cts +84 -0
  84. package/dist/react/index.d.ts +84 -0
  85. package/dist/react/index.js +103 -0
  86. package/dist/scope-Bvh45bOf.d.cts +404 -0
  87. package/dist/scope-Bvh45bOf.d.ts +404 -0
  88. package/dist/server-edge-BPOGA3GH.cjs +51 -0
  89. package/dist/server-edge-GYKAJREU.js +48 -0
  90. package/dist/server-node-HYK2OB2J.js +24 -0
  91. package/dist/server-node-J2DBAHDV.cjs +27 -0
  92. package/dist/session-C_WzbEN2.d.cts +4 -0
  93. package/dist/session-C_WzbEN2.d.ts +4 -0
  94. package/dist/session-propagation-B7REA7uy.d.cts +30 -0
  95. package/dist/session-propagation-BnJjKJbR.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +381 -0
  98. package/docs/configuration.md +269 -0
  99. package/docs/nextjs.md +312 -0
  100. package/docs/node.md +376 -0
  101. package/docs/other-backends.md +232 -0
  102. package/docs/privacy.md +112 -0
  103. package/docs/react.md +187 -0
  104. package/docs/source-maps.md +332 -0
  105. package/docs/troubleshooting.md +171 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +367 -0
  108. package/package.json +98 -4
@@ -0,0 +1,269 @@
1
+ # Configuration reference
2
+
3
+ Every option of every entry point, with its default, and every integration.
4
+ The tables are checked against the source by a test, so an option missing
5
+ here, or listed here but not in the code, fails the build.
6
+
7
+ - [Browser and `next/client`](#browser-and-nextclient)
8
+ - [Node.js](#nodejs)
9
+ - [Next.js server: `register`](#nextjs-server-register)
10
+ - [Build plugins and `withStarko`](#build-plugins-and-withstarko)
11
+ - [Integrations](#integrations)
12
+ - [Adding and removing integrations](#adding-and-removing-integrations)
13
+
14
+ ## Browser and `next/client`
15
+
16
+ `init` from `@starko-one/sdk/browser`, `@starko-one/sdk/next/client` and the
17
+ script-tag bundle.
18
+
19
+ <!-- options: BrowserOptions -->
20
+ | Option | Type | Default | Meaning |
21
+ | --- | --- | --- | --- |
22
+ | `workspaceKey` | `string` | required | Workspace key (public): the workspace id shown in Starko under Settings. Without it the SDK does not start. |
23
+ | `host` | `string` | `"https://v2.starko.one"` | Starko host. Must answer without redirecting. |
24
+ | `release` | `string` | the release a build plugin wrote into the bundle, if any (read for each event) | Version of your app. Use the release the source maps were uploaded for. |
25
+ | `environment` | `string` | none | `production`, `staging`, … |
26
+ | `enabled` | `boolean` | `true` | `false`: install nothing, capture nothing. |
27
+ | `debug` | `boolean` | `false` | Log what the SDK does (and its own failures) to the console. |
28
+ | `sampleRate` | `number` | `1` | Share of events sent, 0 to 1. Multiplied by the workspace's remote sample rate. |
29
+ | `maxBreadcrumbs` | `number` | `50` | Breadcrumbs kept. At most 50. |
30
+ | `beforeSend` | `(event, hint) => event \| null \| Promise<event \| null>` | none | Last step before an event is queued. Return `null` to drop it. If it throws, the event is dropped. |
31
+ | `beforeSendTimeoutMs` | `number` | `5000` | An async `beforeSend` that has not settled after this many ms is abandoned and its event dropped. |
32
+ | `beforeBreadcrumb` | `(breadcrumb, hint?) => breadcrumb \| null` | none | Edit a breadcrumb, or return `null` to drop it, before it is stored. |
33
+ | `ignoreErrors` | `Array<string \| RegExp>` | `[]` | Drop events whose `Type: message` or message contains a string or matches a RegExp. |
34
+ | `allowUrls` | `Array<string \| RegExp>` | `[]` (no restriction) | Only send events whose most recent frame's file matches one of these. |
35
+ | `denyUrls` | `Array<string \| RegExp>` | `[]` | Drop events whose most recent frame's file matches one of these. |
36
+ | `integrations` | `Integration[] \| (defaults) => Integration[]` | none | An array is added to the defaults (an integration with a default's name replaces it). A function receives the defaults and returns the list to use. |
37
+ | `defaultIntegrations` | `false \| Integration[]` | the browser defaults | `false`: no default integrations. An array replaces the defaults. |
38
+ | `transport` | `(options) => Transport` | the `fetch` transport | Custom transport factory (tests, proxies). |
39
+ | `remoteConfig` | `boolean` | `true` | Read the workspace's remote config at `init`; events wait for it (at most 30, at most 10 s). |
40
+ | `user` | `{ id?, email?, name? } \| null` | none | The signed-in user at start. |
41
+ | `userHash` | `string` | none | The user hash for `user` (applied only together with `user`). See [browser.md](./browser.md#identify-the-user). |
42
+ | `maxEventsPerLifetime` | `number` | `100` | Events sent per page load. |
43
+ | `maxEventsPerMinute` | `number` | none | Events sent in any 60 s, all error types together. |
44
+ | `maxQueueSize` | `number` | `100` | Events waiting in memory; past it the oldest are dropped. |
45
+ | `flushInterval` | `number` | `1000` | Milliseconds before a partial batch is sent. |
46
+ | `requestTimeoutMs` | `number` | `12000` | A request to Starko not answered after this many ms is aborted and retried as a network failure. |
47
+
48
+ `next/client`'s `init` takes the same options and adds `NextControlFlow` to
49
+ the defaults.
50
+
51
+ ## Node.js
52
+
53
+ `init` from `@starko-one/sdk/node`.
54
+
55
+ <!-- options: NodeOptions -->
56
+ | Option | Type | Default | Meaning |
57
+ | --- | --- | --- | --- |
58
+ | `workspaceKey` | `string` | required | Workspace key (public). Without it the SDK does not start. |
59
+ | `apiKey` | `string` | none | Secret key (`sk_starko_…`) with the `errors:write` scope. Starko then trusts the `user.id` your server sets. Never in a browser. See [node.md](./node.md#the-secret-key-apikey). |
60
+ | `host` | `string` | `"https://v2.starko.one"` | Starko host. Must answer without redirecting. |
61
+ | `release` | `string` | `STARKO_RELEASE`, then the release a build plugin wrote into the bundle (read for each event) | Version of your app. |
62
+ | `environment` | `string` | none | `production`, `staging`, … |
63
+ | `serverName` | `string` | the host name (`os.hostname()`) | `server_name` on every event. |
64
+ | `enabled` | `boolean` | `true` | `false`: install nothing, capture nothing. |
65
+ | `debug` | `boolean` | `false` | Log what the SDK does to the console. |
66
+ | `sampleRate` | `number` | `1` | Share of events sent, 0 to 1. Multiplied by the workspace's remote sample rate. |
67
+ | `maxBreadcrumbs` | `number` | `50` | Breadcrumbs kept. At most 50. |
68
+ | `beforeSend` | `(event, hint) => event \| null \| Promise<event \| null>` | none | Last step before an event is queued. Runs after source lines are added. If it throws, the event is dropped. |
69
+ | `beforeSendTimeoutMs` | `number` | `5000` | An async `beforeSend` (or the source-line read before it) not settled after this many ms is abandoned and its event dropped. |
70
+ | `beforeBreadcrumb` | `(breadcrumb, hint?) => breadcrumb \| null` | none | Edit or drop a breadcrumb before it is stored. |
71
+ | `ignoreErrors` | `Array<string \| RegExp>` | `[]` | Drop events whose `Type: message` or message contains a string or matches a RegExp. |
72
+ | `allowUrls` | `Array<string \| RegExp>` | `[]` (no restriction) | Only send events whose most recent frame's file path matches one of these. |
73
+ | `denyUrls` | `Array<string \| RegExp>` | `[]` | Drop events whose most recent frame's file path matches one of these. |
74
+ | `integrations` | `Integration[] \| (defaults) => Integration[]` | none | As in the browser. |
75
+ | `defaultIntegrations` | `false \| Integration[]` | the Node defaults | `false`: none. An array replaces the defaults. |
76
+ | `transport` | `(options) => Transport` | `node:http` / `node:https` | Custom transport factory. |
77
+ | `fetch` | `typeof fetch` | none | Send with this `fetch` instead of `node:http(s)` (a proxy). A request in flight then keeps the process alive until it ends (at most 10 s). |
78
+ | `remoteConfig` | `boolean` | `true` | Read the workspace's remote config just before the first send (an idle process makes no request). Exit-time flushes do not wait for it. |
79
+ | `user` | `{ id?, email?, name? } \| null` | none | A user for the whole process. |
80
+ | `userHash` | `string` | none | The user hash for `user` (applied only together with `user`). |
81
+ | `maxEventsPerLifetime` | `number` | none | Events sent over the life of the process. |
82
+ | `maxEventsPerMinute` | `number` | `300` | Events sent in any 60 s, all error types together. |
83
+ | `maxQueueSize` | `number` | `500` | Events waiting in memory; past it the oldest are dropped. |
84
+ | `flushInterval` | `number` | `1000` | Milliseconds before a partial batch is sent. |
85
+ | `requestTimeoutMs` | `number` | `10000` | A request not finished after this many ms is aborted and retried as a network failure. Connecting has its own 3 s limit. |
86
+ | `shutdownTimeout` | `number` | `2000` | Longest wait, in ms, for queued events when the event loop empties and on `SIGTERM` / `SIGINT` (without an app handler). `close(timeout)` and `flush(timeout)` take their own timeout (default 2000 ms). |
87
+ | `fatalFlushTimeout` | `number` | `1000` | Longest wait, in ms, for the crash event before the process exits after an uncaught error. |
88
+
89
+ ## Next.js server: `register`
90
+
91
+ `register` from `@starko-one/sdk/next` takes every [Node.js](#nodejs)
92
+ option, plus:
93
+
94
+ <!-- options: NextServerOptions - NodeOptions -->
95
+ | Option | Type | Default | Meaning |
96
+ | --- | --- | --- | --- |
97
+ | `flushTimeout` | `number` | `2000` | Longest background flush, in ms, that `onRequestError` hands to the platform's `waitUntil`. Without `waitUntil` on a serverless platform the hook waits at most the smaller of this and 500 ms. |
98
+
99
+ On the Edge runtime the same options are accepted, with these differences:
100
+ `STARKO_RELEASE` is not read, `defaultIntegrations` as an array is ignored,
101
+ `serverName`, `shutdownTimeout` and `fatalFlushTimeout` have no effect (there
102
+ is no host name, no process hooks), and requests are sent with the runtime's
103
+ `fetch`.
104
+
105
+ ## Build plugins and `withStarko`
106
+
107
+ `starkoVitePlugin(options)` (`@starko-one/sdk/vite`),
108
+ `starkoRollupPlugin(options)` (`@starko-one/sdk/rollup`),
109
+ `new StarkoWebpackPlugin(options)` (`@starko-one/sdk/webpack`) and
110
+ `withStarko(nextConfig, options)` (`@starko-one/sdk/next/config`).
111
+
112
+ <!-- options: StarkoWebpackPluginOptions -->
113
+ | Option | Type | Default | Meaning |
114
+ | --- | --- | --- | --- |
115
+ | `apiKey` | `string` | `STARKO_API_KEY` | Secret key with the `sourcemaps:write` scope. Without one nothing is changed and a warning is printed once. |
116
+ | `host` | `string` | `STARKO_HOST`, then `"https://v2.starko.one"` | Starko host. |
117
+ | `release` | `string` | `STARKO_RELEASE`, the CI commit, `git rev-parse HEAD` | Release of this build, also written into the bundles for `init`. |
118
+ | `enabled` | `boolean` | production builds only | Vite: `vite build` in production mode, not watch. Rollup: not in watch mode or with `NODE_ENV=development`. webpack: `mode: "production"`. `withStarko`: `next build`. |
119
+ | `deleteSourcemapsAfterUpload` | `boolean` | not set | `true`: delete every map after the upload attempt. Not set or `false`: keep the maps your config asked for. Maps the integration switched on are deleted in every case. See [the table](./source-maps.md#which-maps-are-deleted). |
120
+ | `include` | `string \| RegExp \| Array<string \| RegExp>` | every `.js`, `.mjs` and `.cjs` file | Bundles to process: globs (`*`, `**`, `?`) or RegExps, matched against the path relative to the output directory. |
121
+ | `exclude` | `string \| RegExp \| Array<string \| RegExp>` | `"**/node_modules/**"` | Bundles to skip. |
122
+ | `dryRun` | `boolean` | `false` | Inject, then log what would be uploaded without sending. Maps the integration switched on are still deleted. |
123
+ | `silent` | `boolean` | `false` | No logging. |
124
+ | `failOnError` | `boolean` | `false` | Fail the build when the upload fails. By default a failed upload warns and the build succeeds. |
125
+ | `uploadTimeoutMs` | `number` | `180000` | Deadline for the whole upload, in ms. When it passes the upload is abandoned with a warning. |
126
+ | `upload` | `boolean` | `true` | webpack only: `false` injects without uploading (and deletes nothing), when something else uploads. |
127
+
128
+ ## Integrations
129
+
130
+ An integration is an object with a `name` and hooks the SDK calls. The
131
+ defaults are installed by `init`; the factories below are exported so you
132
+ can configure one, add one that is not a default, or build your own list.
133
+
134
+ ### Browser (`@starko-one/sdk/browser`)
135
+
136
+ | Name | Factory | Default | What it does |
137
+ | --- | --- | --- | --- |
138
+ | `InboundFilters` | `inboundFiltersIntegration()` | yes | Drops noise: empty errors, cross-origin `Script error.`, browser extensions, `ResizeObserver` loops, aborted requests, network failures, errors inside Starko's own scripts. |
139
+ | `Dedupe` | `dedupeIntegration(options)` | yes | Drops an event identical to the one just before it: same exception types, messages and frames, fingerprint, user and session. |
140
+ | `GlobalHandlers` | `globalHandlersIntegration({ onerror, onunhandledrejection })` | yes | Captures uncaught errors and unhandled rejections (window listeners; `window.onerror` and other listeners keep running). |
141
+ | `Breadcrumbs` | `breadcrumbsIntegration({ console, dom, fetch, xhr, history })` | yes | Records clicks, navigation, `fetch`/XHR and console warnings and errors. |
142
+ | `HttpContext` | `httpContextIntegration()` | yes | Adds the page URL and referrer. |
143
+ | `WidgetBridge` | `widgetBridgeIntegration()` | yes | Meets the Starko widget: shared session id, the widget's customer token, telling the widget the SDK captures errors. See [widget.md](./widget.md). |
144
+ | `SessionPropagation` | `sessionPropagationIntegration()` | yes | Adds `x-starko-session-id` to same-origin `fetch` and XHR requests, so server errors link to this session. |
145
+ | `ConsoleErrorCapture` | `consoleErrorCaptureIntegration({ whenWidget })` | yes, with `whenWidget: true` | Captures `Error` objects passed to `console.error`. As a default, only while the Starko widget is on the page; added without options, always. |
146
+ | `FlushOnHide` | `flushOnHideIntegration()` | always added | Sends the queue with `keepalive` when the page is hidden; resumes sending when the browser comes back online. Added even with `defaultIntegrations: false`. |
147
+
148
+ `next/client` adds `NextControlFlow` (`nextControlFlowIntegration()`), which
149
+ drops Next's `redirect()`, `notFound()`, `forbidden()`, `unauthorized()` and
150
+ bail-outs.
151
+
152
+ Options of the configurable ones:
153
+
154
+ <!-- options: BreadcrumbsOptions -->
155
+ | Option | Type | Default | Meaning |
156
+ | --- | --- | --- | --- |
157
+ | `console` | `boolean` | `true` | `console.warn` and `console.error`. |
158
+ | `dom` | `boolean` | `true` | Clicks. |
159
+ | `fetch` | `boolean` | `true` | `fetch` requests. |
160
+ | `xhr` | `boolean` | `true` | `XMLHttpRequest` requests. |
161
+ | `history` | `boolean` | `true` | `pushState`, `replaceState` and back/forward. |
162
+
163
+ <!-- options: GlobalHandlersOptions -->
164
+ | Option | Type | Default | Meaning |
165
+ | --- | --- | --- | --- |
166
+ | `onerror` | `boolean` | `true` | Uncaught errors (the window `error` event). |
167
+ | `onunhandledrejection` | `boolean` | `true` | Unhandled promise rejections. |
168
+
169
+ ### Node.js (`@starko-one/sdk/node`)
170
+
171
+ | Name | Factory | Default | What it does |
172
+ | --- | --- | --- | --- |
173
+ | `Dedupe` | `dedupeIntegration(options)` | yes | Drops an event identical to the one just before it: same exception types, messages and frames, fingerprint, user and session, and the same request. The same failure for two customers, or in two requests, is two events. |
174
+ | `HttpServer` | `httpServerIntegration()` | yes | Gives every request of a `node:http`, `node:https` or `node:http2` server its own scope. Removing it removes the automatic isolation. |
175
+ | `OnUncaughtException` | `onUncaughtExceptionIntegration()` | yes | Captures uncaught exceptions; exits like Node when the app has no listener of its own. |
176
+ | `OnUnhandledRejection` | `onUnhandledRejectionIntegration({ mode })` | yes | Captures unhandled rejections without changing what Node does with them. |
177
+ | `RequestData` | `requestDataIntegration()` | yes | Adds the request's method, URL and route. |
178
+ | `NodeContext` | `nodeContextIntegration()` | yes | Adds the Node version, the OS and `server_name`. |
179
+ | `ConsoleBreadcrumbs` | `consoleBreadcrumbsIntegration()` | yes | Records `console.warn` and `console.error` as breadcrumbs (text, 200 characters). |
180
+ | `ContextLines` | `contextLinesIntegration(options)` | yes | Adds source lines around in-app frames. See [node.md](./node.md#source-lines). |
181
+ | `FlushOnExit` | `flushOnExitIntegration({ signals })` | yes | Sends queued events when the event loop empties and on `SIGTERM` / `SIGINT` without an app handler. |
182
+
183
+ `@starko-one/sdk/next`'s `register` adds `NextControlFlow` on both
184
+ runtimes. On the Edge runtime the defaults are only `Dedupe`, `RequestData`
185
+ and `NextControlFlow`.
186
+
187
+ <!-- options: ContextLinesOptions -->
188
+ | Option | Type | Default | Meaning |
189
+ | --- | --- | --- | --- |
190
+ | `lines` | `number` | `7` | Lines before and after the frame's line (at most 7). |
191
+ | `includeNodeModules` | `boolean` | `false` | Also read files under `node_modules`. |
192
+ | `roots` | `string[]` | `[]` | Directories besides the application root whose files may be read (a monorepo's packages). A filesystem root (`/`) is ignored. |
193
+ | `maxFileBytes` | `number` | `1048576` | Larger files are not read. |
194
+ | `maxFiles` | `number` | `10` | Distinct files read per event. |
195
+ | `cacheSize` | `number` | `100` | Files kept in the cache. |
196
+ | `cacheBytes` | `number` | `8388608` | Bytes of source text kept in the cache. |
197
+
198
+ <!-- options: DedupeOptions -->
199
+ | Option | Type | Default | Meaning |
200
+ | --- | --- | --- | --- |
201
+ | `requestKey` | `() => unknown` | none | Returns the identity of the request the current event belongs to, compared with `===`: events of different requests are never duplicates. The Node and Next.js defaults compare the current request scope. A `dedupeIntegration()` you create yourself compares requests only through a `requestKey` you pass: use `dedupeIntegration({ requestKey: currentRequestKey })`, with `currentRequestKey` from `@starko-one/sdk/node` or `/next`, to keep the default. |
202
+
203
+ <!-- options: FlushOnExitOptions -->
204
+ | Option | Type | Default | Meaning |
205
+ | --- | --- | --- | --- |
206
+ | `signals` | `boolean` | `true` | Flush on `SIGTERM` / `SIGINT` when the app does not listen for them. |
207
+
208
+ <!-- options: OnUnhandledRejectionOptions -->
209
+ | Option | Type | Default | Meaning |
210
+ | --- | --- | --- | --- |
211
+ | `mode` | `"throw" \| "strict" \| "warn" \| "warn-with-error-code" \| "none"` | read from `--unhandled-rejections` in `process.execArgv` and `NODE_OPTIONS`, else `"throw"` | Override the mode the SDK assumes. Meant for tests. |
212
+
213
+ ### Request helpers
214
+
215
+ <!-- options: WrapHandlerOptions -->
216
+ | `wrapHandler` option | Type | Default | Meaning |
217
+ | --- | --- | --- | --- |
218
+ | `flushTimeout` | `number` | `2000` | Longest wait, in ms, for queued events after each call. |
219
+ | `getRequestData` | `(...args) => { method?, url?, route?, sessionId? } \| undefined` | the first argument, when it is a request | Request data for a call whose first argument is not a request. |
220
+
221
+ <!-- options: ExpressErrorHandlerOptions -->
222
+ | `expressErrorHandler` option | Type | Default | Meaning |
223
+ | --- | --- | --- | --- |
224
+ | `shouldHandleError` | `(error) => boolean` | status 500 or more, or no status | Whether to capture an error. |
225
+
226
+ ## Adding and removing integrations
227
+
228
+ Remove a default by name:
229
+
230
+ ```ts
231
+ import * as Starko from "@starko-one/sdk/browser";
232
+
233
+ Starko.init({
234
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
235
+ integrations: (defaults) => defaults.filter((integration) => integration.name !== "SessionPropagation"),
236
+ });
237
+ ```
238
+
239
+ Configure a default by passing your own instance: an integration with the
240
+ same name as a default replaces it, in the default's place.
241
+
242
+ ```ts
243
+ import * as Starko from "@starko-one/sdk/node";
244
+ import { contextLinesIntegration, flushOnExitIntegration } from "@starko-one/sdk/node";
245
+
246
+ Starko.init({
247
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
248
+ integrations: [contextLinesIntegration({ roots: ["../shared"] }), flushOnExitIntegration({ signals: false })],
249
+ });
250
+ ```
251
+
252
+ Write your own: an object with a `name` and any of `setup(client)`,
253
+ `processEvent(event, hint, client)` (return `null` to drop the event) and
254
+ `teardown()`.
255
+
256
+ ```ts
257
+ import * as Starko from "@starko-one/sdk/browser";
258
+ import type { Integration } from "@starko-one/sdk/browser";
259
+
260
+ const tenantTag: Integration = {
261
+ name: "TenantTag",
262
+ processEvent(event) {
263
+ event.tags = { ...event.tags, tenant: document.documentElement.dataset.tenant ?? "unknown" };
264
+ return event;
265
+ },
266
+ };
267
+
268
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>", integrations: [tenantTag] });
269
+ ```
package/docs/nextjs.md ADDED
@@ -0,0 +1,312 @@
1
+ # Next.js
2
+
3
+ A Next.js app needs three files: one for the server, one for the browser,
4
+ and its Next config for source maps. They work with the App Router and the
5
+ Pages Router.
6
+
7
+ | File | Entry | Next versions |
8
+ | --- | --- | --- |
9
+ | `instrumentation.ts` | `@starko-one/sdk/next` | `register` on 15 and later (on 14 the file needs `experimental.instrumentationHook: true`). `onRequestError` is only called by Next 15 and later. |
10
+ | `instrumentation-client.ts` | `@starko-one/sdk/next/client` | Next 15.3 and later. |
11
+ | `next.config.ts` | `@starko-one/sdk/next/config` | 14 and later; what it does depends on the version, see [Releases](#releases) and [source-maps.md](./source-maps.md#nextjs). |
12
+
13
+ Both instrumentation files go in the project root, or in `src/` if your app
14
+ uses a `src` folder.
15
+
16
+ ## 1. `instrumentation.ts` (server)
17
+
18
+ ```ts
19
+ import * as Starko from "@starko-one/sdk/next";
20
+
21
+ export async function register() {
22
+ await Starko.register({
23
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
24
+ apiKey: process.env.STARKO_API_KEY,
25
+ environment: process.env.NODE_ENV,
26
+ });
27
+ }
28
+
29
+ export const onRequestError = Starko.onRequestError;
30
+ ```
31
+
32
+ `register` starts the SDK for the runtime Next calls it in: the full Node SDK
33
+ on the Node.js runtime (see [node.md](./node.md)), a smaller client on the
34
+ Edge runtime (see [Edge runtime](#edge-runtime)), and nothing anywhere else.
35
+ It never rejects. `register` takes every Node option
36
+ ([configuration.md](./configuration.md#nextjs-server-register)) plus
37
+ `flushTimeout`.
38
+
39
+ `onRequestError` captures every error Next reports from rendering, route
40
+ handlers, server actions and the proxy (middleware), with the route, the
41
+ router kind, the route type, the render source and the method (tags
42
+ `next.router_kind`, `next.route_type`, `next.render_source`, `next.method`,
43
+ `next.digest`; context `nextjs`). Next's control flow (`redirect()`,
44
+ `notFound()`, `forbidden()`, `unauthorized()`, postponed and aborted
45
+ renders) is never reported, whatever captured it.
46
+
47
+ If you already export your own `onRequestError`, call the SDK from it:
48
+
49
+ ```ts
50
+ import * as Starko from "@starko-one/sdk/next";
51
+ import type { NextRequestErrorContext, NextRequestErrorRequest } from "@starko-one/sdk/next";
52
+
53
+ export async function onRequestError(error: unknown, request: NextRequestErrorRequest, context: NextRequestErrorContext) {
54
+ await Starko.captureRequestError(error, request, context);
55
+ // your own reporting
56
+ }
57
+ ```
58
+
59
+ `apiKey` is a secret key with the `errors:write` scope. It is optional; with
60
+ it, Starko trusts the `user.id` your server sets and links it to the
61
+ customer without a hash. Keep it on the server: never pass it to
62
+ `instrumentation-client.ts`, and never give it a `NEXT_PUBLIC_` name (Next
63
+ copies those variables into browser bundles).
64
+
65
+ ## 2. `instrumentation-client.ts` (browser)
66
+
67
+ ```ts
68
+ import * as Starko from "@starko-one/sdk/next/client";
69
+
70
+ Starko.init({
71
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
72
+ environment: process.env.NODE_ENV,
73
+ });
74
+ ```
75
+
76
+ Next runs this file after the HTML loads and before React hydrates. `init`
77
+ is the browser SDK's (every option in [browser.md](./browser.md)) plus the
78
+ filter that drops Next's control flow.
79
+
80
+ On Next 14 and 15.0 to 15.2, which do not have this file, call
81
+ `Starko.init` at the top level of a module marked `"use client"` that your
82
+ root layout renders. Errors thrown before that module runs are not
83
+ captured.
84
+
85
+ ## 3. `next.config.ts` (source maps)
86
+
87
+ ```ts
88
+ import { withStarko } from "@starko-one/sdk/next/config";
89
+
90
+ const nextConfig = {
91
+ reactStrictMode: true,
92
+ };
93
+
94
+ export default withStarko(nextConfig);
95
+ ```
96
+
97
+ `withStarko` returns your config unchanged unless it is a production build
98
+ (`next build`) **and** a secret key with the `sourcemaps:write` scope is in
99
+ `STARKO_API_KEY` (or passed as `apiKey`). With both, it makes sure the
100
+ bundles have debug ids (on Next 16 Turbopack writes its own), uploads the
101
+ source maps, and deletes from `.next` the maps it switched on. With
102
+ `experimental.sri` it changes no client chunk after Next has computed the
103
+ integrity hashes, so the pages keep loading. Your config can also be a
104
+ function or an async function; `withStarko` returns the same kind of value
105
+ it is given and passes every field it does not touch through, so it
106
+ combines with other config wrappers
107
+ (`withBundleAnalyzer(withStarko(nextConfig))`). Details, options and the
108
+ deletion rules: [source-maps.md](./source-maps.md#nextjs).
109
+
110
+ ## Releases
111
+
112
+ The release is the version of your app an error is recorded under.
113
+
114
+ You don't need to set `release`. When you run `next build`, `withStarko`
115
+ picks one and builds it into your app: the `release` option, else
116
+ `STARKO_RELEASE`, else the commit your CI sets (`VERCEL_GIT_COMMIT_SHA`,
117
+ `GITHUB_SHA`, …), else `git rev-parse HEAD`. Browser, server and Edge
118
+ events then carry the same release as your source maps, with webpack and
119
+ with Turbopack. The release is worked out once per build, so the upload and
120
+ the events always agree.
121
+
122
+ A `release` you pass to `init` or `register` overrides it.
123
+
124
+ How it gets there: `withStarko` adds `STARKO_BUILD_RELEASE` to the `env` of
125
+ your Next config, and Next replaces `process.env.STARKO_BUILD_RELEASE` with
126
+ that string when it compiles, before it hashes any file. If you set
127
+ `env.STARKO_BUILD_RELEASE` yourself, yours is used, for the upload too.
128
+
129
+ Cases where you set it by hand:
130
+
131
+ | Situation | What to do |
132
+ | --- | --- |
133
+ | The build log says "no release for this build" (no `.git` in the build, no CI commit variable, for example a Docker build) | Set `STARKO_RELEASE` where you run `next build`, or pass `release` in the `withStarko` options. |
134
+ | No `STARKO_API_KEY` / `apiKey` where `next build` runs | `withStarko` changes nothing without a key, so events carry no release. Set the key, or pass `release` to `init` and `register`. |
135
+ | You start the browser SDK from `@starko-one/sdk/browser` instead of `/next/client` | Add `release: process.env.STARKO_BUILD_RELEASE` to that `init`. |
136
+ | `next dev` | Events carry no release unless you pass one. With `enabled: true`, `withStarko` uses only its `release` option or `STARKO_RELEASE` in development, never the commit. |
137
+
138
+ On the Node.js server the order is: the `release` you passed, then the
139
+ build's release, then `STARKO_RELEASE` at run time. A `STARKO_RELEASE` set
140
+ only where the server runs does not replace the release the app was built
141
+ with.
142
+
143
+ ## Errors shown by `global-error.tsx` and `error.tsx`
144
+
145
+ Errors that an `error.tsx` or `global-error.tsx` boundary catches do not
146
+ reach the page's global error handler, so report them from the boundary:
147
+
148
+ ```tsx
149
+ "use client";
150
+ import { useEffect } from "react";
151
+ import { captureGlobalError } from "@starko-one/sdk/next/client";
152
+
153
+ export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
154
+ useEffect(() => {
155
+ captureGlobalError(error);
156
+ }, [error]);
157
+
158
+ return (
159
+ <html>
160
+ <body>
161
+ <h2>Something went wrong</h2>
162
+ <button onClick={() => reset()}>Try again</button>
163
+ </body>
164
+ </html>
165
+ );
166
+ }
167
+ ```
168
+
169
+ The same `useEffect` works in any `error.tsx` (which has no `<html>` or
170
+ `<body>`). Next 16.3 also passes `retry`, which re-fetches before
171
+ re-rendering; use whichever your version has.
172
+
173
+ `captureGlobalError` skips three kinds of error:
174
+
175
+ - Next's control flow;
176
+ - an error the SDK already captured;
177
+ - an error that came from the server. Next gives those a `digest`, and
178
+ `onRequestError` has already reported it on the server, with the same
179
+ value in the `next.digest` tag.
180
+
181
+ Without the server SDK, report server errors from the browser instead with
182
+ `captureGlobalError(error, { serverErrors: true })`.
183
+
184
+ ## Server actions and route handlers
185
+
186
+ An error that escapes a server action or a route handler reaches
187
+ `onRequestError` and is captured; you need nothing else. When you catch an
188
+ error yourself, report it with the same API as everywhere:
189
+
190
+ ```ts
191
+ "use server";
192
+ import * as Starko from "@starko-one/sdk/next";
193
+
194
+ export async function placeOrder(cartId: string) {
195
+ try {
196
+ await fetch(`https://payments.example.com/charge/${cartId}`, { method: "POST" });
197
+ return { ok: true };
198
+ } catch (error) {
199
+ Starko.captureException(error, { tags: { action: "placeOrder" } });
200
+ return { ok: false };
201
+ }
202
+ }
203
+ ```
204
+
205
+ A `redirect()` or `notFound()` caught by a `try` around it is still dropped.
206
+
207
+ ### The user on the server
208
+
209
+ On the Node.js runtime every request has its own scope, so the user you set
210
+ while handling a request stays with that request:
211
+
212
+ ```ts
213
+ "use server";
214
+ import * as Starko from "@starko-one/sdk/next";
215
+
216
+ export async function saveProfile(userId: string, name: string) {
217
+ Starko.setUser({ id: userId });
218
+ if (!name.trim()) throw new Error("Name is required");
219
+ return { ok: true };
220
+ }
221
+ ```
222
+
223
+ With `apiKey` set in `register`, that `id` is linked to the customer in
224
+ Starko. Without it, it is kept as text unless you also send a user hash (see
225
+ [browser.md](./browser.md#identify-the-user)).
226
+
227
+ A user set outside a request (at the top level of a module, in a timer)
228
+ never reaches a request's errors. Every request starts from the same base:
229
+ the `user` passed to `register` and the tags, extra and contexts set before
230
+ `register()` ran. After `register()`, what code outside a request sets stays
231
+ with that code and what it starts (see
232
+ [node.md](./node.md#code-outside-a-request)). `next start` accepts
233
+ connections before `register()` has finished, so a request can arrive
234
+ before the SDK is ready: it is not given a scope of its own, but what it
235
+ sets after `register()` stays with it and never reaches later requests.
236
+
237
+ ## How a server error links to the browser session
238
+
239
+ After `init`, the browser adds an `x-starko-session-id` header to the
240
+ requests the page makes to its own origin with `fetch` or `XMLHttpRequest`.
241
+ The server SDK reads it and stamps that session on the request's errors, so
242
+ the error links to the same session (and its recording) as the browser's
243
+ errors. Requests to other origins never get the header.
244
+
245
+ Not linked: the first request for a page that the browser makes itself (the
246
+ HTML document, before any script runs). A server error while rendering a
247
+ page that the user opened directly or reloaded carries no session.
248
+
249
+ ## Edge runtime
250
+
251
+ On the Edge runtime `register` starts a smaller client. What differs from
252
+ the Node.js runtime:
253
+
254
+ - No HTTP server to instrument: a request has its own scope only inside
255
+ `onRequestError`, `wrapHandler`, `withScope` and `runWithRequestScope`
256
+ (using the runtime's `AsyncLocalStorage`). Tags, extra, contexts and
257
+ breadcrumbs set outside them go to the isolate's global scope: request
258
+ scopes never copy it, but every event captured outside a request scope
259
+ carries it, including an `onRequestError` event for a route that
260
+ `wrapHandler` does not wrap. `setUser` outside them is refused with a
261
+ warning printed once. Wrap Edge route handlers in `wrapHandler`.
262
+ - No process hooks, no source lines, no console breadcrumbs.
263
+ - `STARKO_RELEASE` is not read at run time; the release is the one you
264
+ pass, else the one `withStarko` built into the app.
265
+ - `defaultIntegrations` as an array is ignored (the Edge defaults are used);
266
+ `false` and the `integrations` option work.
267
+
268
+ Give an Edge route handler its own scope with `wrapHandler`:
269
+
270
+ ```ts
271
+ import * as Starko from "@starko-one/sdk/next";
272
+
273
+ export const runtime = "edge";
274
+
275
+ export const GET = Starko.wrapHandler(async (request: Request) => {
276
+ const url = new URL(request.url);
277
+ Starko.setTag("query", url.searchParams.get("q") ?? "");
278
+ return Response.json({ ok: true });
279
+ });
280
+ ```
281
+
282
+ `wrapHandler` captures what the handler throws, flushes (handing the flush
283
+ to the platform's `waitUntil` when there is one), and rethrows the error
284
+ unchanged; `onRequestError` then sees the same error and does not report it
285
+ twice.
286
+
287
+ ## Vercel and long-lived servers
288
+
289
+ Next waits for `onRequestError` before it sends the error response, so the
290
+ hook never waits for the network when it can avoid it:
291
+
292
+ | Where | What the hook does |
293
+ | --- | --- |
294
+ | Vercel (Node.js and Edge), Next's Edge sandbox, Cloudflare via OpenNext | Hands a flush of at most `flushTimeout` (default 2000 ms) to the platform's `waitUntil` and returns at once. |
295
+ | A long-lived Node server (`next start`, standalone output, a container) | Queues the event and returns at once; the queue sends it about a second later. |
296
+ | A serverless platform (detected from `VERCEL`, `AWS_LAMBDA_FUNCTION_NAME`, `NETLIFY`, `FUNCTION_TARGET` or `FUNCTIONS_WORKER_RUNTIME`) without `waitUntil`, or the Edge runtime without one | Waits for a flush of at most 500 ms. |
297
+
298
+ No flush starts while a send is already in flight or waiting out a back-off.
299
+
300
+ Shutting down a long-lived server: `next start` handles `SIGTERM` and
301
+ `SIGINT` itself and calls `process.exit` without waiting, so events still
302
+ queued at that moment (at most about a second's worth) are lost; the SDK's
303
+ own flush on signals only runs when nothing else listens for them (see
304
+ [node.md](./node.md#shutdown-and-signals)). If you set
305
+ `NEXT_MANUAL_SIG_HANDLE=1`, Next leaves the signals to you: call
306
+ `await Starko.flush(2000)` in your handler before `process.exit`.
307
+
308
+ ## See also
309
+
310
+ - [source-maps.md](./source-maps.md#nextjs): what `withStarko` changes and deletes.
311
+ - [configuration.md](./configuration.md): every option.
312
+ - [widget.md](./widget.md): using the SDK together with the Starko widget.