Quick Start - Native Desktop

Build Your First Desktop App in 5 Minutes

This guide will walk you through creating your first Native Desktop application from scratch. By the end, you’ll have a working desktop app built and running on your machine.

Prerequisites Checklist

Before you begin, make sure you have:

✅ Node.js 18+ installed (Download)
✅ Native Desktop license purchased via Polar.sh
✅ GitHub account with repository access
✅ GitHub Personal Access Token with read:packages scope

Step 1: Configure npm Authentication

First, configure npm to access Native Desktop packages from GitHub:

# Create or edit ~/.npmrc
echo "@native-desktop:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

Replace YOUR_GITHUB_TOKEN with your actual GitHub personal access token!

Step 2: Install the CLI

Install the Native Desktop CLI globally:

npm install -g @native-desktop/cli

Verify the installation:

native-desktop --version

You should see the version number (e.g., 0.0.6).

Step 3: Create Your Project

Create a new directory and initialize your project:

# Create project directory
mkdir my-first-app

# Navigate into the directory
cd my-first-app

# Create the project
native-desktop create

The CLI will prompt you for project details. Here’s an example setup:

✔ Select the project type: Manual Project
✔ Enter a name for your project: My First App
✔ Enter the initial version of your project: 1.0.0
✔ Enter the package identifier: my-first-app
✔ Enter a brief description of your project: My first Native Desktop application
✔ Enter the author name: Your Name <your.email@example.com>
✔ Enter your project's domain URL: https://example.com

Choose “Manual Project” for a complete setup with all development tools configured.

The CLI will automatically:

Create the project structure
Generate configuration files
Install all dependencies

Step 4: Run Your App

Start your application in development mode:

native-desktop run

🎉 Your app window should open! You now have a running Native Desktop application.

The app runs with hot-reload enabled - any changes you make to your code will automatically refresh the app.

Making Changes

Try editing your source code:

Open src/index.ts in your code editor
Make some changes
Save the file
Watch your app automatically reload!

Press Ctrl+C in the terminal to stop the app when you’re done testing.

Step 5: Build Your App

When you’re ready to create a distributable version, build your app:

macOS
Windows

# Build a DMG installer
native-desktop build --target dmg

# Or build an APP bundle
native-desktop build --target app

# Or build a PKG installer
native-desktop build --target pkg

# Build a portable EXE
native-desktop build --target exe

# Or build an MSI installer
native-desktop build --target msi

Your built application will be in the bin/ directory:

ls bin/

Step 6: Sign Your App (Optional but Recommended)

For production distribution, sign your application:

macOS
Windows

# Sign with Developer ID
native-desktop sign bin/My-First-App.dmg \
  --platform mac \
  --identity "Developer ID Application: Your Name (TEAMID)"

# Sign with notarization (recommended for distribution)
native-desktop sign bin/My-First-App.dmg \
  --platform mac \
  --identity "Developer ID Application: Your Name (TEAMID)" \
  --apple-id "your.email@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx" \
  --team-id "TEAMID"

You need an Apple Developer ID certificate.

# Sign with certificate file
native-desktop sign bin/My-First-App.exe \
  --platform windows \
  --cert-file "path/to/certificate.pfx" \
  --cert-password "your-cert-password"

You need a code signing certificate. Learn more

Code signing is optional for development but required for distribution to prevent security warnings.

Complete Workflow Example

Here’s the complete workflow from start to finish:

# 1. Setup authentication (one-time)
echo "@native-desktop:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc

# 2. Install CLI (one-time)
npm install -g @native-desktop/cli

# 3. Create project
mkdir my-first-app && cd my-first-app
native-desktop create

# 4. Run in development
native-desktop run

# 5. Build for production (in a new terminal)
native-desktop build --target dmg

# 6. Sign the app
native-desktop sign bin/My-First-App.dmg --platform mac --identity "Developer ID"

# 7. Your app is ready in bin/
ls -lh bin/

What’s Next?

Congratulations! You’ve created your first Native Desktop application.

Development Workflow

For day-to-day development, follow this workflow:

1. Start Development

# Run your app
native-desktop run

2. Write Code

Edit your files in src/ - the app will automatically reload with your changes.

3. Check Code Quality

# Lint your code
native-desktop lint

# Format your code
native-desktop fmt

# Check TypeScript types
native-desktop types

4. Build & Test

# Build the app
native-desktop build --target dmg

# Test the built app
open bin/My-App.dmg

Common Issues

Cannot Install CLI - 401 Error

Problem: npm ERR! 401 UnauthorizedSolution: Your GitHub token is missing or invalid.

Check your .npmrc file has the correct token
Verify the token has read:packages scope
Ensure you have repository access

See Installation Guide for details.

Directory Not Empty Error

Problem: NativeDesktop can only create new projects in an empty folderSolution: The create command requires an empty directory.

mkdir my-new-app
cd my-new-app
native-desktop create

Build Failed - Invalid Target

Problem: Invalid target for platformSolution: Use a target supported by your operating system:

macOS: dmg, app, pkg
Windows: exe, msi, msi-wrapped
Linux: deb, rpm, app-image, flatpak, snap

App Won't Start

Problem: Application window doesn’t openSolution: Check the terminal for error messages and:

Ensure all dependencies are installed: npm install
Check for TypeScript errors: native-desktop types
Try removing node_modules: rm -rf node_modules && npm install

Quick Reference

Essential Commands

# Create project
native-desktop create

# Run in development
native-desktop run

# Build for production
native-desktop build --target <dmg|exe|deb|etc>

# Sign application
native-desktop sign [app-path]

# Code quality
native-desktop lint    # Check code quality
native-desktop fmt     # Format code
native-desktop types   # Check types

Project Structure

my-first-app/
├── src/                          # Your source code
│   └── index.ts                  # Main entry point
├── bin/                          # Build output (after build)
├── package.json                  # Dependencies
├── native-desktop.config.json5   # App configuration
├── tsconfig.json                 # TypeScript config
└── .eslintrc.json                # Linting rules

Tips for Success

Use Manual Project

Choose “Manual Project” when creating for a full-featured setup with all development tools

Run Quality Checks

Always run lint, fmt, and types before building for production

Test Built Apps

Always test your built application before distributing to users

Sign for Distribution

Code sign your apps to avoid security warnings and build user trust

Getting Help

Need assistance? We’re here to help:

📚 Documentation: Native Desktop Docs
📧 Support: support@nativedesktop.com
🐛 Bug Reports: GitHub Issues

Ready to build something amazing? You now have everything you need to create professional desktop applications with Native Desktop. Happy coding! 🚀

​Build Your First Desktop App in 5 Minutes

​Prerequisites Checklist

​Step 1: Configure npm Authentication

​Step 2: Install the CLI

​Step 3: Create Your Project

​Step 4: Run Your App

​Making Changes

​Step 5: Build Your App

​Step 6: Sign Your App (Optional but Recommended)

​Complete Workflow Example

​What’s Next?

​Development Workflow

​1. Start Development

​2. Write Code

​3. Check Code Quality

​4. Build & Test

​Common Issues

​Quick Reference

​Essential Commands

​Project Structure

​Tips for Success

Use Manual Project

Run Quality Checks

Test Built Apps

Sign for Distribution

​Getting Help

Build Your First Desktop App in 5 Minutes

Prerequisites Checklist

Step 1: Configure npm Authentication

Step 2: Install the CLI

Step 3: Create Your Project

Step 4: Run Your App

Making Changes

Step 5: Build Your App

Step 6: Sign Your App (Optional but Recommended)

Complete Workflow Example

What’s Next?

Development Workflow

1. Start Development

2. Write Code

3. Check Code Quality

4. Build & Test

Common Issues

Quick Reference

Essential Commands

Project Structure

Tips for Success

Getting Help