
How to Package an Angular and Electron App as a macOS DMG
Your Angular and Electron app runs fine in development. You run npm start, the window opens, and everything works. But nobody else can run it. Your co-workers and your first users do not want to clone a repo and install Node just to try your app.
They want a DMG. They want to double-click it, drag the app to Applications, and get on with their day.
In this post, I will walk through the checklist I use to package an Angular and Electron app for macOS. We will use electron-builder. I have tried a few packaging tools over the years, and electron-builder is the one that gives me the fewest surprises.
1. Install electron-builder
electron-builder runs on your machine at build time. It does not ship inside your app, so install it as a development dependency.
npm i -D electron-builder
2. Fix the Production Load Path
This is the step that causes the most confusion. In development, your Electron window usually loads the Angular dev server from localhost. In production, there is no dev server. Electron has to load index.html from disk.
If that path is wrong, you get a blank white window and a file-not-found error in the console.
Here is how I handle it in main.ts (or main.js, or whatever you named your Electron entry point):
app.isPackaged is true when the app runs from a build created by electron-builder, and false when you start it with electron . during development. That one check lets the same main.js work in both places.
Pay attention to the folder structure. Angular’s application builder, the esbuild-based builder that became the default in Angular 17, writes its output to dist/<project>/browser/ instead of dist/<project>/. You may love the extra folder or hate it, but that is where the files are. Point Electron there.
There is one more thing to check. Angular puts <base href="/"> in index.html by default. That works on a web server, but it breaks when Electron loads the file from a file:// URL. Every script and stylesheet will try to load from the root of your drive. Build with a relative base path instead:
ng build --base-href ./
You can also set "baseHref": "./" in the build options in angular.json so you do not have to remember the flag.
3. Make a Proper Icon
macOS expects an .icns file. Without one, your app shows the default Electron icon in the Dock and in Finder, and it looks unfinished.
My flow:
- Start with a clean 1024Ă—1024 PNG.
- Convert it to
build/icon.icns. - Leave it in
build/and forget about it.
build/ is the folder electron-builder checks for icons by default. If you put a 1024Ă—1024 icon.png there, electron-builder will convert it for you. I still like to make the .icns file myself so I know what ships. On a Mac, sips and iconutil can do it with no extra tools:
mkdir icon.iconset
for size in 16 32 128 256 512; do
sips -z $size $size icon.png --out icon.iconset/icon_${size}x${size}.png
sips -z $((size*2)) $((size*2)) icon.png --out icon.iconset/icon_${size}x${size}@2x.png
done
iconutil -c icns icon.iconset -o build/icon.icns
4. Configure package.json
This is the part everyone skips. Then the build fails, or it succeeds and the app opens to a blank window.
Here is the configuration I start with:
{
"name": "your-cool-app",
"version": "1.2.3",
"main": "electron/main.js",
"build": {
"appId": "com.yourname.yourcoolapp",
"productName": "Your Cool App",
"directories": {
"output": "release"
},
"mac": {
"target": [
"dmg"
],
"icon": "build/icon.icns",
"category": "public.app-category.productivity"
},
"files": [
"dist/**",
"electron/**",
"!**/*.map"
]
},
"scripts": {
"pack:mac": "ng build --base-href ./ && electron-builder --mac --dir",
"dist:mac": "ng build --base-href ./ && electron-builder --mac --universal"
}
}
A few notes on this configuration:
appIdMUST be unique. The convention is reverse-domain notation, likecom.yourcompany.yourapp. macOS uses this value to identify your app, so do not change it after you ship.directories.outputMUST be set. By default,electron-builderwrites todist/, which is the same folder Angular uses. Send the installers torelease/so the two tools do not step on each other.mainpoints to your compiled Electron entry point. If your main process is TypeScript, compile it before you runelectron-builder.categorysets the app category macOS shows for your app. Pick the value from Apple’s list that fits. Productivity is a safe default for internal tools."!**/*.map"keeps source maps out of the package. Your users do not need them, and they add size.
Do not try to exclude node_modules in files. electron-builder already copies only your production dependencies (the dependencies section, not devDependencies) into the app. Your Angular code is bundled into dist/, so the Angular packages do not need to ship again. You can move them to devDependencies to keep the app small. Keep anything your Electron main process loads at runtime in dependencies.
I use --universal so one DMG runs on both Apple silicon and Intel Macs. A universal build is about twice the size. If everyone you ship to has Apple silicon, use --arm64 instead.
5. Build the DMG
npm run dist:mac
Give it a minute or two. When it finishes, you will find a DMG in release/. The file name comes from your productName and version, so it will look something like Your Cool App-1.2.3-universal.dmg.
Double-click it, drag the app to Applications, and launch it. You now ship a Mac app.
While you work, use npm run pack:mac instead. It builds the .app without the DMG. That is faster when all you want to know is whether the production load path works.
What About Gatekeeper?
If you have not signed the app, macOS blocks it the first time someone opens it. The warning says Apple cannot verify that the app is free of malware.
For friends and family, there is a workaround. On older versions of macOS, you could right-click the app and choose Open. That no longer works in macOS Sequoia (15) and later. Now the person has to:
- Try to open the app, then click Done on the warning.
- Open System Settings and go to Privacy & Security.
- Scroll down to the message that says the app was blocked, and click Open Anyway.
They only have to do this once. It is fine for a coworker. It is not something I would ask a customer to do.
For anything you ship to customers, you MUST sign and notarize the app:
- Join the Apple Developer Program and create a Developer ID Application certificate.
- Install the certificate in your keychain.
electron-builderfinds it and signs the app during the build. On a CI server, setCSC_LINKandCSC_KEY_PASSWORDinstead. - Set
APPLE_ID,APPLE_APP_SPECIFIC_PASSWORD, andAPPLE_TEAM_IDas environment variables. When those are present,electron-buildersends the app to Apple for notarization as part of the build.
Notarization can take several minutes. That is normal. Once it passes, your DMG opens on any Mac without the warning.
If your DMG looks wrong, or Gatekeeper sends it into another dimension, reach out to me on X (@chadmichel).


