Filesystem

Virtual filesystem with static trees, custom adapters, and OPFS.

Static Tree

The simplest approach — pass an array of FsNode objects. Directories have children, files don't.

static-tree.tsx
import { Terminal, type FsNode } from "@trents/terminal"

const filesystem: FsNode[] = [
  {
    name: "docs",
    description: "Documentation",
    path: "/docs",
    children: [
      {
        name: "getting-started",
        description: "Getting started guide",
        path: "/docs/getting-started",
      },
      {
        name: "api",
        description: "API reference",
        path: "/docs/api",
      },
    ],
  },
  {
    name: "blog",
    description: "Blog posts",
    path: "/blog",
  },
]

<Terminal filesystem={filesystem} onNavigate={(p) => window.location.href = p} />

When a user runs cd blog on a file node (no children), the onNavigate callback is called with its path.

Custom FileSystem

For dynamic filesystems, implement the FileSystem interface. This is used instead of the static tree.

types.ts
interface FileSystem {
  list(path: string): Promise<FsEntry[]>
  read(path: string): Promise<string>
  write(path: string, content: string): Promise<void>
  mkdir(path: string): Promise<void>
  remove(path: string): Promise<void>
  exists(path: string): Promise<boolean>
  stat(path: string): Promise<FsStat>
}

interface FsEntry {
  name: string
  type: "file" | "directory"
  size?: number
  modified?: Date
}

interface FsStat {
  type: "file" | "directory"
  size: number
  modified?: Date
  created?: Date
}

OPFS Adapter

The OPFS (Origin Private File System) adapter gives you a real, persistent filesystem in the browser using the File System Access API.

opfs.tsx
import { Terminal } from "@trents/terminal"
import { createOPFSAdapter } from "@trents/terminal/fs"

<Terminal filesystem={createOPFSAdapter()} />

Files written via echo "hello" > file.txt persist across page reloads.

Utilities

Helper functions for working with the static filesystem tree.

utilities.ts
import {
  createStaticFs,  // FsNode[] → FileSystem adapter
  resolveNode,     // Navigate to a path in the tree
  isDir,           // Check if a node has children
  urlToCwd,        // Map a URL pathname to a cwd path
} from "@trents/terminal"
0