> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nativedesktop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Project

> Run your Native Desktop application in development mode

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:

```shellscript theme={null}
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`

```shellscript theme={null}
# 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

```shellscript theme={null}
# Navigate to project directory
cd my-native-desktop-app

# Run with default config
native-desktop run
```

### Using Custom Configuration

```shellscript theme={null}
# 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**
   ```shellscript theme={null}
   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**
   ```shellscript theme={null}
   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:

```json5 theme={null}
{
  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
}
```

<Info>
  Development mode typically enables additional debugging features that are disabled in production builds.
</Info>

## Common Use Cases

### Testing New Features

```shellscript theme={null}
# Start app to test new feature
native-desktop run

# Make changes and test
# Application auto-reloads
```

### Debugging Issues

```shellscript theme={null}
# Run with verbose logging
native-desktop run

# Check developer console
# Inspect error messages and logs
```

### UI/UX Development

```shellscript theme={null}
# Run application
native-desktop run

# Adjust UI components
# See changes instantly with hot reload
```

### Integration Testing

```shellscript theme={null}
# 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

```shellscript theme={null}
^C
Application stopped
```

## Common Issues

<AccordionGroup>
  <Accordion title="Configuration File Not Found">
    **Error**: `Configuration file not found: native-desktop.config.json5`

    **Solution**: Ensure the configuration file exists in your project root.

    ```shellscript theme={null}
    # Check if file exists
    ls native-desktop.config.json5

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

  <Accordion title="Port Already in Use">
    **Error**: `Port 3000 is already in use`

    **Solution**: Stop other applications using the same port or change the port in your configuration.

    ```shellscript theme={null}
    # Find process using the port
    lsof -i :3000

    # Kill the process
    kill -9 <PID>
    ```
  </Accordion>

  <Accordion title="Module Not Found Error">
    **Error**: `Cannot find module 'xyz'`

    **Solution**: Install missing dependencies.

    ```shellscript theme={null}
    # Install all dependencies
    npm install

    # Run again
    native-desktop run
    ```
  </Accordion>

  <Accordion title="TypeScript Compilation Error">
    **Error**: `TypeScript compilation failed`

    **Solution**: Fix TypeScript errors in your code.

    ```shellscript theme={null}
    # Check type errors
    native-desktop types

    # Fix errors in your code
    # Run again
    native-desktop run
    ```
  </Accordion>

  <Accordion title="Application Won't Start">
    **Error**: Application window doesn't appear

    **Solution**: Check terminal for error messages and verify configuration.

    ```shellscript theme={null}
    # Check for errors in terminal
    # Verify configuration is correct
    # Try running with fresh install
    rm -rf node_modules
    npm install
    native-desktop run
    ```
  </Accordion>
</AccordionGroup>

## Performance Tips

<CardGroup cols={2}>
  <Card title="Clean Cache" icon="broom">
    Periodically clean build caches if you experience slow startup times or unexpected behavior.
  </Card>

  <Card title="Optimize Dependencies" icon="gauge-high">
    Remove unused dependencies to improve startup time and reduce application size.
  </Card>

  <Card title="Use TypeScript" icon="code">
    TypeScript provides better development experience with type checking and IntelliSense.
  </Card>

  <Card title="Monitor Resources" icon="chart-line">
    Keep an eye on CPU and memory usage during development to identify performance issues early.
  </Card>
</CardGroup>

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

<Note>
  Always test your application with `native-desktop build` before releasing to ensure production behavior matches your expectations.
</Note>

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

```shellscript theme={null}
# 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:

```shellscript theme={null}
native-desktop run native-desktop.dev.json5
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep It Running" icon="circle-play">
    Keep the development server running while coding to see changes immediately.
  </Card>

  <Card title="Watch for Errors" icon="triangle-exclamation">
    Monitor the terminal for errors and warnings during development.
  </Card>

  <Card title="Regular Testing" icon="vial">
    Test frequently during development to catch issues early.
  </Card>

  <Card title="Clean Builds" icon="arrows-rotate">
    Occasionally restart the dev server for a fresh start, especially after major changes.
  </Card>
</CardGroup>

## Logs and Debugging

### Viewing Logs

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

```shellscript theme={null}
$ 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:

```json5 theme={null}
// 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:

```json theme={null}
{
  "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.