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 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 what you need — no setup, no factory, no config:

import { putJsonFileAsync, getJsonFileAsync, atomicWriteAsync } from "@warlock.js/fs";

await putJsonFileAsync("./out/manifest.json", { version: "1.0.0" });
const manifest = await getJsonFileAsync<{ version: string }>("./out/manifest.json");

Every export is tree-shakeable. Pull in hashString alone and you’re not bundling the directory helpers.

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. It’s plain functions:

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

await atomicWriteJsonAsync(storagePath("manifest.json"), manifest);

Pair it with @warlock.js/core’s path helpers (storagePath, publicPath, etc.) when you want the framework’s path conventions.

TypeScript

Types ship with the package — no separate @types/... install. Every helper is fully typed; the JSON helpers are generic:

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

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

If you skip the generic, you get unknown — narrow it with a guard before reading fields.

Verifying the install

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

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

await putFileAsync("./.fs-check", "ok");
console.log(await getFileAsync("./.fs-check"));   // → "ok"

If that prints ok, you’re done.

Next

• Your first write — chained ensureDirectory
  • putFile + getFile walkthrough.