file-utils is a Node.js library offering a set of synchronous file system utilities, derived from Grunt.file. It is primarily designed for command-line interface tools and user utilities, with explicit warnings against its use in Node.js server environments due to its blocking I/O nature. The package enables the creation of scoped file environments (`createEnv`) that automatically prefix paths for file operations, providing isolated contexts for managing files. It also supports "write filters" and "validation filters" which can modify file content/paths or control write actions, respectively. Filters can be asynchronous, which subsequently makes the `write` and `copy` methods asynchronous. The current stable version is 0.2.2, with its latest release focusing on internal cleanup and import performance improvements. Its release cadence is infrequent, and major changes between 0.1.x and 0.2.x primarily involved Node.js version support and the handling of file content types within filters.
npm install file-utilsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a scoped file utility environment, write and read files synchronously, register a write filter to modify content, and clean up resources.
Upgrade Node.js to version 0.10.0 or higher, or explicitly use 'file-utils@~0.1.0'.
Use this library only for command-line tools or one-off scripts where synchronous operations are acceptable or desired. For server-side applications, opt for asynchronous file system utilities (e.g., Node.js built-in `fs.promises` or `fs` with callbacks).
Update filter functions to check `typeof file.contents` or `Buffer.isBuffer(file.contents)` and handle string and buffer content types appropriately (e.g., `file.contents.toString('utf8')` for buffers, or `Buffer.from(file.contents)` for strings if needed).If an async filter is used, ensure that calls to `env.write` and `env.copy` are handled asynchronously. For example, if `this.async()` is used in a filter, the consumer of `env.write` must treat it as a function returning a Promise or accepting a callback.
Ensure the user running the Node.js script has read/write/delete permissions for the target files and directories. On Linux/macOS, check file permissions with `ls -l` and use `chmod` to grant access if necessary.
Install the package using `npm install file-utils` or `yarn add file-utils`. Ensure your `node_modules` directory is correctly set up.
Modify the filter to check the type of `file.contents` before processing. If it's a Buffer, convert it to a string first (e.g., `file.contents.toString('utf8')`) if string manipulation is intended, or handle it as a Buffer directly.Ensure that `this.async()` is only called within an asynchronous filter function where `this` refers to the correct context provided by file-utils. The filter function itself needs to explicitly handle its asynchronous nature and pass the result to the provided callback (e.g., `done({ path, contents })`).No dependency data recorded yet.