How to Contribute to Cloudflare Computer's `dofs` Package: A Complete Developer Guide

Fork the cloudflare/computer repository, set up the npm workspace with --ignore-scripts, build with npm run build, and run tests via npm test --workspace @cloudflare/dofs to start contributing to the dofs storage layer.

The dofs package is the core SQLite-backed storage layer for Cloudflare Computer, handling virtual filesystem operations and sync replication across the Cloudflare network. Contributing to this package requires understanding its TypeScript architecture, native dependencies, and comprehensive test suite. This guide walks through the complete contributor workflow based on the actual source code in cloudflare/computer.

Fork and Clone the Repository

Start by creating your own copy of the repository and setting up local remotes.

1. Fork on GitHub: https://github.com/cloudflare/computer/fork

2. Clone your fork locally:

git clone https://github.com/<YOUR-USERNAME>/computer.git
cd computer

3. Add the upstream remote for staying synchronized:

git remote add upstream https://github.com/cloudflare/computer.git

Install Development Dependencies

The workspace uses npm workspaces with a native C++ addon for FUSE support. Linux development machines need system build tools first.

# Install system build tools for the native addon

sudo apt-get install build-essential libfuse-dev

# Install Node.js packages while skipping native compilation

npm install --ignore-scripts

The --ignore-scripts flag is critical here. The fuse-native addon attempts to compile a binary unnecessary for most dofs development work. Skipping this step accelerates installation and prevents build failures on non-Linux platforms. See the Environment Setup section in the repository root README.md for platform-specific details.

Build the Workspace

All packages share a common dist/ output directory. Build everything before running tests:

npm run build

This compiles TypeScript for every workspace package (packages/*). Successful completion creates compiled JavaScript in each package's dist/ folder.

Run the dofs Test Suite

The dofs package includes comprehensive tests covering the storage API, sync logic, and virtual filesystem implementation.

# Run the complete dofs test suite

npm test --workspace @cloudflare/dofs

Run a single test file for faster iteration:

npm test --workspace @cloudflare/dofs -- src/provider.test.ts

Tests use Vitest and include benchmarks (*.bench.ts) and fuzz tests. If tests fail, ensure you're on latest upstream code:

git fetch upstream
git checkout main
git merge upstream/main
npm run build

Understand the dofs Architecture

Reviewing these source files builds a solid mental model of how dofs operates:

Component	Location	Purpose
Public API	packages/dofs/src/index.ts	Re-exports Database, Provider, Path, and other public interfaces
Database layer	packages/dofs/src/storage.ts	Wraps SQLite with transaction helpers for the VFS
Sync protocol	packages/dofs/src/sync/push.ts, packages/dofs/src/sync/apply.ts	Implements incremental sync for Durable Object replication
Filesystem façade	packages/dofs/src/fs/filesystem.ts, packages/dofs/src/fs/writeFile.ts, packages/dofs/src/fs/readFile.ts	POSIX-like operations (open, read, write, stat, rename) atop SQLite
Schema & migrations	packages/dofs/src/schema/core.ts, packages/dofs/src/schema/sync.ts, packages/dofs/src/schema/migrations.ts	SQLite schema definitions and version upgrades
Revision handling	packages/dofs/src/rev.ts	Monotonic revision numbers for conflict resolution
Testing utilities	packages/dofs/src/testing.ts, packages/dofs/src/testing-recording.ts	Helpers for in-process dofs instances and sync traffic recording

Make Your Changes

Follow this workflow for effective contributions.

Create a Feature Branch

git checkout -b feature/<short-description>

Common Contribution Areas

• New filesystem operations: Extend packages/dofs/src/fs/ (e.g., extended attributes)
• Sync performance: Improve coalescing in packages/dofs/src/sync/coalesce.ts
• Bug fixes: Address issues uncovered by packages/dofs/src/fs/*.test.ts
• Schema updates: Modify packages/dofs/src/schema/*.ts with proper migrations

Verify Your Changes

# Run tests after each change

npm test --workspace @cloudflare/dofs

# Format and lint (CI enforces zero-exit-code)

npm run format
npx biome check .

The repository uses Biome for formatting and linting. CI automatically rejects pull requests failing these checks.

Submit a Pull Request

Push your branch and open a PR against the upstream repository.

git push origin feature/<short-description>

PR requirements:

• Target branch: main
• Follow the template at .github/pull_request_template.md
• Describe what changed, why, and how you verified it

CI runs the full workspace test suite, lint, and type-checking automatically. Address review comments, push additional commits, and await maintainer approval for merge.

Keep Your Fork Updated

After your PR merges, synchronize to prevent future conflicts:

git checkout main
git fetch upstream
git reset --hard upstream/main
git push origin main --force

Practical Code Examples

Open a dofs Instance in a Test

import { createTestDofs } from '@cloudflare/dofs/testing';

// Spins up an in-process SQLite DB and returns a Provider
const { provider, cleanup } = await createTestDofs();

// Use the provider like a normal filesystem
await provider.mkdir('/mydir', { recursive: true });
await provider.writeFile('/mydir/hello.txt', new TextEncoder().encode('hi'));

await cleanup();   // shuts down the DB

Source: packages/dofs/src/testing.ts

Trigger a Sync Push Operation

import { pushChanges } from '@cloudflare/dofs/sync/push';
import { Provider } from '@cloudflare/dofs';

// Assume `db` is a live Provider
await pushChanges({ provider: db, fromRev: 42, toRev: 53 });

Source: packages/dofs/src/sync/push.ts

Run a Specific Filesystem Test

npm test --workspace @cloudflare/dofs -- src/fs/writeFile.test.ts

Source: packages/dofs/src/fs/writeFile.test.ts

Key Source Files for Contributors

File	Purpose
packages/dofs/src/index.ts	Public export surface
packages/dofs/src/provider.ts	Core Provider implementation (SQLite wrapper)
packages/dofs/src/storage.ts	Low-level SQLite storage helpers
packages/dofs/src/fs/filesystem.ts	Virtual filesystem API implementation
packages/dofs/src/fs/writeFile.ts	writeFile VFS operation
packages/dofs/src/fs/readFile.ts	readFile VFS operation
packages/dofs/src/sync/push.ts	Sync "push" for uploading local changes
packages/dofs/src/sync/apply.ts	Sync "apply" for merging incoming changes
packages/dofs/src/schema/core.ts	Core SQLite schema definitions
packages/dofs/src/rev.ts	Revision tracking for conflict resolution
packages/dofs/src/testing.ts	Test helpers for temporary dofs instances
CONTRIBUTING.md	Project-wide contribution guidelines
docs/08_capnweb_interface.md	RPC contract for Durable Object sync

Summary

• Fork and clone the cloudflare/computer repository with proper upstream remotes
• Install dependencies with npm install --ignore-scripts to skip unnecessary native compilation
• Build the workspace with npm run build before any testing
• Run tests via npm test --workspace @cloudflare/dofs using Vitest
• Understand architecture through key files: storage.ts, provider.ts, fs/filesystem.ts, and sync/
• Format and lint with Biome (npm run format, npx biome check .) to pass CI
• Submit PRs targeting main with clear descriptions following the template

Frequently Asked Questions

What is the dofs package in Cloudflare Computer?

The dofs package is the core SQLite-backed storage layer that provides a virtual filesystem abstraction for Cloudflare Computer. It implements POSIX-like file operations (readFile, writeFile, mkdir, stat, etc.) on top of SQLite and handles incremental synchronization of changes across the Cloudflare network via Durable Objects.

Why use --ignore-scripts during npm install?

The --ignore-scripts flag prevents the fuse-native C++ addon from compiling. This native dependency is only needed for FUSE filesystem mounting, not for core dofs development. Skipping it accelerates installation and avoids build failures on macOS, Windows, or systems without libfuse-dev.

How do I run only specific tests in the dofs package?

Append the test file path after a double dash: npm test --workspace @cloudflare/dofs -- src/fs/writeFile.test.ts. Vitest executes only that file, enabling rapid iteration during development.

What linting and formatting tools does the project use?

The cloudflare/computer repository uses Biome for both formatting and linting. Run npm run format to auto-format code and npx biome check . to verify lint passes. CI enforces a zero-exit-code for lint checks; any failure blocks PR merge.

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