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

Tip: Doorman 2.0 supports both Vercel Firewall and Cloudflare WAF. Use --provider cloudflare to target Cloudflare.

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 .doorman.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.

Note: If you have an existing vercel-firewall.config.json, Doorman will still find and use it automatically. The new default filename is .doorman.json but both are supported.

Basic Usage

1. Create a Configuration File

Ensure you have a .doorman.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 several ways:

Using the add Command (Recommended)

The fastest way to add rules from the command line:

# Interactive mode — guided prompts walk you through it
npx vercel-doorman add --interactive

# Inline mode — one-liner for scripting
npx vercel-doorman add --name "Block Admin" --field path --op pre --value "/admin" --action deny

# Add an IP blocking rule
npx vercel-doorman add ip --ip 192.168.1.100/32 --notes "Blocked for abuse"

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