Skip to main content

The build process

After cloning the repo you can immediately launch Finsemble by running yarn launch. There are no build steps required.

You also don't need to run a build process when making config changes. You can add apps, change config files, or modify theme.css and immediately see the effects by closing Finsemble and re-launching it with yarn launch.

You only need to worry about the Finsemble's build process if you've added source code to the seed project. There are two possibilities:

1) You've added a UI template to customize the look or behavior of Finsemble's built-in UI components such as the Toolbar or the WindowTitleBar by using yarn template. 2) You've added apps, app services, storage adapters or preloads, including their source code, to the seed project by using yarn create-app.

Finsemble's build process uses Webpack and supports Typescript and React by default. It saves the transpiled code to public/build/. You can reference it in config using the $applicationRoot manifest macro:

"My app" : {
    "appId" : "My app",
    "manifest" : {
        "window" : {
            "url" : "$applicationRoot/MyApp/index.html"
        }
    }
}
note

Each of the yarn scripts that come with the seed project call Finsemble's CLI tool. You can run the CLI tool directly by calling npx finsemble <command>.

note

Run npx finsemble without any arguments to get online help for the Finsemble CLI.

Running the build process​

There are two ways to run the build process while developing:

  1. Run yarn dev. This command builds your templates and then launched Finsemble. The development process runs in "watch" mode. Reload components using ctrl-R/cmd-R to get changes, or choose "Restart" from Finsemble's file menu to restart the app (such as when making changes to services or the Toolbar).

  2. Run yarn build in one terminal, and then yarn start in a second terminal. This command runs the build process in "watch" mode, allowing you to make changes without having to restart your development process. You can then stop Finsemble by hitting ctrl-c in your second terminal, and restart it by running the yarn start command.

note

Run yarn dev help or yarn build help to see all command line arguments.

note

yarn dev and yarn build exit immediately if webpack/entries.json doesn't exist or is empty. This happens if you haven't added any templates.

You can add your own entries to webpack/entries.json. Enter the file location of your app's entry point. An output filename will automatically be generated in the corresponding location of public/build. You may also control the output location by explicitly passing an object that contains import and filename fields. Be sure to include the .js extension if you specify the output location

Example webpack/entries.json file. The first entry autogenerates an output filename. The second entry explicitly sets the output filename and location from where to copy files (such as .html, .json, etc).

[
    "./src/MyApp/entryPoint.ts",
    {
        "import" : "./src/MySecondApp/src/index.ts",
        "filename" : "MySecondApp/index.js",
        "copyConfig" : "MySecondApp"
    }
]

copyConfig will also accept a complete config for CopyWebpackPlugin. If a config is passed then Finsemble will not attempt to auto-calculate any copying heuristics.

info

To run the build process for production deployment run yarn prod. This command compiles using Webpack's production mode to optimize the build. Compiled files are minimized so that your smart desktop loads quickly for end users. Running yarn prod also copies Finsemble's "platform" into your project's public/build directory, readying it for deployment. See Deploying your smart desktop.

note

Finsemble's build process automatically resolves dependencies for typescript, react, react-dom, webpack, webpack loaders and any other modules that are required for building Finsemble's UI components. This is done using webpack's resolveLoaders, ts-loader's compiler option, and typescript's paths option.

When running under yarn or npm, the build process will first use any dependencies that you have installed directly in package.json. So for instance, if you install typescript in your seed project using yarn add or npm install then Finsemble's build will use that version instead of its own. When running under pnpm, the build process will always use Finsemble's own versions.

Supported package managers are: npm, yarn and pnpm. Use yarn dev --resolve-dependency-magic=false to override this behavior or when using another package manager. You will need to then install any missing packages.

Finsemble startup​

Here is the startup process when you launch Finsemble in development mode:

  1. yarn launch looks for a "launch" configuration in your project.json file to determine the manifest URL. It defaults to /public/configs/application/manifest-local.json. Finsemble uses this file to bootstrap its full configuration.
  2. The Finsemble Electron Adapter (FEA) is launched. This process appears as Electron.exe to the operating system. There will be more than one copy of this executable running at the same time.
  3. FEA launches its initial Chromium window: Finsemble's service manager, which is Finsemble in the central logger. This window is hidden. It bootstraps Finsemble's services and UI components, most of which are also hidden.
  4. After Finsemble's services and UI components are ready, Finsemble launches the previously loaded apps. The user now can interact with the smart desktop.

The startup sequence for your users is slightly different:

  1. The manifest's location is bundled into your executable.
  2. Your executable launches. This will appear as YourApp.exe to the operating system. There will still be more than one. Your executable is a branded version of FEA. The manifest is loaded from your server at the location specified in the bundle.

Steps 3 and 4 are the same.

note

You will see multiple executables because by default each app runs its own process. For more info see Affinity.

Customizing the build process​

Also see Finsemble CLI API reference.

Finsemble ships with a Typescript and Webpack configuration that is optimized for compiling Finsemble's UI components, templates, and storage adapters. You might need to modify these configurations, such as to build your own apps or to support your specific SDLC requirements. In these situations, you can write a custom build script that imports functions from Finsemble's CLI API. Then, instead of using yarn build or yarn dev you would use your build script.

Here's how to import Finsemble's CLI API functions:

Using require (commonJS) such as when running through node.js

const { ruleCSS, launchFEA} = require("@finsemble/finsemble-core/cli-api");

Using import (ESM) such as when running through ts-node

import { ruleCSS, launchFEA } from "@finsemble/finsemble-core/cli-api";

For example, you might create a new file called my-build.js to run your build process. Inside my-built.js you import functions from the Finsemble CLI API. To build your project you then run node my-build.js, or add a package.json script (my-build : node my-build.js) and run yarn my-build.

Writing a custom build script​

Finsemble's build process uses Webpack. Finsemble's CLI generates a default webpack config file and then populates it with the webpack entry points that were generated when you run yarn template and yarn create-app.

note

You can use the CLI command npx finsemble show-webpack-config to display Finsemble's default webpack config. This can help you decide what changes to make. Please note that Finsemble's build process uses CopyWebpackPlugin and HtmlWebpackPlugin. These will not show up in the webpack config output because they are JavaScript objects. You can override the plugins field though to eliminate them.

Your build script typically follows three steps:

  1. let config = await getWebpackConfig() - Get Finsemble's default webpack config.
  2. Modify the config as appropriate for your environment. See Webpack's config documentation.
  3. runWebpack(config) - Run the Finsemble build process with your modified config.

See Finsemble CLI API reference.

Example build script that adds a SCSS rule (assuming sass-loader was added to package.json)

const { getWebpackConfig, runWebpack } = require("@finsemble/finsemble-core/cli-api");

let webpackConfig = getWebpackConfig();
webpackConfig.module.rules = webpackConfig.module.rules.concat({
    test: /\.s[ac]ss$/i,
    use: [
        "style-loader",
        "css-loader",
        "sass-loader",
    ]
});

runWebpack(webpackConfig);
note

  • Finsemble's default webpack configuration contains rules for building CSS, SVG, React (TSX/JSX), and Typescript. These rules are necessary to build Finsemble's UI components. The Finsemble CLI API exports these rules as functions that look like ruleSVG(), ruleCSS(), etc. Running the function produces the rule which you can then insert into the webpack config. You can add, remove, or modify webpack rules.

  • Finsemble's default webpack configuration looks for an index.tsx, index.jsx, index.ts or index.js file. It automatically generates an index.html file by default, which loads the compiled index.js file as a script. An index.html file will not be generated if one already exists in your input source folder (alongside index.tsx).

  • Finsemble ships with a Typescript and Webpack configuration that is optimized for compiling Finsemble's UI components templates and storage adapters. You might need to modify these configurations, such as to build your own apps or to support your specific SDLC requirements. In these situations, you can write a custom build script that imports functions from Finsemble's CLI API.

  • Finsemble's build process loads dependencies from @finsemble/finsemble-core/node_modules. You don't have to install webpack or other dependencies, but if you do install them Finsemble's build process will use those locally installed versions.

  • Finsemble's build process automatically copies any additional assets in your input folder such as .html, .css, .png files etc.

note

Finsemble supports .env files for setting environment variables. These variables become available on process.env. This can be helpful when you need passwords at development time that you don't want to check into your repo.

Place a .env file in the root of your seed project that contains your environment variables (i.e. SECRET_KEY="YOUR_SECRET_KEY").

note

You can also use yarn dev --webpackConfig=filename to point Finsemble's CLI to your own webpack config file. This should be a JavaScript file that exports a valid webpack config (using module.exports =).

Configuring launch parameters and multiple environments​

Your project.json file can be configured with custom launch parameters by adding a "launch" section. The launch section is only used in development. See Configuring multiple installers by environment for deployment settings.

The launch section can contain any of the following parameters:

  • port - port number for local development (when you run yarn dev and related scripts). This defaults to 3375. It must match the port specified in manifestUrl.

  • manifestUrl - the URL from where the manifest will be retrieved when you launch. For local development work, make sure to use the the same port number as specified in port. This defaults to "http://localhost:3375/configs/application/manifest-local.json".

  • chromiumFlags - chromium command line flags to be set when launching Finsemble. For more info, see Supported command line switches.

  • args - command line arguments to be passed to Finsemble - example: ['--arg1=value1', '--arg2=value2']

Example project.json file with launch section:

{
    "launch" : {
        "port" : 3380,
        "manifestURL" : "http://localhost:3380/configs/application/manifest-local.json"
    }
}

You can specify multiple launch configurations by creating an "environments" section in project.json. Create a separate "launch" section within each environment. These will be merged against a top level "launch" section if it exists.

Example, multiple launch environments in project.json file. Each environment sets different chromium flags:

{
    "launch" : {
        "port" : 3380,
        "manifestURL" : "http://localhost:3380/configs/application/manifest-local.json"
    },
    "environments" : {
        "development" : {
            "launch" : {
                "chromiumFlags" : {
                    "--auth-server-whitelist": "*example.com, *foobar.com, *baz"
                }
            }
        },
        "production" : {
            "launch" : {
                "chromiumFlags" : {}
            }
        }
    }
}

Run yarn dev --environment <environment> to run Finsemble from a specific launch configuration.

See also​

To better understand what happens after start-up, see Configuration.

To understand how Finsemble solves the problem of handling many-window applications, see Process Management.

For more about modules, why you should use them, and what they are, see this blog post.