Installation Guide

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`

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.

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

Visit Polar.sh Native Desktop (or your purchase portal)
Select a plan that fits your needs
Complete the purchase process
You will receive an email with repository access instructions

Repository access is granted automatically upon purchase. If you don’t receive access within a few minutes, contact support.

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

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token → Generate new token (classic)
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
Click Generate token
Copy the token immediately - You won’t be able to see it again!

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

Example Token Permissions

Scopes:
  ✅ read:packages - Download packages from GitHub Package Registry

Store your token securely in a password manager. You’ll need it for authentication.

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:

# Edit or create ~/.npmrc
nano ~/.npmrc

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

@native-desktop:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

The ~/.npmrc file is located at:

macOS/Linux: ~/.npmrc
Windows: C:\Users\YourUsername\.npmrc

Option B: Project-Level Configuration

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

# In your project directory
touch .npmrc

Add the following content:

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

Then set the GITHUB_TOKEN environment variable:

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

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

.npmrc

You can also authenticate using the npm login command:

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

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

{
  "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:

npm install

Installing Individual Packages

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

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

# 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

401 Unauthorized Error

Error: npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/@native-desktop/cliSolutions:

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

# Test authentication
npm whoami --registry=https://npm.pkg.github.com

404 Package Not Found

Error: npm ERR! 404 Not Found - GET https://npm.pkg.github.com/@native-desktop/cliSolutions:

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

Token Expired

Error: Authentication fails after some timeSolution: Your personal access token may have expired. Create a new token:

Go to GitHub Settings → Personal access tokens
Delete the old token
Create a new token with read:packages scope
Update your .npmrc file with the new token

.npmrc Not Found

Error: Cannot find .npmrc fileSolution: Create the file manually:

# macOS/Linux
touch ~/.npmrc
nano ~/.npmrc

# Windows
notepad %USERPROFILE%\.npmrc

Permission Denied

Error: EACCES: permission deniedSolution: This usually happens with global installations. Try:

# 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

No Access After Purchase

Error: Purchased license but still cannot access packagesSolution:

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

Security Best Practices

Token Security

Never commit your personal access token to version control. Use environment variables or secure secret management.

Token Expiration

Set token expiration to 90 days or less and rotate regularly for better security.

Scope Limitation

Only grant read:packages scope - never use tokens with broader permissions.

Environment Variables

Use environment variables for tokens in CI/CD and project configurations.

CI/CD Configuration

GitHub Actions

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

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

# 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

# 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

npm uninstall -g @native-desktop/cli

Uninstall Project Packages

npm uninstall @native-desktop/core @native-desktop/react @native-desktop/app

Quick Start

Getting started

Tips and Tricks

User Guide

Overview

Available Packages

Prerequisites

Step 1: Purchase a License

Step 2: Create a GitHub Personal Access Token

Creating the Token

Example Token Permissions

Step 3: Configure npm Authentication

Option A: User-Level Configuration (Recommended)

Option B: Project-Level Configuration

Step 4: Install Packages

Installing the CLI Globally

Installing Packages in a Project

Installing Individual Packages

Step 5: Verify Installation

Complete Setup Example

Troubleshooting

Security Best Practices

Token Security

Token Expiration

Scope Limitation

Environment Variables

CI/CD Configuration

GitHub Actions

GitLab CI

Environment Variables

Updating Packages

Update All Packages

Update to Specific Version

Uninstalling

Uninstall Global Packages

Uninstall Project Packages

Quick Start

Getting started

Tips and Tricks

User Guide

​Overview

​Available Packages

​Prerequisites

​Step 1: Purchase a License

​Step 2: Create a GitHub Personal Access Token

​Creating the Token

​Example Token Permissions

​Step 3: Configure npm Authentication

​Option A: User-Level Configuration (Recommended)

​Option B: Project-Level Configuration

​Option C: Using npm login (Alternative)

​Step 4: Install Packages

​Installing the CLI Globally

​Installing Packages in a Project

​Installing Individual Packages

​Step 5: Verify Installation

​Complete Setup Example

​Troubleshooting

​Security Best Practices

Token Security

Token Expiration

Scope Limitation

Environment Variables

​CI/CD Configuration

​GitHub Actions

​GitLab CI

​Environment Variables

​Updating Packages

​Update All Packages

​Update to Specific Version

​Uninstalling

​Uninstall Global Packages

​Uninstall Project Packages

Overview

Available Packages

Prerequisites

Step 1: Purchase a License

Step 2: Create a GitHub Personal Access Token

Creating the Token

Example Token Permissions

Step 3: Configure npm Authentication

Option A: User-Level Configuration (Recommended)

Option B: Project-Level Configuration

Option C: Using npm login (Alternative)

Step 4: Install Packages

Installing the CLI Globally

Installing Packages in a Project

Installing Individual Packages

Step 5: Verify Installation

Complete Setup Example

Troubleshooting

Security Best Practices

CI/CD Configuration

GitHub Actions

GitLab CI

Environment Variables

Updating Packages

Update All Packages

Update to Specific Version

Uninstalling

Uninstall Global Packages

Uninstall Project Packages