Build Configuration

This guide covers all configuration options available in electrobun.config for building and distributing your Electrobun applications.

Configuration File

Electrobun uses electrobun.config.ts in your project root to control how your application is built and packaged. The config file uses TypeScript with ESM syntax, providing type safety and modern JavaScript features.

Basic Structure

// electrobun.config.ts
import { type ElectrobunConfig } from "electrobun";

const config: ElectrobunConfig = {
  app: {
    name: "MyApp",
    identifier: "com.example.myapp",
    version: "1.0.0",
  },
  build: {
    bun: {
      entrypoint: "src/bun/index.ts",
    },
  },
};

export default config;

Dynamic Configuration

TypeScript config files support dynamic configuration with full type safety:

// electrobun.config.ts
import { type ElectrobunConfig } from "electrobun";
import { readFileSync } from 'fs';

// Read version from package.json
const packageJson = JSON.parse(readFileSync('./package.json', 'utf8'));

const config: ElectrobunConfig = {
  app: {
    name: "MyApp",
    identifier: process.env.APP_ID || "com.example.myapp",
    version: packageJson.version,
  },
  build: {
    bun: {
      entrypoint: "src/bun/index.ts",
      external: [],
    },
  },
  release: {
    bucketUrl: process.env.RELEASE_BUCKET_URL || "",
  },
};

export default config;

ASAR Packaging

Electrobun supports packaging your application resources into an ASAR archive. ASAR (Atom Shell Archive) is an archive format that combines multiple files into a single file, providing faster file access and improved security for production builds.

Configuration Options

const config: ElectrobunConfig = {
  build: {
    useAsar: true,
    asarUnpack: ["*.node", "*.dll", "*.dylib", "*.so"],
    // ... rest of config
  },
};

useAsar

Type: boolean

Default: false

Enables ASAR packaging for your application resources. When enabled, the entire app/ directory is packed into a single app.asar file.

asarUnpack

Type: string[]

Default: ["*.node", "*.dll", "*.dylib", "*.so"]

Glob patterns for files and folders that should be excluded from the ASAR archive. These files will remain unpacked in the app.asar.unpacked directory alongside the archive.

Common use cases for unpacking:

  • Native modules (*.node, *.dll, *.dylib, *.so)
  • Files that need to be accessed directly by external processes
  • Files that need to be executed or dynamically loaded
  • Large binary files that don't benefit from archiving

Example with ASAR Configuration

import { type ElectrobunConfig } from "electrobun";

const config: ElectrobunConfig = {
  app: {
    name: "MyApp",
    identifier: "com.example.myapp",
    version: "1.0.0",
  },
  build: {
    useAsar: true,
    asarUnpack: [
      "*.node",           // Native modules
      "*.dll",            // Windows DLLs
      "*.dylib",          // macOS dynamic libraries
      "*.so",             // Linux shared objects
      "data/large/**/*",  // Large data files
    ],
    bun: {
      entrypoint: "src/bun/index.ts",
    },
  },
};

export default config;

Benefits of ASAR Packaging

  • Performance: Faster file access and reduced I/O operations
  • Security: App code is extracted to randomized temp files with automatic cleanup
  • Distribution: Fewer files to manage and distribute
  • Integrity: Single archive is easier to verify and protect

Full example from the Electrobun Playground app

// electrobun.config.ts
import { type ElectrobunConfig } from "electrobun";

const config: ElectrobunConfig = {
    app: {
        name: "Electrobun (Playground)",
        identifier: "dev.electrobun.playground",
        version: "0.0.1",
    },
    build: {
        bun: {
            entrypoint: "src/bun/index.ts",
            external: [],
        },
        views: {
            mainview: {
                entrypoint: "src/mainview/index.ts",
                external: [],
            },
            myextension: {
                entrypoint: "src/myextension/preload.ts",
                external: [],
            },
            webviewtag: {
                entrypoint: "src/webviewtag/index.ts",
                external: [],
            },
        },
        copy: {
            "src/mainview/index.html": "views/mainview/index.html",
            "src/mainview/index.css": "views/mainview/index.css",
            "src/webviewtag/index.html": "views/webviewtag/index.html",
            "src/webviewtag/electrobun.png": "views/webviewtag/electrobun.png",
            "assets/electrobun-logo-32-template.png": "views/assets/electrobun-logo-32-template.png",
        },
        mac: {
            codesign: true,
            notarize: true,
            bundleCEF: true,
            entitlements: {
                "com.apple.security.device.camera": "This app needs camera access for video features",
                "com.apple.security.device.microphone": "This app needs microphone access for audio features",
            },
            icons: "icon.iconset",
        },
        linux: {
            bundleCEF: true,
        },
        win: {
            bundleCEF: true,
        },
    },
    scripts: {
        postBuild: "./buildScript.ts",
    },
    release: {
        bucketUrl: "https://static.electrobun.dev/playground/",
    },
};

export default config;