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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +124 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-B5IHeINe.d.ts +558 -0
  6. package/dist/api-DR4HazCu.d.cts +558 -0
  7. package/dist/browser/index.cjs +168 -0
  8. package/dist/browser/index.d.cts +131 -0
  9. package/dist/browser/index.d.ts +131 -0
  10. package/dist/browser/index.js +7 -0
  11. package/dist/build/rollup.cjs +22 -0
  12. package/dist/build/rollup.d.cts +34 -0
  13. package/dist/build/rollup.d.ts +34 -0
  14. package/dist/build/rollup.js +3 -0
  15. package/dist/build/vite.cjs +51 -0
  16. package/dist/build/vite.d.cts +23 -0
  17. package/dist/build/vite.d.ts +23 -0
  18. package/dist/build/vite.js +46 -0
  19. package/dist/build/webpack.cjs +18 -0
  20. package/dist/build/webpack.d.cts +39 -0
  21. package/dist/build/webpack.d.ts +39 -0
  22. package/dist/build/webpack.js +3 -0
  23. package/dist/chunk-7HYGODU6.cjs +583 -0
  24. package/dist/chunk-A5M4NOVT.js +413 -0
  25. package/dist/chunk-A7MYYWMP.cjs +15 -0
  26. package/dist/chunk-BAQA47FM.js +1113 -0
  27. package/dist/chunk-CM7HM6CC.js +563 -0
  28. package/dist/chunk-DFYNIWUN.js +608 -0
  29. package/dist/chunk-DMVVCGKO.cjs +96 -0
  30. package/dist/chunk-FARGXYJ4.cjs +56 -0
  31. package/dist/chunk-G3MYIAX2.js +1226 -0
  32. package/dist/chunk-G4NAVZQ4.js +249 -0
  33. package/dist/chunk-GH7RYPKS.js +96 -0
  34. package/dist/chunk-HADYYQNL.cjs +134 -0
  35. package/dist/chunk-HOQPAB4X.js +178 -0
  36. package/dist/chunk-J5RU73SW.js +214 -0
  37. package/dist/chunk-JNAJ3YZB.cjs +223 -0
  38. package/dist/chunk-KN7H22EQ.cjs +659 -0
  39. package/dist/chunk-LDQ4I7FZ.cjs +1151 -0
  40. package/dist/chunk-NPGESRVQ.js +1212 -0
  41. package/dist/chunk-OPWM5V7A.cjs +258 -0
  42. package/dist/chunk-PYYWPIFL.cjs +1230 -0
  43. package/dist/chunk-R7JLZ4WO.cjs +115 -0
  44. package/dist/chunk-SC6VQSES.js +213 -0
  45. package/dist/chunk-TPSJGLR3.cjs +220 -0
  46. package/dist/chunk-UKBY6HPC.js +131 -0
  47. package/dist/chunk-VRSEHRBX.cjs +185 -0
  48. package/dist/chunk-X74AONZA.js +90 -0
  49. package/dist/chunk-XW3I5CJN.js +12 -0
  50. package/dist/chunk-XW56FKKJ.js +53 -0
  51. package/dist/chunk-Z3G5SW7R.cjs +1251 -0
  52. package/dist/chunk-ZVMAN7OO.cjs +431 -0
  53. package/dist/cli/index.cjs +1487 -0
  54. package/dist/common-ARWXbeS3.d.ts +36 -0
  55. package/dist/common-CwIFh2hK.d.cts +36 -0
  56. package/dist/dedupe-eHBIfUUD.d.cts +13 -0
  57. package/dist/dedupe-fw8aNtt4.d.ts +13 -0
  58. package/dist/handler-DTZ4Rzcf.d.ts +82 -0
  59. package/dist/handler-_00lctTI.d.cts +82 -0
  60. package/dist/index.cjs +277 -0
  61. package/dist/index.d.cts +187 -0
  62. package/dist/index.d.ts +187 -0
  63. package/dist/index.js +4 -0
  64. package/dist/next/client.cjs +113 -0
  65. package/dist/next/client.d.cts +26 -0
  66. package/dist/next/client.d.ts +26 -0
  67. package/dist/next/client.js +41 -0
  68. package/dist/next/config.cjs +275 -0
  69. package/dist/next/config.d.cts +193 -0
  70. package/dist/next/config.d.ts +193 -0
  71. package/dist/next/config.js +261 -0
  72. package/dist/next/index.cjs +148 -0
  73. package/dist/next/index.d.cts +32 -0
  74. package/dist/next/index.d.ts +32 -0
  75. package/dist/next/index.js +59 -0
  76. package/dist/node/index.cjs +257 -0
  77. package/dist/node/index.d.cts +145 -0
  78. package/dist/node/index.d.ts +145 -0
  79. package/dist/node/index.js +83 -0
  80. package/dist/options-0BhybO54.d.cts +47 -0
  81. package/dist/options-0BhybO54.d.ts +47 -0
  82. package/dist/react/index.cjs +107 -0
  83. package/dist/react/index.d.cts +84 -0
  84. package/dist/react/index.d.ts +84 -0
  85. package/dist/react/index.js +103 -0
  86. package/dist/scope-Bvh45bOf.d.cts +404 -0
  87. package/dist/scope-Bvh45bOf.d.ts +404 -0
  88. package/dist/server-edge-BPOGA3GH.cjs +51 -0
  89. package/dist/server-edge-GYKAJREU.js +48 -0
  90. package/dist/server-node-HYK2OB2J.js +24 -0
  91. package/dist/server-node-J2DBAHDV.cjs +27 -0
  92. package/dist/session-C_WzbEN2.d.cts +4 -0
  93. package/dist/session-C_WzbEN2.d.ts +4 -0
  94. package/dist/session-propagation-B7REA7uy.d.cts +30 -0
  95. package/dist/session-propagation-BnJjKJbR.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +381 -0
  98. package/docs/configuration.md +269 -0
  99. package/docs/nextjs.md +312 -0
  100. package/docs/node.md +376 -0
  101. package/docs/other-backends.md +232 -0
  102. package/docs/privacy.md +112 -0
  103. package/docs/react.md +187 -0
  104. package/docs/source-maps.md +332 -0
  105. package/docs/troubleshooting.md +171 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +367 -0
  108. package/package.json +98 -4
@@ -0,0 +1,112 @@
1
+ # Privacy
2
+
3
+ What the SDK collects by default, what it never collects, and how to collect
4
+ less. This page describes the software; it is not legal advice.
5
+
6
+ ## Browser (`/browser`, `/next/client`, script tag)
7
+
8
+ Collected by default with every error:
9
+
10
+ | What | Details |
11
+ | --- | --- |
12
+ | The error | Type, message, stack frames (script URL, function, line, column), the chain of `cause`s. |
13
+ | Page | The page URL (`location.href`) and the referrer, with the URL rules below. |
14
+ | Breadcrumbs | Up to 50: clicks (a short CSS-like selector of the element, never its text or an input's value), navigation (from and to; path only when same-origin), `fetch`/XHR (method, URL, status code), and `console.warn` / `console.error` text cut to 200 characters. |
15
+ | Session | A random session id kept in `sessionStorage` (`starko:errors:session`), or the Starko widget's recorder session id when the widget is on the page. |
16
+ | Widget token | When the Starko widget is on the page: its client token, which links the error to the widget's customer. Verified by Starko and then discarded, not stored. |
17
+ | What you set | The user (`setUser`, `identify`), tags, extra data and contexts. Nothing about the user unless you set it. |
18
+
19
+ The SDK itself adds no user agent and no IP address to the event; Starko
20
+ receives the request like any other HTTP request.
21
+
22
+ Never collected: request or response bodies, cookies, request headers, the
23
+ text of the page, input values, `localStorage`.
24
+
25
+ Clicks inside an element with the `starko-mask` or `starko-no-capture`
26
+ class, or the `data-starko-mask` or `data-starko-no-capture` attribute (the
27
+ same markers the Starko session recorder honours), are not recorded at all.
28
+
29
+ ## Servers (`/node`, `/next`)
30
+
31
+ | What | Details |
32
+ | --- | --- |
33
+ | The error | Type, message, stack frames (file path, function, line, column), the chain of `cause`s. |
34
+ | Request | Method, URL (with the URL rules below) and route pattern of the request the error happened in, and the browser's session id from the `x-starko-session-id` header. |
35
+ | Breadcrumbs | `console.warn` / `console.error` text cut to 200 characters, per request. No HTTP client breadcrumbs. |
36
+ | Host | `server_name` (the host name, or `serverName`), the Node version, OS name, version and architecture. |
37
+ | Source lines | Up to 7 lines before and after each in-app frame, from your own source files only. See [node.md](./node.md#source-lines) for exactly which files may be read; `.env` files and other dotfiles never are. |
38
+ | Next.js | Route path, router kind, route type, render source and the error's `digest`. |
39
+ | What you set | The user, tags, extra data and contexts. |
40
+
41
+ Never collected: request or response bodies, cookies, request headers other
42
+ than `x-starko-session-id`, environment variables, the process's arguments.
43
+
44
+ ## URL rules (every platform)
45
+
46
+ Applied to every URL the SDK sends: page URL, referrer, request URL,
47
+ breadcrumb URLs, stack-frame file names that are URLs, and `http(s)://` URLs
48
+ inside error messages and breadcrumb messages.
49
+
50
+ - The `#fragment` is removed.
51
+ - The `user:password@` part is removed.
52
+ - The **values** of sensitive query parameters become `[redacted]`. A
53
+ parameter is sensitive when its name, or any part of it (split on `_`, `-`
54
+ and camelCase), is one of: `token`, `access_token`, `id_token`,
55
+ `refresh_token`, `code`, `key`, `api_key`, `apikey`, `secret`, `password`,
56
+ `passwd`, `pwd`, `auth`, `authorization`, `session`, `sessionid`, `sid`,
57
+ `sig`, `signature`, `jwt`, `otp`, `pin`, `email`, `phone`, `ssn`,
58
+ `x-amz-signature`, `x-amz-credential`, `x-amz-security-token`. So
59
+ `accessToken`, `clientSecret`, `apiKey`, `sessionId` and `X-Amz-Signature`
60
+ all match.
61
+
62
+ Every other query parameter **is** sent. If your URLs carry personal data
63
+ under other names (`?customer=…`), remove it in `beforeSend`. The rules run
64
+ after `beforeSend`, on whatever it returns.
65
+
66
+ ## Collect less
67
+
68
+ | To stop collecting | Do this |
69
+ | --- | --- |
70
+ | Everything, for some users or pages | `enabled: false`, or `beforeSend` returning `null`. |
71
+ | Any field of an event | Change or delete it in `beforeSend`. |
72
+ | Breadcrumbs of one kind | `breadcrumbsIntegration({ console: false })` (also `dom`, `fetch`, `xhr`, `history`); see [browser.md](./browser.md#breadcrumbs). |
73
+ | One breadcrumb | `beforeBreadcrumb` returning `null`. |
74
+ | All breadcrumbs | `maxBreadcrumbs: 0`. |
75
+ | Clicks in part of the page | Mark it with `starko-mask` / `starko-no-capture`. |
76
+ | The page URL and referrer | Remove the `HttpContext` integration, or edit `event.request` in `beforeSend`. |
77
+ | The session header on your API requests | Remove the `SessionPropagation` integration. Server errors then no longer link to the browser session. |
78
+ | Console errors captured while the widget is on the page | Remove the `ConsoleErrorCapture` integration. |
79
+ | Server console breadcrumbs | Remove the `ConsoleBreadcrumbs` integration. |
80
+ | Source lines | Remove the `ContextLines` integration. |
81
+ | Host name | Set `serverName` to a neutral value, or remove the `NodeContext` integration. |
82
+ | A share of events | `sampleRate`. |
83
+
84
+ How to remove an integration: [configuration.md](./configuration.md#adding-and-removing-integrations).
85
+
86
+ ## What Starko does on its side
87
+
88
+ - It applies the same URL rules again when an event arrives.
89
+ - It removes well-known secret formats (card numbers, bearer tokens, cloud
90
+ and API keys, JWTs) from messages, source lines, extra data, tags and
91
+ breadcrumbs before storing them.
92
+ - It never fetches your scripts or source maps from the internet; it uses
93
+ only the maps you upload.
94
+ - The user hash and the widget's client token are checked when the request
95
+ arrives and are not stored.
96
+ - How long errors are kept is a setting of your Starko workspace, not of
97
+ this SDK.
98
+
99
+ ## What to tell your users
100
+
101
+ In plain terms, a statement along these lines is accurate for the defaults:
102
+
103
+ > When something goes wrong in our app, we send a technical error report to
104
+ > Starko, our customer-support provider. It contains the error, the page or
105
+ > request where it happened, a short record of the clicks, page changes,
106
+ > network requests and console warnings just before it, and, when you are
107
+ > signed in, your account id and email address. It does not contain what you
108
+ > type into forms, passwords, or the content of our network requests.
109
+
110
+ Adjust it to what you actually send: drop the account part if you never set
111
+ a user, and add anything you put in tags, extra data or contexts. If you
112
+ use the Starko widget's session recording, describe that too.
package/docs/react.md ADDED
@@ -0,0 +1,187 @@
1
+ # React
2
+
3
+ `@starko-one/sdk/react` adds an error boundary and handlers for React 19's
4
+ root error options. It needs React 18 or later (the root handlers need 19).
5
+ It does not start the SDK: start it first with `@starko-one/sdk/browser` (or
6
+ `@starko-one/sdk/next/client` in Next.js). Before the SDK is started, these
7
+ components capture nothing.
8
+
9
+ ## Shortest setup
10
+
11
+ ```tsx
12
+ import { createRoot } from "react-dom/client";
13
+ import * as Starko from "@starko-one/sdk/browser";
14
+ import { StarkoErrorBoundary, reactErrorHandler } from "@starko-one/sdk/react";
15
+
16
+ Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>" });
17
+
18
+ function App() {
19
+ return <h1>Shop</h1>;
20
+ }
21
+
22
+ createRoot(document.getElementById("root")!, reactErrorHandler()).render(
23
+ <StarkoErrorBoundary fallback={<p>Something went wrong.</p>}>
24
+ <App />
25
+ </StarkoErrorBoundary>,
26
+ );
27
+ ```
28
+
29
+ On React 18, leave out `reactErrorHandler()`: uncaught render errors still
30
+ reach the page's global error handler, which the browser SDK listens to.
31
+
32
+ ## `StarkoErrorBoundary`
33
+
34
+ ```tsx
35
+ import type { ReactNode } from "react";
36
+ import * as Starko from "@starko-one/sdk/browser";
37
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
38
+
39
+ export function CheckoutSection({ children }: { children: ReactNode }) {
40
+ return (
41
+ <StarkoErrorBoundary
42
+ fallback={({ error, eventId, resetError }) => (
43
+ <div role="alert">
44
+ <p>Checkout failed to load ({error instanceof Error ? error.message : "unknown error"}).</p>
45
+ <p>Reference: {eventId}</p>
46
+ <button onClick={resetError}>Try again</button>
47
+ </div>
48
+ )}
49
+ beforeCapture={(scope) => {
50
+ scope.setTag("section", "checkout");
51
+ }}
52
+ onError={(error, componentStack, eventId) => {
53
+ console.info("checkout error reported", eventId);
54
+ }}
55
+ onReset={() => {
56
+ Starko.addBreadcrumb({ category: "ui", message: "checkout boundary reset" });
57
+ }}
58
+ >
59
+ {children}
60
+ </StarkoErrorBoundary>
61
+ );
62
+ }
63
+ ```
64
+
65
+ <!-- options: StarkoErrorBoundaryProps -->
66
+ | Prop | Meaning |
67
+ | --- | --- |
68
+ | `children` | What the boundary renders until an error. |
69
+ | `fallback` | Rendered instead of the children after an error: a React node, or a function receiving `{ error, componentStack, eventId, resetError }`. Without a fallback the boundary renders nothing after an error. |
70
+ | `onError(error, componentStack, eventId)` | Called after the error is captured. |
71
+ | `beforeCapture(scope, error, componentStack)` | Called before capturing, with a scope that applies to this error only: set tags, extra, context or the user on it. If it throws, the error is still captured. |
72
+ | `onReset(error, componentStack, eventId)` | Called when `resetError` clears the error and the children render again. |
73
+
74
+ What is sent: the error with the component stack in `contexts.react`, and
75
+ `mechanism.type: "react.error-boundary"`. `eventId` is `""` when the SDK is
76
+ not started.
77
+
78
+ During server rendering React does not call error boundaries: the boundary
79
+ renders its children and captures nothing.
80
+
81
+ ### In the Next.js App Router
82
+
83
+ `@starko-one/sdk/react` is a client module (its entry starts with
84
+ `"use client"`), so a Server Component (a layout or a page) can import it
85
+ and render `StarkoErrorBoundary` directly, as long as every prop it passes
86
+ can cross from the server to the client: `children` and a `fallback` that
87
+ is a React node.
88
+
89
+ ```tsx
90
+ import type { ReactNode } from "react";
91
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
92
+
93
+ export default function DashboardLayout({ children }: { children: ReactNode }) {
94
+ return <StarkoErrorBoundary fallback={<p>This section failed to load.</p>}>{children}</StarkoErrorBoundary>;
95
+ }
96
+ ```
97
+
98
+ Functions cannot be passed from a Server Component to a client one, so a
99
+ `fallback` function, `onError`, `beforeCapture` and `onReset` (and
100
+ `withErrorBoundary` and `reactErrorHandler`, which are called rather than
101
+ rendered) only work in a file of your own that starts with `"use client"`:
102
+
103
+ ```tsx
104
+ "use client";
105
+ import type { ReactNode } from "react";
106
+ import { StarkoErrorBoundary } from "@starko-one/sdk/react";
107
+
108
+ export function ClientBoundary({ children }: { children: ReactNode }) {
109
+ return (
110
+ <StarkoErrorBoundary
111
+ fallback={({ resetError }) => <button onClick={resetError}>Something went wrong. Try again</button>}
112
+ beforeCapture={(scope) => scope.setTag("section", "dashboard")}
113
+ >
114
+ {children}
115
+ </StarkoErrorBoundary>
116
+ );
117
+ }
118
+ ```
119
+
120
+ Render `ClientBoundary` from the Server Component instead.
121
+
122
+ For route segments, Next's own `error.tsx` and `global-error.tsx` are the
123
+ usual boundaries; see [nextjs.md](./nextjs.md#errors-shown-by-global-errortsx-and-errortsx).
124
+
125
+ ## `withErrorBoundary`
126
+
127
+ Wraps a component in a `StarkoErrorBoundary`; the second argument takes the
128
+ same props as the boundary (without `children`).
129
+
130
+ ```tsx
131
+ import { withErrorBoundary } from "@starko-one/sdk/react";
132
+
133
+ function OrderHistory({ customerId }: { customerId: string }) {
134
+ return <section>Orders of {customerId}</section>;
135
+ }
136
+
137
+ export const SafeOrderHistory = withErrorBoundary(OrderHistory, {
138
+ fallback: <p>Order history is unavailable.</p>,
139
+ });
140
+ ```
141
+
142
+ ## React 19 root handlers: `reactErrorHandler`
143
+
144
+ React 19's `createRoot` and `hydrateRoot` take `onUncaughtError`,
145
+ `onCaughtError` and `onRecoverableError`. `reactErrorHandler()` returns all
146
+ three:
147
+
148
+ ```tsx
149
+ import { hydrateRoot } from "react-dom/client";
150
+ import { reactErrorHandler } from "@starko-one/sdk/react";
151
+
152
+ function App() {
153
+ return <h1>Shop</h1>;
154
+ }
155
+
156
+ hydrateRoot(document.getElementById("root")!, <App />, {
157
+ ...reactErrorHandler({
158
+ onCaughtError(error, errorInfo) {
159
+ console.warn("caught by a boundary", error, errorInfo.componentStack);
160
+ },
161
+ }),
162
+ identifierPrefix: "shop",
163
+ });
164
+ ```
165
+
166
+ | Hook | Captured as | Then, without your callback |
167
+ | --- | --- | --- |
168
+ | `onUncaughtError` | `react.onUncaughtError`, unhandled | What React does by default: the error is reported to the page (`reportError`). |
169
+ | `onCaughtError` | `react.onCaughtError`, handled | `console.error(error)`, as React does. |
170
+ | `onRecoverableError` | `react.onRecoverableError`, handled | Reported to the page, as React does. |
171
+
172
+ Each event carries the component stack in `contexts.react`. A callback you
173
+ pass for a hook runs instead of React's default for that hook, as when you
174
+ pass it to React directly. An error caught by a `StarkoErrorBoundary` is
175
+ left to the boundary, so it is one event, not two. An error reported once is
176
+ not reported again when it reaches the page's global error handler.
177
+
178
+ ## What `handled` means
179
+
180
+ Every event records `mechanism.handled`:
181
+
182
+ - `false`: the error reached the user without your code dealing with it. Uncaught
183
+ errors, `onUncaughtError`, and a `StarkoErrorBoundary` **without** a
184
+ `fallback` (the subtree simply disappears).
185
+ - `true`: your code caught it. `captureException`, `onCaughtError`,
186
+ `onRecoverableError`, and a `StarkoErrorBoundary` **with** a `fallback`
187
+ (the user saw your fallback).
@@ -0,0 +1,332 @@
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 stops the upload with an
177
+ error naming its `Location` (the maps are your source code). Set
178
+ `--host` to the final address. The same applies to the build plugins
179
+ 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. |
190
+ | `--dry-run` | Show what would be done; change and send nothing. |
191
+ | `--silent` | Print errors only. |
192
+ | `-h`, `--help` | Show the help. |
193
+ | `-v`, `--version` | Print the version. |
194
+
195
+ | Environment variable | Meaning |
196
+ | --- | --- |
197
+ | `STARKO_API_KEY` | The secret key, when `--api-key` is not given. |
198
+ | `STARKO_HOST` | The host, when `--host` is not given. |
199
+ | `STARKO_RELEASE` | The release, when `--release` is not given. |
200
+
201
+ Exit status: `0` success; `1` the command failed (no bundle with a source
202
+ map found, a bundle skipped, a map unreadable, no key for `upload`, an
203
+ upload that failed or timed out); `2` a usage error (also `starko` with no
204
+ command).
205
+
206
+ The CLI deletes nothing unless you pass `--delete-after-upload`. If you
207
+ deploy `<dir>` and do not want maps served, pass it.
208
+
209
+ ## CI: GitHub Actions
210
+
211
+ ```yaml
212
+ name: build
213
+ on:
214
+ push:
215
+ branches: [main]
216
+
217
+ jobs:
218
+ build:
219
+ runs-on: ubuntu-latest
220
+ steps:
221
+ - uses: actions/checkout@v4
222
+ - uses: actions/setup-node@v4
223
+ with:
224
+ node-version: 22
225
+ - run: npm ci
226
+ - run: npm run build
227
+ env:
228
+ STARKO_API_KEY: ${{ secrets.STARKO_API_KEY }}
229
+ ```
230
+
231
+ With a build plugin or `withStarko`, the key in the build step's environment
232
+ is all you need. With the CLI, add the two steps after the build:
233
+
234
+ ```yaml
235
+ - run: npx --package @starko-one/sdk starko sourcemaps inject dist
236
+ - run: npx --package @starko-one/sdk starko sourcemaps upload dist --delete-after-upload
237
+ env:
238
+ STARKO_API_KEY: ${{ secrets.STARKO_API_KEY }}
239
+ ```
240
+
241
+ On GitHub Actions the release defaults to `GITHUB_SHA`.
242
+
243
+ ## One tool per build
244
+
245
+ Use either a plugin (or `withStarko`) or the CLI on a given build, not both.
246
+ The debug id comes from the bundle's bytes at the moment a tool first sees
247
+ them: a plugin sees the chunk inside the bundler, the CLI the file on disk
248
+ after every later step. Run on the same output one after the other, the
249
+ second finds the id already there and keeps it. But if they run on two
250
+ different builds of the same code, or a step between them changes the file
251
+ (a separate minifier, a post-processor), the file you deploy and the map you
252
+ upload can carry different ids, and frames stay unresolved.
253
+
254
+ Any step that changes a bundle after injection (minifying, rewriting asset
255
+ URLs) must run **before** `inject`, or the map no longer matches the file.
256
+
257
+ ## Next to Sentry's plugin
258
+
259
+ A bundle that already has Sentry's debug id keeps it: Starko registers the
260
+ same id and uploads the map under it, and the SDK also reads the ids Sentry's
261
+ snippet registers. Run Starko's step **after** Sentry's: list Starko's
262
+ plugin after Sentry's (the Vite plugin runs last on its own), or run
263
+ `starko sourcemaps inject` after Sentry's inject. That order is the one
264
+ covered by tests.
265
+
266
+ ## Options
267
+
268
+ `starkoVitePlugin`, `starkoRollupPlugin`, `new StarkoWebpackPlugin` and
269
+ `withStarko` take the same options; defaults and the full list are in
270
+ [configuration.md](./configuration.md#build-plugins-and-withstarko).
271
+
272
+ ```ts
273
+ import { defineConfig } from "vite";
274
+ import { starkoVitePlugin } from "@starko-one/sdk/vite";
275
+
276
+ export default defineConfig({
277
+ plugins: [
278
+ starkoVitePlugin({
279
+ release: "shop@4.12.0",
280
+ include: ["assets/**"],
281
+ exclude: ["**/legacy/**"],
282
+ failOnError: true,
283
+ uploadTimeoutMs: 120_000,
284
+ }),
285
+ ],
286
+ });
287
+ ```
288
+
289
+ By default a failed upload only warns and the build succeeds;
290
+ `failOnError: true` fails it instead.
291
+
292
+ ## Limits
293
+
294
+ - A map larger than 64 MiB (uncompressed) is refused. The tools do not send
295
+ it and report it as a failed upload.
296
+ - **Write-once per bundle.** The first map completed for a debug id is the
297
+ one used. Uploading a different map for the same id is refused (409). To
298
+ replace a map, delete it in Starko first. (A changed bundle gets a new id,
299
+ so this only happens when the same bytes were built with a different map.)
300
+ - The whole upload has a deadline: 3 minutes by default (`uploadTimeoutMs`,
301
+ `--timeout`). When it passes the upload is abandoned with a warning.
302
+ - Starko resolves the frames of at most 8 different bundles per event;
303
+ frames from further bundles stay minified.
304
+
305
+ ## Troubleshooting unresolved frames
306
+
307
+ 1. **Does the deployed file have an id?** Open the bundle your site serves:
308
+ its last lines should include `//# debugId=<uuid>`. If not, it was not
309
+ injected: no key at build time (look for the "no API key" warning), the
310
+ plugin did not run (dev or watch mode, `enabled: false`), or the file was
311
+ copied before injection.
312
+ 2. **Does the page know it?** In the browser console,
313
+ `globalThis._starkoDebugIds` should list your bundles (with Turbopack or
314
+ Rolldown ids, `globalThis._debugIds`). The SDK sends each frame's id as
315
+ `chunk_id`.
316
+ 3. **Was the map uploaded?** The build log prints
317
+ `source maps: N uploaded, M already on the server, K failed`. A `409`
318
+ means Starko already has a different map for that id (see Limits).
319
+ 4. **Was the file changed after injection?** See
320
+ [One tool per build](#one-tool-per-build).
321
+ 5. **Inline or `eval` source maps** are never uploaded.
322
+ 6. **Server frames:** server code that is not bundled needs no map; Node
323
+ frames point at your files and the SDK adds source lines. Bundled server
324
+ code needs its maps uploaded like browser code.
325
+ 7. **One function name is still minified.** A function's original name is
326
+ read at the place it was called from, which is the next frame down. The
327
+ outermost frame that resolves (called from code without a map, such as
328
+ a framework or the browser) therefore keeps its minified function name;
329
+ its file and line are resolved.
330
+ 8. **Next.js with `experimental.sri`:** client chunks that had no debug id
331
+ of their own are left uninjected (a build warning says so). On Next 16,
332
+ Turbopack's native debug ids avoid this; see [Next.js](#nextjs).