Documentation

Install

npm install patchly

Also works with pnpm, yarn, or bun.

Quick start

import { init } from "patchly";

const patchly = init({
  dsn: process.env.PATCHLY_DSN!,   // required — from patchly.cc → Settings
  release: "1.2.0",                 // optional — enables source map resolution
  userId: "user_123",               // optional — track affected users
  autoCapture: true,                // default: true — captures uncaught errors
});

// manual capture
patchly.capture(new Error("something broke"));

// flush on shutdown (Node.js)
await patchly.close();

DSN format

Your DSN is available in the Patchly dashboard under Settings. It follows this format:

https://<API_KEY>@api.patchly.cc/<PROJECT_ID>

Add it to your .env file. Never commit it to version control.

Next.js (App Router)

Server-side — instrumentation.ts

Create at your project root:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("patchly");
    init({ dsn: process.env.PATCHLY_DSN! });
  }
}

Enable in next.config.ts:

const nextConfig = {
  experimental: { instrumentationHook: true },
};
export default nextConfig;

Client-side — app/error.tsx

"use client";
import { useEffect } from "react";
import { init } from "patchly";

const patchly = init({ dsn: process.env.NEXT_PUBLIC_PATCHLY_DSN! });

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  useEffect(() => { patchly.capture(error); }, [error]);
  return (
    <div>
      <h2>Something went wrong</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Environment variables

# .env.local
PATCHLY_DSN=https://<key>@api.patchly.cc/<projectId>
NEXT_PUBLIC_PATCHLY_DSN=https://<key>@api.patchly.cc/<projectId>

Node.js / Express

import { init } from "patchly";

const patchly = init({ dsn: process.env.PATCHLY_DSN! });

// Uncaught exceptions are captured automatically.
// For manual capture:
try {
  riskyOperation();
} catch (err) {
  patchly.capture(err as Error);
}

// Graceful shutdown
process.on("SIGTERM", async () => {
  await patchly.close();
  process.exit(0);
});

Source maps

Upload source maps so Patchly can show original file names and line numbers in stack traces.

curl -X POST https://api.patchly.cc/sourcemaps \
  -H "Authorization: Bearer <API_KEY>" \
  -F "release=1.2.0" \
  -F "filePath=_next/static/chunks/app/page.js" \
  -F "sourcemap=@.next/static/chunks/app/page.js.map"

Set the release option in init() to match.

AI fix suggestions

When an error group reaches 3 events, Patchly automatically fetches your source code from GitHub and generates a fix suggestion using an LLM. Fix suggestions include:

• Root cause analysis
• Suggested code fix
• Affected files
• Confidence score (0-1)

View and vote on fixes in the dashboard.

Alerts

Configure Slack webhook or email alerts in Settings. Alerts fire when an error group exceeds your threshold count within a time window.

SDK API reference

Config options

Claude Code integration

Patchly ships a SKILLS.md for Claude Code. Add it to your project so Claude can help integrate and debug Patchly errors:

curl -o PATCHLY.md https://patchly.cc/SKILLS.md

Or get a project-specific version with your DSN pre-filled from /skills.