1# Snippets Configuration Guide
2 
3## Configuration Methods
4 
5### 1. Dashboard (GUI)
6**Best for**: Quick tests, single snippets, visual rule building
7 
8```
91. Go to zone → Rules → Snippets
102. Click "Create Snippet" or select template
113. Enter snippet name (a-z, 0-9, _ only, cannot change later)
124. Write JavaScript code (32KB max)
135. Configure snippet rule:
14   - Expression Builder (visual) or Expression Editor (text)
15   - Use Ruleset Engine filter expressions
166. Test with Preview/HTTP tabs
177. Deploy or Save as Draft
18```
19 
20### 2. REST API
21**Best for**: CI/CD, automation, programmatic management
22 
23```bash
24# Create/update snippet
25curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
26  --request PUT \
27  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
28  --form "[email protected]" \
29  --form "metadata={\"main_module\": \"example.js\"}"
30 
31# Create snippet rule
32curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/snippet_rules" \
33  --request PUT \
34  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
35  --header "Content-Type: application/json" \
36  --data '{
37    "rules": [
38      {
39        "description": "Trigger snippet on /api paths",
40        "enabled": true,
41        "expression": "starts_with(http.request.uri.path, \"/api/\")",
42        "snippet_name": "api_snippet"
43      }
44    ]
45  }'
46 
47# List snippets
48curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets" \
49  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
50 
51# Delete snippet
52curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
53  --request DELETE \
54  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
55```
56 
57### 3. Terraform
58**Best for**: Infrastructure-as-code, multi-zone deployments
59 
60```hcl
61# Configure Terraform provider
62terraform {
63  required_providers {
64    cloudflare = {
65      source  = "cloudflare/cloudflare"
66      version = "~> 4.0"
67    }
68  }
69}
70 
71provider "cloudflare" {
72  api_token = var.cloudflare_api_token
73}
74 
75# Create snippet
76resource "cloudflare_snippet" "security_headers" {
77  zone_id = var.zone_id
78  name    = "security_headers"
79  
80  main_module = "security_headers.js"
81  files {
82    name    = "security_headers.js"
83    content = file("${path.module}/snippets/security_headers.js")
84  }
85}
86 
87# Create snippet rule
88resource "cloudflare_snippet_rules" "security_rules" {
89  zone_id = var.zone_id
90  
91  rules {
92    description  = "Apply security headers to all requests"
93    enabled      = true
94    expression   = "true"
95    snippet_name = cloudflare_snippet.security_headers.name
96  }
97}
98```
99 
100### 4. Pulumi
101**Best for**: Multi-cloud IaC, TypeScript/Python/Go workflows
102 
103```typescript
104import * as cloudflare from "@pulumi/cloudflare";
105import * as fs from "fs";
106 
107// Create snippet
108const securitySnippet = new cloudflare.Snippet("security-headers", {
109  zoneId: zoneId,
110  name: "security_headers",
111  mainModule: "security_headers.js",
112  files: [{
113    name: "security_headers.js",
114    content: fs.readFileSync("./snippets/security_headers.js", "utf8"),
115  }],
116});
117 
118// Create snippet rule
119const snippetRule = new cloudflare.SnippetRules("security-rules", {
120  zoneId: zoneId,
121  rules: [{
122    description: "Apply security headers",
123    enabled: true,
124    expression: "true",
125    snippetName: securitySnippet.name,
126  }],
127});
128```
129 
130## Filter Expressions
131 
132Snippets use Cloudflare's Ruleset Engine expression language to determine when to execute.
133 
134### Common Expression Patterns
135 
136```javascript
137// Host matching
138http.host eq "example.com"
139http.host in {"example.com" "www.example.com"}
140http.host contains "example"
141 
142// Path matching
143http.request.uri.path eq "/api/users"
144starts_with(http.request.uri.path, "/api/")
145ends_with(http.request.uri.path, ".json")
146matches(http.request.uri.path, "^/api/v[0-9]+/")
147 
148// Query parameters
149http.request.uri.query contains "debug=true"
150 
151// Headers
152http.headers["user-agent"] contains "Mobile"
153http.headers["accept-language"] eq "en-US"
154 
155// Cookies
156http.cookie contains "session="
157 
158// Geolocation
159ip.geoip.country eq "US"
160ip.geoip.continent eq "EU"
161 
162// Bot detection (requires Bot Management)
163cf.bot_management.score lt 30
164 
165// Method
166http.request.method eq "POST"
167http.request.method in {"POST" "PUT" "PATCH"}
168 
169// Combine with logical operators
170http.host eq "example.com" and starts_with(http.request.uri.path, "/api/")
171ip.geoip.country eq "US" or ip.geoip.country eq "CA"
172not http.headers["user-agent"] contains "bot"
173```
174 
175### Expression Functions
176 
177| Function | Example | Description |
178|----------|---------|-------------|
179| `starts_with()` | `starts_with(http.request.uri.path, "/api/")` | Check prefix |
180| `ends_with()` | `ends_with(http.request.uri.path, ".json")` | Check suffix |
181| `contains()` | `contains(http.headers["user-agent"], "Mobile")` | Check substring |
182| `matches()` | `matches(http.request.uri.path, "^/api/")` | Regex match |
183| `lower()` | `lower(http.host) eq "example.com"` | Convert to lowercase |
184| `upper()` | `upper(http.headers["x-api-key"])` | Convert to uppercase |
185| `len()` | `len(http.request.uri.path) gt 100` | String length |
186 
187## Deployment Workflow
188 
189### Development
1901. Write snippet code locally
1912. Test syntax with `node snippet.js` or TypeScript compiler
1923. Deploy to Dashboard or use API with `Save as Draft`
1934. Test with Preview/HTTP tabs in Dashboard
1945. Enable rule when ready
195 
196### Production
1971. Store snippet code in version control
1982. Use Terraform/Pulumi for reproducible deployments
1993. Deploy to staging zone first
2004. Test with real traffic (use low-traffic subdomain)
2015. Apply to production zone
2026. Monitor with Analytics/Logpush
203 
204## Limits & Requirements
205 
206| Resource | Limit | Notes |
207|----------|-------|-------|
208| Snippet size | 32 KB | Per snippet, compressed |
209| Snippet name | 64 chars | `a-z`, `0-9`, `_` only, immutable |
210| Snippets per zone | 20 | Soft limit, contact support for more |
211| Rules per zone | 20 | One rule per snippet typical |
212| Expression length | 4096 chars | Per rule expression |
213 
214## Authentication
215 
216### API Token (Recommended)
217```bash
218# Create token at: https://dash.cloudflare.com/profile/api-tokens
219# Required permissions: Zone.Snippets:Edit, Zone.Rules:Edit
220export CLOUDFLARE_API_TOKEN="your_token_here"
221```
222 
223### API Key (Legacy)
224```bash
225export CLOUDFLARE_EMAIL="[email protected]"
226export CLOUDFLARE_API_KEY="your_global_api_key"
227```