@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.
- package/CHANGELOG.md +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- 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.
|