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

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 +248 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-BAFm4Lxj.d.ts +558 -0
  6. package/dist/api-DNrctwJu.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-2PM4FRM5.cjs +431 -0
  24. package/dist/chunk-335HNCOJ.js +249 -0
  25. package/dist/chunk-3AW5B2WW.js +115 -0
  26. package/dist/chunk-3R5TQAWD.js +216 -0
  27. package/dist/chunk-6H5MOPTQ.cjs +1230 -0
  28. package/dist/chunk-7TKNT3QJ.cjs +2487 -0
  29. package/dist/chunk-A4WLNFMU.cjs +220 -0
  30. package/dist/chunk-ALYFFOPR.cjs +134 -0
  31. package/dist/chunk-BVVFVRMO.js +1113 -0
  32. package/dist/chunk-CIHNKN62.cjs +15 -0
  33. package/dist/chunk-CMGCH6HD.js +1212 -0
  34. package/dist/chunk-D6QAPQ7L.cjs +56 -0
  35. package/dist/chunk-DUO5V6WZ.js +213 -0
  36. package/dist/chunk-EC2WZ6PG.js +90 -0
  37. package/dist/chunk-EFURLFJT.cjs +187 -0
  38. package/dist/chunk-EROUORMY.js +53 -0
  39. package/dist/chunk-LXBXFOAP.cjs +96 -0
  40. package/dist/chunk-MF6SA6DB.js +563 -0
  41. package/dist/chunk-N5R6ORIB.js +413 -0
  42. package/dist/chunk-N6R6BWHK.cjs +142 -0
  43. package/dist/chunk-QAGGN2T7.cjs +225 -0
  44. package/dist/chunk-QV4HRIDD.cjs +659 -0
  45. package/dist/chunk-TKNDYQB3.cjs +583 -0
  46. package/dist/chunk-UI5YC4TH.js +131 -0
  47. package/dist/chunk-VEHZYLK6.cjs +1151 -0
  48. package/dist/chunk-VNCWOGTI.js +12 -0
  49. package/dist/chunk-VWNIOGE6.js +180 -0
  50. package/dist/chunk-WDKRKGYF.js +608 -0
  51. package/dist/chunk-XOZIXBUK.js +2462 -0
  52. package/dist/chunk-ZS3K3SDR.cjs +258 -0
  53. package/dist/cli/index.cjs +2780 -0
  54. package/dist/common-DLFAqL2d.d.cts +36 -0
  55. package/dist/common-DbSXkaw6.d.ts +36 -0
  56. package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
  57. package/dist/dedupe-DoYiSx-9.d.ts +13 -0
  58. package/dist/handler-BcnsnvhF.d.cts +82 -0
  59. package/dist/handler-qHzilC9T.d.ts +82 -0
  60. package/dist/index.cjs +309 -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 +277 -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 +263 -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-BUhWuWJX.d.cts +79 -0
  81. package/dist/options-BUhWuWJX.d.ts +79 -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-D1ouJm2h.d.cts +628 -0
  87. package/dist/scope-D1ouJm2h.d.ts +628 -0
  88. package/dist/server-edge-7624N3WF.cjs +51 -0
  89. package/dist/server-edge-BEEXWL7T.js +48 -0
  90. package/dist/server-node-ET4LIPEC.cjs +27 -0
  91. package/dist/server-node-TQUVMZUC.js +24 -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-Pr0Zb9Zn.d.cts +30 -0
  95. package/dist/session-propagation-RM5py1bp.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +386 -0
  98. package/docs/configuration.md +310 -0
  99. package/docs/nextjs.md +488 -0
  100. package/docs/node.md +427 -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 +482 -0
  105. package/docs/troubleshooting.md +263 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +547 -0
  108. package/package.json +191 -4
package/docs/nextjs.md ADDED
@@ -0,0 +1,488 @@
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.VERCEL_ENV ?? process.env.NODE_ENV,
26
+ });
27
+ }
28
+
29
+ export const onRequestError = Starko.onRequestError;
30
+ ```
31
+
32
+ For `environment`, see [below](#environment-production-or-preview): on
33
+ Vercel, `NODE_ENV` alone would file preview errors as production. To keep
34
+ the SDK off where its key is not set (local development, previews), see
35
+ [Configure it from environment variables](#configure-it-from-environment-variables).
36
+
37
+ `register` starts the SDK for the runtime Next calls it in: the full Node SDK
38
+ on the Node.js runtime (see [node.md](./node.md)), a smaller client on the
39
+ Edge runtime (see [Edge runtime](#edge-runtime)), and nothing anywhere else.
40
+ It never rejects. `register` takes every Node option
41
+ ([configuration.md](./configuration.md#nextjs-server-register)) plus
42
+ `flushTimeout`.
43
+
44
+ `onRequestError` captures every error Next reports from rendering, route
45
+ handlers, server actions and the proxy (middleware), with the route, the
46
+ router kind, the route type, the render source and the method (tags
47
+ `next.router_kind`, `next.route_type`, `next.render_source`, `next.method`,
48
+ `next.digest`; context `nextjs`). Next's control flow (`redirect()`,
49
+ `notFound()`, `forbidden()`, `unauthorized()`, postponed and aborted
50
+ renders) is never reported, whatever captured it.
51
+
52
+ If you already export your own `onRequestError`, call the SDK from it:
53
+
54
+ ```ts
55
+ import * as Starko from "@starko-one/sdk/next";
56
+ import type { NextRequestErrorContext, NextRequestErrorRequest } from "@starko-one/sdk/next";
57
+
58
+ export async function onRequestError(error: unknown, request: NextRequestErrorRequest, context: NextRequestErrorContext) {
59
+ await Starko.captureRequestError(error, request, context);
60
+ // your own reporting
61
+ }
62
+ ```
63
+
64
+ `apiKey` is a secret key with the `errors:write` scope. It is optional; with
65
+ it, Starko trusts the `user.id` your server sets and links it to the
66
+ customer without a hash. Keep it on the server: never pass it to
67
+ `instrumentation-client.ts`, and never give it a `NEXT_PUBLIC_` name (Next
68
+ copies those variables into browser bundles).
69
+
70
+ ## 2. `instrumentation-client.ts` (browser)
71
+
72
+ ```ts
73
+ import * as Starko from "@starko-one/sdk/next/client";
74
+
75
+ Starko.init({
76
+ workspaceKey: "<STARKO_WORKSPACE_KEY>",
77
+ environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? process.env.NODE_ENV,
78
+ });
79
+ ```
80
+
81
+ Next runs this file after the HTML loads and before React hydrates. `init`
82
+ is the browser SDK's (every option in [browser.md](./browser.md)) plus the
83
+ filter that drops Next's control flow.
84
+
85
+ On Next 14 and 15.0 to 15.2, which do not have this file, call
86
+ `Starko.init` at the top level of a module marked `"use client"` that your
87
+ root layout renders. Errors thrown before that module runs are not
88
+ captured.
89
+
90
+ ## 3. `next.config.ts` (source maps)
91
+
92
+ ```ts
93
+ import { withStarko } from "@starko-one/sdk/next/config";
94
+
95
+ const nextConfig = {
96
+ reactStrictMode: true,
97
+ };
98
+
99
+ export default withStarko(nextConfig);
100
+ ```
101
+
102
+ `withStarko` returns your config unchanged unless it is a production build
103
+ (`next build`) **and** a secret key with the `sourcemaps:write` scope is in
104
+ `STARKO_API_KEY` (or passed as `apiKey`). With both, it makes sure the
105
+ bundles have debug ids (on Next 16 Turbopack writes its own), uploads the
106
+ source maps, and deletes from `.next` the maps it switched on. With
107
+ `experimental.sri` it changes no client chunk after Next has computed the
108
+ integrity hashes, so the pages keep loading. Your config can also be a
109
+ function or an async function; `withStarko` returns the same kind of value
110
+ it is given and passes every field it does not touch through, so it
111
+ combines with other config wrappers (see
112
+ [Other config wrappers](#other-config-wrappers)). Details, options and the
113
+ deletion rules: [source-maps.md](./source-maps.md#nextjs).
114
+
115
+ ### Other config wrappers
116
+
117
+ `withStarko` does its work (inject, upload, delete the maps it switched
118
+ on) in Next's `compiler.runAfterProductionCompile` hook, which it adds to
119
+ the config it returns, after calling the one your config already has. It
120
+ also switches on `productionBrowserSourceMaps`. So a wrapper around it
121
+ must keep that hook. If a wrapper outside it builds a new config without
122
+ `compiler.runAfterProductionCompile` (or replaces it without calling the
123
+ previous one), nothing is uploaded and **the browser maps `withStarko`
124
+ switched on stay in `.next/static` and are deployed** with your app.
125
+
126
+ - Put `withStarko` outermost when you can: it then sees the final config
127
+ and calls whatever hook the inner wrappers set, before its own.
128
+
129
+ ```ts
130
+ import { withStarko } from "@starko-one/sdk/next/config";
131
+
132
+ const withOther = (config: object) => ({ ...config, poweredByHeader: false });
133
+
134
+ export default withStarko(withOther({ reactStrictMode: true }));
135
+ ```
136
+
137
+ - When another wrapper must be outside it, check once that it keeps the
138
+ hook: after `next build` the log has a `[starko] source maps…` line (or,
139
+ for a large app's first upload, the `source map upload: …` lines) and, by
140
+ default, `deleted N browser source map(s) from .next/static`; and
141
+ `find .next/static -name "*.map"` finds nothing.
142
+
143
+ ## Releases
144
+
145
+ The release is the version of your app an error is recorded under.
146
+
147
+ You don't need to set `release`. When you run `next build`, `withStarko`
148
+ picks one and builds it into your app: the `release` option, else
149
+ `STARKO_RELEASE`, else the commit your CI sets (`VERCEL_GIT_COMMIT_SHA`,
150
+ `GITHUB_SHA`, …), else `git rev-parse HEAD`. Browser, server and Edge
151
+ events then carry the same release as your source maps, with webpack and
152
+ with Turbopack. The release is worked out once per build, so the upload and
153
+ the events always agree.
154
+
155
+ A `release` you pass to `init` or `register` overrides it.
156
+
157
+ How it gets there: `withStarko` adds `STARKO_BUILD_RELEASE` to the `env` of
158
+ your Next config, and Next replaces `process.env.STARKO_BUILD_RELEASE` with
159
+ that string when it compiles, before it hashes any file. If you set
160
+ `env.STARKO_BUILD_RELEASE` yourself, yours is used, for the upload too.
161
+
162
+ Cases where you set it by hand:
163
+
164
+ | Situation | What to do |
165
+ | --- | --- |
166
+ | 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. |
167
+ | 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`. |
168
+ | You start the browser SDK from `@starko-one/sdk/browser` instead of `/next/client` | Add `release: process.env.STARKO_BUILD_RELEASE` to that `init`. |
169
+ | `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. |
170
+
171
+ On the Node.js server the order is: the `release` you passed, then the
172
+ build's release, then `STARKO_RELEASE` at run time. A `STARKO_RELEASE` set
173
+ only where the server runs does not replace the release the app was built
174
+ with.
175
+
176
+ ## Errors shown by `global-error.tsx` and `error.tsx`
177
+
178
+ Errors that an `error.tsx` or `global-error.tsx` boundary catches do not
179
+ reach the page's global error handler, so report them from the boundary.
180
+ Next 16.3 and later (`retry`, which re-fetches before re-rendering):
181
+
182
+ ```tsx
183
+ "use client";
184
+ import { useEffect } from "react";
185
+ import { captureGlobalError } from "@starko-one/sdk/next/client";
186
+
187
+ export default function GlobalError({ error, retry }: { error: Error & { digest?: string }; retry: () => void }) {
188
+ useEffect(() => {
189
+ captureGlobalError(error);
190
+ }, [error]);
191
+
192
+ return (
193
+ <html>
194
+ <body>
195
+ <h2>Something went wrong</h2>
196
+ <button onClick={() => retry()}>Try again</button>
197
+ </body>
198
+ </html>
199
+ );
200
+ }
201
+ ```
202
+
203
+ | Next | The prop to call |
204
+ | --- | --- |
205
+ | 16.3 and later | `retry` (above). `reset` still exists; it re-renders without re-fetching. |
206
+ | 16.2 | `unstable_retry`, or `reset` |
207
+ | 16.1 and earlier | `reset`: `{ error, reset }: { error: Error & { digest?: string }; reset: () => void }` and `onClick={() => reset()}` |
208
+
209
+ The SDK part, the `useEffect` with `captureGlobalError`, is the same in
210
+ every version and in any `error.tsx` (which has no `<html>` or `<body>`).
211
+
212
+ `captureGlobalError` skips three kinds of error:
213
+
214
+ - Next's control flow;
215
+ - an error the SDK already captured;
216
+ - an error that came from the server. Next gives those a `digest`, and
217
+ `onRequestError` has already reported it on the server, with the same
218
+ value in the `next.digest` tag.
219
+
220
+ Without the server SDK, report server errors from the browser instead with
221
+ `captureGlobalError(error, { serverErrors: true })`.
222
+
223
+ ## Environment: production or preview
224
+
225
+ `environment` tells production errors from the others. Do not set it from
226
+ `NODE_ENV` alone: `next build` sets `NODE_ENV` to `production` for every
227
+ build, so on Vercel (and other hosts that build preview deployments the
228
+ same way) errors from previews would be filed as production.
229
+
230
+ Use your host's own variable, with `NODE_ENV` as the fallback (for
231
+ `next dev` and hosts without one):
232
+
233
+ | File | On Vercel |
234
+ | --- | --- |
235
+ | `instrumentation.ts` (server) | `environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV` |
236
+ | `instrumentation-client.ts` (browser) | `environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? process.env.NODE_ENV` |
237
+
238
+ `VERCEL_ENV` is `production`, `preview` or `development`. The browser only
239
+ sees variables whose name starts with `NEXT_PUBLIC_`, which Next writes into
240
+ the bundle at build time; Vercel sets `NEXT_PUBLIC_VERCEL_ENV` for its
241
+ production and preview builds. On another host, set a variable of your
242
+ own (for example `NEXT_PUBLIC_APP_ENV`) where the build runs and read it in
243
+ both files. A Vercel custom environment reports `preview` in `VERCEL_ENV`;
244
+ its name is in `VERCEL_TARGET_ENV`.
245
+
246
+ ## Configure it from environment variables
247
+
248
+ To keep local development and preview deployments silent, start the SDK
249
+ only where its workspace key is set, and set the key only for the
250
+ deployments you want reported. The workspace key is public, so one
251
+ `NEXT_PUBLIC_` variable serves both files:
252
+
253
+ ```ts
254
+ // instrumentation.ts
255
+ import * as Starko from "@starko-one/sdk/next";
256
+
257
+ const workspaceKey = process.env.NEXT_PUBLIC_STARKO_WORKSPACE_KEY;
258
+
259
+ export async function register() {
260
+ if (!workspaceKey) return;
261
+ await Starko.register({
262
+ workspaceKey,
263
+ apiKey: process.env.STARKO_API_KEY,
264
+ environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV,
265
+ });
266
+ }
267
+
268
+ export async function onRequestError(...args: Parameters<typeof Starko.onRequestError>) {
269
+ if (workspaceKey) await Starko.onRequestError(...args);
270
+ }
271
+ ```
272
+
273
+ ```ts
274
+ // instrumentation-client.ts
275
+ import * as Starko from "@starko-one/sdk/next/client";
276
+
277
+ const workspaceKey = process.env.NEXT_PUBLIC_STARKO_WORKSPACE_KEY;
278
+
279
+ if (workspaceKey) {
280
+ Starko.init({
281
+ workspaceKey,
282
+ environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? process.env.NODE_ENV,
283
+ });
284
+ }
285
+ ```
286
+
287
+ Guard `onRequestError` too: the plain
288
+ `export const onRequestError = Starko.onRequestError` loads the SDK's server
289
+ runtime the first time Next reports an error, even when `register` never
290
+ started it (it then sends nothing). Importing `@starko-one/sdk/next` alone
291
+ loads none of it.
292
+
293
+ Next writes `NEXT_PUBLIC_` values into the browser bundle when it builds,
294
+ so the browser SDK follows the variable as it was at build time: on Vercel,
295
+ give `NEXT_PUBLIC_STARKO_WORKSPACE_KEY` to the Production environment only
296
+ and previews build without it. `captureGlobalError` in `global-error.tsx`
297
+ does nothing while `init` has not run, so it needs no guard.
298
+
299
+ `withStarko` follows its own variable: it changes nothing and uploads
300
+ nothing without `STARKO_API_KEY` where `next build` runs.
301
+
302
+ ## Server actions and route handlers
303
+
304
+ An error that escapes a server action or a route handler reaches
305
+ `onRequestError` and is captured; you need nothing else. When you catch an
306
+ error yourself, report it with the same API as everywhere:
307
+
308
+ ```ts
309
+ "use server";
310
+ import * as Starko from "@starko-one/sdk/next";
311
+
312
+ export async function placeOrder(cartId: string) {
313
+ try {
314
+ await fetch(`https://payments.example.com/charge/${cartId}`, { method: "POST" });
315
+ return { ok: true };
316
+ } catch (error) {
317
+ Starko.captureException(error, { tags: { action: "placeOrder" } });
318
+ return { ok: false };
319
+ }
320
+ }
321
+ ```
322
+
323
+ A `redirect()` or `notFound()` caught by a `try` around it is still dropped.
324
+
325
+ ### The user on the server
326
+
327
+ On the Node.js runtime every request has its own scope, so the user you set
328
+ while handling a request stays with that request:
329
+
330
+ ```ts
331
+ "use server";
332
+ import * as Starko from "@starko-one/sdk/next";
333
+
334
+ export async function saveProfile(userId: string, name: string) {
335
+ Starko.setUser({ id: userId });
336
+ if (!name.trim()) throw new Error("Name is required");
337
+ return { ok: true };
338
+ }
339
+ ```
340
+
341
+ With `apiKey` set in `register`, that `id` is linked to the customer in
342
+ Starko. Without it, it is kept as text unless you also send a user hash (see
343
+ [browser.md](./browser.md#identify-the-user)).
344
+
345
+ A user set outside a request (at the top level of a module, in a timer)
346
+ never reaches a request's errors. Every request starts from the same base:
347
+ the `user` passed to `register` and the tags, extra and contexts set before
348
+ `register()` ran. After `register()`, what code outside a request sets stays
349
+ with that code and what it starts (see
350
+ [node.md](./node.md#code-outside-a-request)). `next start` accepts
351
+ connections before `register()` has finished, so a request can arrive
352
+ before the SDK is ready: it is not given a scope of its own, but what it
353
+ sets after `register()` stays with it and never reaches later requests.
354
+
355
+ ## How a server error links to the browser session
356
+
357
+ After `init`, the browser adds an `x-starko-session-id` header to the
358
+ requests the page makes to its own origin with `fetch` or `XMLHttpRequest`.
359
+ The server SDK reads it and stamps that session on the request's errors, so
360
+ the error links to the same session (and its recording) as the browser's
361
+ errors. Requests to other origins never get the header.
362
+
363
+ Not linked: the first request for a page that the browser makes itself (the
364
+ HTML document, before any script runs). A server error while rendering a
365
+ page that the user opened directly or reloaded carries no session.
366
+
367
+ ## Edge runtime
368
+
369
+ On the Edge runtime `register` starts a smaller client. What differs from
370
+ the Node.js runtime:
371
+
372
+ - No HTTP server to instrument: a request has its own scope only inside
373
+ `onRequestError`, `wrapHandler`, `withScope` and `runWithRequestScope`
374
+ (using the runtime's `AsyncLocalStorage`). Tags, extra, contexts and
375
+ breadcrumbs set outside them go to the isolate's global scope: request
376
+ scopes never copy it, but every event captured outside a request scope
377
+ carries it, including an `onRequestError` event for a route that
378
+ `wrapHandler` does not wrap. `setUser` outside them is refused with a
379
+ warning printed once. Wrap Edge route handlers in `wrapHandler`.
380
+ - No process hooks, no source lines, no console breadcrumbs.
381
+ - `STARKO_RELEASE` is not read at run time; the release is the one you
382
+ pass, else the one `withStarko` built into the app.
383
+ - `defaultIntegrations` as an array is ignored (the Edge defaults are used);
384
+ `false` and the `integrations` option work.
385
+
386
+ Give an Edge route handler its own scope with `wrapHandler`:
387
+
388
+ ```ts
389
+ import * as Starko from "@starko-one/sdk/next";
390
+
391
+ export const runtime = "edge";
392
+
393
+ export const GET = Starko.wrapHandler(async (request: Request) => {
394
+ const url = new URL(request.url);
395
+ Starko.setTag("query", url.searchParams.get("q") ?? "");
396
+ return Response.json({ ok: true });
397
+ });
398
+ ```
399
+
400
+ `wrapHandler` captures what the handler throws, flushes (handing the flush
401
+ to the platform's `waitUntil` when there is one), and rethrows the error
402
+ unchanged; `onRequestError` then sees the same error and does not report it
403
+ twice.
404
+
405
+ ## Vercel and long-lived servers
406
+
407
+ Next waits for `onRequestError` before it sends the error response, so the
408
+ hook never waits for the network when it can avoid it:
409
+
410
+ | Where | What the hook does |
411
+ | --- | --- |
412
+ | 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. |
413
+ | 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. |
414
+ | 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. |
415
+
416
+ No flush starts while a send is already in flight or waiting out a back-off.
417
+
418
+ Shutting down a long-lived server: `next start` handles `SIGTERM` and
419
+ `SIGINT` itself and calls `process.exit` without waiting, so events still
420
+ queued at that moment (at most about a second's worth) are lost; the SDK's
421
+ own flush on signals only runs when nothing else listens for them (see
422
+ [node.md](./node.md#shutdown-and-signals)). If you set
423
+ `NEXT_MANUAL_SIG_HANDLE=1`, Next leaves the signals to you: call
424
+ `await Starko.flush(2000)` in your handler before `process.exit`.
425
+
426
+ ## Large builds
427
+
428
+ A large Next.js app has thousands of source maps. With the bulk upload,
429
+ the default whenever the Starko server offers it, `withStarko` sends each
430
+ map from the build machine straight to Starko's storage through a
431
+ short-lived signed URL, 16 at a time, and only small requests go to the
432
+ Starko host. The build machine must therefore reach the storage host too:
433
+ when it cannot (a proxy or a firewall that allows only the Starko host),
434
+ the upload says so in a warning naming the host and sends the remaining
435
+ maps through the Starko host instead (v1, the ones already reserved for
436
+ storage included), which is much slower. Set
437
+ `uploadProtocol: "v1"` to skip storage altogether, or allow the host.
438
+
439
+ A first upload that does not finish within `withStarko`'s 3-minute default
440
+ is not lost: the build goes on, the log says how many maps were uploaded
441
+ and how many were not sent, and the next build continues from there (a
442
+ completed map is never sent again). Later builds send only the chunks that
443
+ changed and finish in seconds. To catch up in one build:
444
+
445
+ ```ts
446
+ import { withStarko } from "@starko-one/sdk/next/config";
447
+
448
+ export default withStarko({ reactStrictMode: true }, { uploadTimeoutMs: 30 * 60_000 });
449
+ ```
450
+
451
+ Keep it within your host's build time limit. What to expect, with
452
+ measurements: [source-maps.md](./source-maps.md#large-builds).
453
+
454
+ ## Building on GitHub Actions for Vercel (`vercel pull` + `vercel build`)
455
+
456
+ When GitHub Actions builds the app with the Vercel CLI and deploys the
457
+ result with `--prebuilt`, `next build` runs on the GitHub runner, inside
458
+ `vercel build`. The source-map key therefore goes into the environment of
459
+ that step, from a GitHub secret:
460
+
461
+ ```yaml
462
+ - run: npx vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
463
+ - run: npx vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
464
+ env:
465
+ STARKO_API_KEY: ${{ secrets.STARKO_API_KEY }}
466
+ - run: npx vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
467
+ ```
468
+
469
+ (`VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` as in Vercel's own guide.) The
470
+ upload runs during `vercel build`; the deploy step uploads no maps, and the
471
+ maps `withStarko` switched on are already deleted from the output it
472
+ deploys.
473
+
474
+ In this flow the build does not run on Vercel, so Vercel's system variables
475
+ may be missing from it:
476
+
477
+ - the release is still the commit being built: `GITHUB_SHA` when Vercel's
478
+ `VERCEL_GIT_COMMIT_SHA` is missing;
479
+ - `NEXT_PUBLIC_VERCEL_ENV` may be unset when Next writes the browser
480
+ bundle, and the browser SDK then reports `NODE_ENV` (`production`). If
481
+ you build previews this way too, set it in the build step:
482
+ `NEXT_PUBLIC_VERCEL_ENV: preview`.
483
+
484
+ ## See also
485
+
486
+ - [source-maps.md](./source-maps.md#nextjs): what `withStarko` changes and deletes.
487
+ - [configuration.md](./configuration.md): every option.
488
+ - [widget.md](./widget.md): using the SDK together with the Starko widget.