RFC: ember-electron initializer pattern

[anulman]

• Start Date: 2017-12-05
• RFC PR: N/A
• Original issue: N/A

Summary

ember-electron should expose and adopt a standard mechanism with which to wrap and run "initializer" code. This will allow us to clean our growing main.js file into compartmentalized steps, and encourage community addons to use our process.env.EMBER_ELECTRON flag to customize build pipelines.

Motivation

With growing adoption of e-electron, we would like to make it easier for Ember app developers to use familiar tools while benefiting from the lower-level APIs Electron exposes. This includes:

• Using a package like fs-storage-plus to provide a main-proc-friendly, localstorage-compliant backend for ember-simple-auth to maintain session data; and
• Allowing packages like ember-render-vendor to bridge native tooling, while degrading gracefully for browser support.

Detailed design

This design is based on these principles:

• Initializers should be able to specify their order—e.g. you may want to load the main BrowserWindow only after a network FS is mounted;
• Initializers should be able to clean up after themselves—e.g. render-vendor's long-lived renderer procs should be cleaned up, so they don't leak memory; and
• Initializers should "just work"—e.g. end users should not need to add boilerplate code for an addon's initializer to run.

Initializers should therefore be implemented: 1) As a set of JS object instances, which MUST expose an initialize and MAY expose a cleanup function, a before declaration, and an after declaration;

• initialize fns MAY return a promise, for which any initializers scheduled after this initializer would wait
• For an example, see ember-render-vendor/ember-electron/initializers 2) Which are read automatically from a standard dir (e.g. ember-electron/initializers/*.js), and organized at compile time into the proper boot order; 3) And are invoked by a short call in main.js, e.g.

  let initializersDir = join(process.cwd(), 'ember-electron', 'initializers');
  readdirSync(initializersDir)
  .map((name) => require(join(initializersDir, name)))
  .forEach((initializer) => initializer(app));

Assuming the above criteria are met, we should be able to use e-cli to 1) find any addons with the ember-electron keyword; and 2) merge their ember-electron trees into the main one we compile.

We may also be able to adopt e-cli's initializer scheduling protocol.

How We Teach This

We should call these objects initializers, as this is in line with Ember's initializer + instance-initializer concepts: short-lived scripts, run once during app boot, which help configure and orchestrate the app's dependencies.

The concept should be self-explanatory, and may even lead to easier onboarding by giving names & clear separation of concerns to what is currently included in the main.js file. For example, we may split current content into:

• ember-electron/initializers/register-http-scheme.js
  • Maybe even move to a separate addon, ember-electron-protocol-serve?
• ember-electron/initializers/cleanup-on-windows-closed.js
• ember-electron/initializers/load-ember-app-window.js
• ember-electron/initializers/handle-uncaught-exceptions.js

Drawbacks

The biggest risk seems to be with teaching proper Squirrel event handling, esp for Windows. This has always been an exception (ie that users should handle Squirrel events before anything else). Ideally it will be fast enough to run a handle-squirrel-events.js script { before: 'all' }.

It also encourages a more compartmentalized approach to the main.js file, which may not be familiar to developers starting down the NodeJS learning curve.

Alternatives

This approach is the result of several iterations of including third-party code in main proc scripts. Currently, solutions seem ad-hoc, and do not reasonably support addon authors' use cases.

Unresolved questions

• How do we schedule initializers?
• What addons will see the most value / may support efforts?

[anulman]

An early list of addon authors we should be communicating with:

• ember-simple-auth
• ember-cli-deploy
• ember-power-select
• ember-data

[felixrieseberg]

I have almost no opinion on this - it's something that I in Ghost Desktop wouldn't really need, but if anyone could benefit from it, I'm all for it.

There's definitely an issue around Ember only living in one window and if this approach brings ember-style development closer to the main process, then I'm all for it.

[anulman]

@felixrieseberg Yeah, that's the goal—I'd like to communicate that better in the RFC. Should I include a link to an example, or add some detail to the Design section?

ember-render-vendor is a (very purpose-specific) example of how this would work for addons:

• ember-electron/initializers/ember-render-vendor.js exports an initialize function, which:
  • boots a websocket server;
  • loads several file:// urls into a renderer proc after boot; and
  • registers the booted renderer + socket server on the electron global; then
• addon/renderer.js loads and uses objects exported from the global.
• Consuming apps extend the addon/renderer.js and automatically make + emit data to the booted procs by setting the object's data attr.

But I think this thinking makes several broader-use scenarios possible, including:

1) Projects like ember-simple-auth could eg include and default to a fs-storage-plus-based encrypted store vs the default session-stores/localstorage when running in electron envs; 2) Offline-mode / PWA-friendly addons could detect the env and back ember-data with fs / IndexedDb / SQLite-backed store caches; and 3) A single-purpose "main app initializer" could help better define the native / web code boundary for new users, esp those looking to write multi-window apps.

[CSstefan]

let initializersDir = join(resolve(__dirname, '../'), 'ember-electron', 'initializers'); This would be a better way to locate the initializers directory and has been tested in a MacOS dev environment and a built package installed in a Linux environment.

[CSstefan]

There needs to be some way to override an initializer. So, in the case of my used of ember-render-vendor, I want to pass additional parameters to Puppeteer that do not exist in the initializer provided with ember-render-vendor. Perhaps there could be a way to put one's own initializer (eg. ember-render-vendor.js) in the e-e initializers folder and the presence of that initializer override the one bundled in the dependancy? Suggestions?

[CSstefan]

I tested putting the my own ember-render-vendor initializer into my ember-electron/initializers but this happens...

Build failed.
Build Canceled: Broccoli Builder ran into an error with BroccoliMergeTrees plugin. 💥
...
Pass option { overwrite: true } to mergeTrees in order to have the latter file win.
...

Maybe this will work. I'm just not sure where to pass that overwrite: true option.

[anulman]

@CSstefan Re your first note, I think it's an addon's responsibility to define its configuration interface, eg via e-cli-build.js, config/environment.js, or package.json files. If the Puppeteer changes solved your problem, we should move this chat to an ember-render-vendor-specific issue.

For your second, that's a problem with e-r-v code as well, though a helpful note on this issue. Were this pattern implemented in e-electron, we'd need to be sensitive to mergeTrees conflicts, and ensure userland files overwrite similarly-named files included from e-electron "plugins".

[anulman]

FWIW, this issue proposes making changes similar to:

• https://github.com/ef4/prember/pull/7
• https://github.com/samselikoff/ember-cli-mirage/pull/1355

[bendemboski]

Closing due to inactivity. If anybody wants to pick this up and move it forward, feel free to comment or re-open.