Next.js (Server/Backend)

Decipher’s Next.js SDK for the backend allows for automatic capture of errors including helpful details like logs and raw payload data.

For frontend Next.js, see the React docs.

⏱ Estimated Time To Completion: 5 minutes

Step 1: Sign in to Decipher

Sign in to Decipher using your work email address and a customerId will be automatically created for you, which you’ll use in the next step.

Step 2: Integrate the SDK

Install the SDK

Terminal

npm install @decipher-sdk/nextjs@latest

Update your API routes

Choose instructions based on your app structure:

App Router

The steps below apply if you’re using Next.js App Router.

Create a decipher.config.[ts|js] at your project root (sibling to app/ directory)

src/decipher.config.ts

import Decipher from "@decipher-sdk/nextjs";

Decipher.init({
  codebaseId: "CODEBASE_NAME_OF_MY_CHOICE",
  customerId: "MY_CUSTOMER_ID_FROM_STEP_1",
});

export default Decipher;

Import Decipher into your route files and wrap your handlers using Decipher.withDecipher as below.

src/app/api/example/route.ts

import type { NextRequest, NextResponse } from "next/server";
import Decipher from "@/decipher.config";

async function handler(req: NextRequest) {
const body = await req.json();
return NextResponse.json({ message: 'Processed successfully' },
{ status: 200 });
}

export const POST = Decipher.withDecipher(handler);

Pages Router

The steps below apply if you’re using Next.js Pages Router.

Import wrapApiHandlerWithDecipher into your route files and wrap your handlers as below.

src/pages/api/example/route.ts

import type { NextApiRequest, NextApiResponse } from "next";
import { wrapApiHandlerWithDecipher } from "decipher-sdk";

const handler = (req: NextApiRequest, res: NextApiResponse) => {
res.status(200).json({ name: "Jane Smith" });
};

export default wrapApiHandlerWithDecipher(handler, {
   // A codebase name of your choice to identify errors in Decipher.
   codebaseId: "CODEBASE_NAME_OF_MY_CHOICE",
   customerId: "MY_CUSTOMER_ID_FROM_STEP_1"
});

Step 3: Add your sourcemaps [IMPORTANT]

When your code runs on production, it is likely minified and/or bundled, so we need to upload sourcemaps to see stack traces with the right code.

Update your next.config.[m]js as below to make sure your sourcemaps are added to Decipher.

next.config.mjs

/** @type {import('next').NextConfig} */
import { withDecipherConfig } from "@decipher-sdk/nextjs";

const nextConfig = {
  // ...your existing NextConfig
};

export default withDecipherConfig(nextConfig, {
  apiKey: "YOUR_DECIPHER_API_KEY", // From the /settings page.
});

Decipher will now automatically upload production sourcemaps upon new releases of your app.

If you don’t use tRPC, you’re now done! Decipher will now monitor and surface all your errors and exceptions on the dashboard. Consider the optional steps below to enhance Decipher’s reporting.

---

[Optional] Step 4: Report caught errors to Decipher

If you want to capture error details like the stack trace for handled exceptions (e.g. in a try/catch block) you can use Decipher.captureError(error):

route.ts

import type { NextRequest, NextResponse } from "next";
import Decipher from "@/decipher.config";

async function handler(req: NextRequest) {
  // ...
  try {
    thisFunctionMightThrowErrors();
  } catch (error) {
    Decipher.captureError(error);
    return NextResponse.json(
      { message: "An error occurred." },
      { status: 500 }
    );
  }
  // ...
  return NextResponse.json(
    { message: "Processed successfully" },
    { status: 200 }
  );
}

export const POST = Decipher.withDecipher(handler);

[Optional] Step 5: Add user information as context for your errors

If you want to add user details to errors make sure to call Decipher.setUser() near the beginning of the request.

You can include any subset of the following: id, email, username

route.ts

// ...other imports
import Decipher from "@/decipher.config";

async function handler(req: NextRequest) {
  // ...

  Decipher.setUser({ email: "[e-mail]" });

  try {
    thisFunctionMightThrowErrors();
  } catch (error) {

  // ...

}\

[Optional] Step 6: For apps using tRPC, add the tRPC Middleware.

Import decipherTrpcMiddleware and add it to the relevant procedure as below.

src/server/api/trpc.ts

// ...
import { decipherTrpcMiddleware } from "@decipher-sdk/nextjs";

// ...
export const publicProcedure = t.procedure.use(
  decipherTrpcMiddleware({
    // A codebase name of your choice to identify errors in Decipher.
    codebaseId: "CODEBASE_NAME_OF_MY_CHOICE",
    customerId: "MY_CUSTOMER_ID_FROM_STEP_1",
  })
);

That’s it! Decipher will now monitor and surface all your errors and exceptions on the dashboard.