cloudflare

cloudflare Best Practices

Cloudflare's developer platform thrives on speed, security, and global distribution. Our focus is on building tiny, observable, and secure bundles that leverage the edge. This guide outlines the definitive best practices for our team.

1. Code Organization and Structure

Prioritize Workers & Pages for all new applications. Use the official wrangler CLI for project scaffolding and deployment.

• Project Initialization:
  • ✅ GOOD: Always start with wrangler generate.

    npx wrangler generate my-worker --type=module --ts
    # For full-stack apps with Pages:
    npx create-cloudflare@latest my-fullstack-app --framework next
    

• Monorepos: For projects with multiple Workers or Pages apps, use pnpm or yarn workspaces.
  • ✅ GOOD: Centralize dependencies and build scripts.

    // package.json
    {
      "workspaces": ["apps/*", "packages/*"]
    }
    

• Environment Variables: Manage secrets securely via wrangler.toml or the Cloudflare dashboard. Use .dev.vars for local development.
  • ❌ BAD: Storing sensitive data directly in code or .env files that aren't .dev.vars.
  • ✅ GOOD: Define variables in wrangler.toml and reference them in your Worker.

    # wrangler.toml
    name = "my-worker"
    main = "src/index.ts"
    compatibility_date = "2025-12-01"
    
    [vars]
    MY_API_KEY = "your-api-key-value" # For non-sensitive defaults or local testing
    
    [secrets] # For sensitive production secrets
    # MY_DB_URL = "set via `wrangler secret put MY_DB_URL`"
    

  • ✅ GOOD: Use .dev.vars for local secrets, and integrate with CLI tools.

    # .dev.vars
    DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
    # Use with Prisma:
    dotenv -e .dev.vars -- npx prisma migrate dev
    

2. Common Patterns and Anti-patterns