Skip to content

Latest commit

 

History

History
140 lines (108 loc) · 5.17 KB

README.md

File metadata and controls

140 lines (108 loc) · 5.17 KB
Raw

Rusty File Dialogs for JavaScript

📂 Lets you open native file picker and message boxes in JavaScript!

👨‍💻 Uses your OS' native API
🐖 Piggy-backs on the Rusty File Dialogs project
📂 Lets you open file picker dialogs
🔔 Utility alert boxes too!

Installation

npm Yarn pnpm

You can install this package using npm, pnpm, Yarn, or your favorite npm-compatible package manager!

npm install @bindrs/rfd

If you're using Deno, you can use the new npm: specifiers to import this package straight from the npm registry. It's not possible to use an npm CDN because this package uses a .node compiled binary.

import {} from "npm:@bindrs/rfd";

🛑 This package doesn't work in the browser. It's meant to be used with Node.js, Deno, or Bun which all support .node native addons.

Support matrix
Node.js v16 Node.js v18 Node.js v20
Windows x64 ✅ ✅ ✅
Windows x32 ❌ ❌ ❌
Windows arm64 ❌ ❌ ❌
macOS x64 ✅ ✅ ✅
macOS arm64 ❌ ❌ ❌
Linux x64 gnu ✅ ✅ ✅
Linux x64 musl ❌ ❌ ❌
Linux arm gnu ❌ ❌ ❌
Linux arm64 gnu ❌ ❌ ❌
Linux arm64 musl ❌ ❌ ❌
Android arm64 ❌ ❌ ❌
Android armv7 ❌ ❌ ❌
FreeBSD x64 ❌ ❌ ❌

Want to add support for your favorite platform? Open a PR! ❤️

Usage

Node.js Deno Bun

import { homedir } from "node:os";
import { AsyncFileDialog } from "@bindrs/rfd";

const fileHandle = await new AsyncFileDialog()
  .addFilter("Images", ["png", "jpg", "jpeg"])
  .addFilter("All Files", ["*"])
  .setTitle("Pick an image")
  .setDirectory(homedir())
  .pickFile();
const path = fileHandle.path();
console.log(`You chose to open ${path}!`);
//=> You chose to open /home/jcbhmr/cool.png!

You can also open message boxes:

import { AsyncMessageDialog } from "@bindrs/rfd";

const answer = await new AsyncMessageDialog()
  .setTitle("Hello!")
  .setDescription("Click OK if you're feeling good 😊")
  .show();
if (answer) {
  console.log("You clicked OK!");
  //=> You clicked OK!
}

📚 Check out the TypeDoc website for more extensive API documentation. You can also refer to the original rfd crate documentation if you want to learn more about the features and limitations inherited from the Rust API.

Development

Rust Node.js

This project uses NAPI-RS to bridge the gap between Rust and JavaScript. Other options like Neon also work, but this seemed the simplest. To get started, you'll need the Rust toolchain installed in addition to the usual Node.js stuff. You'll also need the GTK-3 or other platform-specific libraries installed for your desktop GUI.

To quickly get setup on Ubuntu, you can run the below commands. If you're on Windows, you don't need any extra GUI libraries; those are already all included with the Windows native toolkits!

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sudo apt install libgtk-3-dev

We use a testing REPL instead of more concrete tests. This is because any concrete test we write won't work in CI because there's no GUI in GitHub Actions! 😭 It's better to just tinker around with it in a REPL.

npm run test:repl