@arcjet/astro

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 integration for Astro.

Getting started

Visit the quick start guide to get started.

Example app

Try an Arcjet protected app live at https://example.arcjet.com (source code).

Installation

npx astro add @arcjet/astro

Usage

If installed via the Astro CLI command above, your astro.config.mjs should be changed like:

  // @ts-check
  import { defineConfig } from "astro/config";
+ import arcjet from "@arcjet/astro";

  // https://astro.build/config
  export default defineConfig({
+   integrations: [
+     arcjet(),
+   ],
  });

However, if installed manually, you'll want to add the above lines to your Astro configuration.

We also recommended validating your environment variables at build time. To do this, update your astro.config.mjs to add the option:

  // @ts-check
  import { defineConfig } from "astro/config";
  import arcjet from "@arcjet/astro";

  // https://astro.build/config
  export default defineConfig({
+   env: {
+     validateSecrets: true
+   },
    integrations: [
      arcjet(),
    ],
  });

Once Arcjet is added as an integration, you'll want to start the Astro dev server to build the arcjet:client virtual module and types. In your terminal, run:

npx astro dev

You can now import from the arcjet:client module within your Astro project!

This example adds Arcjet to your middleware, but note this only works for non-prerendered pages:

// src/middleware.ts
import { defineMiddleware } from "astro:middleware";
import aj from "arcjet:client";

export const onRequest = defineMiddleware(
  async ({ isPrerendered, request }, next) => {
    // Arcjet can be run in your middleware; however, Arcjet can only process a
    // request when the page is NOT prerendered.
    if (!isPrerendered) {
      // console.log(request);
      const decision = await aj.protect(request);

      // Deny decisions respond immediately to avoid any additional server
      // processing.
      if (decision.isDenied()) {
        return new Response(null, { status: 403, statusText: "Forbidden" });
      }
    }

    return next();
  },
);

Rate limit + bot detection example

The Arcjet rate limit example below applies a token bucket rate limit rule to a route where we identify the user based on their ID e.g. if they are logged in. The bucket is configured with a maximum capacity of 10 tokens and refills by 5 tokens every 10 seconds. Each request consumes 5 tokens.

The rule is defined in your astro.config.mjs file:

// @ts-check
import { defineConfig } from "astro/config";
import arcjet, { tokenBucket, detectBot } from "@arcjet/astro";

// https://astro.build/config
export default defineConfig({
  env: {
    validateSecrets: true,
  },
  integrations: [
    arcjet({
      characteristics: ["userId"], // track requests by a custom user ID
      rules: [
        // Create a token bucket rate limit. Other algorithms are supported.
        tokenBucket({
          mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
          refillRate: 5, // refill 5 tokens per interval
          interval: 10, // refill every 10 seconds
          capacity: 10, // bucket maximum capacity of 10 tokens
        }),
        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: [], // "allow none" will block all detected bots
        }),
      ],
    }),
  ],
});

Then Arcjet is called from within this page route:

// src/pages/api.json.ts
import type { APIRoute } from "astro";
import aj from "arcjet:client";

export const GET: APIRoute = async ({ request }) => {
  const userId = "user123"; // Replace with your authenticated user ID
  const decision = await aj.protect(request, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
  console.log("Arcjet decision", decision);

  if (decision.isDenied()) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  } else {
    return Response.json({ message: "Hello world" });
  }
};

Shield example

Arcjet Shield protects your application against common attacks, including the OWASP Top 10. You can run Shield on every request with negligible performance impact.

The rule is defined in your astro.config.mjs file:

// @ts-check
import { defineConfig } from "astro/config";
import arcjet, { shield } from "@arcjet/astro";

// https://astro.build/config
export default defineConfig({
  env: {
    validateSecrets: true,
  },
  integrations: [
    arcjet({
      rules: [
        shield({
          mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
        }),
      ],
    }),
  ],
});

Then Arcjet is called from within this page route:

// src/pages/api.json.ts
import type { APIRoute } from "astro";
import aj from "arcjet:client";

export const GET: APIRoute = async ({ request }) => {
  const decision = await aj.protect(request);

  if (decision.isDenied()) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  } else {
    return Response.json({ message: "Hello world" });
  }
};

License

Licensed under the Apache License, Version 2.0.