Next.js integration

Runstamp renders documents in server code. Don't import an engine from a Client Component or an Edge Runtime route.

App Router route handler

// app/api/report/route.ts
import { runstamp } from "@runstamp/sdk";

export const runtime = "nodejs";

export async function GET() {
  const result = await runstamp.operations.run<{ bytes: Uint8Array }>("pdf.render", {
    meta: { title: "Next.js report" },
    page: { size: "Letter", margin: 48 },
    children: [{ type: "paragraph", value: "Generated in a Route Handler." }],
  });

  if (!result.ok) {
    return Response.json(
      { code: result.error.code, remediation: result.error.remediation },
      { status: 422 },
    );
  }

  return new Response(Buffer.from(result.value.bytes), {
    headers: {
      "content-type": "application/pdf",
      "content-disposition": 'attachment; filename="report.pdf"',
    },
  });
}

The local transport needs no hosted key or SDK license. If a negotiated Enterprise/OEM deployment uses an offline certificate, keep it in your server secret manager. Never prefix it with NEXT_PUBLIC_ or pass it to browser code.

Bundler compatibility fallback

Runstamp release CI tests stock App Router apps. If a supported Next.js release cannot trace a native or WASM dependency for your deploy target, externalize the SDK:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: [
    "@runstamp/sdk",
    "@napi-rs/canvas",
    "yoga-wasm-web",
  ],
};

export default nextConfig;

Start without this fallback. Add it only if next build reports a native or WASM resolution or tracing error. Keep the stock production-build check in your CI.

Deployment checklist

• Run Node.js 18.18 or later: Next.js 15 needs Node.js 18.18 or later and the Runstamp SDK needs Node.js 18.14.1 or later, so the Next.js floor is the one that applies. A newer Next.js major can raise it; follow the Node.js version your Next.js release documents.
• Set export const runtime = "nodejs" on every route that renders.
• Render in Route Handlers, Server Actions, background jobs or other server-only modules.
• Store Enterprise/OEM offline certificates in your secret manager, when applicable.
• Write the returned buffer to the response, object storage, or a durable job result.
• Run next build in CI with the same package tarballs and Next.js version you deploy.