Build and Development Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• AGENTS.md
• CLAUDE.md
• src/main/index.ts
• src/main/updates.ts
• landing-page/package.json
• README.md

Messenger Unleashed utilizes a modern JavaScript toolchain centered around Bun and Electron to provide a desktop experience for Facebook Messenger. The workflow is split between the core Electron application and a Next.js-based landing page, utilizing TypeScript for type safety across the main and preload processes.

Development Environment and Tooling

The project requires Bun as the primary package manager and runtime, which is preferred over npm or yarn for dependency management and script execution.

Core Command Reference

The following scripts define the standard development cycle:

Command	Action	Description
bun install	Installation	Installs all dependencies; bun.lock is the authoritative lockfile.
bun run dev	Development	Compiles TypeScript and launches the Electron app with specific JS flags.
bun run debug	Debugging	Starts Electron with extensive environment variables for request blocking and trace logs.
bun run lint	Quality Control	Runs ESLint across the src/ directory.
bun run build	Distribution	Compiles assets and packages the app using electron-builder.

Sources: package.json:7-22, AGENTS.md:15-18, CLAUDE.md:15-25

Development Pipeline Flow

The development workflow follows a strict compilation-before-execution pattern.

The dev script specifically executes bun run build:ts before launching the Electron binary.
Sources: package.json:11-13, AGENTS.md:19, CLAUDE.md:20

Build System Architecture

The build system is managed by electron-builder, which handles the creation of platform-specific artifacts for macOS and Windows.

Compilation Stages

1. TypeScript Transpilation: The main process code is compiled via tsc using a dedicated configuration file (tsconfig.main.json), outputting to build/main/index.js.
2. Preload Bundling: Preload scripts are processed via a custom script (scripts/build-preload.cjs) to ensure security bridges are correctly prepared.
3. Packaging: The electron-builder tool consumes the compiled build/** directory along with static assets like icon.icns, icon.ico, and themes.css.

Sources: package.json:8-10, package.json:89-96, CLAUDE.md:131-133

Build Configuration Table

Key build metadata defined in package.json:

Property	Value	Description
appId	com.messenger.unleashed	Unique identifier for the application.
productName	Messenger Unleashed	The name shown in the OS and installers.
mac.target	["dmg", "zip"]	Artifacts produced for macOS.
win.target	["nsis", "portable"]	Artifacts produced for Windows.
nsis.oneClick	false	Allows users to change installation directory on Windows.

Sources: package.json:57-88

Distribution and Updates

The project implements automated update mechanisms and platform-specific installation scripts.

Auto-Update Mechanism

Updates are handled differently depending on the operating system:

• Windows: Uses electron-updater for automatic background downloading and installation on quit.
• macOS: Utilizes a custom shell script (install.sh) fetched from the GitHub repository, executed via osascript to request administrator privileges.

Quality Assurance and Standards

Testing Guidelines

While a formal automated test suite is partially implemented (using vitest), current guidelines emphasize manual verification of core features before pull requests:

• Launching the app and verifying chat loads.
• Toggling privacy features (Read Receipts, Typing Indicators).
• Switching themes (OLED, Compact) and confirming persistence via electron-store.
• Verifying platform-specific behaviors (macOS menu bar mode, Windows tray toggle).

Sources: AGENTS.md:27-33, package.json:20-22

Coding Standards

• Naming: Use camelCase for identifiers.
• Indentation: 2-space indentation with no trailing semicolons.
• Commits: Follow Conventional Commits (e.g., feat:, fix:, chore:).
• Architecture: Keep the renderer as vanilla as possible, injecting modifications via insertCSS or executeJavaScript from the main process.

Sources: AGENTS.md:21-25, AGENTS.md:35-36, CLAUDE.md:135-144

Landing Page Development

The landing page is a separate Next.js project located in the landing-page/ directory. It uses its own dependency stack and build commands.

• Environment: Next.js 16.1.0 and React 19.2.3.
• Development: bun run dev (executed within the landing-page/ directory).
• Production: bun run build.

Sources: landing-page/package.json:4-13, landing-page/README.md:5-15

Conclusion

The Messenger Unleashed workflow is designed for rapid iteration using Bun's performance benefits. By separating main process logic, preload security bridges, and CSS-based themes, the project maintains a modular structure that supports cross-platform builds and automated updates while ensuring a native desktop feel.