Docs Menu

Quick Start with Electron using React

On this page

  • Overview
  • Setup
  • Create Your React Application
  • Remove the web-vitals dependency
  • Install CRACO to Alter Your Webpack Configuration
  • Create a CRACO Configuration File
  • Install Electron
  • Create Your Electron Main Process File
  • Run Your Application
  • Install Realm
  • Open a Realm

This page contains information to get MongoDB Realm integrated into your Electron application quickly by developing an application using Create React App.

Before you begin, ensure you have:

Note
Version Requirement - Electron

MongoDB Realm works with any of the officially supported Electron versions. However, as Electron is constantly changing with each update, we recommend using Electron version 13.2.x for compatibility with this documentation. To see the officially supported Electron versions, check out the Electron Releases document.

Note
Version Requirement - React.js

This guide was created with support for React.js version 17.0 and Create React App version 4.0. Versions other than those may lead to errors while building the application since new dependencies are frequently added to both React.js and Create React App.

To set up an Electron application using MongoDB Realm use the following instructions:

1

Scaffold your application by using the Create React App toolchain. Enter the following command into your terminal:

npx create-react-app my_electron_react_application

Your application should include the following files. Some additional files in your project, such as CSS, service worker, and test files aren't included below.

.
|-- package.json
|-- package-lock.lock
|-- public
| |-- index.html
|-- src
| |-- App.js // renderer process
|-- |-- index.js // renderer process

Any JS file within the src directory executes on a renderer process.

Note

Each Electron application can only have one main process. The main process creates web pages. Each web page runs in its own process, known as renderer process. To learn more about this, read the official Electron Application Architecture doc.

2

Create React App version 4.0+ includes the web-vitals module. Since 'web-vitals' is designed to work with the web rather than an Electron environment, the inclusion of this module may lead to a "chunk runtime-main [entry] Cannot convert undefined or null to object" error when building the application. To avoid this error, run the following command to uninstall the web-vitals package.

npm uninstall web-vitals

Then delete the reportWebVitals.js file:

rm src/reportWebVitals.js

Finally, remove the following lines from the src/index.js file:

import reportWebVitals from './reportWebVitals';
reportWebVitals();
3

To allow your application to work properly with Electron, you have to alter your webpack configuration. By default, applications created via create-react-app use a preconfigured webpack file and hidden to the end-user. The Create React App default webpack configuration is not compatible with MongoDB Realm and you must override it. You can use CRACO to override these default values. Install CRACO with the following command:

npm install @craco/craco
4

In order to override the preconfigured webpack values, create a CRACO config file called craco.config.js at the root of your application. Add the following to this file:

const nodeExternals = require("webpack-node-externals");
module.exports = {
webpack: {
configure: {
target: "electron-renderer",
externals: [
nodeExternals({
allowlist: [/webpack(\/.*)?/, "electron-devtools-installer"],
}),
],
},
},
};

The target is set to "electron-renderer" to compile your application for browser environments for Electron built-in modules. nodeExternals is also specified to prevent all node_modules from being bundled. The allowList key in the object passed in to nodeExternals specifies a list of modules to include in the bundle, in this case electron's dev tools and webpack. In order to make use of webpack-node-externals, run the following command:

npm install webpack-node-externals --save-dev
5

To add Electron to your project, run the following command:

npm install electron --save-dev
6

The Electron main process file can be thought of as the entry point into your application. This file is responsible for loading your React App's index.html file into the BrowserWindow created by Electron.

Note

Each Electron application can only have one main process. The main process can create web pages. Each web page runs in its own process, known as a renderer process. To learn more about this, read the official Electron Application Architecture doc.

Add the following code to a new file called electron.js in the public directory:

const electron = require("electron");
const path = require("path");
const app = electron.app;
const BrowserWindow = electron.BrowserWindow;
let mainWindow;
function createWindow() {
// Create the browser window.
mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: { nodeIntegration: true, contextIsolation: false },
});
// and load the index.html of the app.
console.log(__dirname);
mainWindow.loadFile(path.join(__dirname, "../build/index.html"));
}
// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.on("ready", createWindow);

Your application should now include the following files. Some additional files in your project, such as CSS, service worker, and test files aren't included below.

.
|-- package.json
|-- package-lock.lock
|-- craco.config.js
|-- public
| |-- index.html
| |-- electron.js // main process
|-- src
| |-- App.js // renderer process
|-- |-- index.js // renderer process

All JS files within the src directory executes on the renderer process. The electron.js and any files required by it execute on the main process.

7

In order to run your application, specify a homepage and a main entry point for Electron by adding the following to your package.json file:

"main": "public/electron.js",
"homepage": "./",

Finally, add the following scripts to your package.json file:

"scripts": {
"build": "craco build",
"start": "electron ."
},

In your terminal, run npm run build and then npm run start. You should see the following:

Electron Desktop App with React
8

In your terminal, use the following command to add Realm to your project:

npm install realm

Use realm in the renderer process by adding the following to the top of the src/App.js file (you will also need to import it in whichever file you write code using Realm in):

import Realm from "realm";

Authenticate a user, define a schema, and sync enabled Realm Sync, then call Realm.open() in a file that you have imported Realm into.

Once you have opened the realm, you can write to the realm.

const app = new Realm.App({ id: "<Your App ID>" }); // create a new instance of the Realm.App
async function run() {
// login with an anonymous credential
await app.logIn(Realm.Credentials.anonymous());
const DogSchema = {
name: "Dog",
properties: {
_id: 'int',
name: "string",
age: "int",
},
primaryKey: '_id'
};
const realm = await Realm.open({
schema: [DogSchema],
sync: {
user: app.currentUser,
partitionValue: "myPartition",
},
});
// The myPartition realm is now synced to the device. You can
// access it through the `realm` object returned by `Realm.open()`
// write to the realm
}
run().catch(err => {
console.error("Failed to open realm:", err)
});
Note

For an example of writing to a realm from both the renderer and main processes, check out the realm-electron-advanced-quickstart repository.

Tip
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.