How to Use the @platformatic/vfs Adapter with Cloudflare Computer

Install @platformatic/vfs as an optional peer dependency and instantiate your Durable Object with withWorkspace() to enable a SQLite-backed VirtualProvider that exposes the full @platformatic/vfs API alongside standard Node.js filesystem methods.

Cloudflare Computer provides a durable virtual filesystem backed by SQLite storage through its dofs (Durable Object File System) package. When you need advanced virtual filesystem capabilities—such as file watching, custom module hooks, or enhanced compatibility with Platformatic tooling—you can integrate the optional @platformatic/vfs adapter. This adapter splices the SQLiteWorkspaceProvider into the VirtualProvider prototype, creating a seamless bridge between Cloudflare's Durable Object storage and the Platformatic VFS ecosystem.

What Is the @platformatic/vfs Adapter?

The @platformatic/vfs adapter is an optional peer dependency in the cloudflare/computer repository that transforms the default SQLite-backed filesystem into a fully-featured Platformatic Virtual File System. According to the source code in packages/computer/src/workspace.ts, when the package is present, the system lazily imports @platformatic/vfs and constructs the filesystem using createNodeVirtualFileSystem(). If the dependency is absent, Computer gracefully falls back to a lightweight in-memory provider that maintains basic fs/promises compatibility.

Architecture and Key Source Files

The integration spans three core components across the monorepo. Each file handles a specific layer of the virtualization stack, from low-level storage persistence to high-level FUSE mounting.

SQLiteWorkspaceProvider in provider.ts

At the foundation lies the SQLiteWorkspaceProvider class defined in packages/dofs/src/provider.ts. This class extends VirtualProvider from @platformatic/vfs and implements the persistent storage layer using Durable Object SQLite. The provider handles block-level operations, transaction management, and directory indexing, serving as the concrete backend for all VFS operations.

FUSE Driver Integration in vfs.ts

The packages/computerd/src/fuse/vfs.ts file splices the SQLiteWorkspaceProvider into the VirtualProvider prototype chain and instantiates the VirtualFileSystem used by the FUSE driver. This allows the same provider instance to serve both the programmatic API and the mountable filesystem interface inside containers, ensuring read-write consistency across access methods.

Workspace Initialization in workspace.ts

The entry point for application developers resides in packages/computer/src/workspace.ts. The createNodeVirtualFileSystem() helper function constructs the VFS by calling create(provider, { moduleHooks: false }), returning a fs object that implements the Node.js fs/promises API. This abstraction allows your code to use standard filesystem methods regardless of whether the Platformatic adapter is active.

Installation and Setup

To enable the adapter, add the package to your project dependencies. Because this is an optional peer dependency, you only need to install it when requiring advanced VFS features.

npm install @platformatic/vfs

Once installed, the cloudflare/computer runtime automatically detects the package and initializes the full VirtualProvider integration. No additional configuration flags are required.

Implementation Example

The following TypeScript example demonstrates how to configure a Durable Object with the Platformatic VFS adapter enabled. The withWorkspace mixin automatically wires up the SQLiteWorkspaceProvider to the VirtualProvider prototype when @platformatic/vfs is present.

import { withWorkspace, getWorkspace } from "@cloudflare/computer";
import { DurableObject } from "cloudflare:workers";

// Define the environment interface
interface Env {
  Agent: DurableObjectNamespace<Agent>;
}

// Create the Durable Object class with workspace support
export class Agent extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({
    storage: self.ctx.storage,
    // Optional: configure additional backends here
  })
) {}

// Worker entry point
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const id = env.Agent.idFromName("user-123");
    
    // Acquire workspace with VFS adapter active
    using ws = await getWorkspace(env.Agent.get(id));
    
    // Standard Node.js fs/promises API
    await ws.fs.writeFile("/hello.txt", "world");
    const content = await ws.fs.readFile("/hello.txt", "utf-8");
    
    // Additional @platformatic/vfs methods available when package is installed
    // for await (const event of ws.fs.watch("/")) {
    //   console.log("File change:", event);
    // }
    
    return new Response(content);
  },
} satisfies ExportedHandler<Env>;

In this implementation, ws.fs provides the same interface whether or not @platformatic/vfs is installed. However, when the adapter is present, you gain access to extended capabilities such as recursive file watching and custom module resolution hooks.

Summary

• The @platformatic/vfs adapter is an optional peer dependency that enhances Cloudflare Computer with advanced virtual filesystem capabilities.
• The integration relies on SQLiteWorkspaceProvider in packages/dofs/src/provider.ts extending the Platformatic VirtualProvider class.
• packages/computerd/src/fuse/vfs.ts handles prototype splicing and FUSE driver integration for consistent filesystem access.
• packages/computer/src/workspace.ts exposes the createNodeVirtualFileSystem() helper that returns a Node.js-compatible fs interface.
• Install @platformatic/vfs only when you need features like file watching or module hooks; the system falls back to a standard in-memory provider otherwise.

Frequently Asked Questions

Is @platformatic/vfs required to use Cloudflare Computer?

No. Cloudflare Computer functions without @platformatic/vfs installed. The repository includes a fallback in-memory provider that satisfies the basic fs/promises API. You only need to install the adapter when your application requires specific Platformatic VFS features such as file watching or custom module resolution.

How does the adapter handle persistence?

The adapter uses SQLiteWorkspaceProvider implemented in packages/dofs/src/provider.ts to persist filesystem data to the Durable Object's SQLite storage. This provider extends VirtualProvider from @platformatic/vfs, ensuring that all virtual filesystem operations are durably stored across requests while maintaining ACID compliance through SQLite transactions.

Can I use standard Node.js fs methods with the adapter?

Yes. The createNodeVirtualFileSystem() function in packages/computer/src/workspace.ts returns an object that implements the Node.js fs/promises API. This means methods like readFile(), writeFile(), and mkdir() work identically whether you use the default provider or the @platformatic/vfs adapter, ensuring portability across different deployment configurations.

Where is the VirtualProvider prototype splicing performed?

The prototype splicing occurs in packages/computerd/src/fuse/vfs.ts, where the SQLiteWorkspaceProvider is integrated into the VirtualProvider inheritance chain. This architectural choice allows the same provider instance to power both the programmatic JavaScript API and the FUSE-mounted filesystem visible inside containers, maintaining consistency across all access patterns.

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