Native Code and Electron | Electron Ir para o conteúdo principal Electron Documentação API Blog Ferramentas * Electron Forge * Electron Fiddle Comunidade * Governança * Vitrine * Recursos Versões Português * English * Deutsch * Español * Français * 日本語 * Português * Русский * 中文 Pesquisar * Comece Agora * Processos no Electron * Boas práticas * Exemplos * Desenvolvimento * Native Node Modules * Módulos Nativos do NodeJS * Tutorial: Native Code and Electron * Native Code and Electron * Native Code and Electron: C++ (Windows) * Native Code and Electron: Swift (macOS) * Native Code and Electron: C++ (Linux) * Distribuição * Testando e Depurando * Referências * Contribuindo * * Native Node Modules * Tutorial: Native Code and Electron * Native Code and Electron Nesta página Native Code and 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: * Access native platform APIs not available in JavaScript. Any macOS, Windows, or Linux operating system API is available to you. * Create UI components that interact with native desktop frameworks. * Integrate with existing native libraries. * Implement performance-critical code that runs faster than JavaScript. 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. Tutorial: Creating a Native Node.js Addon for Electron 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. Requisitos ​ 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 . Requirements: macOS ​ 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. xcode-select --install Requirements: Windows ​ 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. Requirements: Linux ​ * A supported version of Python * make * A proper C/C++ compiler toolchain, like GCC 1. Creating a package ​ First, create a new Node.js package that will contain your native addon: mkdir my-native-addon cd my-native-addon npm init -y This creates a basic package.json file. Next, we'll install the necessary dependencies: npm install node-addon-api bindings * node-addon-api : This is a C++ wrapper for the low-level Node.js API that makes it easier to build addons. It provides a C++ object-oriented API that's more convenient and safer to use than the raw C-style API. * bindings : A helper module that simplifies the process of loading your compiled native addon. It handles finding your compiled .node file automatically. Now, let's update our package.json to include the appropriate build scripts. We will explain what these specifically do further below. package.json { "name" : "my-native-addon" , "version" : "1.0.0" , "description" : "A native addon for Electron" , "main" : "js/index.js" , "scripts" : { "clean" : "node -e \"require('fs').rmSync('build', { recursive: true, force: true })\"" , "build" : "node-gyp configure && node-gyp build" } , "dependencies" : { "bindings" : "^1.5.0" , "node-addon-api" : "^8.3.0" } , "devDependencies" : { "node-gyp" : "^11.1.0" } } These scripts will: * clean : Remove the build directory, allowing for a fresh build * build : Run the standard node-gyp build process to compile your addon 2. Setting up the build system ​ 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: * On Windows: Visual Studio * On macOS: Xcode or command-line tools * On Linux: GCC or similar compilers Configuring node-gyp ​ 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: binding.gyp { "targets" : [ { "target_name" : "my_addon" , "sources" : [ "src/my_addon.cc" , "src/cpp_code.cc" ] , "include_dirs" : [ "<!@(node -p \"require('node-addon-api').include\")" , "include" ] , "dependencies" : [ "<!(node -p \"require('node-addon-api').gyp\")" ] , "defines" : [ "NODE_ADDON_API_CPP_EXCEPTIONS" ] , "cflags!" : [ "-fno-exceptions" ] , "cflags_cc!" : [ "-fno-exceptions" ] , "xcode_settings" : { "GCC_ENABLE_CPP_EXCEPTIONS" : "YES" , "CLANG_CXX_LIBRARY" : "libc++" , "MACOSX_DEPLOYMENT_TARGET" : "10.14" } , "msvs_settings" : { "VCCLCompilerTool" : { "ExceptionHandling" : 1 } } } ] } Let's break down this configuration: * target_name : The name of your addon. This determines the filename of the compiled module (my_addon.node). * sources : List of source files to compile. We'll have two files: the main addon file and our actual C++ implementation. * include_dirs : Directories to search for header files. The cryptic-looking line <!@(node -p \"require('node-addon-api').include\") runs a Node.js command to get the path to the node-addon-api include directory. * dependencies : The node-addon-api dependency. Similar to the include dirs, this executes a Node.js command to get the proper configuration. * defines : Preprocessor definitions. Here we're enabling C++ exceptions for node-addon-api. Platform-specific settings: * cflags ! and cflags_cc!: Compiler flags for Unix-like systems * xcode_settings : Settings specific to macOS/Xcode compiler * msvs_settings : Settings specific to Microsoft Visual Studio on Windows Now, create the directory structure for our project: mkdir src mkdir include mkdir js This creates: * src/ : Where our source files will go * include/ : For header files * js/ : For our JavaScript wrapper 3. "Hello World" from C++ ​ Let's start by defining our C++ interface in a header file. Create include/cpp_code.h : # pragma once # include <string> namespace cpp_code { // A simple function that takes a string input and returns a string std :: string hello_world ( const std :: string & input ) ; } // namespace cpp_code 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 : src/cpp_code.cc # include <string> # include "../include/cpp_code.h" namespace cpp_code { std :: string hello_world ( const std :: string & input ) { // Simply concatenate strings and return return "Hello from C++! You said: " + input ; } } // namespace cpp_code 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 : src/my_addon.cc # include <napi.h> # include <string> # include "../include/cpp_code.h" // Create a class that will be exposed to JavaScript class MyAddon : public Napi :: ObjectWrap < MyAddon > { public : // This static method defines the class for JavaScript static Napi :: Object Init ( Napi :: Env env , Napi :: Object exports ) { // Define the JavaScript class with method(s) Napi :: Function func = DefineClass ( env , "MyAddon" , { InstanceMethod ( "helloWorld" , & MyAddon :: HelloWorld ) } ) ; // Create a persistent reference to the constructor Napi :: FunctionReference * constructor = new Napi :: FunctionReference ( ) ; * constructor = Napi :: Persistent ( func ) ; env . SetInstanceData ( constructor ) ; // Set the constructor on the exports object exports . Set ( "MyAddon" , func ) ; return exports ; } // Constructor MyAddon ( const Napi :: CallbackInfo & info ) : Napi :: ObjectWrap < MyAddon > ( info ) { } private : // Method that will be exposed to JavaScript Napi :: Value HelloWorld ( const Napi :: CallbackInfo & info ) { Napi :: Env env = info . Env ( ) ; // Validate arguments (expecting one string) if ( info . Length ( ) < 1 || ! info [ 0 ] . IsString ( ) ) { Napi :: TypeError :: New ( env , "Expected string argument" ) . ThrowAsJavaScriptException ( ) ; return env . Null ( ) ; } // Convert JavaScript string to C++ string std :: string input = info [ 0 ] . As < Napi :: String > ( ) ; // Call our C++ function std :: string result = cpp_code :: hello_world ( input ) ; // Convert C++ string back to JavaScript string and return return Napi :: String :: New ( env , result ) ; } } ; // Initialize the addon Napi :: Object Init ( Napi :: Env env , Napi :: Object exports ) { return MyAddon :: Init ( env , exports ) ; } // Register the initialization function NODE_API_MODULE ( my_addon , Init ) Let's break down this code: * We define a MyAddon class that inherits from Napi::ObjectWrap<MyAddon> , which handles wrapping our C++ class for JavaScript. * The Init static method: 2.1 Defines a JavaScript class with a method called helloWorld 2.2 Creates a persistent reference to the constructor (to prevent garbage collection) 2.3 Exports the class constructor * The constructor simply passes its arguments to the parent class. * The HelloWorld method: 4.1 Gets the Napi environment 4.2 Validates input arguments (expecting a string) 4.3 Converts the JavaScript string to a C++ string 4.4 Calls our C++ function 4.5 Converts the result back to a JavaScript string and returns it * We define an initialization function and register it with NODE_API_MODULE macro, which makes our module loadable by Node.js. Now, let's create a JavaScript wrapper to make the addon easier to use. Create js/index.js : js/index.js const EventEmitter = require ( 'node:events' ) // Load the native addon using the 'bindings' module // This will look for the compiled .node file in various places const bindings = require ( 'bindings' ) const native = bindings ( 'my_addon' ) // Create a nice JavaScript wrapper class MyNativeAddon extends EventEmitter { constructor ( ) { super ( ) // Create an instance of our C++ class this . addon = new native . MyAddon ( ) } // Wrap the C++ method with a nicer JavaScript API helloWorld ( input = '' ) { if ( typeof input !== 'string' ) { throw new TypeError ( 'Input must be a string' ) } return this . addon . helloWorld ( input ) } } // Export a singleton instance if ( process . platform === 'win32' || process . platform === 'darwin' || process . platform === 'linux' ) { module . exports = new MyNativeAddon ( ) } else { // Provide a fallback for unsupported platforms console . warn ( 'Native addon not supported on this platform' ) module . exports = { helloWorld : ( input ) => ` Hello from JS! You said: ${ input } ` } } This JavaScript wrapper: * Uses bindings to load our compiled native addon * Creates a class that extends EventEmitter (useful for future extensions that might emit events) * Instantiates our C++ class and provides a simpler API * Adds some input validation on the JavaScript side * Exports a singleton instance of our wrapper * Handles unsupported platforms gracefully Building and testing the addon ​ Now we can build our native addon: npm run build 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: test.js // Load our addon const myAddon = require ( './js' ) // Try the helloWorld function const result = myAddon . helloWorld ( 'This is a test' ) // Should print: "Hello from C++! You said: This is a test" console . log ( result ) Run the test: node test.js If everything works correctly, you should see: Hello from C++! You said: This is a test Using the addon in Electron ​ To use this addon in an Electron application, you would: * Include it as a dependency in your Electron project * Build it targeting your specific Electron version. electron-forge handles this step automatically for you - for more details, see Native Node Modules . * Import and use it just like any other module in a process that has Node.js enabled. // In your main process const myAddon = require ( 'my-native-addon' ) console . log ( myAddon . helloWorld ( 'Electron' ) ) References and further learning ​ 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: * Microsoft C++, C, and Assembler documentation * C++/WinRT * MSVC-170 C++ Documentation * Apple Developer Documentation * Programming with Objective-C Editar esta página Anterior Módulos Nativos do NodeJS Avançar Native Code and Electron: C++ (Windows) * Requisitos * Requirements: macOS * Requirements: Windows * Requirements: Linux * 1. Creating a package * 2. Setting up the build system * Configuring node-gyp * 3. "Hello World" from C++ * Building and testing the addon * Using the addon in Electron * References and further learning Documentação * Introdução * Referência da API Listas de verificação * Performance * Segurança Ferramentas * Electron Forge * Electron Fiddle Comunidade * Governança * Recursos * Discord * Bluesky * X * Mastodon * Stack Overflow Mais * GitHub * Open Collective * Painel de infraestrutura Direitos autorais © OpenJS Foundation e contribuidores do Electron. Todos os direitos reservados. A OpenJS Foundation possui marcas registradas e utiliza marcas comerciais. Para uma lista de marcas da OpenJS Foundation , consulte nossa Política de Marcas e Lista de Marcas . Marcas e logotipos não indicados na lista de marcas da OpenJS Foundation são marcas™™ ou marcas registradas®® de seus respectivos proprietários. O uso delas não implica qualquer afiliação ou endosso por parte deles. A OpenJS Foundation | Termos de Uso | Política de Privacidade | Estatuto | Código de Conduta | Política de Marcas | Lista de Marcas | Política de Cookies Hosting and infrastructure graciously provided by