Getting Started

Getting Started

Get up and running with Vercel Doorman in just a few minutes.

Installation

Install Vercel Doorman using your preferred package manager:

# npm
npm install vercel-doorman

# yarn
yarn add vercel-doorman

# pnpm
pnpm add vercel-doorman

# bun
bun add vercel-doorman

Doorman 2.0 Preview: Cloudflare WAF support ships with Doorman 2.0. Install the CLI today and you'll be able to target --provider cloudflare as soon as the release is live.

Existing Projects

If you have an existing Vercel project with firewall rules, start by using the download command to set up your local configuration:

npx vercel-doorman download

This generates a vercel-firewall.config.json file with your existing configuration. When Cloudflare support lands, run npx vercel-doorman download --provider cloudflare to pull your Cloudflare WAF configuration into the same project.

Basic Usage

1. Create a Configuration File

Ensure you have a vercel-firewall.config.json file in your project root:

{
  "projectId": "prj_",
  "teamId": "team_",
  "rules": [],
  "ips": []
}

Replace prj_ and team_ with your actual projectId and teamId from Vercel.

2. Add Firewall Rules

You can add rules in two ways:

Using Templates

Use the template command to add predefined rules:

# List available templates
npx vercel-doorman template

# Add WordPress protection
npx vercel-doorman template wordpress

# Block AI bots
npx vercel-doorman template ai-bots

Manual Configuration

Add rules directly to your config file:

{
  "name": "Block API Access",
  "description": "Block access to API endpoints",
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "path",
          "op": "pre",
          "value": "/api"
        }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "deny",
      "rateLimit": {
        "requests": 100,
        "window": "1m"
      },
      "actionDuration": "1h"
    }
  },
  "active": true
}

Rule Components

• Condition Groups — Define when rules trigger (AND within groups, OR between groups)
• Conditions — Match criteria using type, op, and value
• Actions — Define response (deny, challenge, rateLimit, rewrite)
• Metadata — Rule information (name, description, active)

For more examples and templates, visit the examples folder on GitHub.

3. Sync Your Rules

npx vercel-doorman sync --token YOUR_VERCEL_API_TOKEN

This applies your firewall rules to your Vercel project. Learn how to create and use a Vercel API token.

4. Add Script Aliases (Optional)

Add convenience scripts to your package.json:

{
  "scripts": {
    "firewall:list": "vercel-doorman list",
    "firewall:download": "vercel-doorman download",
    "firewall:sync": "vercel-doorman sync",
    "firewall:validate": "vercel-doorman validate"
  }
}

Now you can run npm run firewall:sync to apply your firewall rules.

Environment Variables

Variables can be provided through a .env file, shell exports, or CI/CD environment settings:

VERCEL_TOKEN=your_vercel_api_token
VERCEL_PROJECT_ID=your_project_id
VERCEL_TEAM_ID=your_team_id

Important: Add .env to your .gitignore to prevent committing secrets.

Next Steps

• Configuration — Deep dive into the configuration format
• Commands Overview — Full reference for all CLI commands
• Examples — Real-world configuration examples
• Templates — Pre-built rule templates