@arcjet/react-router

Arcjet helps developers protect their apps in just a few lines of code. Implement rate limiting, bot protection, email verification, and defense against common attacks.

This is the Arcjet SDK for React Router.

• GitHub source code (arcjet-react-router/ in arcjet/arcjet-js)
• npm package (@arcjet/react-router)

Example

This monorepo contains two examples using @arcjet/react-router:

• examples/react-router-middleware/ — Arcjet + React Router (using middleware)
• examples/react-router/ — Arcjet + React Router

What is this?

This adapter integrates Arcjet and React Router. Arcjet helps you secure your React Router website.

When should I use this?

You can use this if you are using React Router. See our Get started guide for other supported frameworks.

Install

This package is ESM only. Install with npm in Node.js:

npm install @arcjet/react-router

Use

In a route such as app/routes/home.tsx do something like:

import arcjet, { shield } from "@arcjet/react-router";
import type { ReactNode } from "react";
import type { Route } from "../routes/+types/home";

// Get your Arcjet key at <https://app.arcjet.com>.
// Set it as an environment variable instead of hard coding it.
const arcjetKey = process.env.ARCJET_KEY;

if (!arcjetKey) {
  throw new Error("Cannot find `ARCJET_KEY` environment variable");
}

const aj = arcjet({
  key: arcjetKey,
  rules: [
    // Shield protects your app from common attacks.
    // Use `DRY_RUN` instead of `LIVE` to only log.
    shield({ mode: "LIVE" }),
  ],
});

export default function Home(): ReactNode {
  return <h1>Hello!</h1>;
}

export async function loader(
  loaderArguments: Route.LoaderArgs,
): Promise<undefined> {
  const decision = await aj.protect(loaderArguments);

  if (decision.isDenied()) {
    throw new Response(
      undefined,
      decision.reason.isRateLimit()
        ? { statusText: "Too many requests", status: 429 }
        : { statusText: "Forbidden", status: 403 },
    );
  }
}

API

This package exports the identifier createRemoteClient. The default export is arcjet. It also exports all identifiers from arcjet core.

This package exports the TypeScript types ArcjetOptions, ArcjetReactRouterRequest, ArcjetReactRouter, and RemoteClientOptions. It also exports all types from arcjet core.

ArcjetOptions

Configuration for the React Router integration of Arcjet (TypeScript type).

Fields

• characteristics (Array<string>, default: ["src.ip"]) — characteristics to track a user by; can also be passed to rules
• client (Client, optional) — client used to make requests to the Arcjet API; this is configured by adapters (such as @arcjet/react-router) but can be overwritten for testing purposes
• key (string, required) — API key to identify the site in Arcjet
• log (ArcjetLogger, optional) — log interface to emit useful information; this is configured by adapters (such as @arcjet/react-router) but can be overwritten for testing purposes
• proxies (Array<string>, optional, example: ["100.100.100.100", "100.100.100.0/24"]) — IP addresses and CIDR ranges of trusted load balancers and proxies
• rules (Array<Array<Rule>>, required) — rules to apply when protecting a request

ArcjetReactRouterRequest

Request for the React Router integration of Arcjet (TypeScript type).

Fields

• context (unknown, optional) — context for the React Router request; the ip (string) field is used if available
• request (Request, required) — DOM request

ArcjetReactRouter

Instance of the React Router integration of Arcjet (TypeScript type).

Primarily has a protect() method to make a decision about how a request should be handled.

ArcjetReactRouter#protect(details, properties?)

Make a decision about how to handle a request.

This will analyze the request locally where possible and otherwise call the Arcjet decision API.

Parameters

• details (ArcjetReactRouterRequest, required) — details about the React Router request that Arcjet needs to make a decision.
• properties (object, optional) — additional properties required for running rules against a request.

Returns

Promise that resolves to an Arcjet decision indicating Arcjet’s decision about the request (Promise<ArcjetDecision>).

ArcjetReactRouter#withRule(rule)

Augment the client with another rule.

Useful for varying rules based on criteria in your handler such as different rate limit for logged in users.

Parameters

• rule (Array<Rule>, required) — rule to add to Arcjet

Returns

Arcjet instance augmented with the given rule (ArcjetReactRouter).

RemoteClientOptions

Configuration for createRemoteClient (TypeScript type).

Fields

• baseUrl (string, optional) — base URI for HTTP requests to Decide API; defaults to the environment variable ARCJET_BASE_URL (if that value is known and allowed) and the standard production API otherwise
• timeout (number, optional) — timeout in milliseconds for the Decide API; defaults to 500 in production and 1000 in development

arcjet

Create a new React Router integration of Arcjet.

👉 Tip: build your initial base client with as many rules as possible outside of a request handler; if you need more rules inside handlers later then you can call withRule() on that base client.

Parameters

• options (ArcjetOptions, required) — configuration

Returns

React Router integration of Arcjet (ArcjetReactRouter).

createRemoteClient

Create a remote client.

Parameters

• options (RemoteClientOptions, optional) — configuration

Returns

Client (Client).

License

Apache License, Version 2.0 © Arcjet Labs, Inc.