@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.
- package/CHANGELOG.md +124 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-B5IHeINe.d.ts +558 -0
- package/dist/api-DR4HazCu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-7HYGODU6.cjs +583 -0
- package/dist/chunk-A5M4NOVT.js +413 -0
- package/dist/chunk-A7MYYWMP.cjs +15 -0
- package/dist/chunk-BAQA47FM.js +1113 -0
- package/dist/chunk-CM7HM6CC.js +563 -0
- package/dist/chunk-DFYNIWUN.js +608 -0
- package/dist/chunk-DMVVCGKO.cjs +96 -0
- package/dist/chunk-FARGXYJ4.cjs +56 -0
- package/dist/chunk-G3MYIAX2.js +1226 -0
- package/dist/chunk-G4NAVZQ4.js +249 -0
- package/dist/chunk-GH7RYPKS.js +96 -0
- package/dist/chunk-HADYYQNL.cjs +134 -0
- package/dist/chunk-HOQPAB4X.js +178 -0
- package/dist/chunk-J5RU73SW.js +214 -0
- package/dist/chunk-JNAJ3YZB.cjs +223 -0
- package/dist/chunk-KN7H22EQ.cjs +659 -0
- package/dist/chunk-LDQ4I7FZ.cjs +1151 -0
- package/dist/chunk-NPGESRVQ.js +1212 -0
- package/dist/chunk-OPWM5V7A.cjs +258 -0
- package/dist/chunk-PYYWPIFL.cjs +1230 -0
- package/dist/chunk-R7JLZ4WO.cjs +115 -0
- package/dist/chunk-SC6VQSES.js +213 -0
- package/dist/chunk-TPSJGLR3.cjs +220 -0
- package/dist/chunk-UKBY6HPC.js +131 -0
- package/dist/chunk-VRSEHRBX.cjs +185 -0
- package/dist/chunk-X74AONZA.js +90 -0
- package/dist/chunk-XW3I5CJN.js +12 -0
- package/dist/chunk-XW56FKKJ.js +53 -0
- package/dist/chunk-Z3G5SW7R.cjs +1251 -0
- package/dist/chunk-ZVMAN7OO.cjs +431 -0
- package/dist/cli/index.cjs +1487 -0
- package/dist/common-ARWXbeS3.d.ts +36 -0
- package/dist/common-CwIFh2hK.d.cts +36 -0
- package/dist/dedupe-eHBIfUUD.d.cts +13 -0
- package/dist/dedupe-fw8aNtt4.d.ts +13 -0
- package/dist/handler-DTZ4Rzcf.d.ts +82 -0
- package/dist/handler-_00lctTI.d.cts +82 -0
- package/dist/index.cjs +277 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +275 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +261 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-0BhybO54.d.cts +47 -0
- package/dist/options-0BhybO54.d.ts +47 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-Bvh45bOf.d.cts +404 -0
- package/dist/scope-Bvh45bOf.d.ts +404 -0
- package/dist/server-edge-BPOGA3GH.cjs +51 -0
- package/dist/server-edge-GYKAJREU.js +48 -0
- package/dist/server-node-HYK2OB2J.js +24 -0
- package/dist/server-node-J2DBAHDV.cjs +27 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-B7REA7uy.d.cts +30 -0
- package/dist/session-propagation-BnJjKJbR.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +381 -0
- package/docs/configuration.md +269 -0
- package/docs/nextjs.md +312 -0
- package/docs/node.md +376 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +332 -0
- package/docs/troubleshooting.md +171 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +367 -0
- 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.
|