> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bundlit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Building the Desktop App

> How to build the bundl desktop app for distribution

# Building the Desktop App

This guide explains how to build the bundl desktop app for macOS.

## Quick Start

From the `apps/desktop` folder, run:

```bash theme={null}
pnpm build:release
```

This single command builds everything you need.

## Output Files

After the build completes, your files are in:

```
target/release/bundle/macos/
├── bundl.app              # The macOS application
└── bundl_1.0.0_aarch64.dmg # The installer for distribution
```

### What each file is for:

| File                      | Purpose                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `bundl.app`               | The app itself. Double-click to run, or drag to Applications folder.                  |
| `bundl_1.0.0_aarch64.dmg` | The installer. Share this with users - they open it and drag the app to Applications. |

## Common Mistakes

### Looking in the wrong folder

The `target/release/` folder contains raw binaries that don't have icons:

```
target/release/
├── bundl      # ❌ Raw binary - don't use this directly
├── bundl.d    # ❌ Build metadata
└── bundle/    # ✅ Go inside here!
    └── macos/
        ├── bundl.app           # ✅ This is what you want
        └── bundl_1.0.0_aarch64.dmg
```

Always use the files inside `bundle/macos/`, not the raw binaries in `release/`.

## Testing the Build

1. Navigate to `target/release/bundle/macos/`
2. Double-click `bundl.app`
3. The app should open with the proper icon, no terminal window

## Distributing to Users

Share the `.dmg` file with users. When they open it:

1. A window appears with the bundl app and an Applications folder shortcut
2. They drag bundl to Applications
3. They can then launch bundl from their Applications folder or Spotlight

## Troubleshooting

### Build fails with DMG error

The `pnpm build:release` command handles this automatically. If you run `pnpm tauri build` directly, it may fail on the DMG step due to a Tauri bug. Always use `pnpm build:release`.

### App shows no icon

Make sure you're opening `bundl.app` from `bundle/macos/`, not the raw `bundl` binary from `release/`.

### Terminal opens when launching

You're double-clicking the raw binary instead of the `.app` bundle. Navigate to `bundle/macos/` and open `bundl.app`.