Skip to main content
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:
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

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

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
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
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 .
Error: Cannot find module 'xyz'Solution: Install all project dependencies before building.
npm install
native-desktop build --target dmg
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:
  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: 
# 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