bhanditz / electron-link

A module to bundle your electron app into a single file that can be used for V8 snapshots.

electron-link

electron-link is a node module that takes a JavaScript file (typically the entry point of an application) and a list of modules that need to be required lazily (see Atom's build scripts for an example). Then, starting from that file, it traverses the entire require graph and replaces all the forbidden require calls in each file with a function that will be called at runtime. The output is a single script containing the code for all the modules reachable from the entry point. This file can be then supplied to mksnapshot to generate a snapshot blob.

It can also determine whether a module can be snapshotted or not. For instance, the following code can be snapshotted:

const path = require('path')

module.exports = function () {
  return path.join('a', 'b', 'c')
}

And generates the following code:

let path;
function get_path () {
  return path || path = require('path');
}

module.exports = function () {
  return get_path().join('a', 'b', 'c')
}

You can notice that the above code is valid because the forbidden module (i.e. path) is used inside a function that doesn't get called when requiring the script. On the other hand, when trying to process the following code, electron-link will throw an error because it is trying to access a forbidden module right when it gets required:

const path = require('path')

module.exports = path.join('a', 'b', 'c')

Being a tool based on static analysis, however, electron-link is unable to detect all the cases where a piece of code can't be included in a snapshot. Therefore, we recommend running the generated JavaScript file in an empty V8 context (similar to the one provided by mksnapshot) to catch any invalid code that might have slipped through.

Installation

npm install --save electron-link

Usage

const electronLink = require('electron-link')

const snapshotScript = await electronLink({
  baseDirPath: '/base/dir/path',
  mainPath: '/base/dir/path/main.js',
  cachePath: '/cache/path',
  shouldExcludeModule: (modulePath) => excludedModules.has(modulePath)
})

const snapshotScriptPath = '/path/to/snapshot/script.js'
fs.writeFileSync(snapshotScriptPath, snapshotScript)

// Verify if we will be able to use this in `mksnapshot`
vm.runInNewContext(snapshotScript, undefined, {filename: snapshotScriptPath, displayErrors: true})