Arcjet best practices

The following sections describe how to use Arcjet effectively in your applications.

Single client instance

We recommend creating a single instance of the Arcjet client object and reusing it throughout your application. This is because the SDK caches decisions and configuration to improve performance. It also means the object is created outside of the route handler to avoid creating a new instance on every request.

The pattern we recommend is to create a utility file that exports the Arcjet object and then import it where you need it.

JavaScript / TypeScript

In the JS SDKs, use withRule to attach rules specific to each route or location in your app.

For example, in a Next.js app you might create a file /lib/arcjet.ts that creates and exports the Arcjet instance:

/lib/arcjet.ts

import arcjet, {
  detectBot,
  fixedWindow,
  protectSignup,
  sensitiveInfo,
  shield,
  slidingWindow,
} from "@arcjet/next";

// Re-export the rules to simplify imports inside handlers
export {
  detectBot,
  fixedWindow,
  protectSignup,
  sensitiveInfo,
  shield,
  slidingWindow,
};

// Create a base Arcjet instance for use by each handler
export default arcjet({
  // Get your site key from https://app.arcjet.com
  // and set it as an environment variable rather than hard coding.
  // See: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
  key: process.env.ARCJET_KEY!,
  rules: [
    // You could include one or more base rules to run on every request
  ],
});

Then, in your request handler you can import the Arcjet instance and use withRule to add any route-specific rules. protect() can then be called inside the route handler.

import arcjet, { detectBot, fixedWindow } from "@/lib/arcjet";

// Add rules to the base Arcjet instance outside of the handler function
const aj = arcjet
  .withRule(
    detectBot({
      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
      // configured with a list of bots to allow from
      // https://arcjet.com/bot-list
      allow: [], // blocks all automated clients
    }),
  )
  // You can chain multiple rules, so we'll include a rate limit
  .withRule(
    fixedWindow({
      mode: "LIVE",
      max: 100,
      window: "60s",
    }),
  );

export async function GET(req: Request) {
  // The protect method returns a decision object that contains information
  // about the request.
  const decision = await aj.protect(req);

  // ... handle the request
}

Python

In the Python SDK, create one base client and add route-specific rules with with_rule(). The clone shares this instance’s DecisionCache, key, characteristics, and transport. The original client is unchanged.

Use arcjet() for async frameworks (FastAPI, Starlette) and arcjet_sync() for sync frameworks (Flask, Django). HTTP rule factories require mode.

/lib/arcjet.py

import os

from arcjet import Mode, arcjet, detect_bot, shield, sliding_window

# Create one base client and add route-specific rules with with_rule().
# Clones share DecisionCache, key, characteristics, and transport.

aj = arcjet(
    # Get your site key from https://app.arcjet.com
    # and set it as an environment variable rather than hard coding.
    key=os.environ["ARCJET_KEY"],
    rules=[
        shield(mode=Mode.LIVE),
        detect_bot(mode=Mode.LIVE, allow=[]),
    ],
)

# Read endpoints: shared cache plus a lenient rate limit
aj_read = aj.with_rule(sliding_window(mode=Mode.LIVE, interval=60, max=100))

# Write endpoints: shared cache plus a stricter rate limit
aj_write = aj.with_rule(sliding_window(mode=Mode.LIVE, interval=60, max=15))

Then import the client you need inside each route handler and call protect() once per request:

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

from lib.arcjet import aj_read

app = FastAPI()


@app.get("/items")
async def list_items(request: Request):
    decision = await aj_read.protect(request)

    if decision.is_denied():
        return JSONResponse({"error": "Forbidden"}, status_code=403)

    # ... handle the request

If you only need one rule set across the whole app, a single client is fine.

Avoid Arcjet in middleware

We do not recommend using Arcjet in middleware. This is because middleware lacks the context of the route handler, making it difficult to apply route-specific rules or customize responses based on the request.

Our recommendation is to call protect() in each route handler where you need it. This offers the most flexibility and lets you customize the behavior for each route.

Call protect() once per request

Call the Arcjet protect() function only once per request.

This is usually only a problem if you use Arcjet both in middleware and in route handlers. We do not recommend using middleware, but if you are using it then use a middleware helper to scope the call to Arcjet only to routes that need it.

Start in dry run mode

We recommend starting each new rule in DRY_RUN mode. When configured this way, each rule returns its decision, but the end conclusion is always ALLOW. This is useful for testing and tuning your rules before switching to LIVE.

As these are configured in code, you can use other mechanisms to set the mode. For example, you could use an existing feature flag system to dynamically change the rule mode. We have an example showing how to sample traffic between DRY_RUN and LIVE modes in the Sampling traffic blueprint.

For teams with separate security and engineering owners, keep feature-specific rules in code so developers can review them with the route or workflow they protect. Use remote rules for operational changes that SecOps needs to test, promote, or roll back against live traffic without waiting for an application deploy.

Using the MCP server

If you’re using the Arcjet MCP server, call get-dry-run-impact to see exactly how many currently-allowed requests would be blocked before promoting a dry-run rule to live. You can also create and promote remote rules directly through MCP without code changes.

Configure proxies and load balancers

Arcjet needs to see the original client IP address to make accurate decisions. If your application is behind a proxy or load balancer, make sure that Arcjet can access the original IP address.

Most proxies and load balancers add an X-Forwarded-For header to requests that contains the original client IP address. Make sure that this header reaches your application and that you configure Arcjet to ignore the proxy IP addresses.

This is not necessary on platforms such as Firebase, Netlify, Fly.io, or Vercel because Arcjet can auto-detect the proxy IPs for these platforms.

For other platforms, configure the proxies option when creating the Arcjet instance. For example, if the load balancer is at 203.0.113.100 and the client IP address is 198.51.100.1, the X-Forwarded-For header is:

X-Forwarded-For: 198.51.100.1, 203.0.113.100

Set the proxies field to ["203.0.113.100"] so Arcjet uses 198.51.100.1 as the client IP address.

You can also specify CIDR ranges to match multiple IP addresses.

JavaScript / TypeScript

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  rules: [],
  proxies: [
    "203.0.113.100", // A single IP
    "203.0.113.0/24", // A CIDR for the range
  ],
});

Python

import os

from arcjet import arcjet

aj = arcjet(
    key=os.environ["ARCJET_KEY"],
    rules=[],
    proxies=[
        "203.0.113.100",  # A single IP
        "203.0.113.0/24",  # A CIDR for the range
    ],
)

Proxy services like Cloudflare

Some providers don’t add themselves to X-Forwarded-For. Instead they pass the real client IP in their own header – for example, Cloudflare uses CF-Connecting-IP. For these you can pass a proxy service in the proxies option instead of a plain IP address.

The JavaScript SDKs export a cloudflare() helper for this. When a request arrives from a known Cloudflare IP range, Arcjet reads the real client IP from Cloudflare’s header. This is only trusted when the connecting address is within Cloudflare’s verified IP ranges, so the header can’t be spoofed by a direct client.

/lib/arcjet.ts

import arcjet, { cloudflare } from "@arcjet/next";

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  rules: [],
  // Read the real client IP from Cloudflare's `CF-Connecting-IP` header when
  // the request arrives from a Cloudflare IP range
  proxies: [cloudflare()],
});

You can combine proxy services with plain IP addresses in the same list, such as proxies: ["203.0.113.0/24", cloudflare()].

Cloudflare in front of Vercel is not recommended

If you deploy to Vercel, Vercel recommends against putting Cloudflare (or any reverse proxy) in front of your application. Doing so hides traffic and can cause bot challenges to misfire as proxy exit-node IPs rotate. Arcjet already auto-detects the proxy IPs for Vercel, so you don’t need to configure proxies on Vercel unless you’ve added another proxy in front. If you do run Cloudflare in front of Vercel, add cloudflare() to proxies so Arcjet still sees the real client IP.

Add a Cloudflare range the SDK doesn’t recognize

The Cloudflare IP ranges are bundled with the SDK and updated as new versions are released. If Cloudflare publishes a new range before the SDK has been updated, pass it with the ranges option. This replaces the bundled ranges rather than adding to them, so include the full current list plus the new range:

/lib/arcjet.ts

import arcjet, { cloudflare } from "@arcjet/next";

const aj = arcjet({
  key: process.env.ARCJET_KEY!,
  rules: [],
  proxies: [
    cloudflare({
      // This *replaces* the ranges bundled with the SDK, so include the full
      // list from https://www.cloudflare.com/ips/ plus any new range
      ranges: [
        // The current Cloudflare ranges...
        "173.245.48.0/20",
        "103.21.244.0/22",
        // ...plus a new range not yet bundled in the SDK
        "203.0.113.0/24",
      ],
    }),
  ],
});

Implement your own error handling

Calls to protect() don’t throw an error. Arcjet is designed to fail open so that a service issue or misconfiguration does not block all requests.

If there is an error condition when processing the rule, Arcjet returns an ERROR result for that rule and you can check the error message on the rule’s error result for more information. For example:

JavaScript / TypeScript

const decision = await aj.protect(req);

if (decision.isErrored()) {
  // Fail open: log the error and allow the request
  console.error("Arcjet error", decision.reason.message);
}

Python

decision = await aj.protect(request)

if decision.is_error():
    # Fail open: log the error and allow the request
    logger.error("Arcjet error: %s", decision.reason_v2.message)