{"id":11422,"library":"node-fzf","title":"node-fzf: Fuzzy CLI List Selector","description":"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.","status":"active","version":"0.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/talmobi/node-fzf","tags":["javascript","node-fzf","fzf","fuzzy","list","search","cli"],"install":[{"cmd":"npm install node-fzf","lang":"bash","label":"npm"},{"cmd":"yarn add node-fzf","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-fzf","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for terminal rendering and styling.","package":"picocolors","optional":false},{"reason":"Used for terminal rendering and styling.","package":"cli-color","optional":false},{"reason":"Used to handle simultaneous reading from non-TTY stdin and raw keyboard input for interactive mode.","package":"ttys","optional":false}],"imports":[{"note":"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.","wrong":"import nfzf from 'node-fzf'","symbol":"nfzf","correct":"const nfzf = require('node-fzf')"},{"note":"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.","wrong":"import { getInput } from 'node-fzf'","symbol":"nfzf.getInput","correct":"const { getInput } = require('node-fzf'); // or nfzf.getInput"}],"quickstart":{"code":"const nfzf = require('node-fzf');\n\nconst opts = {\n  list: ['apple', 'banana', 'orange', 'grape', 'strawberry', 'blueberry', 'raspberry', 'pineapple', 'mango', 'kiwi'],\n  mode: 'fuzzy',\n  query: '',\n  selectOne: false,\n  height: 50, // Use 50% of the screen height\n  prelinehook: function (index) { return `[${index + 1}] `; },\n  postlinehook: function (index) { return ` (${this.list[index].length} chars)`; }\n};\n\n(async function () {\n  console.log('Starting fuzzy search. Use Ctrl-S to switch modes, Up/Down to navigate.');\n  const result = await nfzf(opts);\n\n  const { selected, query } = result;\n\n  if (!selected) {\n    console.log(`No match found for query: '${query}'`);\n  } else {\n    console.log(`\\nSelected item: '${selected.value}' at index ${selected.index}`);\n    console.log(`Original list item: '${opts.list[selected.index]}'`);\n  }\n  process.exit(0); // Ensure the process exits after selection\n})();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"node-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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Migrate from `nfzf(list, callback)` to `await nfzf(opts)` using the promise-based API for new development and refactoring, leveraging `async/await`.","message":"The 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.","severity":"deprecated","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `const nfzf = require('node-fzf');`","cause":"Attempting to `import { nfzf } from 'node-fzf'` or `import nfzf from 'node-fzf'` in an ES Module context.","error":"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."},{"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.","cause":"Concurrent `stdout` writes from other parts of the application or external processes interfere with `node-fzf`'s terminal rendering.","error":"Output is garbled or disappears unexpectedly during interaction."},{"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)`.","cause":"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.","error":"TypeError: opts.update is not a function"},{"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.","cause":"The user did not select any item from the list, either by pressing `Escape` or by typing a query that yielded no matches.","error":"No match found for query: '...' (or selected is null)"}],"ecosystem":"npm"}