How to create a Deno plugin in Rust

June 24, 2021 · 7 min read

Deno is a new JavaScript runtime built with Rust and V8 that enables you to run JavaScript outside the browser. Deno is more secure than Node.js because it limits network and file system access by default.

One of the cool things about Deno is that it enables you to write and use plugins written in Rust within Deno code. This works thanks to plugins, which can also be written in Rust.

In this tutorial, we’ll show you how to create Deno plugins in Rust. We’ll cover the following:

Why write Deno plugins in Rust?#

Plugins in Deno generally provide better performance and provide access to a wider range of tools.

Due to their performant nature, plugins are often used to perform calculations for heavy tasks such as image processing. Plugins also give you access to a variety of libraries written in other languages, including high-quality Rust crates.

Deno plugin project structure#

The plugin project structure is the same as any Deno module. For project structure, you can use this boilerplate.

git clone https://github.com/anshulrgoyal/deno-rust-starter.git my_module

First, build the Rust boilerplate for the plugin:

cd my_module/nativecargo build

Next, run a test to verify that Deno is picking up the correct library:

cd my_module/nativedeno test --unstable --allow-plugin

The boilerplate includes a Rust project in the native directory and a Deno module in the root.

Building a Rust project#

The Rust project compiles a dynamic library that is loaded by the Deno runtime. The file type and name of the library depends on the operating system. The Rust project may compile to a so file — dylib or dll — and the name of the compiled file may also be different. The boilerplate can handle three major platforms: Linux, macOS, and Windows.

[package]name = "native"version = "0.1.0"authors = ["anshul <anshulgoel151999@gmail.com>"]edition = "2018"
[lib]name = "native"crate-type = ["cdylib"]
[dependencies]deno_core = "0.75.0"

├── README.md├── deps.ts├── mod.ts├── mod_test.ts├── native│   ├── Cargo.lock│   ├── Cargo.toml│   ├── src│       └── lib.rs├── test.ts├── test_deps.ts└── tsconfig.json

The mod.ts file is the main file imported by another application using your module.

Adding Rust code#

For this tutorial, we’ll show you how to build a PNG optimizer using an oxipng crate. Every Deno plugin must export the deno_plugin_init function and register all the methods that the plugin exports.

The #[no_mangle] attribute tells the compiler not to change the name of the function:

#[no_mangle]pub fn deno_plugin_init(interface: &mut dyn Interface) { // register the function. Pass name and function to register method    interface.register_op("hello_world",hello_world);}

Creating the optimizer function#

Each exported function has the same signature. Deno plugins can only export functions. These functions can be sync or async, depending on the return type.

fn optimise(_interface: &mut dyn Interface,    zero_copy: &mut [ZeroCopyBuf],) -> Op {    // get first argument    let first=zero_copy.first().unwrap();    let opts: oxipng::Options = Default::default();    // convert vector    let result = oxipng::optimize_from_memory(&first.to_vec(), &opts).unwrap();    // move to heap so that deno can use it    Op::Sync(Box::from(result))}

The second argument of the function contains an array of buffers. Each buffer in the array represents the argument passed to the exported function when called. These buffers are serialized to strings or other data types based on requirements.

The above code takes the first element of zero_copy and passes it to optimize_from_memory. The first element of the array is the file passed to the optimize function when called from the Deno code. The file is passed as bytes. The function processes the file and returns the result as a Box. The return type is Op enum with two variants sync and async.

Build the code using the cargo build command. Now this plugin can be used in Deno.

Loading a Rust plugin in Deno#

Now that the plugin is compiled, let’s load it using Deno.

The plugin is still in development and is a part of unstable APIs, so the --unstable flag is required, as is --allow-plugin.

let path = ""// check the type of OS to load correct fileif (Deno.build.os === "linux") {// linux file emited by rust compiler  path = "./native/target/debug/libnative.so"} else if (Deno.build.os === "windows") {// windows file emited by rust compiler  path = "./native/target/debug/native.dll"} else if (Deno.build.os === "darwin") {// macos file emited by rust comipler  path = "./native/target/debug/libnative.dylib"}// load plugin from file systemconst rid = Deno.openPlugin(path);// Get available methods on plugin//@ts-Expect-Errorconst { optimise:optimise_native } = (Deno as any).core.ops();
export async function optimise(fileName: string): Promise<Uint8Array> {// reading a file  const file = await Deno.open(fileName);// getting content  const value = await Deno.readAll(file)// closing file  await Deno.close(file.rid)// running the native plugin method using Deno dispatch method  return (Deno as any).core.dispatch(optimise_native, value)}

Each plugin is loaded using the openPlugin method. Then, the ops method is used to get the method identifier, which executes the code exported by the plugin.

dispatch is used to run code exported by the native plugin. The first argument is the method identifier; the rest are passed for the native function. In this case, the file is passed.

Writing async plugins#

Since Deno is single-threaded, it’s not wise to block the main thread. Deno allows you to return a future from the native function, which you can use with OS threads to write a function that doesn’t block the main thread.

fn optimise_async(_interface: &mut dyn Interface,    zero_copy: &mut [ZeroCopyBuf],) -> Op {// get first argument    let first=zero_copy.first().unwrap();    let opts: oxipng::Options = Default::default();    let arg=first.to_vec();// create a new future    let fut = async move {// create a channel to send result once done to main thread        let (tx, rx) = futures::channel::oneshot::channel::<oxipng::PngResult<Vec<u8>>>();// create a new thread        std::thread::spawn(move || {// perform work          let result = oxipng::optimize_from_memory(&arg, &opts);// send result to main thread          tx.send(result).unwrap();        });// receive the result        let result=rx.await;// create a boxed slice        let result_box = result.unwrap().unwrap().into_boxed_slice();// return boxed slice from the future        result_box      };// return the future    Op::Async(fut.boxed())}

A future is created using the async block and returned as a boxed future. Deno handles the completion of the future and informs the Deno side of the plugin. A channel is used to communicate between the new thread and the main thread.

The Deno code doesn’t need much updating — just a new asyncHandler to handle the completion of the task:

let path = ""if (Deno.build.os === "linux") {  path = "./native/target/debug/libnative.so"} else if (Deno.build.os === "windows") {  path = "./native/target/debug/native.dll"} else if (Deno.build.os === "darwin") {  path = "./native/target/debug/libnative.dylib"}const rid = Deno.openPlugin(path);
const { optimise_async } = (Deno as any).core.ops();
export async function optimise(fileName: string){  const file = await Deno.open(fileName);  const value = await Deno.readAll(file);  await Deno.close(file.rid);// new handler  (Deno as any).core.setAsyncHandler(optimise_async, (response:any) => {    Deno.writeFile("l.png",response)  });// executing the native code.  (Deno as any).core.dispatch(optimise_async,value);}await optimise("t.png")
await Deno.close(rid);

Conclusion#

In this tutorial, we covered how to build a simple Deno plugin using Rust as well as how to create an async plugin using Rust futures and the deno_core crate.

Rust has a large ecosystem with high-quality crates. You can use all these crates in Deno by creating plugins. Whether it's an image processing plugin, database connector, etc., access to Rust plugins helps to expand the Deno ecosystem.