@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
@@ -0,0 +1,482 @@
1
+ # Source maps
2
+
3
+ A minified bundle's stack trace (`a (checkout-4f9a2c.js:1:48213)`) says
4
+ nothing useful. With its source map uploaded, Starko shows the original file,
5
+ function and line instead. Source maps are uploaded at build time, with a
6
+ secret key; they are never fetched from your site, and the integrations here
7
+ never leave a map in your build output that you did not ask for.
8
+
9
+ ## How it works
10
+
11
+ Each bundle gets a **debug id**, a UUID derived from its content, written at
12
+ the end of the file (`//# debugId=…`), in its source map, and in a one-line
13
+ snippet at the top that registers the id at run time. When an error is
14
+ captured, the SDK sends each frame with the debug id of the bundle it came
15
+ from, and Starko resolves the frame with the map uploaded under that id. The
16
+ id belongs to the bytes, so the same bundle always gets the same id, and a
17
+ map can never be applied to the wrong file.
18
+
19
+ The tools below inject the ids and upload the maps. All of them need a
20
+ secret key with the `sourcemaps:write` scope, created in Starko under
21
+ Settings, in the `STARKO_API_KEY` environment variable of the build (or the
22
+ `apiKey` option). Keep it in your CI's secret store, never in code.
23
+
24
+ They also write the build's release into the bundles they inject, and the
25
+ SDK's `init` uses it when you pass no `release`. It is read for each event,
26
+ so `init` may run before the bundle that carries it loads. The release is
27
+ the `release` option, else `STARKO_RELEASE`, else the commit your CI
28
+ exposes (`GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `CI_COMMIT_SHA`, …), else
29
+ `git rev-parse HEAD`. With `withStarko`, the release your source maps are
30
+ uploaded under is also built into your app, so events match their source
31
+ maps without a `release` in `init` or `register`; see
32
+ [nextjs.md](./nextjs.md#releases).
33
+
34
+ ## Vite
35
+
36
+ ```ts
37
+ import { defineConfig } from "vite";
38
+ import { starkoVitePlugin } from "@starko-one/sdk/vite";
39
+
40
+ export default defineConfig({
41
+ plugins: [starkoVitePlugin()],
42
+ });
43
+ ```
44
+
45
+ Runs on `vite build` in production mode, not in watch mode. You do not need
46
+ to turn source maps on: when `build.sourcemap` is not set, the plugin makes
47
+ Vite emit hidden maps for the upload and removes them before the output is
48
+ written. `build.sourcemap: "inline"` is not uploaded.
49
+
50
+ ## Rollup
51
+
52
+ ```js
53
+ import { starkoRollupPlugin } from "@starko-one/sdk/rollup";
54
+
55
+ export default {
56
+ input: "src/main.js",
57
+ output: { dir: "dist", format: "es" },
58
+ plugins: [starkoRollupPlugin()],
59
+ };
60
+ ```
61
+
62
+ Runs on every build except in watch mode or when `NODE_ENV` is
63
+ `development`. For each output whose `output.sourcemap` is not set, the
64
+ plugin emits hidden maps for the upload and removes them before that
65
+ output is written; the maps of an output that sets it are yours, also when
66
+ two outputs write to the same directory. Inline maps are not uploaded.
67
+ Rolldown is supported as well.
68
+
69
+ ## webpack
70
+
71
+ ```js
72
+ import { StarkoWebpackPlugin } from "@starko-one/sdk/webpack";
73
+
74
+ export default {
75
+ mode: "production",
76
+ entry: "./src/index.js",
77
+ plugins: [new StarkoWebpackPlugin()],
78
+ };
79
+ ```
80
+
81
+ webpack 5. Runs when `mode` is `"production"`. With no `devtool` and no
82
+ `SourceMapDevToolPlugin` of your own, the plugin adds hidden maps for the
83
+ upload and removes them (only those) before anything is written. A
84
+ `SourceMapDevToolPlugin` in your config counts as your config asking for
85
+ maps. `eval` and `inline` devtools and an `EvalSourceMapDevToolPlugin` put
86
+ the map inside the bundle and are not supported: nothing is injected or
87
+ uploaded, and a warning says so. `upload: false` only injects (when
88
+ something else uploads).
89
+
90
+ ## Next.js
91
+
92
+ ```ts
93
+ import { withStarko } from "@starko-one/sdk/next/config";
94
+
95
+ export default withStarko({ reactStrictMode: true });
96
+ ```
97
+
98
+ Runs on `next build` only, and only with a key. What it does depends on the
99
+ Next version:
100
+
101
+ | Next | What `withStarko` does |
102
+ | --- | --- |
103
+ | 15.4.1 and later (webpack or Turbopack) | Switches `productionBrowserSourceMaps` and `experimental.serverSourceMaps` on, and after compilation (`compiler.runAfterProductionCompile`, chained after yours) injects the bundles under `.next/static` and `.next/server` that have a map and no debug id yet (with the exceptions below), uploads the maps once, and deletes the maps it switched on. |
104
+ | 16 and later | Also sets `turbopack.debugIds`, so Turbopack writes its own debug id into every chunk and registers it at run time; the SDK reads those ids. A bundle that registers its id this way is left byte for byte as it is. |
105
+ | webpack builds (any version) | The webpack plugin injects every client, server and edge bundle in memory, before Next hashes them; client maps that will be deleted are emitted without a `sourceMappingURL`. |
106
+ | `experimental.sri` on (or Next's integrity manifest in `.next`) | No file under `.next/static` is rewritten after compilation, since a changed chunk would no longer match its `integrity` hash and the browser would refuse it. A client chunk without a debug id of its own stays uninjected, and a warning says so: its frames are not resolved. The maps are still uploaded and deleted. |
107
+ | older than 15.4.1 | Only webpack builds are handled: the webpack plugin adds hidden maps, uploads them and removes them before they are written. Your source map flags are not touched. Turbopack builds are left as they are. |
108
+
109
+ The release does not depend on any of this: `withStarko` gives it to the
110
+ build through Next's `env`, so it is compiled into the client, server and
111
+ Edge bundles before Next hashes them ([nextjs.md](./nextjs.md#releases)).
112
+
113
+ With `output: "standalone"` on a webpack build, the server maps under
114
+ `.next/server` are kept: Next copies the traced server files after
115
+ `withStarko` has run and fails the build when one is missing. They are not
116
+ served to browsers. Browser maps are deleted as usual.
117
+
118
+ When `withStarko` deletes maps it switched on, it also removes the
119
+ `sourceMappingURL` comments pointing at them, except in client chunks it
120
+ does not rewrite (the cases above): those keep their comment, pointing at
121
+ the deleted file, and one warning says so. Browsers only request a map
122
+ when developer tools are open, and then get a 404.
123
+
124
+ Options: every option in [the table below](#options) plus
125
+ `deleteSourcemapsAfterUpload`, described in the next section.
126
+
127
+ ## Which maps are deleted
128
+
129
+ Every integration (Vite, Rollup, webpack, `withStarko`) follows the same rule:
130
+
131
+ | API key | Your config asked for maps | `deleteSourcemapsAfterUpload` | Result |
132
+ | --- | --- | --- | --- |
133
+ | none | either | any | Nothing changes: no maps switched on, no ids, no upload. A warning is printed once. |
134
+ | set | no | not set, `false` or `true` | The integration switches maps on for the upload and removes them after the upload attempt, **whatever its outcome**: success, failure, timeout, error, dry run. No `sourceMappingURL` comment points at them afterwards, except in Next.js client chunks `withStarko` does not rewrite (see [Next.js](#nextjs)). |
135
+ | set | yes | not set or `false` | Uploaded, and kept: they are yours. |
136
+ | set | yes | `true` | Uploaded, then deleted with their comments (the same Next.js exception applies), whatever the outcome. Not in a dry run. |
137
+
138
+ "Your config asked for maps" means: Vite `build.sourcemap` set to `true` or
139
+ `"hidden"`; Rollup `output.sourcemap` set (per output); webpack `devtool`
140
+ set, or a `SourceMapDevToolPlugin` in your config; Next
141
+ `productionBrowserSourceMaps: true` (browser maps) and
142
+ `experimental.serverSourceMaps: true` (server maps), decided separately. An
143
+ explicit `false` in Next counts as not asking.
144
+
145
+ ## The CLI
146
+
147
+ For any other build tool, or to keep the upload in CI. Make your build emit
148
+ source maps (preferably without `sourceMappingURL` comments, for example
149
+ Vite `build.sourcemap: "hidden"` or webpack `devtool: "hidden-source-map"`),
150
+ then run, on the final output:
151
+
152
+ ```sh
153
+ npx --package @starko-one/sdk starko sourcemaps inject dist
154
+ npx --package @starko-one/sdk starko sourcemaps upload dist --delete-after-upload
155
+ ```
156
+
157
+ `--package @starko-one/sdk` makes `npx` run the `starko` command from this
158
+ package (your installed copy when it is a dependency). A bare `npx starko`
159
+ would download an unrelated package of that name. In a `package.json`
160
+ script you can write `starko sourcemaps upload dist` directly.
161
+
162
+ - `inject <dir>` gives every bundle under `<dir>` that has a source map a
163
+ debug id, rewriting each bundle and its map in place. A bundle that
164
+ already has a debug id (from a plugin, a bundler, Sentry's tools) keeps it
165
+ and only gets the snippet. Running it twice changes nothing the second
166
+ time. It needs no key.
167
+ - `upload <dir>` uploads the maps of injected bundles. Maps Starko already
168
+ has are skipped. It needs the key.
169
+ - Only files inside `<dir>` are read, written or deleted: a
170
+ `sourceMappingURL` that is absolute, remote or points outside `<dir>`
171
+ (`../`, a symbolic link) is ignored. A bundle and its map are rewritten
172
+ through new temporary files with random names, created exclusively and
173
+ never through a symbolic link.
174
+ - Index maps (with `sections`, as Turbopack writes them) are shifted for
175
+ the injected snippet and uploaded as they are.
176
+ - A redirect is never followed: a `3xx` answer from the Starko host stops
177
+ the upload with an error naming its `Location` (the maps are your
178
+ source code); set `--host` to the final address. A `3xx` from storage
179
+ fails that map. The same applies to the build plugins and `withStarko`.
180
+
181
+ | Flag | Meaning |
182
+ | --- | --- |
183
+ | `--release <version>` | Release of this build. Default: `STARKO_RELEASE`, the CI commit, `git rev-parse HEAD`. |
184
+ | `--api-key <key>` | Secret key with the `sourcemaps:write` scope. Default: `STARKO_API_KEY`. Prefer the variable: flags show up in process lists and shell history. |
185
+ | `--host <url>` | Starko host. Default: `STARKO_HOST`, then `https://v2.starko.one`. |
186
+ | `--include <glob>` | Only bundles matching the glob. Repeatable. |
187
+ | `--exclude <glob>` | Skip bundles matching the glob. Repeatable. Default: `**/node_modules/**`. |
188
+ | `--delete-after-upload` | `upload` only: delete the maps and the `sourceMappingURL` comments pointing at them after the upload attempt, even when it failed. Not with `--dry-run`. |
189
+ | `--timeout <seconds>` | `upload` only: deadline for the whole upload. Default 180. What was uploaded before it passed stays uploaded; the next run sends only the rest. |
190
+ | `--concurrency <n>` | `upload` only: source maps sent at the same time, 1 to 16. Default 16 with the bulk upload, 8 with v1. |
191
+ | `--protocol <name>` | `upload` only: `auto` (default), `bulk` or `v1`. See [Which protocol](#which-protocol). |
192
+ | `--dry-run` | Show what would be done; change and send nothing. |
193
+ | `--silent` | Print errors only. |
194
+ | `-h`, `--help` | Show the help. |
195
+ | `-v`, `--version` | Print the version. |
196
+
197
+ | Environment variable | Meaning |
198
+ | --- | --- |
199
+ | `STARKO_API_KEY` | The secret key, when `--api-key` is not given. |
200
+ | `STARKO_HOST` | The host, when `--host` is not given. |
201
+ | `STARKO_RELEASE` | The release, when `--release` is not given. |
202
+
203
+ Exit status: `0` success; `1` the command failed (no bundle with a source
204
+ map found, a bundle skipped, a map unreadable, no key for `upload`, an
205
+ upload that failed or timed out); `2` a usage error (also `starko` with no
206
+ command).
207
+
208
+ The CLI deletes nothing unless you pass `--delete-after-upload`. If you
209
+ deploy `<dir>` and do not want maps served, pass it.
210
+
211
+ ## CI: GitHub Actions
212
+
213
+ ```yaml
214
+ name: build
215
+ on:
216
+ push:
217
+ branches: [main]
218
+
219
+ jobs:
220
+ build:
221
+ runs-on: ubuntu-latest
222
+ steps:
223
+ - uses: actions/checkout@v4
224
+ - uses: actions/setup-node@v4
225
+ with:
226
+ node-version: 22
227
+ - run: npm ci
228
+ - run: npm run build
229
+ env:
230
+ STARKO_API_KEY: ${{ secrets.STARKO_API_KEY }}
231
+ ```
232
+
233
+ With a build plugin or `withStarko`, the key in the build step's environment
234
+ is all you need. With the CLI, add the two steps after the build:
235
+
236
+ ```yaml
237
+ - run: npx --package @starko-one/sdk starko sourcemaps inject dist
238
+ - run: npx --package @starko-one/sdk starko sourcemaps upload dist --delete-after-upload
239
+ env:
240
+ STARKO_API_KEY: ${{ secrets.STARKO_API_KEY }}
241
+ ```
242
+
243
+ On GitHub Actions the release defaults to `GITHUB_SHA`.
244
+
245
+ ## One tool per build
246
+
247
+ Use either a plugin (or `withStarko`) or the CLI on a given build, not both.
248
+ The debug id comes from the bundle's bytes at the moment a tool first sees
249
+ them: a plugin sees the chunk inside the bundler, the CLI the file on disk
250
+ after every later step. Run on the same output one after the other, the
251
+ second finds the id already there and keeps it. But if they run on two
252
+ different builds of the same code, or a step between them changes the file
253
+ (a separate minifier, a post-processor), the file you deploy and the map you
254
+ upload can carry different ids, and frames stay unresolved.
255
+
256
+ Any step that changes a bundle after injection (minifying, rewriting asset
257
+ URLs) must run **before** `inject`, or the map no longer matches the file.
258
+
259
+ ## Next to Sentry's plugin
260
+
261
+ A bundle that already has Sentry's debug id keeps it: Starko registers the
262
+ same id and uploads the map under it, and the SDK also reads the ids Sentry's
263
+ snippet registers. Run Starko's step **after** Sentry's: list Starko's
264
+ plugin after Sentry's (the Vite plugin runs last on its own), or run
265
+ `starko sourcemaps inject` after Sentry's inject. That order is the one
266
+ covered by tests.
267
+
268
+ ## Options
269
+
270
+ `starkoVitePlugin`, `starkoRollupPlugin`, `new StarkoWebpackPlugin` and
271
+ `withStarko` take the same options; defaults and the full list are in
272
+ [configuration.md](./configuration.md#build-plugins-and-withstarko).
273
+
274
+ ```ts
275
+ import { defineConfig } from "vite";
276
+ import { starkoVitePlugin } from "@starko-one/sdk/vite";
277
+
278
+ export default defineConfig({
279
+ plugins: [
280
+ starkoVitePlugin({
281
+ release: "shop@4.12.0",
282
+ include: ["assets/**"],
283
+ exclude: ["**/legacy/**"],
284
+ failOnError: true,
285
+ uploadTimeoutMs: 120_000,
286
+ }),
287
+ ],
288
+ });
289
+ ```
290
+
291
+ By default a failed upload only warns and the build succeeds;
292
+ `failOnError: true` fails it instead.
293
+
294
+ ## Limits
295
+
296
+ - A map larger than 64 MiB (uncompressed) is refused. The tools do not send
297
+ it and report it as a failed upload.
298
+ - **Write-once per bundle.** The first map completed for a debug id is the
299
+ one used. Uploading a different map for the same id is refused (409). To
300
+ replace a map, delete it in Starko first. (A changed bundle gets a new id,
301
+ so this only happens when the same bytes were built with a different map.)
302
+ - The whole upload has a deadline: 3 minutes by default (`uploadTimeoutMs`,
303
+ `--timeout`). When it passes the upload stops with a warning saying how
304
+ far it got, and the build goes on. See [Large builds](#large-builds).
305
+ - Starko resolves the frames of at most 8 different bundles per event;
306
+ frames from further bundles stay minified.
307
+
308
+ ## Large builds
309
+
310
+ A Next.js app with a few hundred routes easily has 5,000 source maps
311
+ (browser and server chunks together), many of them several MB. What to
312
+ expect:
313
+
314
+ **The upload.** Every map is read and hashed, then the tools ask Starko
315
+ which ones it does not have yet. A map the server already has costs
316
+ nothing more. A missing one is gzipped and sent:
317
+
318
+ - With the **bulk upload** (the default when the server offers it), the
319
+ tools reserve the missing maps with Starko (200 per request), and each
320
+ map goes from the build machine straight to Starko's storage through a
321
+ signed URL that is valid for 10 minutes and only for that map; Starko
322
+ then verifies it (200 per request, two requests at a time: Starko
323
+ verifies a workspace's maps 6 at a time whatever the number of requests,
324
+ so more would not finish sooner). 16 maps are sent to storage at the
325
+ same time (`uploadConcurrency`, `--concurrency`). A map is gzipped once,
326
+ and those bytes are what is declared and sent. A map Starko refuses
327
+ after verifying it (`failed`) is reported and not sent again in that
328
+ build: the same bytes would fail again, and a failed map counts against
329
+ the key's daily budget.
330
+ - With **v1**, every map goes through the Starko host: an upload request
331
+ per 3 MiB part, then a `complete` request, on which the server stores
332
+ and verifies it. 8 maps are sent at the same time by default (at most 16).
333
+
334
+ The steps overlap: the first maps are on their way while later ones are
335
+ still being read and checked. At most 256 MiB of map content is held in
336
+ memory at once (a larger map is sent alone).
337
+
338
+ **The first upload; later builds.** Measured with a local server that
339
+ plays Starko (`scripts/bench/upload-bench.mjs`) on a generated build of
340
+ 5,226 maps (1.8 GB, about 790 MB gzipped):
341
+
342
+ | | First upload | A later build, every map already on the server |
343
+ | --- | --- | --- |
344
+ | v1 (0.1.0-beta.1 before the bulk upload), production-like answers: 1 s per `check`, 6 s per upload, 4 s per `complete` | 136 maps in the 3-minute deadline (the whole build would take well over an hour) | 6 s |
345
+ | Bulk upload: 1 s per check, 1.5 s per start, finish 0.5 s plus 0.4 s per map verified, 6 of the workspace's maps verified at a time (the server's share, across all finishes), each upload to storage 0.8 s plus 5 MB/s | all 5,226 in 6.0 min (2,382 within the 3-minute default) | 5.4 s (three runs) |
346
+
347
+ These are a model, not the real service. In this model the first upload
348
+ is bound by verification: 5,226 maps at 0.4 s each, 6 at a time, is about
349
+ 5.8 minutes whatever the build machine does. How long a real first upload
350
+ takes depends on how fast Starko reads a map back from storage and
351
+ verifies it (and on how many of its server instances answer one build's
352
+ finishes: the share of 6 is per instance) and on how fast the build
353
+ machine reaches the storage host. When the deadline passes, the build log
354
+ says how far it got:
355
+
356
+ ```
357
+ [starko] source map upload: the upload did not finish within 3 min: 2,382 of 5,226 source map(s) uploaded, 0 already on the server, 0 failed, 2,844 not sent (16 of them were being sent and were stopped). The next build continues from there: a map the server has completed is never sent again. …
358
+ ```
359
+
360
+ Nothing is lost: every map that was completed stays on the server, and
361
+ the next build sends only what is still missing. A debug id comes from
362
+ the bundle's content, so a chunk that did not change keeps its id and is
363
+ never sent again; after the first upload, a build sends only the chunks
364
+ that changed.
365
+
366
+ During a long upload a progress line is printed every 30 seconds:
367
+
368
+ ```
369
+ [starko] source map upload: 5,226 of 5,226 checked, 1,578 uploaded, 0 already on the server, 0 failed (2 min so far)
370
+ ```
371
+
372
+ **What to set.** For a first upload that does not fit, either let it
373
+ catch up over a few builds, or give one build more time:
374
+
375
+ ```ts
376
+ import { withStarko } from "@starko-one/sdk/next/config";
377
+
378
+ export default withStarko({ reactStrictMode: true }, { uploadTimeoutMs: 30 * 60_000 });
379
+ ```
380
+
381
+ Mind your host's build time limit when you raise `uploadTimeoutMs`. Once
382
+ the maps are on the server, the default is enough again. With v1, also
383
+ raise `uploadConcurrency` (up to 16). Maps are checked and sent in the
384
+ order they are found, and `withStarko` lists the browser's
385
+ (`.next/static`, minified and unreadable without a map) before the
386
+ server's.
387
+
388
+ ### Which protocol
389
+
390
+ `uploadProtocol` (CLI: `--protocol`):
391
+
392
+ | Value | What happens |
393
+ | --- | --- |
394
+ | `"auto"` (default) | The first request asks the server for the bulk upload. A server that does not have it (it answers 404 or 405) gets v1 for the whole upload. Decided once per upload; the first log line says which: `source map upload: using the bulk upload: …` or `source map upload: using the v1 upload through <host>: …`. If uploads to the storage host then fail three times in a row (each after its own retries), every map not uploaded yet goes through the Starko host (v1) instead, the ones already reserved for storage included, with one warning naming the storage host. |
395
+ | `"bulk"` | The bulk upload only. A server without it, or a storage host that cannot be reached, stops the upload with an error. |
396
+ | `"v1"` | v1 only. The storage host is never contacted. |
397
+
398
+ After a fallback every map that storage does not hold goes through v1,
399
+ including the few that were already reserved for an upload to storage
400
+ (until a first upload to storage succeeds, maps are reserved 4 at a time):
401
+ the server lets v1 take a reservation over at once when storage holds no
402
+ object for it, and keeps the reservation's object key until its URL is
403
+ over, so an upload that still lands there is never lost or counted twice.
404
+ A map whose upload to storage did land is finished through the bulk
405
+ upload as usual. In the rare case that an upload the tools gave up on
406
+ landed after all, v1 is refused for that map for up to about 20 minutes
407
+ (`409`, the message says when); a later build sends it.
408
+
409
+ ### Proxies and firewalls
410
+
411
+ With the bulk upload the build machine must reach **two hosts**: the
412
+ Starko host (`host`, `STARKO_HOST`) and the storage host the server names
413
+ in its signed URLs (the warning above prints it; only the host, the signed
414
+ URL is never printed). An allow-list that lets only the Starko host
415
+ through makes every upload to storage fail; allow the storage host, or set
416
+ `uploadProtocol: "v1"`.
417
+
418
+ The build tools send with Node's global `fetch`, to the Starko host and to
419
+ storage alike, so a proxy applies to both or to neither. Node's `fetch`
420
+ uses `HTTPS_PROXY` / `HTTP_PROXY` and `NO_PROXY` only when Node runs with
421
+ `NODE_USE_ENV_PROXY=1` (checked on Node 24), or when the build installs a
422
+ global dispatcher with a proxy (undici's `setGlobalDispatcher`). Keep the
423
+ storage host out of `NO_PROXY` when it is only reachable through the
424
+ proxy.
425
+
426
+ **The server's limits.** The tools stay within them and say so when they
427
+ meet one:
428
+
429
+ - Requests per API key: Starko allows 2,000 a minute (all routes
430
+ together; uploads to storage are not counted). The tools send at most
431
+ 1,900 a minute. A `429` answer pauses every request for as long as its
432
+ `Retry-After` says, with one warning.
433
+ - Bytes per API key: 8 GiB of gzipped maps a UTC day, counting maps that
434
+ failed verification. When it is spent, Starko answers `429` with a
435
+ `Retry-After` of hours. The upload stops at once with the server's
436
+ message instead of waiting; the next day's build continues.
437
+ - Time per request: each Starko route has a longest run on the server
438
+ (30 s for the checks and `bulk/start`, 60 s for v1's upload and
439
+ complete, 120 s for `bulk/finish`, which verifies maps). The tools wait
440
+ that long plus 15 s for an answer before they count a request as lost,
441
+ so a slow answer is never taken for an unreachable host. A `503` with
442
+ `Retry-After` (Starko busy reserving or verifying) is retried after that
443
+ time.
444
+ - File names: the path shown in Starko is at most 512 characters; a longer
445
+ one keeps its end after a `…`.
446
+ - Storage per workspace: when it is full, Starko answers `over_allowance`
447
+ (bulk) or `413` (v1) and the upload stops (every other map would be
448
+ refused the same way); with the bulk upload the maps already reserved
449
+ are still finished. Delete maps you no longer need in Starko.
450
+ - Uploads switched off: when Starko's storage was found serving a map
451
+ without a signature, the server answers `423` to every upload until an
452
+ operator fixes it. The upload stops without retrying, and the build goes
453
+ on.
454
+
455
+ ## Troubleshooting unresolved frames
456
+
457
+ 1. **Does the deployed file have an id?** Open the bundle your site serves:
458
+ its last lines should include `//# debugId=<uuid>`. If not, it was not
459
+ injected: no key at build time (look for the "no API key" warning), the
460
+ plugin did not run (dev or watch mode, `enabled: false`), or the file was
461
+ copied before injection.
462
+ 2. **Does the page know it?** In the browser console,
463
+ `globalThis._starkoDebugIds` should list your bundles (with Turbopack or
464
+ Rolldown ids, `globalThis._debugIds`). The SDK sends each frame's id as
465
+ `chunk_id`.
466
+ 3. **Was the map uploaded?** The build log prints
467
+ `source maps: N uploaded, M already on the server, K failed`. A `409`
468
+ means Starko already has a different map for that id (see Limits).
469
+ 4. **Was the file changed after injection?** See
470
+ [One tool per build](#one-tool-per-build).
471
+ 5. **Inline or `eval` source maps** are never uploaded.
472
+ 6. **Server frames:** server code that is not bundled needs no map; Node
473
+ frames point at your files and the SDK adds source lines. Bundled server
474
+ code needs its maps uploaded like browser code.
475
+ 7. **One function name is still minified.** A function's original name is
476
+ read at the place it was called from, which is the next frame down. The
477
+ outermost frame that resolves (called from code without a map, such as
478
+ a framework or the browser) therefore keeps its minified function name;
479
+ its file and line are resolved.
480
+ 8. **Next.js with `experimental.sri`:** client chunks that had no debug id
481
+ of their own are left uninjected (a build warning says so). On Next 16,
482
+ Turbopack's native debug ids avoid this; see [Next.js](#nextjs).