workers-binding-validator
Automatically validates Cloudflare Workers binding configuration, ensuring code references match wrangler.toml setup and TypeScript interfaces are accurate
When & Why to Use This Skill
The Workers Binding Validator is a specialized Claude skill designed to automate the synchronization and validation of Cloudflare Workers configurations. It ensures that resource bindings defined in 'wrangler.toml' perfectly align with TypeScript 'Env' interfaces and actual code references. By performing real-time checks on KV namespaces, R2 buckets, D1 databases, and environment variables, it prevents critical runtime failures and deployment mismatches, significantly improving developer productivity and infrastructure reliability.
Use Cases
- Scenario 1: Validating TypeScript 'Env' interfaces to ensure they accurately reflect the bindings defined in wrangler.toml, maintaining strict type safety across the project.
- Scenario 2: Detecting 'Missing Binding' errors during development when code references a resource (like a KV namespace) that hasn't been added to the configuration file yet.
- Scenario 3: Verifying binding type accuracy to prevent developers from incorrectly treating an R2 bucket as a KV namespace or a D1 database in their code.
- Scenario 4: Auditing security configurations by identifying sensitive secrets that are accidentally placed in the plain-text [vars] section instead of being managed as encrypted secrets.
- Scenario 5: Streamlining local development by ensuring remote binding configurations (remote = true) are correctly set up for testing against live Cloudflare resources.
| name | workers-binding-validator |
|---|---|
| description | Automatically validates Cloudflare Workers binding configuration, ensuring code references match wrangler.toml setup and TypeScript interfaces are accurate |
| triggers | ["env parameter usage", "wrangler.toml changes", "TypeScript interface updates", "binding references"] |
Workers Binding Validator SKILL
Activation Patterns
This SKILL automatically activates when:
envparameter is used in Workers code- wrangler.toml file is modified
- TypeScript
Envinterface is defined or updated - New binding references are added to code
- Binding configuration patterns are detected
Expertise Provided
Binding Configuration Validation
- Binding Consistency: Ensures code references match wrangler.toml configuration
- TypeScript Interface Validation: Validates
Envinterface matches actual bindings - Binding Type Accuracy: Ensures correct binding types (KV, R2, D1, Durable Objects)
- Remote Binding Validation: Checks remote binding configuration for development
- Secret Binding Verification: Validates secret vs environment variable bindings
Specific Checks Performed
❌ Critical Binding Mismatches
// These patterns trigger immediate alerts:
// Code references binding that doesn't exist in wrangler.toml
const user = await env.USER_DATA.get(id); // USER_DATA not configured
// TypeScript interface doesn't match wrangler.toml
interface Env {
USERS: KVNamespace; // Code expects USERS
// wrangler.toml has USER_DATA (mismatch!)
}
✅ Correct Binding Patterns
// These patterns are validated as correct:
// Matching wrangler.toml and TypeScript interface
interface Env {
USER_DATA: KVNamespace; // Matches wrangler.toml binding name
API_BUCKET: R2Bucket; // Correct R2 binding type
}
// Proper usage in code
const user = await env.USER_DATA.get(id);
const object = await env.API_BUCKET.get(key);
Integration Points
Complementary to Existing Components
- binding-context-analyzer agent: Handles complex binding analysis, SKILL provides immediate validation
- workers-runtime-validator SKILL: Complements runtime checks with binding validation
- cloudflare-security-checker SKILL: Ensures secret bindings are properly configured
Escalation Triggers
- Complex binding architecture questions →
binding-context-analyzeragent - Migration between binding types →
cloudflare-architecture-strategistagent - Binding performance issues →
edge-performance-oracleagent
Validation Rules
P1 - Critical (Will Fail at Runtime)
- Missing Bindings: Code references bindings not in wrangler.toml
- Type Mismatches: Wrong binding types in TypeScript interface
- Name Mismatches: Different names in code vs configuration
- Missing Env Interface: No TypeScript interface for bindings
P2 - High (Configuration Issues)
- Remote Binding Missing: Development bindings without
remote = true - Secret vs Var Confusion: Secrets in [vars] section or vice versa
- Incomplete Interface: Missing bindings in TypeScript interface
P3 - Medium (Best Practices)
- Binding Documentation: Missing JSDoc comments for bindings
- Binding Organization: Poor organization of related bindings
Remediation Examples
Fixing Missing Bindings
// ❌ Critical: Code references binding not in wrangler.toml
export default {
async fetch(request: Request, env: Env) {
const user = await env.USER_CACHE.get(userId); // USER_CACHE not configured!
}
}
// wrangler.toml (missing binding)
[[kv_namespaces]]
binding = "USER_DATA" # Different name!
id = "user-data"
// ✅ Correct: Matching names
export default {
async fetch(request: Request, env: Env) {
const user = await env.USER_DATA.get(userId); // Matches wrangler.toml
}
}
// wrangler.toml (correct binding)
[[kv_namespaces]]
binding = "USER_DATA" # Matches code!
id = "user-data"
Fixing TypeScript Interface Mismatches
// ❌ Critical: Interface doesn't match wrangler.toml
interface Env {
USERS: KVNamespace; // Code expects USERS
SESSIONS: KVNamespace; // Code expects SESSIONS
}
// wrangler.toml has different names
[[kv_namespaces]]
binding = "USER_DATA" # Different!
id = "user-data"
[[kv_namespaces]]
binding = "SESSION_DATA" # Different!
id = "session-data"
// ✅ Correct: Matching interface and configuration
interface Env {
USER_DATA: KVNamespace; # Matches wrangler.toml
SESSION_DATA: KVNamespace; # Matches wrangler.toml
}
// wrangler.toml (matching names)
[[kv_namespaces]]
binding = "USER_DATA" # Matches interface!
id = "user-data"
[[kv_namespaces]]
binding = "SESSION_DATA" # Matches interface!
id = "session-data"
Fixing Binding Type Mismatches
// ❌ Critical: Wrong binding type
interface Env {
MY_BUCKET: KVNamespace; # Wrong type - should be R2Bucket
MY_DB: D1Database; # Wrong type - should be KVNamespace
}
// wrangler.toml
[[r2_buckets]]
binding = "MY_BUCKET" # R2 bucket, not KV!
[[kv_namespaces]]
binding = "MY_DB" # KV namespace, not D1!
// ✅ Correct: Proper binding types
interface Env {
MY_BUCKET: R2Bucket; # Correct type for R2 bucket
MY_DB: KVNamespace; # Correct type for KV namespace
}
// wrangler.toml (same as above)
[[r2_buckets]]
binding = "MY_BUCKET"
[[kv_namespaces]]
binding = "MY_DB"
Fixing Remote Binding Configuration
// ❌ High: Missing remote binding for development
// wrangler.toml
[[kv_namespaces]]
binding = "USER_DATA"
id = "user-data"
# Missing remote = true for development!
// ✅ Correct: Remote binding configured
[[kv_namespaces]]
binding = "USER_DATA"
id = "user-data"
remote = true # Enables remote binding for development
Fixing Secret vs Environment Variable Confusion
// ❌ High: Secret in [vars] section (visible in git)
// wrangler.toml
[vars]
API_KEY = "sk_live_12345" # Secret exposed in git!
// ✅ Correct: Secret via wrangler secret command
// wrangler.toml (no secrets in [vars])
[vars]
PUBLIC_API_URL = "https://api.example.com" # Non-secret config only
# Set secret via command line:
# wrangler secret put API_KEY
# (prompt: enter secret value)
// Code accesses both correctly
interface Env {
API_KEY: string; # From wrangler secret
PUBLIC_API_URL: string; # From wrangler.toml [vars]
}
MCP Server Integration
When Cloudflare MCP server is available:
- Query actual binding configuration from Cloudflare account
- Verify bindings exist and are accessible
- Check binding permissions and limits
- Get latest binding configuration best practices
Benefits
Immediate Impact
- Prevents Runtime Failures: Catches binding mismatches before deployment
- Reduces Debugging Time: Immediate feedback on configuration issues
- Ensures Type Safety: Validates TypeScript interfaces match reality
Long-term Value
- Consistent Configuration: Ensures all code uses correct binding patterns
- Better Developer Experience: Clear error messages for binding issues
- Reduced Deployment Issues: Configuration validation prevents failed deployments
Usage Examples
During Binding Usage
// Developer types: const data = await env.CACHE.get(key);
// SKILL immediately activates: "❌ CRITICAL: CACHE binding not found in wrangler.toml. Add [[kv_namespaces]] binding = 'CACHE' or check spelling."
During Interface Definition
// Developer types: interface Env { USERS: R2Bucket; }
// SKILL immediately activates: "⚠️ HIGH: USERS binding type mismatch. wrangler.toml shows USERS as KVNamespace, not R2Bucket."
During Configuration Changes
// Developer modifies wrangler.toml binding name
// SKILL immediately activates: "⚠️ HIGH: Binding name changed from USER_DATA to USERS. Update TypeScript interface and code references."
Binding Type Reference
KV Namespace
interface Env {
MY_KV: KVNamespace;
}
// Usage: await env.MY_KV.get(key)
R2 Bucket
interface Env {
MY_BUCKET: R2Bucket;
}
// Usage: await env.MY_BUCKET.get(key)
D1 Database
interface Env {
MY_DB: D1Database;
}
// Usage: await env.MY_DB.prepare(query).bind(params).all()
Durable Object
interface Env {
MY_DO: DurableObjectNamespace;
}
// Usage: env.MY_DO.get(id)
AI Binding
interface Env {
AI: Ai;
}
// Usage: await env.AI.run(model, params)
Vectorize
interface Env {
VECTORS: VectorizeIndex;
}
// Usage: await env.VECTORS.query(vector, options)
This SKILL ensures Workers binding configuration is correct by providing immediate, autonomous validation of binding patterns, preventing runtime failures and configuration mismatches.