Creating a New Electron Browser Module

Welcome to the Electron API guide! If you are unfamiliar with creating a new Electron API module within the browser directory, this guide serves as a checklist for some of the necessary steps that you will need to implement.

This is not a comprehensive end-all guide to creating an Electron Browser API, rather an outline documenting some of the more unintuitive steps.

Add your files to Electron’s project configuration

Electron uses GN as a meta build system to generate files for its compiler, Ninja. This means that in order to tell Electron to compile your code, we have to add your API’s code and header file names into filenames.gni.

You will need to append your API file names alphabetically into the appropriate files like so:

  1. lib_sources = [
  2.     "shell/browser/api/electron_api_demo.cc",
  3.     "shell/browser/api/electron_api_demo.h",
  4. ]
  6. lib_sources_mac = [
  7.     "shell/browser/api/electron_api_demo_mac.h",
  8.     "shell/browser/api/electron_api_demo_mac.mm",
  9. ]
  11. lib_sources_win = [
  12.     "shell/browser/api/electron_api_demo_win.cc",
  13.     "shell/browser/api/electron_api_demo_win.h",
  14. ]
  16. lib_sources_linux = [
  17.     "shell/browser/api/electron_api_demo_linux.cc",
  18.     "shell/browser/api/electron_api_demo_linux.h",
  19. ]

Note that the Windows, macOS and Linux array additions are optional and should only be added if your API has specific platform implementations.

Create API documentation

Type definitions are generated by Electron using @electron/docs-parser and @electron/typescript-definitions. This step is necessary to ensure consistency across Electron’s API documentation. This means that for your API type definition to appear in the electron.d.ts file, we must create a .md file. Examples can be found in this folder.

Set up ObjectTemplateBuilder and Wrappable

Electron constructs its modules using object_template_builder.

wrappable is a base class for C++ objects that have corresponding v8 wrapper objects.

Here is a basic example of code that you may need to add, in order to incorporate object_template_builder and wrappable into your API. For further reference, you can find more implementations here.

In your shell/browser/api/electron_api_demo.h file:

  1. //
  2. //  electron_api_demo.h
  3. //
  4. //  Created by Danny Zhu on 10/7/22.
  5. //
  7. #ifndef ELECTRON_SHELL_BROWSER_API_ELECTRON_API_DEMO_H_
  8. #define ELECTRON_SHELL_BROWSER_API_ELECTRON_API_DEMO_H_
  9. #include <string>
  10. #include "gin/handle.h"
  11. #include "gin/wrappable.h"
  13. namespace electron {
  14. namespace api {
  16. class Demo : public gin::Wrappable<Demo>  {
  17.  public:
  18.   static gin::Handle<Demo> Create(v8::Isolate* isolate);
  19.   // gin::Wrappable
  20.   static gin::WrapperInfo kWrapperInfo;
  22.   gin::ObjectTemplateBuilder GetObjectTemplateBuilder(
  23.       v8::Isolate* isolate) override;
  25.   const char* GetTypeName() override;
  27.   //
  28.   void PrintMessage(const std::string &message);
  29. };
  31. } // namespace api
  32. } // namespace electron
  34. #endif

In your shell/browser/api/electron_api_demo.cc file:

  1. //
  2. //  electron_api_demo.cpp
  3. //  sources
  4. //
  5. //  Created by Danny Zhu on 10/7/22.
  6. //
  7. #include "shell/browser/api/electron_api_demo.h"
  9. #include <iostream>
  10. #include "gin/dictionary.h"
  11. #include "gin/object_template_builder.h"
  12. #include "shell/common/node_bindings.h"
  13. #include "shell/common/node_includes.h"
  15. namespace electron {
  16. namespace api {
  18. gin::WrapperInfo Demo::kWrapperInfo = {gin::kEmbedderNativeGin};
  20. gin::Handle<Demo> Demo::Create(v8::Isolate* isolate) {
  21.   return gin::CreateHandle(isolate, new Demo());
  22. }
  24. void Demo::PrintMessage(const std::string& message) {
  25.   std::cout << "PrintMessage " << message << std::endl;
  26. }
  28. // gin::Wrappable:
  29. gin::ObjectTemplateBuilder Demo::GetObjectTemplateBuilder(
  30.     v8::Isolate* isolate) {
  31.   return gin::Wrappable<Demo>::GetObjectTemplateBuilder(isolate).SetMethod(
  32.       "printMessage", &Demo::PrintMessage);
  33. }
  35. const char* Demo::GetTypeName() {
  36.   return "Demo";
  37. }
  39. }  // namespace api
  40. }  // namespace electron
  42. namespace {
  44. void Initialize(v8::Local<v8::Object> exports,
  45.                 v8::Local<v8::Value> unused,
  46.                 v8::Local<v8::Context> context,
  47.                 void* priv) {
  48.   gin::Dictionary dict(context->GetIsolate(), exports);
  49.   dict.Set("demo", electron::api::Demo::Create(context->GetIsolate()));
  50. }
  52. }  // namespace
  54. NODE_LINKED_MODULE_CONTEXT_AWARE(electron_api_demo, Initialize)

In your shell/common/node_bindings.cc file, add your node binding name to Electron’s built-in modules.

  1. #define ELECTRON_BUILTIN_MODULES(V)      \
  2.   V(electron_api_demo)

Note: More technical details on how Node links with Electron can be found on our blog.

Expose your API to TypeScript

Export your API as a module

We will need to create a new TypeScript file in the path that follows:

"lib/browser/api/demo.ts"

  1. const { demo } = process._linkedBinding('electron_api_demo');
  2. export default demo;

Expose your module to TypeScript

Add your module to the module list found at "lib/browser/api/module-list.ts" like so:

  1. export const browserModuleList: ElectronInternal.ModuleEntry[] = [
  2.   { name: 'demo', loader: () => require('./demo') },
  3. ];