Development Workflow for cloudflare/computer: From Clone to Release

The development workflow for cloudflare/computer follows an eight-stage process spanning repository setup, Biome formatting, type-checking, workspace-aware testing, imperative scoped commits, and Changeset-driven releases.

The cloudflare/computer repository is a TypeScript monorepo that implements a virtual filesystem backed by Durable Objects, providing container and isolate back-ends for remote execution. Understanding the development workflow for cloudflare/computer ensures consistent code quality across packages like @cloudflare/dofs and @cloudflare/computerd, while leveraging the repository's automated CI pipeline for releases.

Repository Setup and Installation

Begin by cloning the repository and installing dependencies across all workspaces in a single step.

git clone https://github.com/cloudflare/computer.git
cd computer
npm install

The root package.json defines an npm workspace configuration that installs dependencies for every package simultaneously, including the core dofs (Durable Object filesystem), rpc, computerd, and computer packages.

Build Process

Compile TypeScript source files to their respective dist directories using the standard build command. For contributors needing pre-built Linux x64 binaries or Docker images, use the extended build target.

# Standard compilation

npm run build

# Full build including binaries and Docker images

npm run build:all

The build process references tsconfig.json files in each workspace and generates the bundled artifacts required by the computerd daemon.

Code Quality Pipeline

Formatting and Linting with Biome

The repository uses Biome for both formatting and linting. Always run the formatter before committing, then verify that both lint and format checks pass.

npm run format      # Apply Biome formatting fixes

npm run check       # Verify lint rules and formatting (must exit 0)

Type Checking

Run the TypeScript compiler in no-emit mode across all workspaces to catch type errors without generating output files.

npm run typecheck   # Equivalent to tsc --noEmit across workspaces

This command type-checks the entire monorepo, including the Cap'n Proto RPC definitions in packages/rpc and the FUSE filesystem implementations in packages/computerd.

Testing Strategy

Execute the test suite at the repository root to run all tests, or target specific workspaces and individual test files for faster iteration.

# Entire monorepo

npm test

# Specific package (e.g., the Durable Object filesystem)

npm test --workspace @cloudflare/dofs

# Single test file within a package

npm test --workspace @cloudflare/dofs -- src/path/to/file.test.ts

The test runner respects the workspace boundaries defined in package.json and supports the test-driven development patterns documented in .agents/skills/test-driven-development/SKILL.md.

Commit Conventions and Pull Requests

Write commit messages using the imperative mood, prefixed with the owning package scope, and limited to 50 characters in the subject line.

git add .
git commit -m "dofs: fix race condition in sync"
git commit -m "computerd: add transaction support for batch writes"

Valid scope prefixes include dofs:, computerd:, rpc:, and computer:, corresponding to the packages in packages/. When opening a pull request, follow the template in COLLABORATORS.md to provide verification steps and context for the change.

Release Management with Changesets

For changes that require a version bump, generate a Changeset describing the impact level (patch, minor, or major).

npm run changeset

# Follow interactive prompts to select packages and describe changes

git add .changeset
git commit -m "chore: add changeset for new transaction feature"

The CI pipeline automatically processes these Changesets during the release workflow, building the computerd binary, pushing Docker images to the registry, and publishing public npm packages with appropriate semantic versions.

Essential Documentation References

Several files define the boundaries and conventions of this workflow:

• COLLABORATORS.md – The primary contributor guide covering setup, formatting, testing, commit conventions, and the PR process.
• AGENTS.md – Describes repository-wide conventions for the RPC boundary and the skill system used for automated assistance.
• packages/dofs/README.md – Documents the SQLite-backed virtual filesystem and sync protocol.
• packages/rpc/README.md – Specifies the Cap'n Proto (capnweb) contract between the Durable Object and the computerd daemon.

Summary

• The cloudflare/computer monorepo uses npm workspaces for dependency management across packages including dofs, computerd, and rpc.
• Biome handles formatting and linting via npm run format and npm run check, while npm run typecheck validates TypeScript across all workspaces.
• Tests execute via npm test with support for workspace-specific and file-specific targeting using the --workspace flag.
• Commit messages must use imperative mood with package scope prefixes (e.g., dofs:, computerd:) and follow the 50-character subject limit.
• Changesets drive the release process; run npm run changeset to version packages, then let CI handle binary builds, Docker pushes, and npm publishing.

Frequently Asked Questions

How do I run tests for only one package in the monorepo?

Use the --workspace flag with the package name. For example, npm test --workspace @cloudflare/dofs runs only the Durable Object filesystem tests, and you can further narrow scope by appending a specific file path: npm test --workspace @cloudflare/dofs -- src/sync.test.ts.

What is the correct format for commit messages in cloudflare/computer?

Commit subjects must be imperative (e.g., "add" not "added"), prefixed with the package scope (e.g., dofs:, computerd:), and limited to 50 characters. This convention appears in COLLABORATORS.md and ensures readable git history across the monorepo.

How are releases handled in the cloudflare/computer repository?

Releases are managed through Changesets. Developers run npm run changeset to document changes, which creates files in .changeset/. The CI pipeline then reads these files to bump versions, build the computerd Linux binary, push Docker images, and publish npm packages automatically.

What is the purpose of the AGENTS.md file?

AGENTS.md serves as an internal guide for repository conventions, particularly regarding the RPC boundary between Durable Objects and the daemon. It documents the skill system in .agents/skills/ and provides context for automated assistance tools and testing strategies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}