Skip to main content
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:
  1. Load your project configuration
  2. Compile your TypeScript code
  3. Start the application runtime
  4. 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:
  1. Start Development Server 
    native-desktop run
  2. Make Code Changes
    • Edit your source files in the src/ directory
    • Application will automatically reload
  3. Test Features
    • Interact with your application
    • Check console for errors or logs
  4. Iterate and Refine
    • Make additional changes
    • Test again until satisfied
  5. 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

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
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>
Error: Cannot find module 'xyz'Solution: Install missing dependencies.
# Install all dependencies
npm install

# Run again
native-desktop run
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
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:
FeatureDevelopment (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.