{"id":13202,"library":"fs-fixture","title":"File System Fixture Management","description":"fs-fixture is a JavaScript/TypeScript library designed to simplify the creation and management of temporary file system fixtures for testing purposes. Currently at version 2.13.0, the library is under active development with frequent minor and patch releases, indicating a robust and responsive maintenance schedule. Key differentiators include its extremely small footprint (1.1 kB gzipped) with no external dependencies, a simple object-based API for defining file structures, automatic resource cleanup via TypeScript 5.2+ `using` keyword, and built-in support for JSON serialization/deserialization. It inherits `fs/promises` type signatures for file operations, ensuring strong type safety and familiar API patterns. The library also supports advanced features like symlinks, binary file handling with Buffers, and a pluggable filesystem interface for custom `fs/promises`-compatible implementations.","status":"active","version":"2.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/privatenumber/fs-fixture","tags":["javascript","test","fixture","temporary","file-system","disk","json","object","template","typescript"],"install":[{"cmd":"npm install fs-fixture","lang":"bash","label":"npm"},{"cmd":"yarn add fs-fixture","lang":"bash","label":"yarn"},{"cmd":"pnpm add fs-fixture","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"fs-fixture is primarily designed for ESM environments, especially given its Node.js >=18.0.0 requirement. Named imports are correct; CommonJS `require()` may fail.","wrong":"const { createFixture } = require('fs-fixture')","symbol":"createFixture","correct":"import { createFixture } from 'fs-fixture'"},{"note":"This is the TypeScript interface for the object returned by `createFixture`, providing methods like `readFile`, `rm`, `path`, etc. Always import as a type.","symbol":"Fixture","correct":"import type { Fixture } from 'fs-fixture'"},{"note":"This type represents the object structure used to define the file system fixture, allowing you to specify nested files and directories.","symbol":"FileTree","correct":"import type { FileTree } from 'fs-fixture'"}],"quickstart":{"code":"import { createFixture } from 'fs-fixture'\n\nasync function main() {\n    // Create a temporary fixture\n    const fixture = await createFixture({\n        'package.json': JSON.stringify({ name: 'my-app' }),\n        'src/index.js': 'console.log(\"Hello world\")'\n    })\n\n    // Read files\n    const content = await fixture.readFile('src/index.js', 'utf8')\n    console.log('Content of src/index.js:', content);\n\n    // Write a JSON file\n    await fixture.writeJson('config.json', { port: 3000 });\n    console.log('config.json written.');\n\n    // Cleanup when done\n    await fixture.rm()\n    console.log('Fixture cleaned up.');\n}\nmain();","lang":"typescript","description":"Demonstrates creating a file system fixture with nested files, reading a file's content, writing a JSON file, and explicitly cleaning up the temporary directory."},"warnings":[{"fix":"Always use `await fixture.rm()` in a `finally` block or utilize the `await using fixture = ...` syntax (requires TypeScript 5.2+ and compatible runtime) for automatic disposal.","message":"Resource cleanup with `fs-fixture` is asynchronous. If not using the `using` keyword, you must explicitly call `await fixture.rm()` to prevent temporary files and directories from persisting after your tests or operations complete. Forgetting this can lead to disk space consumption and unintended side effects in subsequent runs.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure your project's Node.js runtime is version 18 or higher. Update `nvm use 18` or adjust CI/CD configurations accordingly.","message":"fs-fixture requires Node.js version >=18.0.0. Using the package with older Node.js versions may lead to runtime errors due to reliance on modern Node.js APIs and ECMAScript module (ESM) features.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade TypeScript to 5.2 or later. If using Node.js, ensure you're running a version with stable ERM support, or explicitly call `await fixture.rm()` instead.","message":"The `using` keyword for automatic resource management is a TypeScript 5.2+ feature. If your project uses an older TypeScript version or a Node.js runtime that does not yet fully support Explicit Resource Management (ERM), this syntax will cause compilation or runtime errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"When using a custom `fs` option, always define your fixture structure using a `FileTree` object instead of a string path to an existing directory.","message":"While `fs-fixture` can accept a custom `fs/promises`-compatible API for virtual filesystems, template directory sources (string paths) are generally not supported with custom filesystems as most virtual `fs` implementations lack recursive copy (`cp`) functionality.","severity":"gotcha","affected_versions":">=2.13.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project uses ES modules (`\"type\": \"module\"` in `package.json`) and import `createFixture` using `import { createFixture } from 'fs-fixture'`.","cause":"Attempting to import `createFixture` using CommonJS `require()` syntax in a project that is configured for ES modules, or if the package itself is ESM-only.","error":"TypeError: (intermediate value).createFixture is not a function"},{"fix":"Upgrade your TypeScript version to 5.2 or newer. If in Node.js, ensure your Node.js version supports ERM or fall back to explicitly calling `await fixture.rm()`.","cause":"The `using` keyword is a feature of TypeScript 5.2+ and Node.js with Explicit Resource Management (ERM). This error occurs if your environment does not support it.","error":"ReferenceError: using is not defined"},{"fix":"Verify that the path you are trying to access (`e.g., fixture.readFile('non-existent.txt')`) corresponds exactly to a file or directory specified in your `createFixture` object or template. Use `await fixture.exists('path')` to check for its presence.","cause":"Attempting to access a file or directory within the fixture that was not defined when the fixture was created, or an incorrect path was provided.","error":"Error: ENOENT: no such file or directory, open '/tmp/fs-fixture-xxxx/non-existent.txt'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}