nativefiledialog-for-bun

Cross-platform native file dialogs (Open, Save, Pick Folder) for Bun.

This library provides a high-performance, Promise-based API for native file dialogs in Bun, using a hybrid approach of FFI (Bun.dlopen) and Script Fallbacks (PowerShell, osascript, zenity) to ensure maximum compatibility and speed.

日本語のREADMEはこちら

🚀 Key Features

• Auto-Download: Automatically downloads pre-built binaries for your platform on installation.
• High DPI Support: Native Windows dialogs are now crisp and clear on 4K/high-resolution monitors (no more blurry UI).

📦 Installation

bun install nativefiledialog-for-bun

💻 Usage

import * as nfd from "nativefiledialog-for-bun";

// Open a single file
const file = await nfd.openFile({
  defaultPath: "./",
  filters: [{ name: "Images", extensions: ["png", "jpg"] }]
});
console.log(file); // "/path/to/file.png" or null if cancelled

// Open multiple files
const files = await nfd.openFiles();
console.log(files); // ["/path/1.png", "/path/2.png"] or null

// Select a folder
const folder = await nfd.pickFolder();
console.log(folder);

// Select multiple folders
const folders = await nfd.pickFolders();
console.log(folders);

// Save a file
const savePath = await nfd.saveFile({
  defaultName: "data.json",
  filters: [{ name: "JSON", extensions: ["json"] }]
});

const fileWithParent = await nfd.openFile({
  parentWindow: windowHandle // number or bigint
});

// Custom Library Path (useful for bundled apps like ElectroBun)
// Call this BEFORE any other nfd calls.
nfd.setLibraryPath("/path/to/your/bin/directory");

🛠 Platform Support

| OS | FFI Backend | Script Fallback | pickFolders | parentWindow | | --- | --- | --- | --- | --- | | Windows | Win32 API (nfd.dll) | PowerShell | ✅ | ✅ (FFI) | | macOS | AppKit (libnfd.dylib) | AppleScript | ✅ | ✅ (FFI) | | Linux | GTK3 (libnfd.so) | Zenity | ✅ | ✅ (FFI) |

[!NOTE] parentWindow support requires the FFI backend. Handlers passed to the script fallback will currently be ignored.

📜 License

This wrapper library is released under the MIT License.

Third-party Acknowledgments

This project uses the nativefiledialog-extended library for providing native dialog functionality.

nativefiledialog-extended License (zlib):

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.