Protect your Cloudflare project with Appwarden

Overview

To secure your domain against an in-progress attack, add the Appwarden middleware to your Cloudflare project. When you issue the /quarantine lock command from Discord, Appwarden will quarantine your website and redirect users to your lock page.

Prevent users from reaching your website with a single command

Appwarden supports any orange clouded website on Cloudflare. This guide helps you choose the right integration approach for your project.

Appwarden middleware runs on every request to your website and may incur additional usage-based charges. Cloudflare has an affordable pricing model, but be sure to review it before proceeding.

Choosing a deployment strategy

The universal middleware is the recommended approach for all Cloudflare deployments. It deploys as a single Cloudflare Worker with no code changes required to your application.

Universal

The universal middleware works with all Cloudflare projects. This deployment strategy:

Seamlessly synchronizes with Appwarden configuration — Appwarden configuration is synchronized with your domain configuration repository, so all Appwarden configuration is managed in a single place.
Active security patching — Always deploys the latest security patches and updates.
Pick your deployment strategy — Deploy Appwarden at application build time or on demand.

💡

Learn how to install the Appwarden universal middleware on Cloudflare.

Framework-specific adapters (fallback)

Only use a framework-specific adapter if the universal middleware is not compatible with your project. The universal middleware is the recommended approach unless your architecture prevents you from using it.

If the universal middleware is not compatible with your project, you can use a framework-specific adapter that integrates Appwarden into your framework’s middleware system.

This approach:

Runs as middleware in your application — Appwarden runs as part of your application framework
Single deployment — deploy Appwarden together with your application
Some frameworks may not be compatible with all of the features offered by the universal middleware. Check the framework-specific guide for more information.

See the framework-specific guides:

Astro on Cloudflare Workers
React Router on Cloudflare Workers
TanStack Start on Cloudflare Workers
Next.js on Cloudflare Workers

Universal Middleware

This section covers deploying the universal Appwarden middleware. The universal middleware deploys as a Cloudflare Workers service that services requests to Appwarden-configured domains via Worker Routes.

How the middleware works

Deploys the most up-to-date version of Appwarden at project build time

The action automatically deploys the most up-to-date version of Appwarden to Cloudflare. Your middleware stays current with the latest security features and improvements.

The GitHub Actions workflow deploys the latest version of `appwarden-production` to Cloudflare

Configuration management

Your middleware configuration is automatically applied from the domain configuration file. Simply manage your domain configuration and the action handles the rest.

Full CSP support

This middleware fully supports Appwarden’s nonce-based Content Security Policy (CSP) functionality, enabling robust protection against browser-based attacks while maintaining compatibility with your application.

Routing behavior

The action builds a single Cloudflare Worker script that runs on every request to the hostnames listed in the middleware section of your domain configuration files.

For example, given this domain configuration:

1
hostname: appwarden.cc
2
version: 1
3
websites:
4
  middleware:
5
    - url: appwarden.cc
6
      options:
7
        lock-page-slug: /maintenance
8
        csp-mode: report-only
9
        csp-directives:
10
          script-src:
11
            - "self"
12
            - "{{nonce}}"
13
    - url: tanstack.appwarden.cc
14
      options:
15
        lock-page-slug: /maintenance
16
        csp-mode: enforced
17
        csp-directives:
18
          img-src:
19
            - "self"

The deployed Cloudflare Workers service will include a route for each configured hostname:

Cloudflare Workers routes on `appwarden-production` for Appwarden-configured hostnames

Prerequisites

Before proceeding, ensure you have:

A domain proxied through Cloudflare (orange-clouded)
A GitHub project repository or domain configuration repository
Your Appwarden API token
Your Cloudflare Account ID and API token

Deployment

We recommend deploying Appwarden middleware via GitHub Actions to have fine-grained control over your deployment strategy. The deployment workflow template is available in the domain configuration repository.

1. Set up the GitHub Actions workflow

Choose whether to deploy Appwarden from your domain configuration repository (e.g. when you update your domain configuration) or your project repository (e.g. when you release a new version of your project).

You may combine your domain configuration repository into your project repository to manage your Appwarden configuration and project together by adding a .appwarden directory to your project repository and updating your Settings > GitHub > Domain Configuration Repository in the Appwarden dashboard.

In the chosen repository, create a GitHub Actions workflow file at .github/workflows/deploy-appwarden-middleware.yml with the content below.

2. Configure the workflow

Follow the emoji action item instructions (e.g. 1️⃣) in the workflow file above:

To set CLOUDFLARE_ACCOUNT_ID, navigate to Cloudflare Dashboard > Your Account > Workers and copy the Account ID from the sidebar
To set APPWARDEN_API_TOKEN, refer to the API token management guide
To set CLOUDFLARE_API_TOKEN, create an API token in your Cloudflare dashboard with Worker permissions

3. Deploy the workflow

Push the modified workflow file to your repository
In your repository Actions tab, run the workflow using the workflow_dispatch trigger and ensure the workflow runs successfully
- If the job failed, inspect the logs to identify the issue. Feel free to reach out in our community for assistance

Inspect your logs to identify and resolve any errors from the GitHub Actions workflow

If you enabled a on push or on release trigger in 1️⃣ above, push a change to the target branch or create a release to ensure the workflow succeeds
Ensure the middleware is deployed by navigating to Cloudflare Dashboard > Your Account > Your Domain > Worker Routes and checking the appwarden-production script is associated with the *your.app/* route

Finishing up

After deploying your project, navigate to your Cloudflare Dashboard > Workers & Pages > appwarden-production > Logs for error messages from @appwarden/middleware after refreshing the website repeatedly. Inspect any errors and adjust your environment before redeploying your project until all errors are resolved.

Once any errors are resolved, issue the /quarantine test command in Discord. Then, navigate to your.app/_appwarden/test in your browser. If the lock page appears (may take up to 30 seconds), Appwarden is correctly installed in your web project. You may re-issue the test command to unlock your test page.

🎉

Congratulations — Appwarden is protecting your domain! In the event of a security breach, you can now issue the /quarantine lock command in Discord to quarantine your website within seconds, protecting your users while the problem is resolved.

Framework-Specific Adapters

If the universal middleware is not compatible with your project, you can use a framework-specific adapter that integrates Appwarden into your framework’s middleware system. The following sections provide detailed integration guides for each supported framework.

Astro on Cloudflare Workers

This section covers integrating Appwarden with Astro projects deployed to Cloudflare Workers. Appwarden integrates as native Astro middleware by running before your routes to protect your site.

This guide applies to server-rendered (SSR) Astro projects using the @astrojs/cloudflare adapter. For static Astro sites, see the Universal Middleware section.

Prerequisites

Before proceeding, ensure you have:

An Astro project with SSR enabled (output: "server" or output: "hybrid")
The @astrojs/cloudflare adapter installed and configured
Your Appwarden API token

Installation

Install the Appwarden middleware package:

1
npm install @appwarden/middleware
2
# or
3
pnpm add @appwarden/middleware
4
# or
5
yarn add @appwarden/middleware

Configuration

1. Create Astro middleware

Create (or update) your Astro middleware file at src/middleware.ts:

1
import { sequence } from "astro:middleware"
2
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare/astro"
3

4
const appwarden = createAppwardenMiddleware((cloudflare) => ({
5
  lockPageSlug: cloudflare.env.APPWARDEN_LOCK_PAGE_SLUG,
6
  appwardenApiToken: cloudflare.env.APPWARDEN_API_TOKEN,
7
  debug: cloudflare.env.DEBUG,
8
  contentSecurityPolicy: {
9
    // See [Configuration > contentSecurityPolicy](https://appwarden.io/docs/reference/appwarden-middleware#contentsecuritypolicy) section for details
10
  },
11
}))
12

13
export const onRequest = sequence(appwarden)

The cloudflare parameter provides access to Cloudflare’s environment via cloudflare.env and execution context via cloudflare.ctx. This is the same runtime available in context.locals.runtime in your Astro pages.

2. Create a maintenance page

Create a page that will be shown when your site is quarantined:

1
---
2
// This page is shown when your site is quarantined
3
---
4
<html lang="en">
5
  <head>
6
    <meta charset="utf-8" />
7
    <meta name="viewport" content="width=device-width" />
8
    <title>Site Under Maintenance</title>
9
  </head>
10
  <body>
11
    <main>
12
      <h1>Site Under Maintenance</h1>
13
      <p>We're performing scheduled maintenance. Please check back soon.</p>
14
    </main>
15
  </body>
16
</html>

3. Configure Astro for Cloudflare

Ensure your astro.config.mjs is configured for Cloudflare:

1
import { defineConfig } from "astro/config"
2
import cloudflare from "@astrojs/cloudflare"
3

4
export default defineConfig({
5
  output: "server",
6
  adapter: cloudflare(),
7
})

4. Set environment variables

Create a .dev.vars file for local development:

1
APPWARDEN_API_TOKEN=your-api-token-here
2
APPWARDEN_LOCK_PAGE_SLUG=/maintenance

For production, set APPWARDEN_LOCK_PAGE_SLUG in your wrangler.toml and APPWARDEN_API_TOKEN via wrangler secret:

1
wrangler secret put APPWARDEN_API_TOKEN

Local Development

Test locally with the Astro dev server:

1
npm run dev

The Astro dev server with the Cloudflare adapter provides access to Cloudflare bindings via wrangler. Ensure you have a wrangler.jsonc or wrangler.toml file in your project root.

Deployment

Deploy your project to Cloudflare:

1
wrangler deploy

Finishing up

After deploying, navigate to your Cloudflare Dashboard > Workers & Pages > your-project > Logs to check for any error messages from @appwarden/middleware.

🎉

Congratulations — Appwarden is protecting your Astro site! In the event of a security breach, you can now issue the /quarantine lock command in Discord to quarantine your website within seconds.

React Router on Cloudflare Workers

This section covers integrating Appwarden with React Router v7 (formerly Remix) projects deployed to Cloudflare Workers. Appwarden integrates as native React Router middleware, running before your loaders and actions to protect your site.

Prerequisites

Before proceeding, ensure you have:

A React Router v7 project configured for Cloudflare Workers
React Router’s middleware feature enabled (see React Router middleware docs)
Your Appwarden API token

Installation

Install the Appwarden middleware package:

1
npm install @appwarden/middleware
2
# or
3
pnpm install @appwarden/middleware
4
# or
5
yarn add @appwarden/middleware

Configuration

1. Enable middleware in React Router config

React Router’s middleware feature requires the v8_middleware future flag. Add this to your react-router.config.ts:

1
import type { Config } from "@react-router/dev/config"
2

3
export default {
4
  ssr: true,
5
  future: {
6
    v8_middleware: true,
7
  },
8
} satisfies Config

Without the v8_middleware flag, React Router will silently ignore your middleware exports and Appwarden will not run.

2. Add middleware to your root route

Add Appwarden middleware to your root route file (app/root.tsx). React Router middleware executes hierarchically from parent to child, so middleware on the root route automatically runs for every nested route in your application:

1
import { env } from "cloudflare:workers"
2
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare/react-router"
3

4
export const middleware = [
5
  createAppwardenMiddleware(() => ({
6
    lockPageSlug: env.APPWARDEN_LOCK_PAGE_SLUG,
7
    appwardenApiToken: env.APPWARDEN_API_TOKEN,
8
    // "debug" can be a string or boolean; the schema will normalize it
9
    debug: env.DEBUG,
10
    // "directives" can be a JSON string or an object; the schema will parse it
11
    contentSecurityPolicy: {
12
      // See [Configuration > contentSecurityPolicy](https://appwarden.io/docs/reference/appwarden-middleware#contentsecuritypolicy) section for details
13
    },
14
  })),
15
]

3. Create a maintenance page route

Create a maintenance page that will be shown when your site is locked:

1
export default function MaintenancePage() {
2
  return (
3
    <div className="flex min-h-screen items-center justify-center">
4
      <div className="text-center">
5
        <h1 className="text-4xl font-bold">Site Under Maintenance</h1>
6
        <p className="mt-4 text-gray-600">
7
          We're performing scheduled maintenance. Please check back soon.
8
        </p>
9
      </div>
10
    </div>
11
  )
12
}

4. Set environment variables

Create a .dev.vars file for local development:

1
APPWARDEN_API_TOKEN=your-api-token-here
2
APPWARDEN_LOCK_PAGE_SLUG=/maintenance

For production, set APPWARDEN_LOCK_PAGE_SLUG in your wrangler.toml and APPWARDEN_API_TOKEN via wrangler secret:

1
wrangler secret put APPWARDEN_API_TOKEN

5. Ensure Cloudflare context is passed

Your worker entry file should pass the Cloudflare context to React Router. This is typically already configured if you’re using the Cloudflare template:

1
import { createRequestHandler } from "react-router"
2

3
const requestHandler = createRequestHandler(
4
  () => import("virtual:react-router/server-build"),
5
  import.meta.env.MODE,
6
)
7

8
export default {
9
  async fetch(request, env, ctx) {
10
    return requestHandler(request, {
11
      cloudflare: { env, ctx },
12
    })
13
  },
14
} satisfies ExportedHandler<Env>

Deployment

Deploy your project to Cloudflare:

1
wrangler deploy

Finishing up

After deploying, navigate to your Cloudflare Dashboard > Workers & Pages > your-project > Logs to check for any error messages from @appwarden/middleware.

🎉

Congratulations — Appwarden is protecting your React Router site! In the event of a security breach, you can now issue the /quarantine lock command in Discord to quarantine your website within seconds.

TanStack Start on Cloudflare Workers

This section covers integrating Appwarden with TanStack Start projects deployed to Cloudflare Workers. Appwarden integrates as global request middleware, running before every request to protect your site.

This guide applies to TanStack Start projects. For other websites, see the Universal Middleware section.

Prerequisites

Before proceeding, ensure you have:

A TanStack Start project configured for Cloudflare Workers
Your Appwarden API token

Installation

Install the Appwarden middleware package:

1
npm install @appwarden/middleware
2
# or
3
pnpm add @appwarden/middleware
4
# or
5
yarn add @appwarden/middleware

Configuration

1. Create global middleware

Create (or update) your src/start.ts file to configure global request middleware:

1
import { createMiddleware } from "@tanstack/start"
2
import { env } from "cloudflare:workers"
3
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare/tanstack-start"
4

5
const appwardenMiddleware = createMiddleware().server(
6
  createAppwardenMiddleware(() => ({
7
    lockPageSlug: env.APPWARDEN_LOCK_PAGE_SLUG,
8
    appwardenApiToken: env.APPWARDEN_API_TOKEN,
9
    debug: env.DEBUG, // Accepts string or boolean
10
    contentSecurityPolicy: {
11
      // See [Configuration > contentSecurityPolicy](https://appwarden.io/docs/reference/appwarden-middleware#contentsecuritypolicy) section for details
12
    },
13
  })),
14
)
15

16
export const startInstance = createStart(() => ({
17
  requestMiddleware: [appwardenMiddleware],
18
}))

2. Create a maintenance page

Create a maintenance page that will be shown when your site is locked:

1
import { createFileRoute } from "@tanstack/react-router"
2

3
export const Route = createFileRoute("/maintenance")({
4
  component: MaintenancePage,
5
})
6

7
function MaintenancePage() {
8
  return (
9
    <div className="flex min-h-screen items-center justify-center">
10
      <div className="text-center">
11
        <h1 className="text-4xl font-bold">Site Under Maintenance</h1>
12
        <p className="mt-4 text-gray-600">
13
          We're performing scheduled maintenance. Please check back soon.
14
        </p>
15
      </div>
16
    </div>
17
  )
18
}

3. Set environment variables

Create a .dev.vars file for local development:

1
APPWARDEN_API_TOKEN=your-api-token-here
2
APPWARDEN_LOCK_PAGE_SLUG=/maintenance

For production, set APPWARDEN_LOCK_PAGE_SLUG in your wrangler.toml and APPWARDEN_API_TOKEN via wrangler secret:

1
wrangler secret put APPWARDEN_API_TOKEN

Deployment

Deploy your project to Cloudflare:

1
wrangler deploy

Finishing up

After deploying, navigate to your Cloudflare Dashboard > Workers & Pages > your-project > Logs to check for any error messages from @appwarden/middleware.

🎉

Congratulations — Appwarden is protecting your TanStack Start site! In the event of a security breach, you can now issue the /quarantine lock command in Discord to quarantine your website within seconds.

Next.js on Cloudflare Workers

This section covers integrating Appwarden with Next.js projects deployed to Cloudflare Workers using OpenNext. Appwarden integrates as native Next.js middleware by running before your routes to protect your site.

For Next.js on Vercel, see the Vercel integration guide which uses a simpler middleware approach.

Prerequisites

Before proceeding, ensure you have:

A Next.js project (App Router or Pages Router)
The @opennextjs/cloudflare adapter installed and configured
Your Appwarden API token

Installation

Install the Appwarden middleware package:

1
npm install @appwarden/middleware
2
# or
3
pnpm add @appwarden/middleware
4
# or
5
yarn add @appwarden/middleware

Configuration

1. Create Next.js middleware

Next.js 16+ users: Next.js 16 renamed middleware.ts to proxy.ts. The middleware.ts convention is deprecated in Next.js 16+. See the Next.js 16+ section below for the updated filename.

Create (or update) your middleware file in your project root.

Next.js 15 and earlier (middleware.ts)

Create the file at middleware.ts:

1
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare/nextjs"
2

3
export const config = {
4
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
5
}
6

7
export default createAppwardenMiddleware((cloudflare) => ({
8
  lockPageSlug: cloudflare.env.APPWARDEN_LOCK_PAGE_SLUG,
9
  appwardenApiToken: cloudflare.env.APPWARDEN_API_TOKEN,
10
  debug: cloudflare.env.DEBUG,
11
  // Headers-only CSP (no HTML rewriting, no nonce support; do not use `{{nonce}}` here)
12
  contentSecurityPolicy: {
13
    // See [Configuration > contentSecurityPolicy](https://appwarden.io/docs/reference/appwarden-middleware#contentsecuritypolicy) section for details
14
  },
15
}))

Next.js 16+ (proxy.ts)

In Next.js 16, middleware was renamed to “proxy”. Create the file at proxy.ts:

1
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare/nextjs"
2

3
export const config = {
4
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
5
}
6

7
export default createAppwardenMiddleware((cloudflare) => ({
8
  lockPageSlug: cloudflare.env.APPWARDEN_LOCK_PAGE_SLUG,
9
  appwardenApiToken: cloudflare.env.APPWARDEN_API_TOKEN,
10
  debug: cloudflare.env.DEBUG,
11
  // Headers-only CSP (no HTML rewriting, no nonce support; do not use `{{nonce}}` here)
12
  contentSecurityPolicy: {
13
    // See [Configuration > contentSecurityPolicy](https://appwarden.io/docs/reference/appwarden-middleware#contentsecuritypolicy) section for details
14
  },
15
}))

2. Create a maintenance page

Create a maintenance page that will be shown when your site is locked:

1
export default function MaintenancePage() {
2
  return (
3
    <div className="flex min-h-screen items-center justify-center">
4
      <div className="text-center">
5
        <h1 className="text-4xl font-bold">Site Under Maintenance</h1>
6
        <p className="mt-4 text-gray-600">
7
          We're performing scheduled maintenance. Please check back soon.
8
        </p>
9
      </div>
10
    </div>
11
  )
12
}

3. Configure OpenNext

Ensure your open-next.config.ts is properly configured:

1
import type { OpenNextConfig } from "@opennextjs/cloudflare"
2

3
export default {
4
  // Your OpenNext configuration
5
} satisfies OpenNextConfig

4. Set environment variables

Create a .dev.vars file for local development:

1
APPWARDEN_API_TOKEN=your-api-token-here
2
APPWARDEN_LOCK_PAGE_SLUG=/maintenance

For production, set APPWARDEN_LOCK_PAGE_SLUG in your wrangler.toml and APPWARDEN_API_TOKEN via wrangler secret:

1
wrangler secret put APPWARDEN_API_TOKEN

Deploy

Build your Next.js project with OpenNext and deploy:

1
# Deploy to Cloudflare
2
wrangler deploy

Finishing up

After deploying, navigate to your Cloudflare Dashboard > Workers & Pages > your-project > Logs to check for any error messages from @appwarden/middleware.

🎉

Congratulations — Appwarden is protecting your Next.js site on Cloudflare! In the event of a security breach, you can now issue the /quarantine lock command in Discord to quarantine your website within seconds.

Need help?

If you’re unsure which approach to use, here’s a quick summary:

Deployment Type	Recommendation
Cloudflare Pages (`*.pages.dev`)	Universal Middleware
Orange-clouded domain (external origin)	Universal Middleware
Workers static assets (`wrangler deploy`)	Universal Middleware (recommended) or framework-specific adapter

If you have any questions or need assistance, please don’t hesitate to reach out to us on Discord.