Node.js is a popular tool for running JavaScript on servers but can sometimes struggle with heavy-duty tasks. That's where Neon comes in. It's like a sidekick for Node.js, using Rust's muscle to make things run smoother and quicker.

Think of Neon as a cousin to WebAssembly (or Wasm for short). Both let you add Rust's superpowers to your project. But while Wasm changes Rust into a different language, Neon keeps it as is, turning it into the kind of code your computer uses naturally. This trick helps your project zip along faster than it would with Wasm.

One of Neon's neat tricks is that it plays nice with nearly everything Rust can do. This lets you mix Rust's swiftness and smarty-pants tools into your Node.js project to give it a boost.

We're about to take a closer look at what Neon is all about and how it can make your application zip along with the help of Rust. Let's get started!

What is Neon?

Let's explore Neon, a remarkable toolkit designed for Node.js applications to seamlessly integrate with Rust's robust capabilities. Neon serves as a bridge, allowing developers to craft native bindings—specialized libraries that are executed directly by the computer's hardware, enhancing the app's performance immensely.

As opposed to typical Node modules, which are interpreted, native bindings are pre-compiled into the machine's native language, offering a turbocharged experience for any process they engage with.

Why Neon?

Here's why Neon shines: Neon elevates your Node.js projects by allowing you to harness Rust's power—envision the raw speed, enhanced concurrency through threading, and a treasure trove of Rust’s packages. Plus, you gain direct access to libraries native to your operating system.

Craft native Node modules, akin to those you'd build with C or C++, but leave behind the complexities and potential risks that come with low-level systems programming. Neon's user-friendly CLI and its adherence to best practices pave the way for a smoother construction of native modules, freeing you from the typical encumbrances of native development.

How to create a Neon project

Starting a Neon project is really easy, but you have to make sure that you've already installed two things on your computer: Node.js and Rust. Neon needs them to work properly.

If you've got those set up, here's what you need to do next:

1. Open your terminal. This is like the command center where you type in instructions for your computer.

2. Check that you're in the place where you want your new project to be made. If not, move to the right spot using the 'cd' command (like 'cd Documents/my_projects').

3. Once you're there, type this command in the terminal and press Enter:

npm init neon my-project

After you do that, your computer will make a new folder in that spot, and it will name the folder my-project (or whatever name you choose to put at the end of that command). Make sure you don't put any spaces in the project name you choose!

The project folder will have this structure:

.
├── Cargo.toml
├── README.md
├── package.json
└── src
    └── lib.rs

Let’s take a closer look at the unique structure of our Neon project.

Neon project structure

The way a Neon project is set up is pretty neat. Think of it as a mix of two types of projects: one part is for Node.js and the other part is for a Rust library. That's the standard setup for Neon projects.

Here's where the magic happens:

• For the Rust part, you'll be working in a file called src/lib.rs. That's where you'll write your Rust code, known as "bindings." These bindings are like special translators that let Node.js understand Rust functions.

• For the JavaScript part, your files can be scattered around the project folder wherever you feel is best.

Zooming into the Rust side a bit more:

The lib.rs File:

The Rust library file contains the following code:

use neon::prelude::*;

fn hello(mut cx: FunctionContext) -> JsResult<JsString> {
    Ok(cx.string("hello node"))
}

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
    cx.export_function("hello", hello)?;
    Ok(())
}

The Rust library lib.rs file serves as a bridge between the high-performance world of Rust and the flexible environment of Node.js. Let's break it down into simpler terms:

1. Including Necessary Tools: At the very top in line one, use neon::prelude::*; is like grabbing a toolbox. This line tells Rust to bring in a bunch of tools and materials you're going to need for the rest of your code.

2. The Friendly hello Function: Lines three to five focus on a function named hello. This isn't just any function; it's special because it's made to be used directly in your JavaScript code. When you call hello from JavaScript, what you're actually getting is a friendly greeting from Rust, "hello node," which is created and sent back as a JavaScript string.

3. Setting Up the Welcome Mat with main: The chunk of code from lines seven to eleven acts as the welcome mat for your Rust functions. It sets things up so that when your JavaScript code starts running, it knows exactly where to find the hello function. It's like a signpost that says, "Hello function available here!"

Now, diving into the nitty-gritty:

• The argument cx in the hello function is your key to working with JavaScript. It lets you speak JavaScript's language from within Rust. In this case, you're using it to make a brand new string that says "hello node."

• JsResult<JsString> is a way of saying, "Hey, I'm going to give you a string, but just to be safe, I'm wrapping it in a special package that makes sure everything goes smoothly when I hand it over to JavaScript."

• The Ok(...) part is Rust's way of giving a thumbs-up, saying "All good here!" It wraps up the "hello node" string so that it's ready to be used by JavaScript without any issues.

• As for the main function, think of it as the director of a play. It's where you point out to Neon: "See that hello function? It has a part to play in our JavaScript world." And just like the hello function, cx is used here, but this time it's for attaching the hello function to the grand stage of JavaScript.

• And finally, the NeonResult<()> return type is like a guarantee sign-off. It's Rust's way of saying, "I have done my part, and everything is set up correctly for JavaScript to use."

Interacting with the Rust library in JavaScript

Great, you're ready to make your JavaScript code and Rust library work together!

To set the stage for this interaction, follow these two steps:

1. Install JavaScript Dependencies: Open your terminal and run the npm install command (or npm i for short). This command tells npm, which is like a personal shopping assistant for code, to go out and fetch all the bits and bobs your JavaScript code needs to run smoothly.

   Just type this in your terminal:

    npm i
   

2. Build the Rust Library: Once your JavaScript is all set with its dependencies, you need to compile your Rust code so it can mingle with JavaScript. For this, you'll use the command npm run build. This is like telling a builder to take all your neatly written Rust instructions and turn them into something solid and usable that JavaScript can understand.

   In your terminal, type:

    npm run build
   

After you finish that, you can try it out using Node's interactive shell.

node                                                                                                                         ─╯
Welcome to Node.js v21.4.0.
Type ".help" for more information.
> const mod = require(".")
undefined
> mod.hello()
'hello node'
>

You can also test it using a regular JavaScript file. Just make a file called index.js, paste the code given below into it, and then run node index.js.

const mod = require(".");
console.log(mod.hello());

Conclusion

In summary, Neon is a useful tool that makes Node.js projects much better by combining the strength and security of Rust. It lets you take advantage of all the cool features Rust offers. I hope this guide has made it easier for you to understand Neon.

To get a practical understanding and see the code in action, the GitHub repository for this tutorial will be your go-to resource. It houses all the code snippets we've touched upon, enabling you to review and try them out in your own environment.

And if you have any questions about using Neon to connect Node.js with Rust, feel free to ask in the comments below. Thanks for reading!