Installation

@warlock.js/fs is standalone. It has no runtime dependencies beyond Node’s built-in node:fs and node:crypto. Requires Node 18 or newer (uses cp with the recursive option from node:fs/promises).

Standalone

Install with your package manager:

yarn

yarn add @warlock.js/fs

npm

npm install @warlock.js/fs

pnpm

pnpm add @warlock.js/fs

Then import the fs object — no setup, no factory, no config:

import { fs } from "@warlock.js/fs";

await fs.files.putJson("./out/manifest.json", { version: "1.0.0" });
const manifest = await fs.files.getJson<{ version: string }>("./out/manifest.json");

That’s the whole entry point: one import, and the entire filesystem toolkit is on fs.

Warlock.js

@warlock.js/fs is a dependency of @warlock.js/core, so any Warlock project already has it on the dependency graph. If your package.json doesn’t list it directly, add it so you get a stable version pin:

yarn

yarn add @warlock.js/fs

npm

npm install @warlock.js/fs

pnpm

pnpm add @warlock.js/fs

Use it the same way as the standalone setup — no framework wiring, no config file, no connector. Pair it with @warlock.js/core’s path helpers when you want the framework’s path conventions:

import { fs } from "@warlock.js/fs";
import { storagePath } from "@warlock.js/core";

await fs.files.putJson(storagePath("manifest.json"), manifest, { atomic: true });

TypeScript

Types ship with the package — no separate @types/... install. Every method is fully typed, and the JSON reads are generic:

type Manifest = { version: string; files: string[] };

const manifest = await fs.files.getJson<Manifest>("./manifest.json");
//    ^? Manifest

Skip the generic and you get unknown — narrow it with a guard, or pass a schema to getJson to validate and type in one step (see Read and write files).

Verifying the install

A one-liner to prove it’s wired up:

import { fs } from "@warlock.js/fs";

await fs.files.put("./.fs-check", "ok");
console.log(await fs.files.get("./.fs-check"));   // → "ok"

If that prints ok, you’re done.

Need synchronous, tree-shakeable functions?

The fs facade is async by design. Synchronous callers — CLI tools, code generators — and bundles that want to pull in a single operation can drop to the low-level primitives (putFile, getFile, hashString, …), which are individually tree-shakeable. For app code, reach for fs first.

Next

• Your first write — write JSON, read it back typed, and grab a lazy file handle, all through the fs facade.