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

# Installation Guide

> Complete guide to installing and configuring Native Desktop packages

## Overview

Native Desktop packages are distributed as private packages on GitHub via Polar.sh. When you purchase a Native Desktop license, you gain access to the private repository containing all packages based on your plan.

## Available Packages

The Native Desktop ecosystem includes the following packages:

| Package    | Description                                   | npm Package Name         |
| ---------- | --------------------------------------------- | ------------------------ |
| **CLI**    | Command-line interface for project management | `@native-desktop/cli`    |
| **Config** | Configuration management utilities            | `@native-desktop/config` |
| **Core**   | Core Native Desktop functionality             | `@native-desktop/core`   |
| **React**  | React integration for Native Desktop          | `@native-desktop/react`  |
| **App**    | Application runtime and utilities             | `@native-desktop/app`    |

<Note>
  All packages are scoped under `@native-desktop` and hosted on GitHub Packages. You will receive read-only access to these packages after purchasing a license.
</Note>

## Prerequisites

Before installing Native Desktop packages, ensure you have:

* **Node.js** version 16 or higher
* **npm** version 7 or higher (or **yarn** 1.22+)
* A **GitHub account**
* A **Native Desktop license** (purchased via Polar.sh)
* Access to the Native Desktop private repository

## Step 1: Purchase a License

1. Visit [Polar.sh Native Desktop](https://nativedesktop.com) (or your purchase portal)
2. Select a plan that fits your needs
3. Complete the purchase process
4. You will receive an email with repository access instructions

<Info>
  Repository access is granted automatically upon purchase. If you don't receive access within a few minutes, contact support.
</Info>

## Step 2: Create a GitHub Personal Access Token

To install packages from GitHub Packages, you need to create a personal access token (classic) with the appropriate permissions.

### Creating the Token

1. Go to [GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)
2. Click **Generate new token** → **Generate new token (classic)**
3. Configure the token:
   * **Note**: `Native Desktop Packages` (or any descriptive name)
   * **Expiration**: Choose an expiration period (90 days recommended)
   * **Scopes**: Select the following:
     * ✅ `read:packages` - Required to download packages
4. Click **Generate token**
5. **Copy the token immediately** - You won't be able to see it again!

<Warning>
  Treat your personal access token like a password. Never commit it to version control or share it publicly.
</Warning>

### Example Token Permissions

```text theme={null}
Scopes:
  ✅ read:packages - Download packages from GitHub Package Registry
```

<Tip>
  Store your token securely in a password manager. You'll need it for authentication.
</Tip>

## Step 3: Configure npm Authentication

You need to configure npm to authenticate with GitHub Packages using your personal access token.

### Option A: User-Level Configuration (Recommended)

Configure authentication globally in your user `.npmrc` file:

```shellscript theme={null}
# Edit or create ~/.npmrc
nano ~/.npmrc
```

Add the following lines, replacing `YOUR_GITHUB_TOKEN` with your personal access token:

```text theme={null}
@native-desktop:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

<Note>
  The `~/.npmrc` file is located at:

  * **macOS/Linux**: `~/.npmrc`
  * **Windows**: `C:\Users\YourUsername\.npmrc`
</Note>

### Option B: Project-Level Configuration

For project-specific configuration, create an `.npmrc` file in your project root:

```shellscript theme={null}
# In your project directory
touch .npmrc
```

Add the following content:

```text theme={null}
@native-desktop:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

Then set the `GITHUB_TOKEN` environment variable:

```shellscript theme={null}
# macOS/Linux
export GITHUB_TOKEN=your_personal_access_token

# Windows (Command Prompt)
set GITHUB_TOKEN=your_personal_access_token

# Windows (PowerShell)
$env:GITHUB_TOKEN="your_personal_access_token"
```

<Warning>
  If using project-level configuration, **`never commit .npmrc with your token`** to version control. Add it to `.gitignore`:

  ```text theme={null}
  .npmrc
  ```
</Warning>

### Option C: Using npm login (Alternative)

You can also authenticate using the `npm login` command:

```shellscript theme={null}
npm login --scope=@native-desktop --auth-type=legacy --registry=https://npm.pkg.github.com
```

When prompted:

* **Username**: Your GitHub username
* **Password**: Your personal access token (not your GitHub password!)
* **Email**: Your public email address

## Step 4: Install Packages

Once authentication is configured, you can install Native Desktop packages.

### Installing the CLI Globally

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

# Install specific version
npm install -g @native-desktop/cli@1.0.0
```

### Installing Packages in a Project

Add packages to your `package.json`:

```json theme={null}
{
  "name": "my-native-desktop-app",
  "version": "1.0.0",
  "dependencies": {
    "@native-desktop/core": "^1.0.0",
    "@native-desktop/react": "^1.0.0",
    "@native-desktop/app": "^1.0.0"
  },
  "devDependencies": {
    "@native-desktop/cli": "^1.0.0",
    "@native-desktop/config": "^1.0.0"
  }
}
```

Then install:

```shellscript theme={null}
npm install
```

### Installing Individual Packages

```shellscript theme={null}
# Install core package
npm install @native-desktop/core

# Install React integration
npm install @native-desktop/react

# Install app utilities
npm install @native-desktop/app

# Install config utilities
npm install @native-desktop/config
```

## Step 5: Verify Installation

Verify that packages are installed correctly:

```shellscript theme={null}
# Check CLI installation
native-desktop --version

# List installed Native Desktop packages
npm list @native-desktop/cli
npm list @native-desktop/core
npm list @native-desktop/react
```

You should see version information for each installed package.

## Complete Setup Example

Here's a complete example of setting up a new Native Desktop project:

```shellscript theme={null}
# 1. Configure authentication
echo "@native-desktop:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc

# 2. Install CLI globally
npm install -g @native-desktop/cli

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

# 4. Project packages are auto-configured in package.json
npm install

# 5. Start developing
native-desktop run
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized Error">
    **Error**: `npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/@native-desktop/cli`

    **Solutions**:

    * Verify your personal access token is correct and not expired
    * Ensure the token has `read:packages` scope
    * Check that `.npmrc` is configured correctly
    * Confirm you have access to the Native Desktop repository

    ```shellscript theme={null}
    # Test authentication
    npm whoami --registry=https://npm.pkg.github.com
    ```
  </Accordion>

  <Accordion title="404 Package Not Found">
    **Error**: `npm ERR! 404 Not Found - GET https://npm.pkg.github.com/@native-desktop/cli`

    **Solutions**:

    * Verify you have purchased a license and received repository access
    * Check the package name is correct (all lowercase, with scope)
    * Ensure `.npmrc` includes the registry configuration
    * Contact support if access issues persist
  </Accordion>

  <Accordion title="Token Expired">
    **Error**: Authentication fails after some time

    **Solution**: Your personal access token may have expired. Create a new token:

    1. Go to GitHub Settings → Personal access tokens
    2. Delete the old token
    3. Create a new token with `read:packages` scope
    4. Update your `.npmrc` file with the new token
  </Accordion>

  <Accordion title=".npmrc Not Found">
    **Error**: Cannot find `.npmrc` file

    **Solution**: Create the file manually:

    ```shellscript theme={null}
    # macOS/Linux
    touch ~/.npmrc
    nano ~/.npmrc

    # Windows
    notepad %USERPROFILE%\.npmrc
    ```
  </Accordion>

  <Accordion title="Permission Denied">
    **Error**: `EACCES: permission denied`

    **Solution**: This usually happens with global installations. Try:

    ```shellscript theme={null}
    # macOS/Linux - use sudo (not recommended for security)
    sudo npm install -g @native-desktop/cli

    # Better: Configure npm to use a different directory
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```
  </Accordion>

  <Accordion title="No Access After Purchase">
    **Error**: Purchased license but still cannot access packages

    **Solution**:

    * Wait a few minutes for access to be granted
    * Check your GitHub account's email matches the purchase email
    * Verify you're logged into the correct GitHub account
    * Contact Native Desktop support with your purchase details
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card icon="lock" title="Token Security">
    Never commit your personal access token to version control. Use environment variables or secure secret management.
  </Card>

  <Card icon="clock" title="Token Expiration">
    Set token expiration to 90 days or less and rotate regularly for better security.
  </Card>

  <Card icon="shield" title="Scope Limitation">
    Only grant `read:packages` scope - never use tokens with broader permissions.
  </Card>

  <Card icon="key" title="Environment Variables">
    Use environment variables for tokens in CI/CD and project configurations.
  </Card>
</CardGroup>

## CI/CD Configuration

### GitHub Actions

```yaml theme={null}
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@native-desktop'
      
      - name: Install dependencies
        run: npm install
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Build
        run: npm run build
```

### GitLab CI

```yaml theme={null}
build:
  image: node:18
  before_script:
    - echo "@native-desktop:registry=https://npm.pkg.github.com" >> .npmrc
    - echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc
  script:
    - npm install
    - npm run build
```

### Environment Variables

For CI/CD, set these environment variables:

* `GITHUB_TOKEN`: Your personal access token
* `NODE_AUTH_TOKEN`: Alias for GitHub token (some CI systems)

## Updating Packages

### Update All Packages

```shellscript theme={null}
# Check for updates
npm outdated @native-desktop/*

# Update all Native Desktop packages
npm update @native-desktop/cli @native-desktop/core @native-desktop/react

# Update CLI globally
npm update -g @native-desktop/cli
```

### Update to Specific Version

```shellscript theme={null}
# Update to specific version
npm install @native-desktop/cli@1.2.0

# Update CLI globally to specific version
npm install -g @native-desktop/cli@1.2.0
```

## Uninstalling

### Uninstall Global Packages

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

### Uninstall Project Packages

```shellscript theme={null}
npm uninstall @native-desktop/core @native-desktop/react @native-desktop/app
```