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

> Learn how to contribute to Cloudflare Computer's dofs package. Fork the repo, set up the workspace, build, and test to join development on this essential storage layer.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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:

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

```

3. **Add the upstream remote** for staying synchronized:

```bash
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.

```bash

# 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`](https://github.com/cloudflare/computer/blob/main/README.md) for platform-specific details.

## Build the Workspace

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

```bash
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.

```bash

# Run the complete dofs test suite

npm test --workspace @cloudflare/dofs

```

Run a single test file for faster iteration:

```bash
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:

```bash
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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/index.ts) | Re-exports `Database`, `Provider`, `Path`, and other public interfaces |
| **Database layer** | [`packages/dofs/src/storage.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/storage.ts) | Wraps SQLite with transaction helpers for the VFS |
| **Sync protocol** | [`packages/dofs/src/sync/push.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/sync/push.ts), [`packages/dofs/src/sync/apply.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/sync/apply.ts) | Implements incremental sync for Durable Object replication |
| **Filesystem façade** | [`packages/dofs/src/fs/filesystem.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/filesystem.ts), [`packages/dofs/src/fs/writeFile.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/writeFile.ts), [`packages/dofs/src/fs/readFile.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/readFile.ts) | POSIX-like operations (`open`, `read`, `write`, `stat`, `rename`) atop SQLite |
| **Schema & migrations** | [`packages/dofs/src/schema/core.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/core.ts), [`packages/dofs/src/schema/sync.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/sync.ts), [`packages/dofs/src/schema/migrations.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/migrations.ts) | SQLite schema definitions and version upgrades |
| **Revision handling** | [`packages/dofs/src/rev.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/rev.ts) | Monotonic revision numbers for conflict resolution |
| **Testing utilities** | [`packages/dofs/src/testing.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/testing.ts), [`packages/dofs/src/testing-recording.ts`](https://github.com/cloudflare/computer/blob/main/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

```bash
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`](https://github.com/cloudflare/computer/blob/main/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

```bash

# 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.

```bash
git push origin feature/<short-description>

```

**PR requirements:**
- Target branch: `main`
- Follow the template at [`.github/pull_request_template.md`](https://github.com/cloudflare/computer/blob/main/.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:

```bash
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

```ts
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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/testing.ts)

### Trigger a Sync Push Operation

```ts
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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/sync/push.ts)

### Run a Specific Filesystem Test

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

```

*Source:* [`packages/dofs/src/fs/writeFile.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/writeFile.test.ts)

## Key Source Files for Contributors

| File | Purpose |
|------|---------|
| [`packages/dofs/src/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/index.ts) | Public export surface |
| [`packages/dofs/src/provider.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/provider.ts) | Core `Provider` implementation (SQLite wrapper) |
| [`packages/dofs/src/storage.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/storage.ts) | Low-level SQLite storage helpers |
| [`packages/dofs/src/fs/filesystem.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/filesystem.ts) | Virtual filesystem API implementation |
| [`packages/dofs/src/fs/writeFile.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/writeFile.ts) | `writeFile` VFS operation |
| [`packages/dofs/src/fs/readFile.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/readFile.ts) | `readFile` VFS operation |
| [`packages/dofs/src/sync/push.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/sync/push.ts) | Sync "push" for uploading local changes |
| [`packages/dofs/src/sync/apply.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/sync/apply.ts) | Sync "apply" for merging incoming changes |
| [`packages/dofs/src/schema/core.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/schema/core.ts) | Core SQLite schema definitions |
| [`packages/dofs/src/rev.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/rev.ts) | Revision tracking for conflict resolution |
| [`packages/dofs/src/testing.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/testing.ts) | Test helpers for temporary `dofs` instances |
| [`CONTRIBUTING.md`](https://github.com/cloudflare/computer/blob/main/CONTRIBUTING.md) | Project-wide contribution guidelines |
| [`docs/08_capnweb_interface.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/storage.ts), [`provider.ts`](https://github.com/cloudflare/computer/blob/main/provider.ts), [`fs/filesystem.ts`](https://github.com/cloudflare/computer/blob/main/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.