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

# Build Project

> Build and package your Native Desktop application for distribution

The `build` command compiles and packages your Native Desktop application into distributable formats for your target platform. This command creates production-ready binaries that can be distributed to end users.

## Prerequisites

Before building your project, ensure:

* Your project has been created using `native-desktop create`
* All dependencies are installed (`npm install`)
* Your application has been tested in development mode
* You have a valid `native-desktop.config.json5` configuration file

<Warning>
  Native Desktop only allows you to build native applications for the operating system you are currently using. Cross-platform builds are not supported.
</Warning>

## Basic Usage

To build your project, open the terminal in the **root directory** of your Native Desktop project and run:

```shellscript theme={null}
native-desktop build --target <target-type>
```

### With Custom Configuration

If you need to specify a custom configuration file:

```shellscript theme={null}
native-desktop build --config <config-file> --target <target-type>
```

## Command Options

### `--config` (Required)

Path to the project configuration file.

* **Type**: String
* **Default**: `native-desktop.config.json5`
* **Example**: `--config my-config.json5`

```shellscript theme={null}
native-desktop build --config native-desktop.config.json5 --target dmg
```

### `--target` (Required)

Output format for the build. The available targets depend on your operating system.

* **Type**: String
* **Required**: Yes

```shellscript theme={null}
native-desktop build --config native-desktop.config.json5 --target exe
```

### `--sign` (Optional)

Automatically sign the application after building.

* **Type**: Boolean
* **Default**: `false`

```shellscript theme={null}
native-desktop build --config native-desktop.config.json5 --target dmg --sign
```

<Info>
  When using `--sign`, the CLI will automatically sign your application after the build completes. This requires proper signing credentials to be configured.
</Info>

## Supported Target Types

The available build targets vary by platform:

<Tabs>
  <Tab title="macOS">
    Native Desktop supports the following targets on macOS:

    ### `dmg`

    Creates a macOS Disk Image (.dmg) file for distribution.

    ```shellscript theme={null}
    native-desktop build --target dmg
    ```

    * **File Extension**: `.dmg`
    * **Distribution**: App Store and direct distribution
    * **User Experience**: Drag-and-drop installation
    * **Recommended**: ✅ Best for public distribution

    ### `app`

    Creates a macOS application bundle (.app) directory.

    ```shellscript theme={null}
    native-desktop build --target app
    ```

    * **File Type**: Directory bundle
    * **Distribution**: Development and testing
    * **User Experience**: Raw application bundle
    * **Recommended**: For development only

    ### `pkg`

    Creates a macOS Installer Package (.pkg) file.

    ```shellscript theme={null}
    native-desktop build --target pkg
    ```

    * **File Extension**: `.pkg`
    * **Distribution**: Enterprise and Mac App Store
    * **User Experience**: Guided installation wizard
    * **Recommended**: For enterprise distribution
  </Tab>

  <Tab title="Windows">
    Native Desktop supports the following targets on Windows:

    ### `exe`

    Creates a portable Windows executable.

    ```shellscript theme={null}
    native-desktop build --target exe
    ```

    * **File Extension**: `.exe`
    * **Distribution**: Portable, no installation required
    * **User Experience**: Single executable file
    * **Recommended**: ✅ Best for portable apps

    ### `msi`

    Creates a Windows Installer package.

    ```shellscript theme={null}
    native-desktop build --target msi
    ```

    * **File Extension**: `.msi`
    * **Distribution**: Enterprise and standard distribution
    * **User Experience**: Standard Windows installation
    * **Recommended**: ✅ Best for enterprise deployment

    ### `msi-wrapped`

    Creates an enhanced MSI installer with additional features.

    ```shellscript theme={null}
    native-desktop build --target msi-wrapped
    ```

    * **File Extension**: `.msi`
    * **Distribution**: Enhanced installer with wrapper
    * **User Experience**: Advanced installation options
    * **Recommended**: For complex installations
  </Tab>

  <Tab title="Linux">
    Native Desktop supports the following targets on Linux:

    ### `deb`

    Creates a Debian package for Debian-based distributions.

    ```shellscript theme={null}
    native-desktop build --target deb
    ```

    * **File Extension**: `.deb`
    * **Distribution**: Ubuntu, Debian, Linux Mint
    * **User Experience**: Standard package manager installation
    * **Recommended**: ✅ For Debian-based systems

    ### `rpm`

    Creates an RPM package for Red Hat-based distributions.

    ```shellscript theme={null}
    native-desktop build --target rpm
    ```

    * **File Extension**: `.rpm`
    * **Distribution**: Fedora, Red Hat, CentOS
    * **User Experience**: Standard package manager installation
    * **Recommended**: ✅ For Red Hat-based systems

    ### `app-image`

    Creates an AppImage portable application.

    ```shellscript theme={null}
    native-desktop build --target app-image
    ```

    * **File Extension**: `.AppImage`
    * **Distribution**: Universal Linux binary
    * **User Experience**: Single portable file
    * **Recommended**: ✅ For universal distribution

    ### `flatpak`

    Creates a Flatpak package.

    ```shellscript theme={null}
    native-desktop build --target flatpak
    ```

    * **File Format**: Flatpak bundle
    * **Distribution**: Flatpak repositories
    * **User Experience**: Sandboxed application
    * **Recommended**: For Flatpak ecosystem

    ### `snap`

    Creates a Snap package.

    ```shellscript theme={null}
    native-desktop build --target snap
    ```

    * **File Extension**: `.snap`
    * **Distribution**: Snap Store
    * **User Experience**: Sandboxed application
    * **Recommended**: For Ubuntu and Snap ecosystem
  </Tab>
</Tabs>

## Build Output

After successful execution, the Native Desktop CLI generates build output inside a directory named `bin/` in your project root:

```text theme={null}
your-project/
├── bin/
├── src/
├── package.json
└── native-desktop.config.json5
```

## Complete Examples

### Building for macOS

```shellscript theme={null}
# Build DMG for distribution
native-desktop build --config native-desktop.config.json5 --target dmg

# Build and sign DMG
native-desktop build --config native-desktop.config.json5 --target dmg --sign

# Build PKG for enterprise
native-desktop build --config native-desktop.config.json5 --target pkg

# Build APP bundle for testing
native-desktop build --config native-desktop.config.json5 --target app
```

### Building for Windows

```shellscript theme={null}
# Build portable EXE
native-desktop build --config native-desktop.config.json5 --target exe

# Build MSI installer
native-desktop build --config native-desktop.config.json5 --target msi

# Build and sign MSI
native-desktop build --config native-desktop.config.json5 --target msi --sign
```

### Building for Linux

```shellscript theme={null}
# Build DEB package
native-desktop build --config native-desktop.config.json5 --target deb

# Build RPM package
native-desktop build --config native-desktop.config.json5 --target rpm

# Build AppImage
native-desktop build --config native-desktop.config.json5 --target app-image

# Build Flatpak
native-desktop build --config native-desktop.config.json5 --target flatpak

# Build Snap
native-desktop build --config native-desktop.config.json5 --target snap
```

## Build Process

The build command performs the following steps:

1. **Configuration Loading**: Reads the configuration file
2. **Dependency Resolution**: Ensures all dependencies are available
3. **TypeScript Compilation**: Compiles TypeScript to JavaScript
4. **Asset Bundling**: Bundles application assets and resources
5. **Native Packaging**: Creates platform-specific package
6. **Output Generation**: Writes build artifacts to `bin/` directory
7. **Signing** (if `--sign` flag is used): Signs the application
8. **Verification**: Validates the build output

## Build Configuration

The build process uses settings from your `native-desktop.config.json5` file. Key configuration options include:

* Application metadata (name, version, description)
* Build targets and architectures
* Icon and asset paths
* Platform-specific settings
* Code signing configuration

## Common Issues

<AccordionGroup>
  <Accordion title="Invalid Target Error">
    **Error**: `Invalid target "xyz" for platform "mac". Supported targets: dmg, app, pkg`

    **Solution**: Use a target type that is supported on your current platform. Check the supported targets list for your OS.

    ```shellscript theme={null}
    # macOS
    native-desktop build --target dmg  # ✅ Valid
    native-desktop build --target exe  # ❌ Invalid on macOS
    ```
  </Accordion>

  <Accordion title="Configuration File Not Found">
    **Error**: `Configuration file not found`

    **Solution**: Ensure the configuration file exists and the path is correct.

    ```shellscript theme={null}
    # Check if file exists
    ls native-desktop.config.json5

    # Use correct path
    native-desktop build --config ./native-desktop.config.json5 --target dmg
    ```
  </Accordion>

  <Accordion title="Build Directory Permission Error">
    **Error**: `Permission denied: cannot write to bin/`

    **Solution**: Ensure you have write permissions in the project directory.

    ```shellscript theme={null}
    # Check permissions
    ls -la

    # Fix permissions if needed
    chmod 755 .
    ```
  </Accordion>

  <Accordion title="Missing Dependencies">
    **Error**: `Cannot find module 'xyz'`

    **Solution**: Install all project dependencies before building.

    ```shellscript theme={null}
    npm install
    native-desktop build --target dmg
    ```
  </Accordion>

  <Accordion title="Signing Failed">
    **Error**: `Code signing failed`

    **Solution**: Ensure signing credentials are properly configured. Run the `sign` command separately for more control.

    ```shellscript theme={null}
    # Build without signing
    native-desktop build --target dmg

    # Sign separately
    native-desktop sign bin/your-app.dmg --platform mac --identity "Developer ID"
    ```
  </Accordion>
</AccordionGroup>

## Platform Limitations

<Note>
  **Cross-Platform Builds**: You can only build for the operating system you are currently using. For example:

  * On macOS → Build macOS apps only
  * On Windows → Build Windows apps only
  * On Linux → Build Linux apps only
</Note>

To build for multiple platforms, you need to:

1. Use a machine running each target OS, or
2. Use cloud build services with multiple OS environments, or
3. Use virtual machines or containers for each platform

## Build Optimization

### Production Builds

For production releases, consider:

```shellscript theme={null}
# Build with signing enabled
native-desktop build --target dmg --sign

# Verify build output
ls -lh bin/

# Test the built application
open bin/your-app.dmg  # macOS
```

### Development Builds

For testing and development:

```shellscript theme={null}
# Use faster build targets
native-desktop build --target app  # macOS
```

## CI/CD Integration

The build command can be integrated into CI/CD pipelines:

```yaml theme={null}
# Example GitHub Actions workflow
- name: Build Application
  run: |
    native-desktop build --config native-desktop.config.json5 --target dmg
    
- name: Upload Artifacts
  uses: actions/upload-artifact@v3
  with:
    name: build-output
    path: bin/
```

## Best Practices

<CardGroup cols={2}>
  <Card icon="vial" title="Test Before Building">
    Always test your application with `native-desktop run` before building for distribution
  </Card>

  <Card icon="tag" title="Version Management">
    Update version numbers in your config file before each production build
  </Card>

  <Card icon="check-double" title="Build Verification">
    Test built applications on clean systems to ensure all dependencies are included
  </Card>

  <Card icon="certificate" title="Code Signing">
    Always sign production builds to ensure user trust and meet platform requirements
  </Card>
</CardGroup>