@appwarden/middleware

--- name: appwarden-middleware-cloudflare-workflow description: > Deploy @appwarden/middleware as a standalone Cloudflare Worker using the deploy-appwarden.yml GitHub Actions workflow. The Worker mounts on a wildcard route (e.g. *your.app/*) to intercept all HTML traffic. Covers workflow triggers, required variables/secrets, and the build/deploy steps. Load this skill when a user is on Cloudflare but not using a supported framework adapter. metadata: type: framework library: "@appwarden/middleware" library_version: "3.16.3" requires: - "appwarden-middleware-get-started" sources: - "appwarden/appwarden-core-b:websites/appwarden-io/docs/snippets/TEMPLATE--deploy-appwarden.yml" - "appwarden/middleware:src/bundles/cloudflare.ts" - "appwarden/middleware:src/runners/appwarden-on-cloudflare.ts" --- # Appwarden Middleware — Standalone Cloudflare Workflow Use this approach when the application is on Cloudflare but not using a supported framework adapter (Astro, React Router, TanStack Start, or Next.js). The Appwarden middleware is deployed as a standalone Worker that sits in front of your application via a route. ## Setup 1. In the domain configuration repository, create `.github/workflows/deploy-appwarden.yml` from the template. 2. Set the required variables and secrets in the repository. 3. Trigger the workflow to build and deploy the middleware. ## Core Patterns ### Deployment model The standalone Cloudflare middleware is deployed as a Worker through the `deploy-appwarden.yml` GitHub Actions workflow. It mounts on the wildcard entrypoint of your domain, for example `*your.app/*`, so it can intercept all HTML traffic before it reaches the origin. The Worker entrypoint is generated by the build action in `.appwarden/generated-middleware` and does not need to be committed to the application repository. ### deploy-appwarden.yml workflow ```yaml name: 🤖 Deploy Appwarden on Cloudflare on: workflow_dispatch: # release: # types: [published] # push: # branches: [main] env: CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }} APPWARDEN_API_TOKEN: ${{ secrets.APPWARDEN_API_TOKEN }} CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} jobs: build: name: Build @appwarden/middleware runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - uses: pnpm/action-setup@v4 - run: pnpm install - name: Build @appwarden/middleware id: build uses: appwarden/build-cloudflare-action@v3 with: debug: true cloudflare-account-id: ${{ env.CLOUDFLARE_ACCOUNT_ID }} appwarden-api-token: ${{ env.APPWARDEN_API_TOKEN }} - name: Deploy to Cloudflare uses: cloudflare/wrangler-action@v4.0.0 env: APPWARDEN_API_TOKEN: ${{ env.APPWARDEN_API_TOKEN }} with: packageManager: pnpm workingDirectory: .appwarden/generated-middleware environment: production accountId: ${{ env.CLOUDFLARE_ACCOUNT_ID }} apiToken: ${{ env.CLOUDFLARE_API_TOKEN }} secrets: | APPWARDEN_API_TOKEN ``` ### Required variables and secrets - `CLOUDFLARE_ACCOUNT_ID`: repository variable (not a secret). Account IDs are not sensitive. - `CLOUDFLARE_API_TOKEN`: repository secret with Worker permissions. - `APPWARDEN_API_TOKEN`: repository secret created in the Appwarden dashboard. ### Monitoring and versioning After deployment, view live logs with the Wrangler CLI: ```bash wrangler tail appwarden-production ``` You can also inspect the Worker in the Cloudflare dashboard under Workers & Pages > appwarden-production. The Appwarden middleware version is automatically managed to the latest stable version by the `appwarden/build-cloudflare-action` build step. You do not need to pin or manually update the middleware package in the domain configuration repository. ### Trigger the workflow The default trigger is `workflow_dispatch`. Uncomment `release` or `push` to deploy automatically on releases or main-branch pushes. ## Common Mistakes ### CRITICAL Forgetting the build step before deploying Wrong: ```yaml # Only a deploy job is present ``` Correct: ```yaml jobs: build: steps: - uses: appwarden/build-cloudflare-action@v3 ``` The build step produces `.appwarden/generated-middleware`. Skipping it leaves nothing for the deploy step to deploy. ### MEDIUM Setting CLOUDFLARE_ACCOUNT_ID as a secret instead of a repository variable Wrong: ```yaml CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` Correct: ```yaml CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }} ``` Account IDs are not secrets. The template expects them as repository variables. ### MEDIUM Using the wrong packageManager in the deploy step Wrong: ```yaml with: packageManager: npm # but the project uses pnpm ``` Correct: ```yaml with: packageManager: pnpm ``` The `wrangler-action` deploy step installs dependencies inside `.appwarden/generated-middleware`. The package manager must match what the generated middleware expects. ### CRITICAL Deploying from the wrong workingDirectory Wrong: ```yaml # workingDirectory omitted or set to repository root ``` Correct: ```yaml with: workingDirectory: .appwarden/generated-middleware ``` The build action outputs the generated middleware to `.appwarden/generated-middleware`. The deploy step must use that exact directory. ### CRITICAL Missing CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID Wrong: ```text # Only APPWARDEN_API_TOKEN is set ``` Correct: ```text # Set CLOUDFLARE_ACCOUNT_ID as a variable # Set CLOUDFLARE_API_TOKEN (with Workers permissions) and APPWARDEN_API_TOKEN as secrets ``` The workflow needs both Cloudflare credentials to deploy and the Appwarden token to function at runtime. ### HIGH Passing APPWARDEN_API_TOKEN to the build step but not uploading it to the Worker Wrong: ```yaml # Build step has the token, but deploy step does not list secrets ``` Correct: ```yaml - uses: cloudflare/wrangler-action@v4.0.0 env: APPWARDEN_API_TOKEN: ${{ env.APPWARDEN_API_TOKEN }} with: secrets: | APPWARDEN_API_TOKEN ``` The token must be available to the build action and uploaded as a Worker secret by the deploy step. ### MEDIUM Expecting CSP changes to apply without redeploying the workflow Wrong: ```text // Merge a domain config PR and expect CSP changes immediately ``` Correct: ```text // Merge the PR, then trigger deploy-appwarden.yml ``` The universal middleware reads CSP from the domain configuration file at deploy time. After merging a CSP change, the workflow must run again. ## Next Steps - To verify the deployment, see `appwarden-middleware-verify-setup`. - To use a framework adapter instead, see `appwarden-middleware-cloudflare-adapters`.