Coulomb

Coulomb is a framework for building cross-platform GUIs for structured data entry using TypeScript, React, and Electron.

Demo

To be added.

Installation

Note	It is assumed that you are using electron-builder and electron-webpack. We recommend to base your Electron application on top of electron-builder: see http://electron.build for more information.

Coulomb

$ yarn add @riboseinc/coulomb

Peer dependencies at runtime

React and Blueprint 3

Currently, Coulomb provides some GUI components based on React and Palantir’s Blueprint 3.

It is on our roadmap to make the library GUI-agnostic, but for now it is required for a Coulomb-based app to use those.

Coulomb does not bundle them, so add them to your runtime dependencies:

yarn add react-dom react @blueprintjs/core @blueprintjs/icons

electron-log

Coulomb uses electron-log, but it doesn’t bundle it. However, it assumes that the end Electron app will use it too, and relies on its availability.

Add electron-log to your runtime dependencies:

yarn add electron-log

Build configuration & build-time dependencies

Note

If you have not added custom Webpack configuration for main thread, make sure you configure electron-webpack to use it by updating your package.json: ... "electronWebpack": { ... "main": { ... "webpackConfig": "main.webpack.js" } }, Given that, Webpack configuration described below will go in file named "main.webpack.js" in the same directory as your package.json.

Threads

Coulomb uses Node workers for Git operations that would otherwise block the UI, even though they run in main thread.

To bundle dependencies (such as isomorphic-git) alongside worker code, it uses threads and requires your project to configure the corresponding Webpack plugin.

The configuration is done in two steps:

1. Add the threads-plugin build-time dependency:

   yarn add --dev threads-plugin

2. Configure Webpack for your main thread to use threads-plugin:

   const ThreadsPlugin = require('threads-plugin');
   
   module.exports = function (config) {
     config.plugins.unshift(
       new ThreadsPlugin({ target: 'electron-node-worker' })
     );
     // other configuration...
   }

Node native extensions

Some Coulomb dependencies use Node extensions (namely, node-keytar).

To ensure those extensions get appropriately packed,

1. add the native-ext-loader build-time dependency:

   yarn add --dev native-ext-loader

2. Configure Webpack for your main thread to use native-ext-loader instead of electron-webpack’s default choice of node-loader.

   This may be done like so:

   module.exports = function (config) {
   
     config.module.rules = config.module.rules.filter(r => {
       return (r.use !== 'node-loader');
     })
   
     config.module.rules.unshift({
       test: /\.node$/,
       use: {
         loader: 'native-ext-loader',
         options: {
           rewritePath: undefined,
           name: '[path][name].[ext]',
         },
       },
     });
     // other configuration...
   }

Note	Heads-up! This exact solution may break if electron-webpack changes the way it specifies node-loader, so be careful when upgrading it.

Electron build configuration

Add the following to your package.json file under "build":

  ...
  "build": {
    ...
    "asarUnpack": [
      "**/*.node",
      "node_modules/source-map/**/*",
      "node_modules/source-map-support/**/*",
      "node_modules/buffer-from/**/*",
      "dist/main/*.worker.js*"
    ]
  }

This ensures that dependencies of Coulomb’s workers are accessible at runtime within packaged app. If you get a JavaScript error alert during packaged app startup, especially if it’s being launched from within macOS’s Applications folder, check this setting.

Contributing

Coulomb uses Commitizen. To follow commit message conventions, it is suggested to use git commit CLI command, which would show interactive prompt and format commit message appropriately.

Release process

From repository root:

vim package-dist.json
# Edit package-dist.json to increment version
# Make sure to keep dependencies in check

git tag -s <new version>

yarn
# Builds the package into ./dist

cd dist

npm publish