Skip to content

Latest commit

 

History

History
102 lines (67 loc) · 5.6 KB

build-lifecycle.md

File metadata and controls

102 lines (67 loc) · 5.6 KB
Raw
description
How Forge takes your app code from development to distribution.

Build Lifecycle

Once your app is ready to be released, Electron Forge can handle the rest to make sure it gets into your users' hands. The complete build flow for Electron Forge can be broken down into three smaller steps:

Each one of these steps is a separate command exposed through Forge's electron-forge command line interface, and is usually mapped to a script in your package.json file.

{% hint style="info" %} Cascading build steps

Running each of these tasks will also run the previous ones in the sequence (i.e. running the electron-forge publish script will first run package and make as prerequisite steps). {% endhint %}

graph TB
    dev["fa:fa-code development Electron project"] -.-> package
    publish -.-> cloud
    subgraph forge["fa:fa-hammer Electron Forge"]
        package["fa:fa-box Package"] -->|executable app bundle| make 
        make["fa:fa-compact-disc Make"] -->|platform installers| publish["fa:fa-upload Publish"]
    end
    cloud["fa:fa-cloud Uploaded to cloud object storage"]
Loading

Step 1: Package

{% hint style="info" %} For command usage, see the #package CLI command documentation. {% endhint %}

In the Package step, Forge uses Electron Packager to package your app. This means creating an executable bundle for a target operating system (e.g. .app on macOS or .exe on Windows).

This step also performs a few supporting tasks:

By default, running the Package step will only create a packaged application for your machine's platform and architecture.

{% hint style="info" %} On bundling app code

Note that Forge does not perform any bundling of your app code for production in the Package step without additional configuration.

If you need to perform any custom JavaScript build tasks (e.g. module bundling with Parcel or webpack) for either renderer or main process code, see the #using-lifecycle-hooks section below. {% endhint %}

{% hint style="success" %} After the Package step, your packaged application will be available in the /out/ directory. {% endhint %}

Step 2: Make

{% hint style="info" %} For command usage, see the #make CLI command documentation. {% endhint %}

Forge's Make step takes the bundled executable output from the previous Package step and creates "distributables" from it. Distributables refer to any output format that you want to distribute to users, whether it be an OS-specific installer (e.g. .dmg or .msi) or a simple compressed archive (e.g. .zip) of the bundle.

You can choose which distributables you want to build by adding makers to your Forge config.

By default, running the Make step will only run Makers targeting your machine's platform and architecture.

{% hint style="success" %} After the Make step, distributable archives or installers are generated for your packaged app in the /out/make/ folder of your project. {% endhint %}

Step 3: Publish

{% hint style="info" %} For command usage, see the #publish CLI command documentation. {% endhint %}

Forge's Publish step takes the distributable build artifacts from the Make step and uploads for distribution to your app's end users (e.g. to GitHub Releases or AWS S3 static storage). Publishing is an optional step in the Electron Forge pipeline, since the artifacts from the Make step are already in their final format.

You can choose which platforms you want to target by adding publishers to your Forge config.

{% hint style="success" %} After the Publish step, your app distributables will be available to download by users. {% endhint %}

Using lifecycle hooks

Your Electron application might have custom build needs that aren't handled with the most basic Forge pipeline described above. To solve this issue, Electron Forge exposes callback hooks at various points in the build process.

These hooks can be used to implement custom logic that your application needs. For instance, you can perform actions between the Package and Make steps with the premake hook.

{% hint style="info" %} For a full list of Forge hooks and usage examples, see the hooks.md documentation. {% endhint %}

If you want to share a specific sequence of build hook logic, you can modularize your hook code into a plugin instead. This is how Forge's webpack.md works, for instance. For more details on authoring custom plugins, see the writing-plugins.md guide.

Cross-platform build systems

By default, Electron Forge will only build your app for the operating system it's running on. Targeting a different operating system (e.g. building a Windows app from macOS) has many caveats.

If you don't have access to Windows, macOS, and Linux machines, we highly recommend creating a build pipeline on a Continuous Integration platform that supports all these platforms (e.g. CircleCI or GitHub Actions). For an example of CI builds in action, see Electron Fiddle's CircleCI pipeline.