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

> Learn how to use the @platformatic/vfs adapter with Cloudflare Computer. Enable a SQLite-backed VirtualProvider with withWorkspace() for full @platformatic/vfs API access.

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

---

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

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

```typescript
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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/provider.ts) extending the Platformatic `VirtualProvider` class.
- [`packages/computerd/src/fuse/vfs.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/vfs.ts) handles prototype splicing and FUSE driver integration for consistent filesystem access.
- [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.