(DOCSP-11147): Initted Realm Electron Quickstart Doc

source/examples/QuickStarts/electron/quickstart-main.js

@@ -0,0 +1,56 @@
+const { app, BrowserWindow, ipcMain } = require("electron");
+const Realm = require("realm");
+
+function createWindow() {
+  const mainWindow = new BrowserWindow({
+    webPreferences: {
+      nodeIntegration: true,
+    },
+  });
+
+  mainWindow.loadFile("index.html");
+}
+
+app.whenReady().then(() => {
+  const realmApp = new Realm.App({ appId: "<Your App ID>"}); // Replace <Your App ID> with your application id
+  let credentials = Realm.Credentials.anonymous();
+  // log in anonymously
+  let user = await realmApp.logIn(credentials);
+
+  const PersonSchema = {
+    name: 'Person',
+    properties: {
+      _id: 'objectId',
+      name: 'string'
+    },
+    primaryKey: '_id',
+  };
+
+  const config = {
+    schema: [PersonSchema],
+    path: "myrealm.realm",
+    sync: {
+      user: user,
+      partitionValue: "My Partition"
+    }
+  };
+  // open a synced realm
+
+  const realm = await Realm.open(config)
+
+
+  // when receiving an "asynchronous-message" from the renderer process,
+  // upload all local changes to the synced realm
+
+  ipcMain.on("asynchronous-message", (event, arg) => {
+
+    if (arg === "sync") {
+      console.log("Syncing all local changes");
+
+      realm.syncSession.uploadAllLocalChanges();
+
+    }
+  });
+
+  createWindow();
+});

source/examples/QuickStarts/electron/quickstart-renderer.js

@@ -0,0 +1,45 @@
+const { ipcRenderer } = require("electron");
+const Realm = require("realm");
+const ObjectId = require("bson").ObjectId;
+
+async function run() {
+  const realmApp = new Realm.App({ id: "<Your App ID>" }); // Replace <Your App ID> with your application id
+  let credentials = Realm.Credentials.anonymous();
+  // log in anonymously
+  let user = await realmApp.logIn(credentials);
+
+  var PersonSchema = {
+    name: "Person",
+    properties: {
+      _id: "objectId",
+      name: "string",
+    },
+    primaryKey: "_id",
+  };
+
+  const config = {
+    path: "myrealm.realm",
+    schema: [PersonSchema],
+    sync: true,
+  };
+
+  // open a non synced realm
+
+  const realm = new Realm(config);
+
+  const personList = realm.objects("Person");
+
+  // create a new "Person"
+  realm.write(() => {
+    john = realm.create("Person", {
+      _id: new ObjectId(),
+      name: "John Smith",
+    });
+  });
+
+  // Sending a request for sync to main
+
+  ipcRenderer.send("asynchronous-message", "sync");
+}
+
+run();

source/examples/QuickStarts/electron/quickstart-setup-main.js

@@ -0,0 +1,20 @@
+const electron = require("electron");
+const Realm = require("realm");
+
+const { app, BrowserWindow } = electron;
+
+function createWindow() {
+  // Create the browser window.
+  const win = new BrowserWindow({
+    width: 800,
+    height: 600,
+    webPreferences: {
+      nodeIntegration: true,
+    },
+  });
+
+  // and load the index.html of the app.
+  win.loadFile("index.html");
+}
+
+app.whenReady().then(createWindow);

source/examples/QuickStarts/electron/quickstart-setup-react-cracoconfig.js

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

source/examples/QuickStarts/electron/quickstart-setup-react-electron.js

@@ -0,0 +1,24 @@
+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 },
+  });
+  // 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);

source/includes/steps-realm-with-electron-using-create-react-app.yaml

@@ -0,0 +1,135 @@
+title: Create Your React Application
+ref: create-your-react-application
+content: |
+  Scaffold your application by using the `Create React App
+  <https://reactjs.org/docs/create-a-new-react-app.html>`_ toolchain.
+  Enter the following command into your terminal:
+
+  .. code-block:: shell
+
+     npx create-react-app my_electron_react_application
+
+---
+title: Install CRACO to Alter Your Webpack Configuration
+ref: install-craco
+content: |
+  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 {+service+} and you must override it. Using `CRACO
+  <https://www.npmjs.com/package/@craco/craco>`_ you can override these
+  default configurated values. Install CRACO with the following command:
+
+  .. code-block:: shell
+
+     npm install @craco/craco
+
+---
+title: Create a CRACO Configuration File
+ref: create-craco-config
+content: |
+  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:
+
+  .. literalinclude:: /examples/QuickStarts/electron/quickstart-setup-react-cracoconfig.js
+
+  The `target <https://webpack.js.org/configuration/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. Here, webpack
+  and the electron-devtools are included in the bundle. In order to make
+  use of webpack-node-externals, run the following command:
+
+  .. code-block:: shell
+
+     npm install webpack-node-externals --save-dev
+
+---
+title: Install Electron
+ref: install-electron
+content: |
+  To add Electron to your project, run the following command:
+
+  .. code-block:: shell
+
+     npm install electron --save-dev
+
+---
+title: Create Your Electron Main Process File
+ref: create-your-electron-main-process
+content: |
+  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 <https://www.electronjs.org/docs/tutorial/application-architecture>`_
+     doc.
+
+  Add the following code to a new file called ``electron.js`` in the
+  ``public`` directory:
+
+  .. literalinclude:: /examples/QuickStarts/electron/quickstart-setup-react-electron.js
+
+---
+title: Run Your Application
+ref: run-your-app
+content: |
+  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: 
+
+  .. code-block:: shell
+
+     "main": "public/electron.js",
+     "homepage": "./",
+
+  Finally, add the following scripts to your ``package.json`` file:
+
+  .. code-block:: shell
+
+     "scripts": {
+       "build": "craco build",
+       "start": "electron ."
+     },
+
+  In your terminal, run ``npm run build`` in one tab and ``npm run
+  start`` in another tab. You should see the following:
+
+  .. cssclass:: bordered-figure
+  .. figure:: /images/electron-cra.png
+    :alt: Electron Desktop App with React
+
+---
+title: Install Realm
+ref: install-realm
+content: |
+  In your terminal use the following command to add Realm to your project:
+
+  .. code-block:: shell
+
+     npm install realm@beta
+
+  You can now begin using Realm in either the renderer processes or the
+  main process. 
+
+  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):
+
+  .. code-block:: shell
+
+     import Realm from "realm";
+
+  Use Realm in the main process by adding the following to the top of the ``public/electron.js`` file:
+
+  .. code-block:: shell
+
+     const Realm = require("realm");

source/includes/steps-realm-with-electron.yaml

@@ -0,0 +1,95 @@
+title: Set up Your Application Files
+ref: setup-application-files
+content: |
+  To begin developing your application, create an application directory:
+
+  .. code-block:: shell
+
+     mkdir myElectronApplication
+
+  Create an index.html and main.js file in the root directory of
+  your application. The code in the main.js file is the Electron main
+  process file, which can be thought of as the entry point into your
+  application. The main.js file is responsible for loading your
+  index.html file into the BrowserWindow created by Electron.
+
+  .. 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 a ``renderer process``. To learn more about
+     this, read the official `Electron Application
+     Architecture <https://www.electronjs.org/docs/tutorial/application-architecture>`_
+     doc.
+---
+title: Set up a ``package.json``
+ref: setup-packagejson
+content: |
+  Initialize a package.json to begin installing packages and using them
+  in your project. Run the following command in your terminal:
+
+  .. code-block:: shell
+
+     npm init -y
+---
+title: Install Your Project Dependencies
+ref: install-dependencies
+content: |
+  In order to begin developing your Electron Application that uses
+  Realm, install the necessary dependencies. Install electron as a dev
+  dependency by running the following command:
+
+  .. code-block:: shell
+
+     npm install electron --save-dev
+
+  Install Realm by running the following command:
+
+  .. code-block:: shell
+
+     npm install realm@beta
+
+---
+title: Create a Script to Run Your Application
+ref: create-script-to-run-app
+content: |
+  Add a script to your ``package.json`` file to run your application.
+
+  .. code-block:: json
+
+     "scripts": {
+      "start": "electron ."
+     }
+
+  Running the command ``npm start`` will now start your Electron app.
+---
+title: Create a Browser Window Using Your Main Process
+ref: create-browser-window
+content: |
+  In order to display HTML to the users, your application needs a
+  browser window. Create a `browser window
+  <https://www.electronjs.org/docs/api/browser-window>`_ using the
+  Electron API. Copy the following code into your ``main.js`` file:
+
+  .. literalinclude:: /examples/QuickStarts/electron/quickstart-setup-main.js
+    :language: javascript
+    :emphasize-lines: 2, 8
+    :linenos:
+
+  Notice the ``require("realm")`` on line 2. This line makes Realm
+  accessible in this main process file.
+---
+title: Run Your Application
+ref: run-electron-app
+content: |
+  In order to run your application, enter the following into your terminal:
+
+  .. code-block:: shell
+
+     npm start
+
+  You should see the following:
+
+  .. cssclass:: bordered-figure
+  .. figure:: /images/electron-app.png
+    :alt: Electron Desktop App