neutrino

Build cross-platform desktop applications using your OS' native web engine.

Note: this project is still in its early stages. Feel free to tinker around with it, but don't use it in production.

Neutrino is a experimental lightweight alternative to the popular Electron framework. It is capable of producing apps that are 100x smaller compared to Electron by leveraging the native web engine of the OS.

To render a webview, it uses my C++ webview library.

Usage

1. Clone this repo
2. Install Node dependencies: npm install
3. Build neutrino
   • cmake -S . -B build to generate build files
4. To use in another project, link it locally:
   • npm install --save-dev /path/to/neutrino

Make sure to check the webview build steps for your platform.

CLI

Neutrino

Upon launching, Neutrino will first check for the file ./app/index.html. If it exists, then it will try to load the app located there. This is intended for production builds.

Otherwise, Neutrino will accept a single CLI argument to locate the app:

Usage: neutrinojs [path]

The path must be a directory that contains at least two files:

• main.js: Entry point for the main process
• index.html: Web page for renderer process

Neutrino Webpack

neutrino-webpack simplifies the integration with webpack and Neutrino by building the main and renderer processes using webpack. For development builds, the renderer process is run with webpack-dev-server and Neutrino is automatically opened.

Usage: neutrino-webpack [options]

Options are any combination of:

• -p, --production: Build a production version (default is dev build)
• -m, --config-main [main config file]: Custom webpack config file for main process
• -r, --config-renderer [renderer config file]: Custom webpack config file for renderer process
• -h, --help: Show help

Examples:

# Development build
neutrino-webpack -m ./webpack.main.config.js -r ./webpack.renderer.config.js

# Production build
neutrino-webpack -p -m ./webpack.main.config.js -r ./webpack.renderer.config.js

To modify and extend the webpack configurations, neutrino-webpack supports additional config files, specified using -m and -r. These files must export a function that accepts the provided config object as its only argument.

Within the function, feel free to make any modifications to the default config. The returned object will be used as the webpack config.

For example, here is an example of adding React to your build:

module.exports = config => {
  // Add @babel/preset-react to the config
  config.rules.push({
    test: /\.jsx?$/,
    exclude: /node_modules/,
    use: [
      {
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-react']
        }
      }
    ]
  });

  return config;
};

The default config files are located at ./webpack.main.config.js and ./webpack.renderer.config.js.

Neutrino Builder

neutrino-builder takes the built main and renderer files (i.e. created by neutrino-webpack), and copies them into an unpacked app directory along with the neutrino binary. It will also place a copy of the neutrino executable, renamed to your package name.

Usage: neutrino-builder [options]

Options are any combination of:

• -m, --main [path to built main files]: default is ./dist/main
• -r, --renderer [path to built renderer files]: default is ./dist/renderer
• -h, --help: Show help

Packaging

To package your app, use the neutrino-builder command to package all of your built app files into a directory (by default ./dist/${package-name}/app.

To perform this manually, grab a copy of neutrino (neutrino.exe for Windows) and place it in a directory. Create an app/ subdirectory, and place all of your app's files in it. At the very least, this must include

• main.js: Main process
• index.html: Renderer process

Supported APIs

Currently, Neutrino is highly limited and only supports the following Node / Electron APIs:

• app
  • on
    • 'ready'
• BrowserWindow
• fs
  • readFile
  • writeFile

Build

Neutrino uses three external libraries:

• Duktape
• nlohmann's JSON library
• my own webview library

The JSON library is fairly simple to compile, but my webview library is a bit more complicated. Check out the build steps there.

Windows

Use Visual Studio 2019 and CMake.

There is experimental support with clang-cl. Check out the webview README under Windows.

TL;DR:

Install Windows 10 SDK, generate WinRT projection headers, install clang-cl (LLVM) and run this in Powershell:

clang-cl neutrino.cpp third_party/duktape/duktape.c /EHsc /TP /I "." /I "./third_party/webview/" /I "./third_party/duktape/" /I "./third_party/nlohmann/" /DWEBVIEW_WIN -Xclang -std=c++17 -Xclang -Wno-delete-non-virtual-dtor -o "lib/neutrino.exe" /link "WindowsApp.lib" "user32.lib" "kernel32.lib"

This will generate an executable at ./lib/neutrino.exe.

MacOS

Neutrino uses the experimental std::filesystem header, so you'll need a compiler with filesystem support.

The clang that comes with macOS Catalina includes it, but older versions may require either a linker flag (-lc++fs) or installing it directly from LLVM.

Linux

Neutrino uses the experimental std::filesystem header, so you'll need a compiler with filesystem support. Depending on your compiler, this may require a linker flag (e.g. lstdc++fs).