Registry / devops / node-fzf

node-fzf

JSON →
library0.14.0jsnpmunverified

node-fzf is a Node.js utility inspired by the `fzf` command-line fuzzy finder, providing an interactive CLI for list selection. It enables developers to integrate fuzzy searching capabilities into their Node.js applications, offering both a standalone CLI and a programmatic API. The current stable version is 0.14.0, published approximately 10 months ago, suggesting a maintenance or slow release cadence rather than rapid iteration. Key differentiators include its promise-based and callback-based API for integration, support for piping input and output with other CLI tools, and customizable display options like height and pre/post-line hooks. Unlike `fzf-node` which are direct Go bindings, `node-fzf` is a pure JavaScript implementation.

devopshttp-networking
npm install node-fzf
github ↗package ↗
INSTALL
IMPORT
SIG · NODE-FZF
N
node-fzf
devopsjavascriptv0.14.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

nfzf
✓ const nfzf = require('node-fzf')
✗ import nfzf from 'node-fzf'
As of v0.14.0, node-fzf is a CommonJS module and does not natively support ES Module `import` syntax. Attempting to use `import` will result in a runtime error in Node.js environments unless transpiled.
nfzf.getInput
✓ const { getInput } = require('node-fzf'); // or nfzf.getInput
✗ import { getInput } from 'node-fzf'
The `getInput` method is a property of the main `nfzf` export. It should be accessed directly from the `require`'d object or destructured after requiring the package. It does not exist as a separate named export in CommonJS.

This quickstart demonstrates the promise-based API of `node-fzf` to present an interactive fuzzy selection list to the user, allowing them to pick an item from a predefined array. It showcases basic configuration, result handling, and interactive features.

const nfzf = require('node-fzf'); const opts = { list: ['apple', 'banana', 'orange', 'grape', 'strawberry', 'blueberry', 'raspberry', 'pineapple', 'mango', 'kiwi'], mode: 'fuzzy', query: '', selectOne: false, height: 50, // Use 50% of the screen height prelinehook: function (index) { return `[${index + 1}] `; }, postlinehook: function (index) { return ` (${this.list[index].length} chars)`; } }; (async function () { console.log('Starting fuzzy search. Use Ctrl-S to switch modes, Up/Down to navigate.'); const result = await nfzf(opts); const { selected, query } = result; if (!selected) { console.log(`No match found for query: '${query}'`); } else { console.log(`\nSelected item: '${selected.value}' at index ${selected.index}`); console.log(`Original list item: '${opts.list[selected.index]}'`); } process.exit(0); // Ensure the process exits after selection })();
fzf --version
Debug
Known issues
gotchanode-fzf directly interacts with and manipulates `stdout` and `stdin` to provide its interactive CLI. This can lead to messy or corrupted output if your application is concurrently writing to `stdout` or reading from `stdin` while `node-fzf` is active.
fix
Ensure all `stdout` writes and `stdin` reads are paused or buffered while `node-fzf` is running. Execute `node-fzf` in a separate child process or pipe its output carefully if integrating with other CLI tools.
affects: >=0.1.0
gotchaThe package officially states 'windows - unable to test automatically', indicating potential instability or untested behavior on Windows operating systems. Users might encounter platform-specific issues or unexpected rendering problems.
fix
Thoroughly test `node-fzf` functionality in your specific Windows environment. Report any issues to the GitHub repository. Consider using Windows Subsystem for Linux (WSL) for a more robust experience.
affects: >=0.1.0
gotchaAs of version 0.14.0, `node-fzf` is distributed as a CommonJS module. Attempting to use ES Module `import` syntax (`import nfzf from 'node-fzf'`) in an ES Module context without proper transpilation or Node.js loader configuration will result in a runtime error.
fix
Always use `const nfzf = require('node-fzf')` for importing `node-fzf` in your Node.js projects, or ensure your build setup correctly handles CommonJS module interoperability if you are in an ESM project.
affects: <1.0.0
deprecatedThe callback-based API for `node-fzf` is less idiomatic in modern Node.js asynchronous programming. While still functional, the promise-based API is generally preferred for better error handling and readability.
fix
Migrate from `nfzf(list, callback)` to `await nfzf(opts)` using the promise-based API for new development and refactoring, leveraging `async/await`.
affects: >=0.1.0
Errors
Common errors & fixes
SyntaxError: Named export 'nfzf' not found. The requested module 'node-fzf' is a CommonJS module, which may not support all module.exports as named exports.
Attempting to `import { nfzf } from 'node-fzf'` or `import nfzf from 'node-fzf'` in an ES Module context.
fix
Change the import statement to `const nfzf = require('node-fzf');`
Output is garbled or disappears unexpectedly during interaction.
Concurrent `stdout` writes from other parts of the application or external processes interfere with `node-fzf`'s terminal rendering.
fix
Ensure `node-fzf` has exclusive control over the terminal's `stdout` and `stdin` during its operation. Avoid `console.log` calls or other terminal output from your application while `nfzf` is running. Consider piping `node-fzf` output if mixing with other CLI tools.
TypeError: opts.update is not a function
The `update` method is attached to the *list object itself* when using the array-based API (e.g., `nfzf(list, callback)`), or to the `opts.list` array when `opts` is passed to `nfzf`. It's not a global method on `nfzf` or implicitly available on a new array.
fix
Ensure you are calling `update()` on the *original list reference* that was passed to `nfzf`. For the object-based API, `opts.list.update(newList)` or if `api = nfzf(list, cb)`, then `api.update(newList)`.
No match found for query: '...' (or selected is null)
The user did not select any item from the list, either by pressing `Escape` or by typing a query that yielded no matches.
fix
Always check if `result.selected` is `null` or `undefined` after `nfzf` resolves. Provide appropriate user feedback or handle the `no selection` case gracefully in your application logic, as shown in the quickstart.
Upgrade
Version history
0.14.0latest on npm
Audit
Dependencies
picocolorsrequiredUsed for terminal rendering and styling.
cli-colorrequiredUsed for terminal rendering and styling.
ttysrequiredUsed to handle simultaneous reading from non-TTY stdin and raw keyboard input for interactive mode.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/talmobi/node-fzf ↗
packagehttps://www.npmjs.com/package/node-fzf ↗