Skip to content

AGENTS.md

Latest commit

 

History

History
201 lines (144 loc) · 10.1 KB

AGENTS.md

File metadata and controls

201 lines (144 loc) · 10.1 KB

AGENTS.md

This file provides guidance to AI coding agents working in this repository.

Project Overview

This is the Cloudflare Workers SDK monorepo containing tools and libraries for developing, testing, and deploying applications on Cloudflare. The main components are Wrangler (CLI), Miniflare (local dev simulator), and Create Cloudflare (project scaffolding).

Development Commands

Package Management:

  • Use pnpm - never use npm or yarn
  • pnpm install - Install dependencies for all packages
  • pnpm build - Build all packages (uses Turbo for caching)

Testing:

  • pnpm test:ci - Run tests in CI mode
  • pnpm test:e2e - Run end-to-end tests (requires Cloudflare credentials)
  • pnpm test -F <package> "pattern" - Run a single test by name pattern

Code Quality:

  • pnpm check - Run all checks (lint, type, format)
  • pnpm fix - Auto-fix linting issues and format code

Working with Specific Packages:

  • pnpm run build --filter <package-name> - Build specific package
  • pnpm run test:ci --filter <package-name> - Test specific package
  • pnpm --filter <package> test:watch - Watch mode for a specific package

Architecture Overview

Core Tools:

  • packages/wrangler/ - Main CLI tool for Workers development and deployment
  • packages/miniflare/ - Local development simulator powered by workerd runtime
  • packages/create-cloudflare/ - Project scaffolding CLI (C3)
  • packages/vite-plugin-cloudflare/ - Vite plugin for Cloudflare Workers

Development & Testing:

  • packages/vitest-pool-workers/ - Vitest integration for testing Workers in actual runtime
  • packages/chrome-devtools-patches/ - Modified Chrome DevTools for Workers debugging

Shared Libraries:

  • packages/pages-shared/ - Code shared between Wrangler and Cloudflare Pages
  • packages/workers-shared/ - Code shared between Wrangler and Workers Assets
  • packages/workers-utils/ - Utility package for common Worker operations
  • packages/workflows-shared/ - Internal Cloudflare Workflows functionality
  • packages/containers-shared/ - Shared container functionality
  • packages/unenv-preset/ - Cloudflare preset for unenv (Node.js polyfills)
  • packages/cli/ - SDK for building workers-sdk CLIs
  • packages/kv-asset-handler/ - KV-based asset handling for Workers Sites

Build System:

  • Turbo (turborepo) orchestrates builds across packages
  • TypeScript compilation with shared configs in packages/workers-tsconfig/
  • Shared lint config in packages/lint-config-shared/
  • Dependency management via pnpm catalog system

WHERE TO LOOK

Task Location Notes
Add/modify a CLI command packages/wrangler/src/ Commands registered in src/index.ts (2k+ line yargs tree)
Change local dev behavior packages/miniflare/src/ src/index.ts is the main Miniflare class
Modify Workers runtime simulation packages/miniflare/src/workers/ ~30 embedded worker scripts, built via worker: virtual imports
Add a test fixture fixtures/ Each fixture is a full workspace member with own package.json
Shared config types/validation packages/workers-utils/src/config/ validation.ts is the config normalizer (large file)
Test helpers (runInTempDir, seed, mockConsole) packages/workers-utils/src/test-helpers/ Shared across wrangler, miniflare, others
Cloudflare API mocks for tests packages/wrangler/src/__tests__/helpers/msw/ MSW handlers per API domain
CI workflows .github/workflows/ test-and-check.yml is the primary gate
Build/deploy scripts tools/deployments/ Validation + deployment helpers, run via esbuild-register
Changeset config and rules .changeset/README.md Must read before creating changesets

Development Guidelines

Requirements:

  • Node.js >= 20
  • pnpm

Code Style:

  • TypeScript with strict mode
  • Use import type { X } for type-only imports (@typescript-eslint/consistent-type-imports)
  • No any (@typescript-eslint/no-explicit-any)
  • No non-null assertions (!)
  • No floating promises - must be awaited or explicitly voided (@typescript-eslint/no-floating-promises)
  • Always use curly braces for control flow (curly: error)
  • Use node: prefix for Node.js imports (import/enforce-node-protocol-usage)
  • Prefix unused variables with _
  • No .only() in tests (no-only-tests/no-only-tests)
  • Format with oxfmt - run pnpm prettify in the workspace root before committing
  • All changes to published packages require a changeset (see below)

Formatting (oxfmt):

  • Tabs (not spaces), double quotes, semicolons, trailing commas (es5)
  • Import order enforced: builtins → third-party → parent → sibling → index → types
  • sortPackageJson option sorts package.json keys

Security:

  • Custom ESLint rule workers-sdk/no-unsafe-command-execution: no template literals or string concatenation in exec/spawn/execFile calls (command injection prevention, CWE-78). Disabled in test files only.

Dependencies:

  • Packages must bundle deps into distributables; runtime dependencies are forbidden except for an explicit allowlist
  • External (non-bundled) deps must be declared in scripts/deps.ts with EXTERNAL_DEPENDENCIES and a comment explaining why

Testing Standards:

  • Unit tests with Vitest for all packages
  • Fixture tests in /fixtures directory for filesystem/Worker scenarios
  • E2E tests require real Cloudflare account credentials
  • Use vitest-pool-workers for testing actual Workers runtime behavior
  • Shared vitest config (vitest.shared.ts): 50s timeouts, retry: 2, restoreMocks: true
  • Vitest 4 pool config: use maxWorkers: 1 instead of the removed poolOptions.forks.singleFork: true when tests must run sequentially

Git Workflow:

  • Check you are not on main before committing. Create a new branch for your work from main if needed.
  • Clean commit history required before first review
  • Don't squash commits after review
  • Never commit without changesets for user-facing changes
  • PR template requirements: Remove "Fixes #..." line when no relevant issue exists, keep all checkboxes (don't delete unchecked ones)

Creating Pull Requests:

  • Always use the PR template from .github/PULL_REQUEST_TEMPLATE.md - do not replace it with your own format
  • Fill in the template: replace the issue link placeholder, add description, check appropriate boxes
  • Keep all checkboxes in the template (don't delete unchecked ones)
  • PR title format: [package name] description (e.g. [wrangler] Fix bug in dev command)
  • If the change doesn't require a changeset, add the no-changeset-required label

Key Locations

  • /fixtures - Test fixtures and example applications (each a workspace member)
  • /packages/wrangler/src - Main Wrangler CLI source code
  • /packages/miniflare/src - Miniflare source
  • /tools - Build scripts and deployment utilities (run via esbuild-register, no build step)
  • turbo.json - Turbo build configuration
  • pnpm-workspace.yaml - Workspace configuration (~156 workspace members)

Testing Strategy

Package-specific tests: Most packages have their own test suites Integration tests: Use fixtures to test real-world scenarios E2E tests: Test against actual Cloudflare services (requires auth) Workers runtime tests: Use vitest-pool-workers for workerd-specific behavior

Run pnpm check before submitting changes to ensure all quality gates pass.

Changesets

Every change to package code requires a changeset or it will not trigger a release. Read .changeset/README.md before creating changesets.

Changeset Format:

The changeset descriptions can either use conventional commit prefixes (e.g., "fix: remove unused option") or start with a capital letter and describe the change directly (e.g., "Remove unused option" not").

Changeset Rules:

  • Major versions for wrangler are currently forbidden
  • patch: bug fixes; minor: new features, deprecations, experimental breaking changes; major: stable breaking changes only
  • No h1/h2/h3 headers in changeset descriptions (changelog uses h3)
  • Config examples must use wrangler.json (JSONC), not wrangler.toml
  • Separate changesets for distinct changes; do not lump unrelated changes

Anti-Patterns

These are explicitly forbidden across the repo:

  • npm/yarn → use pnpm
  • any type → properly type everything
  • Non-null assertions (!) → use type narrowing
  • Floating promises → await or void explicitly
  • Missing curly braces → always brace control flow
  • console.* in wrangler → use the logger singleton
  • Direct Cloudflare REST API calls → use the Cloudflare TypeScript SDK
  • Named imports from ci-info → use default import (import ci from "ci-info")
  • Runtime dependencies → bundle deps; external deps need explicit allowlist entry
  • Committing to main → always work on a branch

Subdirectory Knowledge

Packages with their own AGENTS.md for deeper context:

  • packages/wrangler/AGENTS.md - CLI architecture, command structure, test patterns
  • packages/miniflare/AGENTS.md - Worker simulation, embedded workers, build system
  • packages/vite-plugin-cloudflare/AGENTS.md - Plugin architecture, playground setup
  • packages/create-cloudflare/AGENTS.md - Scaffolding, template system
  • packages/vitest-pool-workers/AGENTS.md - 3-context architecture, cloudflare:test module
  • packages/workers-utils/AGENTS.md - Shared config validation, test helpers