How to Use the `dofs` Package in Cloudflare Computer: Examples and Implementation Guide

The @cloudflare/dofs package provides a SQLite-backed virtual filesystem used internally by Cloudflare Computer, with direct usage examples found primarily in the test suite where the package is exercised in isolation.

If you're building on Cloudflare Computer, understanding the dofs package helps you grasp how file operations work under the hood. While most developers interact with higher-level APIs, direct access to dofs enables custom storage patterns and testing scenarios. This guide walks through concrete examples from the cloudflare/computer source code.

What Is the dofs Package?

The dofs package implements a distributed object filesystem—a virtual filesystem layer backed by SQLite. According to the Cloudflare Computer source code, it powers all file operations in the platform. The package is located in packages/dofs/ and exposes a low-level Database class that higher-level Computer APIs delegate to.

Most repository examples use dofs indirectly through @cloudflare/computer wrappers. For direct usage, you need to examine the test suite and internal components.

Direct Usage Examples in the Repository

The cloudflare/computer repository contains four key patterns for using dofs directly. These patterns appear in test files and internal implementations rather than public examples/ directories.

Creating a Workspace Database

The foundational pattern initializes a SQLite store and prepares the root inode. You'll see this in packages/rpc/tests/shell-and-composite.test.ts at lines 21-22, where the test suite sets up isolated database instances:

import { Database, initializeSchema } from '@cloudflare/dofs';

The initializeSchema function prepares the database tables for file and directory storage, while ROOT_INODE provides the entry point for the filesystem hierarchy.

Using Test Storage with SQLiteTestStorage

For unit tests and prototypes, the @cloudflare/dofs/testing submodule provides SQLiteTestStorage. This in-memory SQLite implementation avoids persistence overhead.

Found in packages/rpc/tests/wire.test.ts at lines 15-16:

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

This pattern is essential for fast, isolated testing without external dependencies.

Reading and Writing Files

Low-level file operations use methods like stat, writeFile, and mkdir on a Database instance. The packages/computerd/src/exec/runner.test.ts file demonstrates these operations, showing how the Computer runtime ultimately delegates to dofs primitives.

These same methods power the workspace.runtime APIs that most developers use daily.

Synchronizing Changes with applyResult and readWatermark

The sync flow between Durable Objects and sandboxes uses applyResult and readWatermark utilities. Found in packages/rpc/src/sync-driver.ts at line 29, this pattern shows how the dofs sync driver propagates filesystem changes:

// From sync-driver.ts line 29
import { applyResult, readWatermark } from '@cloudflare/dofs';

Complete Working Example

Based on the repository patterns, here's a standalone demonstration combining all four approaches. This runs in Node.js or any Worker-compatible environment with SQLite access:

// Import the core types and helpers
import { Database, initializeSchema, ROOT_INODE } from '@cloudflare/dofs';
import { SQLiteTestStorage } from '@cloudflare/dofs/testing';

async function demo() {
  // 1️⃣ Create an in-memory SQLite DB (perfect for demos or tests)
  const storage = new SQLiteTestStorage();

  // 2️⃣ Open the DB and set up the schema
  const db = await Database.open(storage);
  await initializeSchema(db);

  // 3️⃣ Write a file under the root inode
  const helloPath = '/hello.txt';
  await db.writeFile(ROOT_INODE, helloPath, Buffer.from('Hello, dofs!'));

  // 4️⃣ Read the file back
  const content = await db.readFile(ROOT_INODE, helloPath);
  console.log(content.toString()); // → "Hello, dofs!"
}

demo().catch(console.error);

This example mirrors the initialization pattern in packages/rpc/tests/shell-and-composite.test.ts and the file operations from packages/computerd/src/exec/runner.test.ts.

Key Source Files for Reference

File	Purpose
packages/dofs/src/index.ts	Core public API of the dofs package
packages/dofs/src/testing.ts	Test utilities including SQLiteTestStorage
packages/rpc/tests/shell-and-composite.test.ts	Typical imports and database setup
packages/computerd/src/exec/runner.test.ts	File operations using Database
packages/rpc/src/sync-driver.ts	Sync driver implementing push/pull changes

When to Use dofs Directly vs. Higher-Level APIs

• Use @cloudflare/computer APIs for application code, build tooling, and most production scenarios
• Use @cloudflare/dofs directly when:
  • Building custom test environments
  • Implementing alternative storage backends
  • Debugging filesystem synchronization issues
  • Prototyping low-level storage features

Summary

• The dofs package provides Cloudflare Computer's SQLite-backed virtual filesystem
• Direct usage examples live in the test suite, not public examples/ directories
• Key imports: Database, initializeSchema, ROOT_INODE from @cloudflare/dofs
• Testing helper: SQLiteTestStorage from @cloudflare/dofs/testing
• Core operations: writeFile, readFile, stat, mkdir on Database instances
• Sync utilities: applyResult and readWatermark for Durable Object synchronization

Frequently Asked Questions

How do I install the dofs package?

The @cloudflare/dofs package is part of the cloudflare/computer monorepo. If you're working within that repository, import directly from the package path. For external projects, check the repository's published packages or build from source. The package is designed for internal use alongside @cloudflare/computer.

Can I use dofs outside of Cloudflare Workers?

Yes. The SQLiteTestStorage backend runs in standard Node.js environments, making dofs usable for local development and testing. Production deployments typically use Durable Object storage bindings, which require the Workers runtime.

What's the difference between dofs and the workspace.runtime APIs?

The workspace.runtime APIs in @cloudflare/computer are higher-level wrappers that delegate to dofs. They add features like permission management, sandbox isolation, and automatic synchronization. Direct dofs usage gives you raw filesystem access without these abstractions.

Where are the official dofs examples?

As of the current cloudflare/computer source code, no public examples demonstrate standalone dofs usage. The package is exercised indirectly through Computer APIs in examples/ and directly in test files under packages/*/tests/. The patterns in this article derive from those test implementations.

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