https://github.com/catharacta/nativefiledialog-for-bun
Cross-platform native file dialogs (Open, Save, Pick Folder) for Bun. Supports Windows, macOS, and Linux with FFI and script fallbacks.
https://github.com/catharacta/nativefiledialog-for-bun
bun cross-platform dialog ffi file file-dialog linux macos native-file-dialog nfd-extended typescript windows
Last synced: 2 months ago
JSON representation
Cross-platform native file dialogs (Open, Save, Pick Folder) for Bun. Supports Windows, macOS, and Linux with FFI and script fallbacks.
- Host: GitHub
- URL: https://github.com/catharacta/nativefiledialog-for-bun
- Owner: Catharacta
- License: mit
- Created: 2026-03-18T13:40:34.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-18T14:45:57.000Z (3 months ago)
- Last Synced: 2026-03-19T04:49:28.720Z (3 months ago)
- Topics: bun, cross-platform, dialog, ffi, file, file-dialog, linux, macos, native-file-dialog, nfd-extended, typescript, windows
- Language: TypeScript
- Homepage:
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# nativefiledialog-for-bun
[](https://github.com/Catharacta/nativefiledialog-for-bun/actions/workflows/build-binaries.yml)
[](https://www.npmjs.com/package/nativefiledialog-for-bun)
[](https://opensource.org/licenses/MIT)
**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はこちら](./README.ja.md)
---
## 🚀 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
```bash
bun install nativefiledialog-for-bun
```
## 💻 Usage
```typescript
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](https://github.com/btzy/nativefiledialog-extended) library for providing native dialog functionality.
**nativefiledialog-extended License (zlib):**
```text
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.
```