Unfortunately I don't think I have many resources to point to other than some of Electron's documentation, but I'm more than happy to be a resource and give advice, etc., and I think having a migration guide would be awesome. I did it in many steps spread over quite a long time, so I can try to reproduce them here, but it'll just be a starting point since I'm sure I'll mis-remember/mis-represent some stuff.

Also, I started this migration with the goal of turning off nodeIntegration and turning on contextIsolation purely for security posture reasons, nothing to do with Ember/Vite, and then realized that it got me much closer to Ember/Vite, so continued through the remaining steps. So, some steps might not be strictly necessary, but also this migration will get your app in line with several of Electron's key security best practices and, IMO, massively improve the developer experience.

Background

The main areas of complexity this change/migration addresses that pave the way for a cleaner integration between the Ember app and the Electron app are the build tooling and the webapp route/resource loading.

In the build tooling, it's a big pain to have the Electron build and the Ember build intertwined into a single command, and it's a big pain for all the Ember build tooling to have to understand that it's not running in a browser and that Node.js and Electron APIs exist, and it's a huge pain to make Ember's AMD module loading and Node's CJS module loader (both of which rely on a global symbol named require()) work together.

In the webapp routing/resources realm, loading the app using the file: protocol makes things difficult because normal webapp routing doesn't work (you can't append a URL path to file://whatever/wherever/index.html, so the Ember app has to use the hash router), asset loading is funky (for the same reason -- relative subpaths of a file: origin just don't work), and web browsers disable a bunch of security controls when loading via the file: protocol which isn't necessarily problematic, but isn't ideal for production applications.

Migration

The steps I'd recommend are:

1. Starting using @electron-forge/plugin-vite

Why

This probably isn't strictly necessary, but having a build system for your preload script (see below) rather than having to make it just a single .js file is a big win. Additional benefits:

Allows you to port your main process code to TypeScript if you want
Allows bundling of the main process Node.js dependencies rather than having to include them in the Electron bundle in node_modules, which eventually unblocks the ability to make the Electron app a part of a yarn >1 or pnpm monorepo/workspace, rather than a weird package-within-a-package like with ember-electron

How

I created a new Electron app using the vite + typescript template (you can use the vite template if you don't care about being able to write your main process or preload script code in TypeScript), and then compared it to my electron-app and figured out how to merge the two.

Notably, I added a build for the main process when running in test mode, commented out the preload script build (because I didn't have a preload script yet), and made the renderers be an empty list (to not try to build any). My forge/vite plugin config in this step ended up looking like (I also ported all my main process code to typescript, but some/all of this could be .js files as well):

    new VitePlugin({
      build: [
        // The main process code
        {
          entry: 'src/index.ts',
          config: join(__dirname, 'vite.main.config.ts'),
        },
        // The main process code when running Ember tests via `ember
        // electron:test`
        {
          entry: 'src/test-ember.ts',
          config: join(__dirname, 'vite.main.config.ts'),
        },        
        // {
        //   entry: 'src/preload.ts',
        //   config: path.join(__dirname, 'vite.preload.config.ts'),
        // },
      ],
      // Don't build the renderer, the Ember tooling handles that
      renderer: [],
    })

Note: The main process gets bundled into a single file that ends up in .vite/build/index.js, which has a couple implications:

You'll need to make sure your packagerConfig includes (doesn't exclude) that file when packaging the Electron app
If you use __dirname or the like in any of your main process source files, it will resolve to .vite/build rather than whatever folder the source file lives in, so you'll have to update any such path constructions

I also had to apply a patch to ember-electron to keep it working with this setup:

diff --git a/lib/test-runner.js b/lib/test-runner.js
index dec558affaf861079ad2d5c800093c2833fc5a28..a872d0ec8d10d414efd035b3ac68114f8b23ee42 100644
--- a/lib/test-runner.js
+++ b/lib/test-runner.js
@@ -41,7 +41,7 @@ async function main() {
   // Start electron
   let { pid } = await api.start({
     dir: path.join(process.cwd(), electronProjectPath),
-    appPath: './tests',
+    appPath: './.vite/build/test-ember.js',
     args: [
       '--', // needed because https://github.com/electron/electron/pull/13039
       testPageUrl,
diff --git a/lib/utils/prepare-run-command.js b/lib/utils/prepare-run-command.js
index e0ca3a9f3acccb2be60f73f6e6eb2684ba35816f..c0e6a2dbe4125aad6330cc2de489e78c1f57f093 100644
--- a/lib/utils/prepare-run-command.js
+++ b/lib/utils/prepare-run-command.js
@@ -27,4 +27,10 @@ module.exports = async function prepareRun(project) {
   process.env.EMBER_CLI_ELECTRON = true;
 
   await Win.checkIfSymlinksNeedToBeEnabled(project.ui);
+
+  // electron forge loads its configs using `ts-node`, but by default `ts-node`
+  // will use the tsconfig.json in the current working directory, which is the
+  // Ember app's, not the Electron app's. So set an environment variable to
+  // override this.
+  process.env.TS_NODE_PROJECT = electronProjectPath;
 };

2. Create a preload script

(if you don't already have one)

Why

You'll need a preload script to install an API in your renderer process that gives it access to the platform APIs & resources (Node/Electron) it needs. You can read about it here, but note that in this step you're not turning context isolation on yet.

How

Create a src/preload.js or src/preload.ts, uncomment the preload section of your new VitePlugin() config (see #1 above), and put preload: <path to built preload script> in the webPreferences of all your new BrowserWindow() calls. The path to the built preload script should probably be path.join(__dirname, preload.js) since the bundled main process code that contains your new BrowserWindow() calls and the bundled preload script both get emitted into the same folder (.vite/build).

You can leave the preload script empty, or to validate that this step is working, populate it with something like

window.electronAPI = {};

(which works because context isolation is still disabled), and then run the app and check that in the Ember app, window.electronAPI is defined as {}.

3. Move all of your Node/Electron API calls to the preload script

Why

This is the point of preload scripts -- rather than your code having access to every Node and Electron API, which is both a security risk and a pain for the build tooling to manage, your preload script exposes the functionality your app needs using a custom API on the window object. Build tooling isn't bothered at all by the Ember app calling window.electronAPI.doSomething(), whereas it's very bothered by it calling require('some-dependency-in-node-modules').doSomething(). Plus then if some malicious code infiltrates your app, it doesn't have access to the full set of Node and Electron APIs, limiting its harm.

How

This is a big one. You have to hunt around your app and find all the places that it does something that it's not allowed to do in a web browser, and then rewrite that functionality as a method that the preload script exposes, e.g.

const { readFileSync } = require('node:fs');

window.electronAPI = {
  // Instead of require('fs').readFileSync('foo.txt')
  readFooTxt() {
    return readFileSync('foo.txt')
  }
};

Of course the API design is up to you -- maybe instead you expose a function that accepts a path as an argument and calls readFileSync() on that path (more flexible -- don't need a separate API method for each file the app needs to read, less secure -- allows malicious code access to the entire filesystem rather than just the files the app needs to be able to access).

This works similarly for Node.js dependencies in node_modules -- instead of just Node-CJS-requiring them from the Ember app, you can import them into the preload script and then wrap them in functions on electronAPI.

This also works the same for Electron dependencies, including IPC calls.

You can also of course expose your APIs on multiple window.whatever objects rather than all on one, but I have never seen much benefit to that.

All in all, this step may be the bulk of the work in this migration.

Note that you can organize your code into multiple files because you're using Vite to bundle your preload script, so it will get compiled into a single file, meeting Electron's requirement that the preload script be a single module.

4. Disable nodeIntegration (optional)

Why

You don't technically need to do this for the migration, but now that you've removed all usage of Node APIs from the Ember app, you may as well disable them entirely since they aren't providing you any benefit and are purely a security risk.

How

Remove nodeIntegration: true from all of your new BrowserWindow() webPreferences (of if you're on Electron <5 when true was the default, you'll have to explicitly set it to false. Also tell 2019 I said hi, and to get ready for a rough couple of years).

5. Enable contextIsolation (optional)

Why

See https://www.electronjs.org/docs/latest/tutorial/context-isolation

You don't technically need to do this for the migration, but it's a significant security win, and it's probably not much extra effort once you've gotten this far in the migration.

How

In your preload script, change

window.electronAPI = {
  // functions
};

const { contextBridge } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  // functions
});

and then remove contextIsolation: false from all of your new BrowserWindow() webPreferences (of if you're on Electron <12 when false was the default, you'll have to explicitly set it to true. And tell 2021 I said hi, and to stay strong, it's gonna get better real soon).

For the most part it should "just work" except that now all arguments to the functions you expose, return values from them, and errors thrown by them, will be serialized and passed across the context bridge, which comes with some caveats.

6. Serve the app from a custom protocol

Why

Using the file: protocol is a security risk, and also makes Ember app routing and asset loading complicated because the webapp's origin is an absolute file: URL pointing to index.html, so you can't just append sub-paths to it to point to webapp sub-routes, or to assets that the webapp needs to load.

How

Electron's documentation shows how to set up a custom protocol handler, which is the mechanism to use. You may already be using a handleAppUrls() from ember-electron's blueprint -- this would replace that if so, but either way you need this. Mine ended up looking something like:

import { net, protocol } from 'electron';

protocol.handle('app', async (req) => {
  const webappRootPath = path.join(__dirname, '../../ember-dist');
  const url = new URL(req.url);

  if (url.host === 'renderer') {
    // Strip off the leading `/` and decode it in case it contains URL-encoded
    // characters like spaces
    const requestPath = decodeURI(url.pathname.substring(1));

    // Webapp path handler
    if (requestPath.startsWith('webapp/')) {
      return await net.fetch(
        pathToFileURL(path.join(webappRootPath, 'index.html')).toString(),
      );
    }

    // Otherwise treat it as a filesystem path
    const absPath = path.resolve(webappRootPath, requestPath);
    if (isInside(absPath, webappRootPath)) {
      try {
        return await net.fetch(pathToFileURL(absPath).toString());
      } catch {
        // It could be other reasons that the file doesn't exist, but we don't
        // really care about the distinction right now
        return new Response('Not found', {
          status: 404,
          headers: { 'content-type': 'text/html' },
        });
      }
    } else {
      return new Response('bad', {
        status: 400,
        headers: { 'content-type': 'text/html' },
      });
    }
  } else {
    return new Response('Host not found', {
      status: 400,
      headers: { 'content-type': 'text/html' },
    });
  }
});

/**
 * Given an absolute path and the path to a root folder, make sure the absolute
 * points inside the root folder.
 */
function isInside(absPath: string, rootPath: string) {
  let relPath = path.relative(rootPath, absPath);
  return (
    // It doesn't point to the root (not sure if this really matters, but it's
    // in the Electron sample code)
    relPath &&
    // It doesn't point to a parent directory
    !relPath.startsWith('..') &&
    // It doesn't resolve to an absolute path
    !path.isAbsolute(relPath)
  );
}

This sets up app://renderer/webapp as the base URL of the webapp, makes it so that absolute paths such as <img src="/foo.jpg"> get resolved relative to ember-dist (as they would if it was served from a web server), and also makes sure HTTP requests can't use relative paths or some such mechanism to reach outside the ember-dist folder.

Then you'll need to:

update all of your BrowserWindow#loadUrl calls to pass app://renderer/webapp as the URL to load (or if you are loading an Ember route other than /, append the path to the end, e.g. app://renderer/webapp/login or app://renderer/webapp/landing-page)
in your config/environment, set rootUrl: '/', routerRootURL: '/webapp/', and locationType: 'history'

7. Migrate off of `ember-electron`

Why

Cuz it's the whole point of this!

How

The key points that make this step possible are that the Ember app is now just a regular ol' webapp that can be served over HTTP by a web server and loaded directly from the renderer process via an http: URL, but can also be served from the filesystem by the main process via the custom protocol handler. This means that when the app is packaged, we can point the renderer at the production-bundled Electron-packaged in-filesystem Ember app, and in dev mode we can point the render process directly at a dev server (ember-cli's or, eventually, Vite's) or, if we want, at a bundled in-filesystem Ember app (e.g. the contents of the dist/ folder after running ember build or vite build).

The pattern that I came up with was to allow an environment variable to point the Electron main process at the Ember app, either via a file: URL, indicating that it should serve it out of the filesystem via the main process, or via an http URL, indicating that it should point the renderer directly at an HTTP (dev) server.

Here's some code I threw together to enable this:

import { app } from 'electron';
import path from 'node:path';
import { appRoot } from './app-paths.js';
import { fileURLToPath } from 'node:url';

/**
 * The origin that our webapp will be loaded from in the renderer windows when
 * running against an in-filesystem version of the Ember app. This is handled
 * via a custom protocol handler set up in `handle-app-urls.ts`.
 */
const filesystemWebappLoadOrigin = 'app://renderer';

/**
 * The filesystem path to the Ember app when running in a packaged app.
 */
const packagedWebappServeDirectory = path.join(__dirname, '../../ember-dist');

/**
 * Get the load origin and serve directory when running in development mode.
 */
function getDevModeWebappInfo() {
  const webappLocation = process.env.ELECTRON_WEBAPP_LOCATION;

  if (!webappLocation) {
    throw new Error('ELECTRON_WEBAPP_LOCATION must be set in development');
  }

  if (new URL(webappLocation).protocol === 'file:') {
    // The webapp location is a file URL, so set the load origin to the
    // filesystem origin (so it goes through the custom protocol handler) and
    // set the serve directory to the path pointed to by the file URL (so the
    // custom protocol handler can find the files to serve).
    return {
      loadOrigin: filesystemWebappLoadOrigin,
      serveDirectory: fileURLToPath(webappLocation),
    };
  } else {
    // It's not a file URL, so presumably an HTTP URL. Point the webapp load
    // origin to that URL, and set the serve directory to null since we'll be
    // loading it via a web server rather than from the filesystem.
    return {
      loadOrigin: webappLocation,
      serveDirectory: null,
    };
  }
}

/**
 * Get info about the webapp -- the origin that the renderer windows will load
 * it from, and the filesystem directory we're serving it from (if any). We have
 * two scenarios:
 *
 * 1. Loading the Ember app from the filesystem, in which case it's loaded via
 *    our custom `app://renderer` protocol that serves files from the
 *    filesystem.
 * 2. Loading the Ember app from a web server, in which case it's loaded
 *    directly via the URL of that web server.
 *
 * In production, we only allow (1) for security reasons, but in development we
 * allow both. We require that the `ELECTRON_WEBAPP_LOCATION` environment
 * variable is set in development, and it can either be set to a file URL
 * pointing to the Ember app's location in the filesystem, or to the URL of a
 * web server serving the Ember app.
 */
function getWebappInfo() {
  return app.isPackaged
    ? {
        loadOrigin: filesystemWebappLoadOrigin,
        serveDirectory: packagedWebappServeDirectory,
      }
    : getDevModeWebappInfo();
}

/**
 * The origin from which we have the renderer windows load the Ember app. This
 * will be `app://renderer` in production, but in development it can be either
 * `app://renderer` or a custom URL of a web server depending on the
 * `ELECTRON_WEBAPP_LOCATION` environment variable.
 */
export function getWebappLoadOrigin() {
  return getWebappInfo().loadOrigin;
}

/**
 * The filesystem directory we're serving the Ember app from, or null if we're
 * serving it from a web server. This will be the path to the Ember app bundle
 * embedded in the application in production, but in development it can be a
 * path to an Ember app bundle, or null if we're loading the Ember app from a
 * web server.
 */
export function getWebappServeDirectory() {
  return getWebappInfo().serveDirectory;
}

and then ${getWebappLoadOrigin()}/webapp can replace app://renderer/webapp when calling BrowserWindow#loadUrl, and in the protocol.handle() code from step 7, you can replace the hard-coded const webappRootPath = ... with getWebappServeDirectory() (with a null check or something).

Then to run the app in dev mode (instead of ember electron), you run ember serve inside the Ember app, and in electron-app, run ELECTRON_WEBAPP_LOCATION="http://localhost:4200" yarn electron-forge start.

To run the tests (with the Ember dev server running) (instead of ember electron:test -s), you run pnpm electron-forge start --app-path .vite/build/test-ember.js -- http://localhost:4200/tests.

To get tests running in CI via testem, I made my testem.js look like this:

'use strict';

module.exports = {
  // <standard testem args>

  // When we run under testem, we build into dist-tests (see the test script in
  // package.json), so set testem's cwd to dist-tests so its dev server will
  // serve files from there
  cwd: 'dist-tests',
  // Configure a custom Electron launcher to launch our Electron app
  launchers: {
    Electron: {
      // Run from the `electron-app` directory
      cwd: 'electron-app',
      // Ideally we would just spawn `electron-forge` directly, but it doesn't
      // do proper signal handling, so when testem kills it when the tests
      // complete, it doesn't kill the Electron app, which causes problems for
      // CI. So instead we launch this file as a script (see below) in place of
      // `electron-forge` so it can set up the proper signal handling to
      // terminate `electron-forge` *and* the Electron app when testem signals
      // that the tests are done.
      //
      // All the arguments after `__filename` are forwarded to `electron-forge`.
      exe: process.execPath,
      args: [
        __filename,
        'start',
        // `electron-forge` will build the test main process code, but since
        // `package.json`'s `main` entry points to the actual main process
        // entrypoint, we need to specify the app path so it runs the test main
        // process entrypoint.
        '--app-path',
        '.vite/build/test-ember.js',
        // This tells `electron-forge` to pass the remaining arguments through
        // to the Electron app. Testem will pass the URL at the end of all the
        // arguments, so this will cause it to be passed to the Electron app so
        // our test entrypoint (`test-ember.ts`) can use it to load the test
        // webapp via the testem server.
        '--',
      ],
      protocol: 'browser',
    },
  },
  launch_in_ci: ['Electron'],
  launch_in_dev: ['Electron'],
  browser_args: {
    // <normal browser args>
  },
};

// As mentioned above, `electron-forge` doesn't do proper signal handling, so we
// tell testem to launch this file as the Electron launcher so we can set up the
// proper signal handling.
if (require.main === module) {
  const { spawn } = require('child_process');

  const child = spawn(
    // As configured above, our current working directory will be `electron-app`
    'node_modules/.bin/electron-forge',
    // Forward all the command-line arguments configured above
    process.argv.slice(2),
    {
      // Make `electron-forge` the leader of a new process group so we can kill
      // the entire group at once below
      detached: true,
      stdio: 'inherit',
    },
  );

  // When testem sends us a SIGTERM, kill the entire process group to ensure
  // both `electron-forge` and the Electron app are terminated

  // Capture termination signals to trigger a clean exit to ensure that when
  // testem terminates us, or when we receive a SIGINT e.g. from a ctrl-c, we
  // also clean up the Electron process.
  process.on('SIGINT', () => process.exit());
  process.on('SIGTERM', () => process.exit());

  process.on('exit', () => {
    process.kill(-child.pid, 'SIGTERM');
  });
}

Then to run tests in CI/the command-line via testem (instead of ember electron:test), run pnpm ember build --environment test --output-path dist-tests && testem --file testem.js ci --port 0

Finally, to be able to package the Electron app, I defined a packageAfterCopy Electron Forge hook:

    async packageAfterCopy(_config, buildPath) {
      if (!process.env.PACKAGE_WEBAPP_PATH) {
        throw new Error('PACKAGE_WEBAPP_PATH must be set in order to package');
      }

      // When packaging, copy the Ember app from the specified location into
      // the expected location inside the package.
      await cp(process.env.PACKAGE_WEBAPP_PATH, join(buildPath, 'ember-dist'), {
        recursive: true,
      });
    },

So then to package the app, you can run ember build or ember build -e production in your Ember app, and then in electron-app, run (instead of ember electron:package) PACKAGE_WEBAPP_PATH=../dist electron-forge package or (instead of ember electron:make) PACKAGE_WEBAPP_PATH=../dist electron-forge make.

Note that you'll want to delete your electron-app/ember-dist folder, leftover from when ember-electron would build the Ember app there, or it will get included in the package before the packageAfterCopy hook and Bad Stuff will probably happen.

Next Steps

That was a lot! And I'm sure it didn't all work without some effort because I forgot stuff or had typos or whatever! But once you've successfully gotten through the steps that I meant (which may not have been the steps that I've written 😂) you'll have entirely separate Ember and Electron builds, where the Electron app consumes the Ember app via a dev HTTP server, or from a built filesystem bundle. So now you can:

Migrate to Vite

At the end of the steps above you'll still be building/serving the app using ember-cli, but all ember-cli functionality will be invoked directly (ember serve and ember build), so you can migrate your Ember app to build using Vite, plug in the equivalent vite commands (vite dev, vite build) and you're off to the races!

Move `electron-app` out of your Ember app's folder

There's no hard dependency on electron-app being inside your Ember app's folder, so you can make your project a monorepo (if it's not already) and put them side by side in the filesystem, or wherever else you want.

Unify package management

If you make your project a monorepo, you can make electron-app part of the workspace rather than a weird separately-package-managed folder inside your repo. One note is that electron-packager doesn't work with pnpm's or yarn >1's node_modules layout (there are a bunch of issues filed in GitHub you can go find to read up on it), so if you want to do this, you'll have to bundle all of your main process Node dependencies, which means making them all devDependencies in electron-app (and you can't have any native modules).

Extract preload API types

If you use TypeScript and you unify the package management, you can create another package in the monorepo that contains all the types for the APIs in your preload script, and then consume them from the preload script and from your Ember app so you have type-safety across the main/renderer process interface boundary.

Uh oh!

Uh oh!

Vite support #1849

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions