Arcjet Next.js SDK reference

[giscus[bot]]

Arcjet Next.js SDK reference

Arcjet documentation. Bot detection. Rate limiting. Email validation. Attack protection. Data redaction. A developer-first approach to security.

https://docs.arcjet.com/reference/nextjs/

[sheariley]

I'm getting the following warning in my Vercel build log (NOTE: I've used the NextJS guide on the docs.arcjet.com website):

./node_modules/@arcjet/runtime/index.js
A Node.js API is used (process.release at line: 42) which is not supported in the Edge Runtime.
Learn more: https://nextjs.org/docs/api-reference/edge-runtime

Import trace for requested module:
./node_modules/@arcjet/runtime/index.js
./node_modules/arcjet/index.js
./node_modules/@arcjet/next/index.js
./src/lib/middleware/arcjet/index.ts

===============================

NOTE: That last file in the import trace list is where I put the code for executing the arcjet.protect method. I did a little bit of abstraction to make my middleware code more procedural, but nothing crazy. The code is still very similar to what is in the NextJS guide.

[davidmytton]

hi @sheariley - is this showing up as a warning or an error? This usually shows up as a warning, but doesn't block the build. Our Next.js SDK supports all environments (including edge) and adapts the code called at runtime. It gets highlighted during the build because it detects the incompatible code, but doesn't cause any issues at runtime,.

[sheariley]

Thanks for the explanation. It was just a warning and have verified that it is running correctly in production.

[davidmytton]

Ok great. I've logged an issue at arcjet/arcjet-js#3876 to see if we can get rid of the warnings. Thanks for raising this!

[developedbynick]

Just clarifying something:

Suppose I have middleware that uses detectBots and some shield rules configured on the base Arcjet object. Then, on my forgot password route, I reuse that same Arcjet instance with .withRule() to add specific rate limiting.

In that case, do the original detectBots and shield rules still run in addition to the new rate limit rule?

[developedbynick]

I ask because I looked at the decision's results, and they say the state is RUN for the first two rules. Is there a better way to do this if the results aren't actually cached?

[davidmytton]

In that case, do the original detectBots and shield rules still run in addition to the new rate limit rule?

Yes.

If you create a client as you describe:

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  rules: [
    detectBot({
      mode: "LIVE",
      allow: [
        "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc
      ],
    }),
    shield({
      mode: "DRY_RUN",
    }),
  ],
});

then any other use of this client, such as withRule, will use those two base rules as well i.e. if you export aj and then later do this:

const decision = aj.withRule(fixedWindow({max: 10, window: "1m"})).protect(req);

then you'll have 3 rules executed.

If you want to be able to take advantage of the cached client everywhere in your app then you can export a client with an empty set of initial rules. Then wherever you want to use it, you call it using withRule. We do this in our example app with a base client that has no rules set. Then later it's used with various rules added using withRule.

Let me know if that doesn't make sense!

[developedbynick]

Thanks. I'm a bit hesitant to just use the middleware to protect against all types of requests because of the recent bypass, so for now, I'll deal with the additional overhead just in case

[davidmytton]

Righto. In that case I'd recommend excluding specific routes from the middleware where you directly call aj.protect(). This can be done with the Next.js middleware matcher config.

[developedbynick]

Thanks!

[developedbynick]

I'm implementing rate limiting for a login form and would like to apply two different rules:

1. IP + Email-based Rule: Limits the number of failed attempts for a specific email from a specific IP address (e.g., 5 attempts per 15 minutes).

2. Email-only Rule: Limits the number of failed attempts for a given email address globally, regardless of the IP (e.g., 10 attempts per 30 minutes).

This setup is meant to:

Prevent brute force attacks from a single IP,
And protect individual accounts from distributed attacks across multiple IPs.

Is this multi-rule configuration supported?
If yes, could you point me to documentation or examples that explain how to configure and enforce multiple rules simultaneously?

Thanks in advance.

[davidmytton]

Yes, this is possible! I've created a docs issue at #482 so we can build an example and include it in the docs for you. We'll work on it right away and come back to you shortly :)

[qw-in]

Hi @developedbynick,

I'm working on updating our docs and examples to include more multi-rule configurations. In the meantime, here’s a configuration that should match your requirements:

// configuration
const aj = arcjet({
  key: process.env.ARCJET_KEY,
  characteristics: ["fingerprint"],
  rules: [
    fixedWindow({
      mode: "LIVE",
      characteristics: ["fingerprint"],
      max: 5,
      window: "15m",
    }),
    fixedWindow({
      mode: "LIVE",
      characteristics: ["emailHash"],
      max: 10,
      window: "30m",
    }),
  ],
});

// usage
const decision = await aj.protect(req, {
  fingerprint: hash(`${userEmail}-${userIp}`),
  emailHash: hash(userEmail),
});

A couple things to keep in mind:

1. Our Cloud API currently caches based on the top-level characteristics. That’s why the example combines ip and email into a single fingerprint characteristic. We’re working to remove this limitation soon.
2. Although characteristic values are always hashed by our Cloud API, it’s still best practice not to send sensitive information (like raw email addresses). In this example, we hash the email before passing it to protect.

Let me know if you run into any issues or have any questions!

Full example

import crypto from "node:crypto";
import { NextResponse, type NextRequest } from "next/server";
import arcjet, { fixedWindow } from "@arcjet/next";
import ip from "@arcjet/ip";
import { setRateLimitHeaders } from "@arcjet/decorate";

export const dynamic = "force-dynamic";

const aj = arcjet({
  key: process.env.ARCJET_KEY,
  characteristics: ["fingerprint"],
  rules: [
    fixedWindow({
      mode: "LIVE",
      characteristics: ["fingerprint"],
      max: 5,
      window: "15m",
    }),
    fixedWindow({
      mode: "LIVE",
      characteristics: ["emailHash"],
      max: 10,
      window: "30m",
    }),
  ],
});

export async function POST(req: NextRequest) {
  // Next.js 15 doesn't provide the IP address in the request object so we use
  // the Arcjet utility package to parse the headers and find it. If we're
  // running in development mode, we'll use a local IP address.
  const userIp = process.env.NODE_ENV === "development" ? "127.0.0.1" : ip(req);

  // In a real application, you would retrieve the email from the request body.
  const userEmail = /* extract from request body */;

  const decision = await aj.protect(req, {
    // Email and ip are combined into a single fingerprint characteristic since
    // the Cloud API caches based on the top-level characteristics. Since it
    // includes the email, we hash it before sending it to the API.
    fingerprint: hash(`${userEmail}-${userIp}`),

    // Best practice to hash the email before sending it to the Arcjet API.
    emailHash: hash(userEmail),
  });

  const headers = new Headers();
  setRateLimitHeaders(headers, decision);

  if (decision.isDenied()) {
    if (decision.reason.isRateLimit()) {
      return NextResponse.json(
        { error: "Too many requests" },
        { status: 429, headers },
      );
    }

    return NextResponse.json({ message: "Other reason" }, { status: 500 });
  }

  return NextResponse.json({ message: "OK" }, { status: 200, headers });
}

// Helper function that uses SHA-256 to hash the input value. This works
// in Node but other runtimes may require a different approach.
function hash(value: string) {
  return crypto.createHash("sha256").update(value).digest("hex");
}

[developedbynick]

It makes sense now that when I sent the raw email, the API ignored it and failed to rate limit. I assume this is a protective measure in case that part in the docs was overlooked. I've since changed the characteristics to 'mail' and hashed it. Thanks @qw-in & @davidmytton