@koderlabs/tasks-sdk-nextjs

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).

Three things in one package:

1. next.config plugin — enables productionBrowserSourceMaps and uploads source maps to the InstantTasks API after a production client build.
2. /client entry — re-exports the React adapter (<InstantTasksProvider>, <ErrorBoundary>, useInstantTasks, useUser) with the 'use client' directive at the module boundary.
3. /server entry — getInstantTasks() helper for Route Handlers and Server Components / Actions.

Install

npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-react @koderlabs/tasks-sdk-nextjs
# or
pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-react @koderlabs/tasks-sdk-nextjs
# or
yarn add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-react @koderlabs/tasks-sdk-nextjs

Plugin — withInstantTasks

// next.config.js
const { withInstantTasks } = require('@koderlabs/tasks-sdk-nextjs');

module.exports = withInstantTasks({
  endpoint: 'https://tasks.koderlabs.net',
  secretKey: process.env.INSTANTTASKS_SECRET_KEY,
  // disableSourceMapUpload: true,    // skip upload on CI dry-runs
  // distDir: '.next',                 // override if you've customised it
})({
  // your existing next config
});

The plugin:

• Forces productionBrowserSourceMaps: true.
• Adds InstantTasksSourceMapsPlugin to the Webpack config for production client builds only.
• 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.

WithInstantTasksOptions

| Option | Type | Default | Notes | |---|---|---|---| | endpoint | string | https://tasks.koderlabs.net | API root. | | secretKey | string | process.env.INSTANTTASKS_SECRET_KEY | Management key with upload permission. Must not be a NEXT_PUBLIC_* var. | | disableSourceMapUpload | boolean | false | Skip upload even in prod. | | distDir | string | '.next' | Output directory to scan for .map files. |

InstantTasksSourceMapsPlugin

Stand-alone Webpack plugin if you don't want the withInstantTasks wrapper.

| Option | Type | Default | Notes | |---|---|---|---| | endpoint | string | required | | | secretKey | string | required | | | distDir | string | .next | | | strict | boolean | process.env.CI === 'true' | Fail the build on any failed upload. | | maxFileBytes | number | 52428800 (50 MB) | Files above this are skipped with a warning. |

Uploads POST {endpoint}/api/v1/sdk/source-maps with the relative path as key. Path-traversal protected — files must resolve inside the dist root.

Client — /client

// app/providers.tsx
'use client';
import { InstantTasksProvider } from '@koderlabs/tasks-sdk-nextjs/client';
import { errorsIntegration } from '@koderlabs/tasks-sdk-web-errors';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <InstantTasksProvider
      options={{
        projectId: process.env.NEXT_PUBLIC_IT_PROJECT_ID!,
        accessKey: process.env.NEXT_PUBLIC_IT_ACCESS_KEY!,
        integrations: [errorsIntegration()],
      }}
    >
      {children}
    </InstantTasksProvider>
  );
}

Re-exports: InstantTasksProvider, ErrorBoundary, useInstantTasks, useUser, plus types.

Server — /server

// app/api/route.ts
import { getInstantTasks } from '@koderlabs/tasks-sdk-nextjs/server';

export async function GET() {
  try {
    /* … */
    return Response.json({ ok: true });
  } catch (err) {
    const it = getInstantTasks();           // reuses global client if init() ran in instrumentation.ts
    await it.notify(err as Error, { context: 'GET /api/route' });
    return new Response('Internal Server Error', { status: 500 });
  }
}

If you haven't called init() in instrumentation.ts, pass options to getInstantTasks(initOptions) and it will init on first call.

Caveats

• 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.
• Source-map upload runs in afterEmit for the client compiler only. Server bundles are skipped.
• There is no per-request singleton on the server — Edge / Node Worker contexts are isolated. Call getInstantTasks() at the top of each handler.
• notify() from the server entry is best-effort; failures log via console.error and do not throw.
• Initial RSC render errors are not auto-captured in v1 — wait for v1.1 / onUncaughtException instrumentation. Use try/catch + notify() in the meantime.

Suite overview

Full SDK suite map + platform availability matrix: docs/sdk/overview.md.

License

KoderLabs proprietary. See LICENSE for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.

Licensing inquiries: [email protected]