How to secure your NestJS application with Arcjet

How do you secure a NestJS application with Arcjet?

Use @arcjet/nest v1 on NestJS 10 or 11. Configure ArcjetModule.forRoot, apply ArcjetGuard globally or per controller, and attach route rules with @WithArcjetRules. Bot rules use detectBot({ allow: [...] }), not the old block list.

Arcjet is ESM-only. NestJS starters default to CommonJS. Switch the project to ESM before you import the SDK, or you will get ERR_REQUIRE_ESM.

This article covers that module setup, the guard, and per-route rules. For login-specific limits see secure login pages. For abuse that is not framework-specific see the web app security checklist.

What versions does this apply to?

• NestJS 10.4 or later, including NestJS 11
• Node.js 22 (Arcjet supports 22.21.0 or later on the current SDK line)
• Express or Fastify adapters
• "type": "module" in package.json

1
npm i @arcjet/nest@1.10.0 @nestjs/config

Why do you need ESM for @arcjet/nest?

The SDK ships as ECMAScript modules so it can run on modern Node, Deno, and Bun. require() of an ESM package throws:

1
Error [ERR_REQUIRE_ESM]: require() of ES Module .../arcjet-nest/... not supported.

NestJS supports both CommonJS and ESM. The CLI starter still emits CommonJS ("module": "commonjs" in tsconfig.json, no "type" in package.json). Change both files.

tsconfig.json:

1
{
2
  "compilerOptions": {
3
    "module": "nodenext",
4
    "moduleResolution": "nodenext",
5
    "target": "ES2022"
6
  }
7
}

package.json:

1
{
2
  "type": "module"
3
}

Use .js extensions on relative imports in emitted files (./app.service.js) as Node ESM requires. Nest's default jest config often still expects CommonJS; update the test runner or run tests with a Node ESM preset so CI matches npm run start. The Arcjet NestJS example shows a working layout.

If you cannot move the whole monorepo to ESM, isolate the Nest app in a package that is ESM and keep other packages CommonJS. Do not try to require() @arcjet/nest from a CommonJS file.

How do you register ArcjetModule?

Create one root client in AppModule. Rules you set here run on every guarded request. Leave rules empty if you prefer to declare them only on controllers.

1
import { ArcjetGuard, ArcjetModule, shield } from "@arcjet/nest";
2
import { Module } from "@nestjs/common";
3
import { ConfigModule } from "@nestjs/config";
4
import { APP_GUARD } from "@nestjs/core";
5

6
@Module({
7
  imports: [
8
    ConfigModule.forRoot({ isGlobal: true }),
9
    ArcjetModule.forRoot({
10
      isGlobal: true,
11
      key: process.env.ARCJET_KEY!,
12
      rules: [shield({ mode: "LIVE" })],
13
    }),
14
  ],
15
  providers: [
16
    {
17
      provide: APP_GUARD,
18
      useClass: ArcjetGuard,
19
    },
20
  ],
21
})
22
export class AppModule {}

ARCJET_KEY is not read implicitly; pass it into forRoot. A global ArcjetGuard calls protect() for you. You do not see the ArcjetDecision unless you inject ARCJET and call protect() in the controller.

How do you add per-route rules?

@WithArcjetRules overlays rules on the root client for that controller. Keep ArcjetGuard on the controller if you are not using a global guard.

1
import { Controller, Get, UseGuards } from "@nestjs/common";
2
import {
3
  ArcjetGuard,
4
  WithArcjetRules,
5
  detectBot,
6
  fixedWindow,
7
} from "@arcjet/nest";
8

9
@Controller("login")
10
@UseGuards(ArcjetGuard)
11
@WithArcjetRules([
12
  detectBot({
13
    mode: "LIVE",
14
    allow: [],
15
  }),
16
  fixedWindow({
17
    mode: "LIVE",
18
    window: "10m",
19
    max: 5,
20
  }),
21
])
22
export class LoginController {
23
  @Get()
24
  ready() {
25
    return { ok: true };
26
  }
27
}

allow: [] denies every detected bot. On a public page, allow crawlers you want:

1
detectBot({
2
  mode: "LIVE",
3
  allow: ["CATEGORY:SEARCH_ENGINE"],
4
});

Token-bucket and sliding-window constructors work the same way as in the other Arcjet SDKs. Use a tighter window on login and password reset than on a public GET.

When do you call protect() yourself?

Use a guard when a deny should become a generic 403 or 429 and you do not need the decision in the handler. Call protect() in the controller when you need the reason, IP analysis, or custom status bodies.

1
import { ARCJET, type ArcjetNest, detectBot } from "@arcjet/nest";
2
import {
3
  Controller,
4
  Get,
5
  HttpException,
6
  HttpStatus,
7
  Inject,
8
  Req,
9
} from "@nestjs/common";
10
import type { Request } from "express";
11

12
@Controller("page")
13
export class PageController {
14
  constructor(@Inject(ARCJET) private readonly arcjet: ArcjetNest) {}
15

16
  @Get()
17
  async index(@Req() req: Request) {
18
    const decision = await this.arcjet
19
      .withRule(
20
        detectBot({
21
          mode: "LIVE",
22
          allow: [],
23
        }),
24
      )
25
      .protect(req);
26

27
    if (decision.isDenied()) {
28
      if (decision.reason.isRateLimit()) {
29
        throw new HttpException(
30
          "Too many requests",
31
          HttpStatus.TOO_MANY_REQUESTS,
32
        );
33
      }
34
      if (decision.reason.isBot()) {
35
        throw new HttpException("No bots allowed", HttpStatus.FORBIDDEN);
36
      }
37
      throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
38
    }
39

40
    return { message: "Hello" };
41
  }
42
}

On ERROR results, decide per route whether to fail open (log and continue) or fail closed (503). Fail closed on login and payment.

protect() accepts the Express or Fastify request object Nest already injected. Do not pass a plain object you built yourself unless it has the headers and IP the SDK expects. If Nest sits behind a load balancer, set proxies on ArcjetModule.forRoot so fingerprints use the client address.

A global guard cannot take per-request options such as ipSrc or metadata. Use a controller-level protect() call when you already trust a client IP from your own proxy parser.

What NestJS security work sits outside Arcjet?

Guards and rules do not replace:

• Validation pipes (ValidationPipe with whitelist: true) on every DTO
• Authentication (Auth.js, Passport, or your session) and object-level authorization
• Helmet (or equivalent) for security headers
• Parameterized queries and least-privilege database roles
• CSRF protection on cookie-authenticated browser POSTs

Enable ValidationPipe globally with whitelist: true and forbidNonWhitelisted: true so undeclared DTO fields are dropped or rejected. Helmet belongs in main.ts (app.use(helmet())) for Express. Cookie-authenticated browser POSTs still need a CSRF strategy; an API that uses only bearer tokens does not.

Centralize those in modules the same way you centralize ArcjetModule. A controller that skips the validation pipe is an unvalidated endpoint, even if Shield runs. Exception filters should return generic bodies to clients and keep stack traces in the Nest logger.

How do you log NestJS and Arcjet together?

Implement LoggerService and pass it as log to ArcjetModule.forRoot so SDK lines go through Logger. When you call protect() yourself, log decision.id, decision.conclusion, and the reason flags. Do not log passwords or tokens.

Use DRY_RUN on a new rule, iterate decision.results, and only then switch to LIVE.

What should you do next?

Protect login and signup with the 5-per-10-minute window and an empty bot allow list from secure login pages. Then apply the same habit to every costly route on the web app security checklist.