Run Project - Native Desktop

The run command starts your Native Desktop application in development mode, allowing you to test and develop your application with live updates and debugging capabilities.

Prerequisites

Before running your project, ensure:

Your project has been created using native-desktop create
All dependencies are installed (npm install)
You have a valid native-desktop.config.json5 configuration file

Basic Usage

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

native-desktop run

This command will:

Load your project configuration
Compile your TypeScript code
Start the application runtime
Launch your application window

Command Options

`[project-config-file]` (Optional)

Path to the project configuration file.

Type: String (positional argument)
Default: native-desktop.config.json5
Example: custom-config.json5

# Use default configuration
native-desktop run

# Use custom configuration
native-desktop run custom-config.json5

Development Features

When running in development mode, you get access to several helpful features:

Hot Reload

Your application automatically reloads when you make changes to your source code, allowing for rapid development and testing.

Debug Console

Access to developer tools and debug console for troubleshooting and inspecting your application’s behavior.

Error Messages

Detailed error messages and stack traces to help identify and fix issues quickly.

Live Testing

Test your application’s functionality in real-time without needing to rebuild after every change.

Complete Examples

Using Default Configuration

# Navigate to project directory
cd my-native-desktop-app

# Run with default config
native-desktop run

Using Custom Configuration

# Run with development config
native-desktop run native-desktop.dev.json5

# Run with staging config
native-desktop run native-desktop.staging.json5

# Run with custom path
native-desktop run configs/development.json5

Development Workflow

A typical development workflow looks like this:

Start Development Server
native-desktop run
Make Code Changes
- Edit your source files in the src/ directory
- Application will automatically reload
Test Features
- Interact with your application
- Check console for errors or logs
Iterate and Refine
- Make additional changes
- Test again until satisfied

Run Quality Checks

native-desktop lint
native-desktop fmt
native-desktop types

Configuration File

The run command reads settings from your project configuration file. Here’s a basic structure:

{
  name: "My App",
  version: "1.0.0",
  main: "src/index.ts",
  window: {
    width: 1200,
    height: 800,
    resizable: true,
    title: "My Native Desktop App"
  },
  devtools: true
}

Development mode typically enables additional debugging features that are disabled in production builds.

Common Use Cases

Testing New Features

# Start app to test new feature
native-desktop run

# Make changes and test
# Application auto-reloads

Debugging Issues

# Run with verbose logging
native-desktop run

# Check developer console
# Inspect error messages and logs

UI/UX Development

# Run application
native-desktop run

# Adjust UI components
# See changes instantly with hot reload

Integration Testing

# Run with test configuration
native-desktop run native-desktop.test.json5

# Test integrations and APIs

Stopping the Application

To stop the running application:

Close the application window, or
Press Ctrl+C in the terminal where the command is running

^C
Application stopped

Common Issues

Configuration File Not Found

Error: Configuration file not found: native-desktop.config.json5Solution: Ensure the configuration file exists in your project root.

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

# If missing, specify correct path
native-desktop run path/to/config.json5

Port Already in Use

Error: Port 3000 is already in useSolution: Stop other applications using the same port or change the port in your configuration.

# Find process using the port
lsof -i :3000

# Kill the process
kill -9 <PID>

Module Not Found Error

Error: Cannot find module 'xyz'Solution: Install missing dependencies.

# Install all dependencies
npm install

# Run again
native-desktop run

TypeScript Compilation Error

Error: TypeScript compilation failedSolution: Fix TypeScript errors in your code.

# Check type errors
native-desktop types

# Fix errors in your code
# Run again
native-desktop run

Application Won't Start

Error: Application window doesn’t appearSolution: Check terminal for error messages and verify configuration.

# Check for errors in terminal
# Verify configuration is correct
# Try running with fresh install
rm -rf node_modules
npm install
native-desktop run

Performance Tips

Clean Cache

Periodically clean build caches if you experience slow startup times or unexpected behavior.

Optimize Dependencies

Remove unused dependencies to improve startup time and reduce application size.

Use TypeScript

TypeScript provides better development experience with type checking and IntelliSense.

Monitor Resources

Keep an eye on CPU and memory usage during development to identify performance issues early.

Development vs Production

Understanding the differences between development and production modes:

Feature	Development (`run`)	Production (`build`)
Hot Reload	✅ Enabled	❌ Disabled
DevTools	✅ Enabled	❌ Disabled
Source Maps	✅ Enabled	⚠️ Optional
Minification	❌ Disabled	✅ Enabled
Optimization	❌ Minimal	✅ Full
Startup Time	⚠️ Slower	✅ Faster
File Size	⚠️ Larger	✅ Smaller

Always test your application with native-desktop build before releasing to ensure production behavior matches your expectations.

Keyboard Shortcuts

When running in development mode, you can use keyboard shortcuts (platform-dependent):

Reload: Cmd+R (macOS) / Ctrl+R (Windows/Linux)
DevTools: Cmd+Option+I (macOS) / Ctrl+Shift+I (Windows/Linux)
Quit: Cmd+Q (macOS) / Alt+F4 (Windows/Linux)

Environment Variables

You can use environment variables to customize the development environment:

# Set custom environment variables
NODE_ENV=development native-desktop run

# Use different API endpoints
API_URL=http://localhost:8080 native-desktop run

# Enable debug logging
DEBUG=* native-desktop run

Multiple Configurations

You can maintain multiple configuration files for different environments:

project/
├── native-desktop.config.json5          # Production
├── native-desktop.dev.json5             # Development
├── native-desktop.staging.json5         # Staging
└── native-desktop.test.json5            # Testing

Then run with the appropriate configuration:

native-desktop run native-desktop.dev.json5

Best Practices

Keep It Running

Keep the development server running while coding to see changes immediately.

Watch for Errors

Monitor the terminal for errors and warnings during development.

Regular Testing

Test frequently during development to catch issues early.

Clean Builds

Occasionally restart the dev server for a fresh start, especially after major changes.

Logs and Debugging

Viewing Logs

Application logs are displayed in the terminal where you ran the command:

$ native-desktop run

[INFO] Loading configuration...
[INFO] Starting application...
[INFO] Window created: 1200x800
[INFO] Application ready

Debug Mode

Enable verbose logging for more detailed information:

// native-desktop.config.json5
{
  debug: true,
  verbose: true
}

Integration with Code Editors

The run command works seamlessly with popular code editors:

VS Code

Create a launch configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Run Native Desktop",
  "program": "${workspaceFolder}/node_modules/@native-desktop/cli/bin/cli.js",
  "args": ["run"]
}

WebStorm

Create a Node.js run configuration pointing to the Native Desktop CLI.

​Prerequisites

​Basic Usage

​Command Options

​[project-config-file] (Optional)

​Development Features

​Hot Reload

​Debug Console

​Error Messages

​Live Testing

​Complete Examples

​Using Default Configuration

​Using Custom Configuration

​Development Workflow

​Configuration File

​Common Use Cases

​Testing New Features

​Debugging Issues

​UI/UX Development

​Integration Testing

​Stopping the Application

​Common Issues

​Performance Tips

Clean Cache

Optimize Dependencies

Use TypeScript

Monitor Resources

​Development vs Production

​Keyboard Shortcuts

​Environment Variables

​Multiple Configurations

​Best Practices

Keep It Running

Watch for Errors

Regular Testing

Clean Builds

​Logs and Debugging

​Viewing Logs

​Debug Mode

​Integration with Code Editors

​VS Code

​WebStorm

Prerequisites

Basic Usage

Command Options

`[project-config-file]` (Optional)

Development Features

Hot Reload

Debug Console

Error Messages

Live Testing

Complete Examples

Using Default Configuration

Using Custom Configuration

Development Workflow

Configuration File

Common Use Cases

Testing New Features

Debugging Issues

UI/UX Development

Integration Testing

Stopping the Application

Common Issues

Performance Tips

Development vs Production

Keyboard Shortcuts

Environment Variables

Multiple Configurations

Best Practices

Logs and Debugging

Viewing Logs

Debug Mode

Integration with Code Editors

VS Code

WebStorm