Help us improve
Share bugs, ideas, or general feedback.
From aai-stack-electron
Configures multi-platform Electron app builds using esbuild for bundling TypeScript/React code, electron-builder for packaging DMG/EXE/AppImage, and native module handling.
npx claudepluginhub bradtaylorsf/alphaagent-teamHow this skill is triggered — by the user, by Claude, or both
Slash command
/aai-stack-electron:electron-build-configThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Configure the build pipeline for cross-platform Electron distribution with proper bundling, native module handling, and code signing.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Breaks plans, specs, or PRDs into thin vertical-slice issues on the project issue tracker using tracer bullets. Useful for converting high-level work into grabbable implementation tickets.
Share bugs, ideas, or general feedback.
Configure the build pipeline for cross-platform Electron distribution with proper bundling, native module handling, and code signing.
Source Files → esbuild → electron-builder → Distribution
↓ ↓ ↓ ↓
TypeScript Bundle JS Package App DMG/EXE/AppImage
+ React + Externals + Rebuild + Code Signing
# Build server code for Electron main process
esbuild src/server/index.ts \
--bundle \
--platform=node \
--format=cjs \
--outfile=dist/server/index.cjs \
--external:better-sqlite3 \
--external:sharp \
--external:keytar \
--external:electron \
--define:process.env.NODE_ENV=\"production\"
# Build Electron main/preload scripts
esbuild electron/main.ts electron/preload.ts \
--bundle \
--platform=node \
--format=cjs \
--outdir=electron-dist \
--out-extension:.js=.cjs \
--external:electron \
--external:keytar \
--external:better-sqlite3 \
--external:sharp
{
"scripts": {
"build": "vite build",
"build:server": "esbuild src/server/index.ts --bundle --platform=node --format=cjs --outfile=dist/server/index.cjs --external:better-sqlite3 --external:sharp --external:keytar",
"electron:build": "esbuild electron/*.ts --bundle --platform=node --format=cjs --outdir=electron-dist --out-extension:.js=.cjs --external:electron --external:keytar --external:better-sqlite3 --external:sharp",
"build:electron": "npm run build && npm run build:server && npm run electron:build",
"electron:dev": "NODE_ENV=development electron electron-dist/main.cjs",
"dev:electron": "concurrently \"npm run dev:client\" \"wait-on http://localhost:3000 && npm run electron:dev\"",
"dist": "npm run build:electron && electron-builder",
"dist:mac": "npm run build:electron && electron-builder --mac",
"dist:win": "npm run build:electron && electron-builder --win",
"dist:linux": "npm run build:electron && electron-builder --linux"
}
}
// electron-builder.config.cjs
module.exports = {
appId: 'com.yourcompany.yourapp',
productName: 'Your App Name',
// Directories
directories: {
output: 'release',
buildResources: 'build-resources',
},
// Files to include in the app
files: [
// Built output
'dist/**/*',
'electron-dist/**/*',
'public/**/*',
'package.json',
// Native modules with their binaries
'node_modules/better-sqlite3/**/*',
'node_modules/keytar/**/*',
'node_modules/sharp/**/*',
// Native module dependencies
'node_modules/bindings/**/*',
'node_modules/file-uri-to-path/**/*',
'node_modules/prebuild-install/**/*',
// Exclude dev files
'!**/*.ts',
'!**/*.tsx',
'!**/*.map',
'!**/node_modules/**/*.md',
'!**/node_modules/**/test/**',
'!**/node_modules/**/tests/**',
'!**/node_modules/**/*.d.ts',
],
// CRITICAL: Rebuild native modules for Electron
npmRebuild: true,
// Disable asar for simpler native module handling
asar: false,
// macOS Configuration
mac: {
category: 'public.app-category.developer-tools',
icon: 'build-resources/icon.icns',
target: [
{ target: 'dmg', arch: ['x64', 'arm64'] },
{ target: 'zip', arch: ['x64', 'arm64'] },
],
// Required for keytar and hardened runtime
hardenedRuntime: true,
gatekeeperAssess: false,
entitlements: 'build-resources/entitlements.mac.plist',
entitlementsInherit: 'build-resources/entitlements.mac.plist',
},
// DMG Configuration
dmg: {
contents: [
{ x: 130, y: 220 },
{ x: 410, y: 220, type: 'link', path: '/Applications' },
],
window: {
width: 540,
height: 380,
},
},
// Windows Configuration
win: {
icon: 'build-resources/icon.ico',
target: [
{ target: 'nsis', arch: ['x64'] },
],
// Sign Windows builds (requires certificate)
// certificateFile: 'path/to/cert.pfx',
// certificatePassword: process.env.WIN_CERT_PASSWORD,
},
// NSIS Installer Configuration
nsis: {
oneClick: false,
perMachine: false,
allowToChangeInstallationDirectory: true,
createDesktopShortcut: true,
createStartMenuShortcut: true,
},
// Linux Configuration
linux: {
icon: 'build-resources/icons',
target: [
{ target: 'AppImage', arch: ['x64'] },
{ target: 'deb', arch: ['x64'] },
],
category: 'Development',
maintainer: 'Your Name <your@email.com>',
},
// Publish configuration (for auto-updater)
publish: {
provider: 'github',
owner: 'your-org',
repo: 'your-repo',
releaseType: 'release',
},
};
<!-- build-resources/entitlements.mac.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- Allow JIT compilation (for V8/Node.js) -->
<key>com.apple.security.cs.allow-jit</key>
<true/>
<!-- Allow unsigned executable memory -->
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<!-- Allow DYLD environment variables -->
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<true/>
<!-- Keychain access for keytar -->
<key>com.apple.security.keychain-access-groups</key>
<array>
<string>$(AppIdentifierPrefix)com.yourcompany.yourapp</string>
</array>
</dict>
</plist>
// tsconfig.electron.json
{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"moduleResolution": "Node",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"outDir": "electron-dist",
"rootDir": "electron",
"declaration": false,
"sourceMap": false
},
"include": ["electron/**/*.ts"],
"exclude": ["node_modules"]
}
Create this structure:
build-resources/
├── icon.icns # macOS icon (512x512)
├── icon.ico # Windows icon
├── icons/ # Linux icons
│ ├── 16x16.png
│ ├── 32x32.png
│ ├── 48x48.png
│ ├── 64x64.png
│ ├── 128x128.png
│ ├── 256x256.png
│ └── 512x512.png
├── entitlements.mac.plist
└── background.png # DMG background (optional)
#!/bin/bash
# scripts/generate-icons.sh
# Requires: ImageMagick (brew install imagemagick)
SOURCE="source-icon.png" # Your 1024x1024 source
# Linux icons
mkdir -p build-resources/icons
for size in 16 32 48 64 128 256 512; do
convert "$SOURCE" -resize ${size}x${size} "build-resources/icons/${size}x${size}.png"
done
# macOS icns (requires iconutil on macOS)
mkdir -p icon.iconset
for size in 16 32 64 128 256 512; do
convert "$SOURCE" -resize ${size}x${size} "icon.iconset/icon_${size}x${size}.png"
convert "$SOURCE" -resize $((size*2))x$((size*2)) "icon.iconset/icon_${size}x${size}@2x.png"
done
iconutil -c icns icon.iconset -o build-resources/icon.icns
rm -rf icon.iconset
# Windows ico
convert "$SOURCE" -resize 256x256 build-resources/icon.ico
echo "Icons generated in build-resources/"
{
"scripts": {
"dev": "concurrently -n client,electron \"npm run dev:client\" \"npm run dev:electron-watch\"",
"dev:client": "vite",
"dev:electron-watch": "wait-on http://localhost:3000 && nodemon --watch electron --ext ts --exec \"npm run electron:build && npm run electron:dev\""
},
"devDependencies": {
"concurrently": "^8.0.0",
"nodemon": "^3.0.0",
"wait-on": "^7.0.0"
}
}
// electron/main.ts
const isDev = process.env.NODE_ENV === 'development';
// In development, load from Vite dev server
if (isDev) {
mainWindow.loadURL('http://localhost:3000');
} else {
// In production, load from built files
mainWindow.loadFile(path.join(app.getAppPath(), 'dist', 'index.html'));
}
files array--external flag in esbuilddependencies, not devDependenciesnode_modules and reinstall./node_modules/.bin/electron-rebuildcodesign --verify --deep --strict YourApp.appprocess.cwd() not used (returns /)app.getAppPath()app.getPath('userData')files arraynpmRebuild: true in electron-builder configUsed by:
electron-converter agent