Snippets Configuration Guide

Configuration Methods

1. Dashboard (GUI)

Best for: Quick tests, single snippets, visual rule building

1. Go to zone → Rules → Snippets
2. Click "Create Snippet" or select template
3. Enter snippet name (a-z, 0-9, _ only, cannot change later)
4. Write JavaScript code (32KB max)
5. Configure snippet rule:
   - Expression Builder (visual) or Expression Editor (text)
   - Use Ruleset Engine filter expressions
6. Test with Preview/HTTP tabs
7. Deploy or Save as Draft

2. REST API

Best for: CI/CD, automation, programmatic management

# Create/update snippet
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --form "files=@example.js" \
  --form "metadata={\"main_module\": \"example.js\"}"

# Create snippet rule
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/snippet_rules" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [
      {
        "description": "Trigger snippet on /api paths",
        "enabled": true,
        "expression": "starts_with(http.request.uri.path, \"/api/\")",
        "snippet_name": "api_snippet"
      }
    ]
  }'

# List snippets
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Delete snippet
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

3. Terraform

Best for: Infrastructure-as-code, multi-zone deployments

# Configure Terraform provider
terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

provider "cloudflare" {
  api_token = var.cloudflare_api_token
}

# Create snippet
resource "cloudflare_snippet" "security_headers" {
  zone_id = var.zone_id
  name    = "security_headers"
  
  main_module = "security_headers.js"
  files {
    name    = "security_headers.js"
    content = file("${path.module}/snippets/security_headers.js")
  }
}

# Create snippet rule
resource "cloudflare_snippet_rules" "security_rules" {
  zone_id = var.zone_id
  
  rules {
    description  = "Apply security headers to all requests"
    enabled      = true
    expression   = "true"
    snippet_name = cloudflare_snippet.security_headers.name
  }
}

4. Pulumi

Best for: Multi-cloud IaC, TypeScript/Python/Go workflows

import * as cloudflare from "@pulumi/cloudflare";
import * as fs from "fs";

// Create snippet
const securitySnippet = new cloudflare.Snippet("security-headers", {
  zoneId: zoneId,
  name: "security_headers",
  mainModule: "security_headers.js",
  files: [{
    name: "security_headers.js",
    content: fs.readFileSync("./snippets/security_headers.js", "utf8"),
  }],
});

// Create snippet rule
const snippetRule = new cloudflare.SnippetRules("security-rules", {
  zoneId: zoneId,
  rules: [{
    description: "Apply security headers",
    enabled: true,
    expression: "true",
    snippetName: securitySnippet.name,
  }],
});

Filter Expressions

Snippets use Cloudflare's Ruleset Engine expression language to determine when to execute.

Common Expression Patterns

// Host matching
http.host eq "example.com"
http.host in {"example.com" "www.example.com"}
http.host contains "example"

// Path matching
http.request.uri.path eq "/api/users"
starts_with(http.request.uri.path, "/api/")
ends_with(http.request.uri.path, ".json")
matches(http.request.uri.path, "^/api/v[0-9]+/")

// Query parameters
http.request.uri.query contains "debug=true"

// Headers
http.headers["user-agent"] contains "Mobile"
http.headers["accept-language"] eq "en-US"

// Cookies
http.cookie contains "session="

// Geolocation
ip.geoip.country eq "US"
ip.geoip.continent eq "EU"

// Bot detection (requires Bot Management)
cf.bot_management.score lt 30

// Method
http.request.method eq "POST"
http.request.method in {"POST" "PUT" "PATCH"}

// Combine with logical operators
http.host eq "example.com" and starts_with(http.request.uri.path, "/api/")
ip.geoip.country eq "US" or ip.geoip.country eq "CA"
not http.headers["user-agent"] contains "bot"

Expression Functions

Function	Example	Description
`starts_with()`	`starts_with(http.request.uri.path, "/api/")`	Check prefix
`ends_with()`	`ends_with(http.request.uri.path, ".json")`	Check suffix
`contains()`	`contains(http.headers["user-agent"], "Mobile")`	Check substring
`matches()`	`matches(http.request.uri.path, "^/api/")`	Regex match
`lower()`	`lower(http.host) eq "example.com"`	Convert to lowercase
`upper()`	`upper(http.headers["x-api-key"])`	Convert to uppercase
`len()`	`len(http.request.uri.path) gt 100`	String length

Deployment Workflow

Development

Write snippet code locally
Test syntax with node snippet.js or TypeScript compiler
Deploy to Dashboard or use API with Save as Draft
Test with Preview/HTTP tabs in Dashboard
Enable rule when ready

Production

Store snippet code in version control
Use Terraform/Pulumi for reproducible deployments
Deploy to staging zone first
Test with real traffic (use low-traffic subdomain)
Apply to production zone
Monitor with Analytics/Logpush

Limits & Requirements

Resource	Limit	Notes
Snippet size	32 KB	Per snippet, compressed
Snippet name	64 chars	`a-z`, `0-9`, `_` only, immutable
Snippets per zone	20	Soft limit, contact support for more
Rules per zone	20	One rule per snippet typical
Expression length	4096 chars	Per rule expression

Authentication

API Token (Recommended)

# Create token at: https://dash.cloudflare.com/profile/api-tokens
# Required permissions: Zone.Snippets:Edit, Zone.Rules:Edit
export CLOUDFLARE_API_TOKEN="your_token_here"

API Key (Legacy)

export CLOUDFLARE_EMAIL="your@email.com"
export CLOUDFLARE_API_KEY="your_global_api_key"

6.2 KiB Raw Permalink Blame History