Skip to content
wtf platform

@wtf/platform-fs-node

Documentation / @wtf/platform-fs-node

Get a folder handle of the WHATWG File System Standard on the disk in Node, and a navigator.storage to pass to Node’s platform. It passes Node’s own file system to @wtf/platform-fs-adapter, which works with any file system shaped like Node’s.

SubpathWhat you get
./handlesnodeDirectory(path, { create }): the handle of a folder on disk; nodeFileSystem, Node’s file system as the adapter takes it
./storagenodeStorage(): a navigator.storage whose root is the disk’s root, /, for nodePlatform({ fetch, storage }) of @wtf/platform-node
import { nodeDirectory } from '@wtf/platform-fs-node/handles'


const root = await nodeDirectory('out', { create: true })
const file = await root.getFileHandle('notes.md', { create: true })
await new Blob(['# Notes\n']).stream().pipeTo(await file.createWritable())

A path is relative to the process’s working folder. The handles are the adapter’s, over Node’s fs/promises, openAsBlob and the synchronous calls of node:fs, so you get:

  • snapshots that are Files on disk, read as they stream;
  • writables that write next to the file and replace it when they close, keeping its mode;
  • mode: 'exclusive', held across every process;
  • sync access to a file by createSyncAccessHandle(), through the synchronous calls of node:fs.

Whatever Node throws becomes the standard’s DOMException.

Node’s platform

nodeStorage() gives the root of the disk as navigator.storage.getDirectory(), so a program reaches every file by its path, resolved against dirs.cwd:

import { runMain } from '@wtf/platform-node/runtime'
import { readText } from '@wtf/platform-fs/files'
import { nodeStorage } from '@wtf/platform-fs-node/storage'


await runMain(
  async ({ platform }) => {
    platform.console.log(await readText(platform, 'package.json'))
  },
  { fetch, storage: nodeStorage() }
)

To extend the handles with calls of your own, as the adapter’s README shows, make the root of your class over nodeFileSystem: MyDirectoryHandle.root(nodeFileSystem, resolve(path)).

The package depends on @wtf/platform-fs-adapter, and is the one package of the file systems that imports Node’s modules. Its tests run the file system suite on a folder on disk, hold glob to Node’s own, and run the Web Platform Tests of fs/, with their known failures in test/wpt/fs.json.

Modules