{"id":13203,"library":"fs-jetpack","title":"fs-jetpack: Enhanced File System API","description":"fs-jetpack provides a more convenient and opinionated API for common file system manipulations, designed as an alternative to Node.js's native `fs` module and `fs-extra`. It is particularly well-suited for scripting, tooling, and build pipelines. Currently at stable version 5.1.0, the library has an active development pace with several minor and major releases in recent years, indicating ongoing maintenance and feature additions. Key differentiators include the ability to create multiple independent Current Working Directories (CWDs) for an object-oriented approach to file operations, first-class support for JSON serialization/deserialization, automatic handling of `ENOENT` errors (creating parent directories as needed and returning `undefined` for non-existent reads), and a consistent `method()` (synchronous) and `methodAsync()` (promise-based asynchronous) naming convention, which deviates from standard Node.js patterns but aims for clarity within the library.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/szwacz/fs-jetpack","tags":["javascript","fs","file system","typescript"],"install":[{"cmd":"npm install fs-jetpack","lang":"bash","label":"npm"},{"cmd":"yarn add fs-jetpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add fs-jetpack","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"fs-jetpack exports a default instance, not named exports for the main object. Use direct default import for ESM.","wrong":"import { jetpack } from 'fs-jetpack';","symbol":"jetpack","correct":"import jetpack from 'fs-jetpack';"},{"note":"Standard CommonJS import pattern. This works in older Node.js environments and CJS modules.","symbol":"jetpack (CommonJS)","correct":"const jetpack = require('fs-jetpack');"},{"note":"Import the `FSJetpack` interface for type annotations, especially when creating custom jetpack instances or extending functionality in TypeScript.","symbol":"FSJetpack (Type)","correct":"import type { FSJetpack } from 'fs-jetpack';"}],"quickstart":{"code":"import jetpack from 'fs-jetpack';\nimport path from 'path';\n\nasync function runFsJetpackExample() {\n  // Create a temporary directory for this example\n  const tempDir = jetpack.tmpDir();\n  const tempDirPath = tempDir.path();\n  console.log(`Working in temporary directory: ${tempDirPath}`);\n\n  // Write a simple text file\n  tempDir.write('hello.txt', 'Hello fs-jetpack!\\nThis is a synchronous write.');\n  console.log('Written hello.txt synchronously.');\n\n  // Write a JSON object directly\n  const data = { greet: 'World', version: '5.1.0' };\n  await tempDir.writeAsync('data.json', data);\n  console.log('Written data.json asynchronously.');\n\n  // Read the text file synchronously\n  const textContent = tempDir.read('hello.txt');\n  console.log(`Content of hello.txt: ${textContent}`);\n\n  // Read the JSON file asynchronously and parse it\n  const jsonData = await tempDir.readAsync('data.json', 'json');\n  console.log(`Content of data.json: ${JSON.stringify(jsonData)}`);\n\n  // Create a nested directory and file using chaining\n  tempDir.dir('nested/sub-folder').file('nested.txt', { content: 'This is nested!' });\n  console.log('Created nested/sub-folder/nested.txt using chaining.');\n\n  // List contents of the temporary directory\n  const contents = tempDir.list();\n  console.log('Contents of temp directory:', contents);\n\n  // Clean up the temporary directory\n  await tempDir.removeAsync('.');\n  console.log(`Cleaned up temporary directory: ${tempDirPath}`);\n}\n\nrunFsJetpackExample().catch(console.error);","lang":"typescript","description":"Demonstrates basic synchronous and asynchronous file writes and reads, JSON handling, directory creation, and the chaining API using a temporary directory."},"warnings":[{"fix":"Upgrade your Node.js environment to version 14 or newer, or pin fs-jetpack to a version older than 5.0.0 (e.g., `^4.0.0`).","message":"fs-jetpack v5.0.0 and above dropped support for Node.js engines older than v14.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review any code that relies on the exact output of `inspect()` with the `times` option and adjust for the presence of `birthTime`.","message":"`inspect(\"some-file\", { times: true })` now includes `birthTime` of a file, which might affect applications expecting a specific structure or comparing results.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use `methodAsync()` when expecting a Promise and asynchronous behavior. Use `method()` for immediate, synchronous results.","message":"The naming convention in fs-jetpack flips the common Node.js pattern: `method()` is synchronous, and `methodAsync()` is asynchronous (returns a Promise).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test file removal operations when upgrading to v5.0.0 or later, especially in environments with complex file structures or restrictive permissions.","message":"The internal implementation for recursive file removal (`remove()`/`removeAsync()`) switched from `rimraf` to Node.js native recursive file removal in v5.0.0. While generally compatible, subtle behavioral differences might exist in edge cases (e.g., permissions, symlinks).","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If you need asynchronous behavior (returning a Promise), use `jetpack.readAsync()`. If you need synchronous behavior, use `jetpack.read()`.","cause":"Attempting to call a method like `read` as an async function, when the synchronous version (`read()`) was intended, or vice-versa expecting a promise from `read()`.","error":"TypeError: jetpack.readAsync is not a function"},{"fix":"fs-jetpack provides a default export. Use `import jetpack from 'fs-jetpack';` for ESM, or `const jetpack = require('fs-jetpack');` for CommonJS.","cause":"Trying to import the main fs-jetpack instance using named import syntax for ESM.","error":"SyntaxError: Named export 'jetpack' not found (module 'fs-jetpack')"},{"fix":"Upgrade your Node.js installation to version 14 or a newer Long Term Support (LTS) release. Alternatively, use an older version of fs-jetpack (e.g., `npm install fs-jetpack@^4.0.0`).","cause":"Running fs-jetpack v5.0.0 or newer on a Node.js environment older than v14.","error":"fs-jetpack: Your Node.js version is too old. Please upgrade to Node.js v14 or newer to use this version of fs-jetpack."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}