# @file-services/overlay

> Overlay files and directories from one file system on top of another.

Latest version **11.1.1** (published 2026-07-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @file-services/overlay
pnpm add @file-services/overlay
yarn add @file-services/overlay
bun add @file-services/overlay
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 11.1.1 |
| Published | 2026-07-09 |
| First published | 2019-03-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 37.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Maintainers | avi.vahl, pistolpete_, cijoe |

## Links

- npm: https://www.npmjs.com/package/@file-services/overlay
- Repository: https://github.com/dazl-dev/file-services
- Issues: https://github.com/dazl-dev/file-services/issues
- npm.io page: https://npm.io/package/@file-services/overlay

## Dependencies (2)

- [@file-services/types](https://npm.io/package/@file-services/types.md) ^11.1.1
- [@file-services/utils](https://npm.io/package/@file-services/utils.md) ^11.1.1

## Recent versions

- 11.1.1 (latest) — 2026-07-09
- 11.1.0 — 2026-05-24
- 11.0.1 — 2025-09-14
- 11.0.0 — 2025-09-04
- 10.0.1 — 2025-04-07
- 10.0.0 — 2025-04-07
- 9.4.1 — 2024-08-04
- 9.4.0 — 2024-07-14
- 9.3.1 — 2024-06-09
- 9.3.0 — 2024-05-26
- 9.2.1 — 2024-04-25
- 9.2.0 — 2024-04-03
- 9.1.0 — 2024-03-18
- 9.0.0 — 2024-03-10
- 8.3.3 — 2023-11-09
- … 44 more at https://npm.io/package/@file-services/overlay/versions

## README

# @file-services/overlay

Overlay files and directories from one file system on top of another.

## Motivation

Overlay file system allows taking a native node file system ("lower fs") and overlay files and directories from an in-memory file system ("higher fs"). It can be used as a virtual layer providing a solution for storing and manipulating temporary data.

## Behavior

Read operations (`readFile`, `readdir`, `stat`, etc.) are checking higher fs first, and fallback to lower fs.

Currently, all write operations go directly to the original lower fs.

## Getting started

Install library in project:

```sh
npm i @file-services/overlay
```

Then, use the programmatic API:

```ts
import { createOverlayFs } from "@file-services/overlay";
import { createMemoryFs } from "@file-services/memory";
import { nodeFs } from "@file-services/node";

const memFs = createMemoryFs({
  src: {
    "a.txt": `A`,
    "b.txt": `B`,
  },
});

const overlayFs = createOverlayFs(nodeFs /* lower fs */, memFs /* higher fs */);

// overlayFs.readFileSync('src/a.txt', 'utf8') === 'A'
```

`createOverlayFs` also accepts a directory path as third parameter which specifies which directory in lower fs should be overlaid upon (defaults to `lowerFs.cwd()`). This is important when overlaying a memory fs over native node fs and running on Windows. Memory fs uses posix-style paths, so the base directory is where memory's root `/` begins to overlay.

## License

MIT

---
_Source: https://npm.io/package/@file-services/overlay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._