Build Project - Native Desktop

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

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

Basic Usage

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

native-desktop build --target <target-type>

With Custom Configuration

If you need to specify a custom configuration file:

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

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

native-desktop build --config native-desktop.config.json5 --target exe

`--sign` (Optional)

Automatically sign the application after building.

Type: Boolean
Default: false

native-desktop build --config native-desktop.config.json5 --target dmg --sign

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

Supported Target Types

The available build targets vary by platform:

macOS
Windows
Linux

Native Desktop supports the following targets on macOS:

`dmg`

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

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.

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.

native-desktop build --target pkg

File Extension: .pkg
Distribution: Enterprise and Mac App Store
User Experience: Guided installation wizard
Recommended: For enterprise distribution

Native Desktop supports the following targets on Windows:

`exe`

Creates a portable Windows executable.

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.

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.

native-desktop build --target msi-wrapped

File Extension: .msi
Distribution: Enhanced installer with wrapper
User Experience: Advanced installation options
Recommended: For complex installations

Native Desktop supports the following targets on Linux:

`deb`

Creates a Debian package for Debian-based distributions.

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.

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.

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.

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.

native-desktop build --target snap

File Extension: .snap
Distribution: Snap Store
User Experience: Sandboxed application
Recommended: For Ubuntu and Snap ecosystem

Build Output

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

your-project/
├── bin/
├── src/
├── package.json
└── native-desktop.config.json5

Complete Examples

Building for macOS

# 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

# 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

# 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:

Configuration Loading: Reads the configuration file
Dependency Resolution: Ensures all dependencies are available
TypeScript Compilation: Compiles TypeScript to JavaScript
Asset Bundling: Bundles application assets and resources
Native Packaging: Creates platform-specific package
Output Generation: Writes build artifacts to bin/ directory
Signing (if --sign flag is used): Signs the application
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

Invalid Target Error

Error: Invalid target "xyz" for platform "mac". Supported targets: dmg, app, pkgSolution: Use a target type that is supported on your current platform. Check the supported targets list for your OS.

# macOS
native-desktop build --target dmg  # ✅ Valid
native-desktop build --target exe  # ❌ Invalid on macOS

Configuration File Not Found

Error: Configuration file not foundSolution: Ensure the configuration file exists and the path is correct.

# Check if file exists
ls native-desktop.config.json5

# Use correct path
native-desktop build --config ./native-desktop.config.json5 --target dmg

Build Directory Permission Error

Error: Permission denied: cannot write to bin/Solution: Ensure you have write permissions in the project directory.

# Check permissions
ls -la

# Fix permissions if needed
chmod 755 .

Missing Dependencies

Error: Cannot find module 'xyz'Solution: Install all project dependencies before building.

npm install
native-desktop build --target dmg

Signing Failed

Error: Code signing failedSolution: Ensure signing credentials are properly configured. Run the sign command separately for more control.

# Build without signing
native-desktop build --target dmg

# Sign separately
native-desktop sign bin/your-app.dmg --platform mac --identity "Developer ID"

Platform Limitations

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

To build for multiple platforms, you need to:

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

Build Optimization

Production Builds

For production releases, consider:

# 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:

# Use faster build targets
native-desktop build --target app  # macOS

CI/CD Integration

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

# 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

Test Before Building

Always test your application with native-desktop run before building for distribution

Version Management

Update version numbers in your config file before each production build

Build Verification

Test built applications on clean systems to ensure all dependencies are included

Code Signing

Always sign production builds to ensure user trust and meet platform requirements

​Prerequisites

​Basic Usage

​With Custom Configuration

​Command Options

​--config (Required)

​--target (Required)

​--sign (Optional)

​Supported Target Types

​dmg

​app

​pkg

​exe

​msi

​msi-wrapped

​deb

​rpm

​app-image

​flatpak

​snap

​Build Output

​Complete Examples

​Building for macOS

​Building for Windows

​Building for Linux

​Build Process

​Build Configuration

​Common Issues

​Platform Limitations

​Build Optimization

​Production Builds

​Development Builds

​CI/CD Integration

​Best Practices

Test Before Building

Version Management

Build Verification

Code Signing

Prerequisites

Basic Usage

With Custom Configuration

Command Options

`--config` (Required)

`--target` (Required)

`--sign` (Optional)

Supported Target Types

`dmg`

`app`

`pkg`

`exe`

`msi`

`msi-wrapped`

`deb`

`rpm`

`app-image`

`flatpak`

`snap`

Build Output

Complete Examples

Building for macOS

Building for Windows

Building for Linux

Build Process

Build Configuration

Common Issues

Platform Limitations

Build Optimization

Production Builds

Development Builds

CI/CD Integration

Best Practices