@koderlabs/tasks-sdk-nextjs 0.1.0 → 0.1.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/README.md +121 -5
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,9 +1,125 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @koderlabs/tasks-sdk-nextjs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Runtime: Next.js 13+ (App Router). Client hooks require browser DOM. Server helpers run on Node and Edge runtimes. Webpack-based production builds only (Turbopack plugin support deferred to v1.1).
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
Three things in one package:
|
|
6
|
+
|
|
7
|
+
1. **`next.config` plugin** — enables `productionBrowserSourceMaps` and uploads source maps to the InstantTasks API after a production client build.
|
|
8
|
+
2. **`/client` entry** — re-exports the React adapter (`<InstantTasksProvider>`, `<ErrorBoundary>`, `useInstantTasks`, `useUser`) with the `'use client'` directive at the module boundary.
|
|
9
|
+
3. **`/server` entry** — `getInstantTasks()` helper for Route Handlers and Server Components / Actions.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-react @koderlabs/tasks-sdk-nextjs
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Plugin — `withInstantTasks`
|
|
18
|
+
|
|
19
|
+
```js
|
|
20
|
+
// next.config.js
|
|
21
|
+
const { withInstantTasks } = require('@koderlabs/tasks-sdk-nextjs');
|
|
22
|
+
|
|
23
|
+
module.exports = withInstantTasks({
|
|
24
|
+
endpoint: 'https://tasks.koderlabs.net',
|
|
25
|
+
secretKey: process.env.INSTANTTASKS_SECRET_KEY,
|
|
26
|
+
// disableSourceMapUpload: true, // skip upload on CI dry-runs
|
|
27
|
+
// distDir: '.next', // override if you've customised it
|
|
28
|
+
})({
|
|
29
|
+
// your existing next config
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The plugin:
|
|
34
|
+
|
|
35
|
+
- Forces `productionBrowserSourceMaps: true`.
|
|
36
|
+
- Adds `InstantTasksSourceMapsPlugin` to the Webpack config for **production client** builds only.
|
|
37
|
+
- **Crashes the build** if any env var matching `NEXT_PUBLIC_.*INSTANTTASKS.*SECRET` is set — those values are inlined into the client bundle and would leak the secret key.
|
|
38
|
+
|
|
39
|
+
### `WithInstantTasksOptions`
|
|
40
|
+
|
|
41
|
+
| Option | Type | Default | Notes |
|
|
42
|
+
|---|---|---|---|
|
|
43
|
+
| `endpoint` | `string` | `https://tasks.koderlabs.net` | API root. |
|
|
44
|
+
| `secretKey` | `string` | `process.env.INSTANTTASKS_SECRET_KEY` | Management key with upload permission. **Must not** be a `NEXT_PUBLIC_*` var. |
|
|
45
|
+
| `disableSourceMapUpload` | `boolean` | `false` | Skip upload even in prod. |
|
|
46
|
+
| `distDir` | `string` | `'.next'` | Output directory to scan for `.map` files. |
|
|
47
|
+
|
|
48
|
+
### `InstantTasksSourceMapsPlugin`
|
|
49
|
+
|
|
50
|
+
Stand-alone Webpack plugin if you don't want the `withInstantTasks` wrapper.
|
|
51
|
+
|
|
52
|
+
| Option | Type | Default | Notes |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| `endpoint` | `string` | required | |
|
|
55
|
+
| `secretKey` | `string` | required | |
|
|
56
|
+
| `distDir` | `string` | `.next` | |
|
|
57
|
+
| `strict` | `boolean` | `process.env.CI === 'true'` | Fail the build on any failed upload. |
|
|
58
|
+
| `maxFileBytes` | `number` | `52428800` (50 MB) | Files above this are skipped with a warning. |
|
|
59
|
+
|
|
60
|
+
Uploads `POST {endpoint}/api/v1/sdk/source-maps` with the relative path as key. Path-traversal protected — files must resolve inside the dist root.
|
|
61
|
+
|
|
62
|
+
## Client — `/client`
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
// app/providers.tsx
|
|
66
|
+
'use client';
|
|
67
|
+
import { InstantTasksProvider } from '@koderlabs/tasks-sdk-nextjs/client';
|
|
68
|
+
import { errorsIntegration } from '@koderlabs/tasks-sdk-web-errors';
|
|
69
|
+
|
|
70
|
+
export function Providers({ children }: { children: React.ReactNode }) {
|
|
71
|
+
return (
|
|
72
|
+
<InstantTasksProvider
|
|
73
|
+
options={{
|
|
74
|
+
projectId: process.env.NEXT_PUBLIC_IT_PROJECT_ID!,
|
|
75
|
+
accessKey: process.env.NEXT_PUBLIC_IT_ACCESS_KEY!,
|
|
76
|
+
integrations: [errorsIntegration()],
|
|
77
|
+
}}
|
|
78
|
+
>
|
|
79
|
+
{children}
|
|
80
|
+
</InstantTasksProvider>
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Re-exports: `InstantTasksProvider`, `ErrorBoundary`, `useInstantTasks`, `useUser`, plus types.
|
|
86
|
+
|
|
87
|
+
## Server — `/server`
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
// app/api/route.ts
|
|
91
|
+
import { getInstantTasks } from '@koderlabs/tasks-sdk-nextjs/server';
|
|
92
|
+
|
|
93
|
+
export async function GET() {
|
|
94
|
+
try {
|
|
95
|
+
/* … */
|
|
96
|
+
return Response.json({ ok: true });
|
|
97
|
+
} catch (err) {
|
|
98
|
+
const it = getInstantTasks(); // reuses global client if init() ran in instrumentation.ts
|
|
99
|
+
await it.notify(err as Error, { context: 'GET /api/route' });
|
|
100
|
+
return new Response('Internal Server Error', { status: 500 });
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
If you haven't called `init()` in `instrumentation.ts`, pass options to `getInstantTasks(initOptions)` and it will init on first call.
|
|
106
|
+
|
|
107
|
+
## Caveats
|
|
108
|
+
|
|
109
|
+
- **Webpack only**. Next.js 15 uses Turbopack for dev but Webpack for production builds — the plugin hooks the production path. Turbopack plugin support is deferred until the experimental plugin API stabilises.
|
|
110
|
+
- Source-map upload runs in `afterEmit` for the client compiler only. Server bundles are skipped.
|
|
111
|
+
- There is no per-request singleton on the server — Edge / Node Worker contexts are isolated. Call `getInstantTasks()` at the top of each handler.
|
|
112
|
+
- `notify()` from the server entry is best-effort; failures log via `console.error` and do not throw.
|
|
113
|
+
- Initial RSC render errors are **not** auto-captured in v1 — wait for v1.1 / `onUncaughtException` instrumentation. Use try/catch + `notify()` in the meantime.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Suite overview
|
|
118
|
+
|
|
119
|
+
Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
|
|
8
124
|
|
|
9
125
|
Licensing inquiries: jawaidgadiwala@gmail.com
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@koderlabs/tasks-sdk-nextjs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Next.js plugin + source-map upload + client/server entries for the InstantTasks SDK.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"instanttasks",
|
|
@@ -55,8 +55,8 @@
|
|
|
55
55
|
],
|
|
56
56
|
"sideEffects": false,
|
|
57
57
|
"dependencies": {
|
|
58
|
-
"@koderlabs/tasks-sdk": "0.1.
|
|
59
|
-
"@koderlabs/tasks-sdk-react": "0.1.
|
|
58
|
+
"@koderlabs/tasks-sdk": "0.1.1",
|
|
59
|
+
"@koderlabs/tasks-sdk-react": "0.1.1"
|
|
60
60
|
},
|
|
61
61
|
"peerDependencies": {
|
|
62
62
|
"next": "^14 || ^15",
|
|
@@ -74,7 +74,7 @@
|
|
|
74
74
|
"node": ">=20"
|
|
75
75
|
},
|
|
76
76
|
"publishConfig": {
|
|
77
|
-
"access": "
|
|
77
|
+
"access": "public"
|
|
78
78
|
},
|
|
79
79
|
"scripts": {
|
|
80
80
|
"build": "tsup",
|