Native Code and Electron | Electron

One of Electron's most powerful features is the ability to combine web technologies with native code - both for compute-intensive logic as well as for the occasional native user interface, where desired.
Electron does so by building on top of "Native Node.js Addons". You've probably already come across a few of them - packages like the famous sqlite use native code to combine JavaScript and native technologies. You can use this feature to extend your Electron application with anything a fully native application can do:
Native Node.js addons are dynamically-linked shared objects (on Unix-like systems) or DLL files (on Windows) that can be loaded into Node.js or Electron using the require() or import functions. They behave just like regular JavaScript modules but provide an interface to code written in C++, Rust, or other languages that can compile to native code.
This tutorial will walk you through building a basic Node.js native addon that can be used in Electron applications. We'll focus on concepts common to all platforms, using C++ as the implementation language. Once you complete this tutorial common to all native Node.js addons, you can move on to one of our platform-specific tutorials.
This tutorial assumes you have Node.js and npm installed, as well as the basic tools necessary for compiling code on your platform (like Visual Studio on Windows, Xcode on macOS, or GCC/Clang on Linux). You can find detailed instructions in the node-gyp readme.
To build native Node.js addons on macOS, you'll need the Xcode Command Line Tools. These provide the necessary compilers and build tools (namely, clang, clang++, and make). The following command will prompt you to install the Command Line Tools if they aren't already installed.
The official Node.js installer offers the optional installation of "Tools for Native Modules", which installs everything required for the basic compilation of C++ modules - specifically, Python 3 and the "Visual Studio Desktop development with C++" workload. Alternatively, you can use chocolatey, winget, or the Windows Store.
First, create a new Node.js package that will contain your native addon:
This creates a basic package.json file. Next, we'll install the necessary dependencies:
Now, let's update our package.json to include the appropriate build scripts. We will explain what these specifically do further below.
Node.js addons use a build system called node-gyp, which is a cross-platform command-line tool written in Node.js. It compiles native addon modules for Node.js using platform-specific build tools behind the scenes:
The binding.gyp file is a JSON-like configuration file that tells node-gyp how to build your native addon. It's similar to a make file or a project file but in a platform-independent format. Let's create a basic binding.gyp file:
Let's break down this configuration:
Now, create the directory structure for our project:
Let's start by defining our C++ interface in a header file. Create include/cpp_code.h:
The #pragma once directive is a header guard that prevents the file from being included multiple times in the same compilation unit. The actual function declaration is inside a namespace to avoid potential name conflicts.
Next, let's implement the function in src/cpp_code.cc:
This is a simple implementation that just adds some text to the input string and returns it.
Now, let's create the addon code that bridges our C++ code with the Node.js/JavaScript world. Create src/my_addon.cc:
Let's break down this code:
Now, let's create a JavaScript wrapper to make the addon easier to use. Create js/index.js:
This JavaScript wrapper:
Now we can build our native addon:
This will run node-gyp configure and node-gyp build to compile our C++ code into a .node file. Let's create a simple test script to verify everything works. Create test.js in the project root:
If everything works correctly, you should see:
To use this addon in an Electron application, you would:
Native addon development can be written in several languages beyond C++. Rust can be used with crates like napi-rs, neon, or node-bindgen. Objective-C/Swift can be used through Objective-C++ on macOS.
The specific implementation details differ significantly by platform, especially when accessing platform-specific APIs or UI frameworks, like Windows' Win32 API, COM components, UWP/WinRT - or macOS's Cocoa, AppKit, or ObjectiveC runtime.
This means that you'll likely use two groups of references for your native code: First, on the Node.js side, use the N-API documentation to learn about creating and exposing complex structures to JavaScript - like asynchronous thread-safe function calls or creating JavaScript-native objects (error, promise, etc). Secondly, on the side of the technology you're working with, you'll likely be looking at their lower-level documentation:
La Fondation OpenJS | Conditions Générales d'Utilisation | Politique de Confidentialité | Règlement intérieur | Code de Conduite | Politique de Marques Commerciales | Liste des Marques Commerciales | Politique de Cookies