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

# Quick Start

> Get started with Native Desktop in minutes - create your first desktop application.

## 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](https://nodejs.org/))
* ✅ **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:

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

<Warning>
  Replace `YOUR_GITHUB_TOKEN` with your actual GitHub personal access token!
</Warning>

## Step 2: Install the CLI

Install the Native Desktop CLI globally:

```shellscript theme={null}
npm install -g @native-desktop/cli
```

Verify the installation:

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

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

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

<Tip>
  Choose "Manual Project" for a complete setup with all development tools configured.
</Tip>

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:

```shellscript theme={null}
native-desktop run
```

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

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

### Making Changes

Try editing your source code:

1. Open `src/index.ts` in your code editor
2. Make some changes
3. Save the file
4. 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:

<Tabs>
  <Tab title="macOS">
    ```shellscript theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    ```shellscript theme={null}
    # Build a portable EXE
    native-desktop build --target exe

    # Or build an MSI installer
    native-desktop build --target msi
    ```
  </Tab>
</Tabs>

Your built application will be in the `bin/` directory:

```shellscript theme={null}
ls bin/
```

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

For production distribution, sign your application:

<Tabs>
  <Tab title="macOS">
    ```shellscript theme={null}
    # 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"
    ```

    <Note>
      You need an Apple Developer ID certificate.
    </Note>
  </Tab>

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

    <Note>
      You need a code signing certificate. [Learn more](/sign#windows-signing)
    </Note>
  </Tab>
</Tabs>

<Info>
  Code signing is optional for development but **required** for distribution to prevent security warnings.
</Info>

## Complete Workflow Example

Here's the complete workflow from start to finish:

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

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

```shellscript theme={null}
# Lint your code
native-desktop lint

# Format your code
native-desktop fmt

# Check TypeScript types
native-desktop types
```

### 4. Build & Test

```shellscript theme={null}
# Build the app
native-desktop build --target dmg

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

## Common Issues

<AccordionGroup>
  <Accordion title="Cannot Install CLI - 401 Error">
    **Problem**: `npm ERR! 401 Unauthorized`

    **Solution**: Your GitHub token is missing or invalid.

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

    See [Installation Guide](/installation) for details.
  </Accordion>

  <Accordion title="Directory Not Empty Error">
    **Problem**: `NativeDesktop can only create new projects in an empty folder`

    **Solution**: The `create` command requires an empty directory.

    ```shellscript theme={null}
    mkdir my-new-app
    cd my-new-app
    native-desktop create
    ```
  </Accordion>

  <Accordion title="Build Failed - Invalid Target">
    **Problem**: `Invalid target for platform`

    **Solution**: Use a target supported by your operating system:

    * macOS: `dmg`, `app`, `pkg`
    * Windows: `exe`, `msi`, `msi-wrapped`
    * Linux: `deb`, `rpm`, `app-image`, `flatpak`, `snap`
  </Accordion>

  <Accordion title="App Won't Start">
    **Problem**: Application window doesn't open

    **Solution**: Check the terminal for error messages and:

    1. Ensure all dependencies are installed: `npm install`
    2. Check for TypeScript errors: `native-desktop types`
    3. Try removing node\_modules: `rm -rf node_modules && npm install`
  </Accordion>
</AccordionGroup>

## Quick Reference

### Essential Commands

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

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

<CardGroup cols={2}>
  <Card icon="sliders" title="Use Manual Project">
    Choose "Manual Project" when creating for a full-featured setup with all development tools
  </Card>

  <Card icon="check-double" title="Run Quality Checks">
    Always run `lint`, `fmt`, and `types` before building for production
  </Card>

  <Card icon="vial" title="Test Built Apps">
    Always test your built application before distributing to users
  </Card>

  <Card icon="signature" title="Sign for Distribution">
    Code sign your apps to avoid security warnings and build user trust
  </Card>
</CardGroup>

## Getting Help

Need assistance? We're here to help:

* 📚 **Documentation**: [Native Desktop Docs](/native-desktop/introduction)
* 📧 **Support**: [support@nativedesktop.com](mailto: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! 🚀