Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Packaging and Auto-update

Packaging an Electron App with Electron Forge

Turn your Electron project into a distributable app with Electron Forge: package versus make, makers, config, assets and icons, ignore rules, cross-platform limits and build scripts.

Running electron . is fine for development, but nobody else can use your app that way. To ship, you need a self-contained application: an .exe or installer on Windows, an .app and .dmg on macOS, .deb, .rpm or AppImage on Linux. That means bundling your code, the Electron runtime and any native modules into one folder, then wrapping that folder in whatever format each platform expects.

Electron Forge is the official all-in-one tool for this. It handles three steps: package (build the runnable app folder), make (turn it into installers) and publish (upload them). This lesson walks through each step, the configuration file, and the traps that waste an afternoon the first time.

Starting a Forge project

TEXT
npm init electron-app@latest my-app -- --template=vite
cd my-app
npm start        # development with hot reload
npm run make     # build installers for the current platform

Templates exist for Vite, Webpack and plain JavaScript or TypeScript. Existing projects can be converted with npx electron-forge import.

Forge adds three scripts to package.json:

Script What it does
npm start runs the app in development
npm run package builds the unpacked app folder only
npm run make package, then create installers from forge.config
npm run publish make, then upload to a publisher such as GitHub Releases

package versus make

flowchart LR
  A["Source code and node_modules"] --> B["package"]
  B --> C["out/my-app-win32-x64/ (runnable folder)"]
  C --> D["make"]
  D --> E["Installers: Squirrel, MSI, DMG, ZIP, DEB, RPM"]
  E --> F["publish"]
  F --> G["GitHub Releases, S3"]

Package produces the app; make wraps it; publish uploads it.

package is useful on its own: it gives you a quick folder you can double-click to test a production build. Always test the packaged app, because it runs differently from npm start: paths are inside app.asar, app.isPackaged is true, and dev dependencies are gone.

The configuration file

Everything lives in forge.config.js:

JavaScript
import { FusesPlugin } from '@electron-forge/plugin-fuses';
import { FuseV1Options, FuseVersion } from '@electron/fuses';

export default {
  packagerConfig: {
    asar: true,
    name: 'Notes Studio',
    executableName: 'notes-studio',
    icon: './assets/icon',            // no extension: .ico, .icns and .png are picked per platform
    appBundleId: 'com.example.notesstudio',
    ignore: [/^\/src\//, /^\/\.git/, /^\/tests\//],
    extraResource: ['./assets/templates'],
  },
  makers: [
    { name: '@electron-forge/maker-squirrel', config: { name: 'notes_studio' } },
    { name: '@electron-forge/maker-zip', platforms: ['darwin'] },
    { name: '@electron-forge/maker-deb', config: { options: { maintainer: 'Ana', homepage: 'https://example.com' } } },
    { name: '@electron-forge/maker-rpm', config: {} },
  ],
  plugins: [
    new FusesPlugin({
      version: FuseVersion.V1,
      [FuseV1Options.RunAsNode]: false,
      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
      [FuseV1Options.OnlyLoadAppFromAsar]: true,
    }),
  ],
};

Key parts:

  • packagerConfig controls the packaging step (@electron/packager underneath): name, icon, bundle id, what to leave out, extra files.
  • makers each produce one installer type. platforms restricts a maker to certain operating systems.
  • plugins hook into the build: the Vite or Webpack bundler plugins, and the Fuses plugin from the previous chapter.

Icons, extra files and the ASAR

The icon option takes a path without extension. Provide icon.ico (Windows), icon.icns (macOS) and icon.png (Linux, at least 512 by 512). Missing icons are not an error; users just see the default Electron logo, which looks unprofessional.

Files that are not code, such as templates, sounds or sample documents, should not live in the ASAR if another program must open them. List them in extraResource and find them at runtime with process.resourcesPath:

JavaScript
import { app } from 'electron';
import { join } from 'node:path';

const templates = app.isPackaged
  ? join(process.resourcesPath, 'templates')
  : join(app.getAppPath(), 'assets', 'templates');

Native Node modules (.node files) cannot be loaded from inside an ASAR archive. Forge's auto-unpack-natives plugin moves them to app.asar.unpacked for you. They must also be compiled against Electron's Node ABI, which Forge handles with @electron/rebuild during packaging.

What goes into the app

The packager copies your project including node_modules. Two habits keep the result small:

  • Put build-time tools in devDependencies. Only dependencies are included.
  • With a bundler (Vite, Webpack), the code is bundled, so most dependencies do not need to ship at all.

You can check the final size, and what contributes to it, with a quick script over the output folder. The next example does a size report for a pretend package tree, the kind of audit worth running before release.

Node.js Auditing what a package contains

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In real life the biggest rows are surprising, and replacing one heavy dependency with a native API (Intl instead of moment) can shave megabytes.

A config checker

Forge config mistakes show up late, after a five-minute build. A small validator run in a pre-build script catches the common ones early. This stand-in checks the config object like a lint rule.

Node.js Validating a Forge-style config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Cross-platform builds

make builds for the platform you run it on. You cannot reliably create a macOS .dmg on Windows, and creating a Windows installer on Linux needs Wine. The practical solution is CI with a matrix: one job per operating system, each running npm ci && npm run make, each uploading its artifacts. GitHub Actions does this with runs-on: [windows-latest, macos-latest, ubuntu-latest].

Architecture matters too: pass --arch=arm64 or --arch=x64 to make, or build a macOS universal binary. Apple Silicon Macs run x64 builds only through Rosetta, which is slower.

Common mistakes

  • Testing only with npm start. Run npm run package and open the result before every release.
  • Reading files with paths relative to the source tree; use app.getAppPath() and process.resourcesPath.
  • Forgetting that devDependencies are not shipped, then requiring one at runtime.
  • Using an app name with spaces in places where the maker wants an identifier-like name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between npm run package and npm run make?

    package produces the unpacked app. make runs package and then each maker to produce installers or archives.
  2. 2. Where should files that other programs must open live in a packaged app?

    ASAR is a virtual archive only Electron can read. extraResource copies files next to it as real files.
  3. 3. Why does make usually run in CI on several operating systems?

    Makers rely on platform tools such as hdiutil and codesign. A matrix of Windows, macOS and Linux runners builds each properly.
  4. 4. Which icon option value is correct for Forge's packagerConfig?

    Pass the path without extension; the packager picks the right file for each platform.

Summary

  • Forge has three stages: package, make, publish.
  • forge.config.js defines packager options, makers and plugins such as Fuses.
  • Provide proper icons, keep non-code files in extraResource, and unpack native modules from the ASAR.
  • Audit the size of what you ship and test the packaged app, not just npm start.
  • Build each platform on its own CI runner.

Next: Installers and Code Signing