npm install Git Repository Guide

Covers how to install npm packages directly from GitHub repositories. Useful for installing packages not in the npm registry, specific branches, or private repositories.

When to use this skill

Packages Not on npm: Install packages not yet published
Specific Branch/Tag: Install main, develop, specific release tags
Private Repositories: Install packages within an organization
Forked Packages: Use a modified fork version
Test Latest Commits: Test the latest code before a release

1. Installation Commands

Basic Syntax

npm install git+https://github.com/<owner>/<repo>.git#<branch|tag|commit>

HTTPS Method (Common)

# Specific branch
npm install -g git+https://github.com/JEO-tech-ai/supercode.git#main

# Specific tag
npm install git+https://github.com/owner/repo.git#v1.0.0

# Specific commit
npm install git+https://github.com/owner/repo.git#abc1234

# Default branch (omit #)
npm install git+https://github.com/owner/repo.git

SSH Method (With SSH Key Setup)

npm install -g git+ssh://git@github.com:JEO-tech-ai/supercode.git#main

Verbose Logging

npm install -g git+https://github.com/JEO-tech-ai/supercode.git#main --verbose

2. npm install Flow

What npm performs when installing from a Git URL:

1. Git Clone
   └─ Clone repository at specified branch (#main)
        ↓
2. Install Dependencies
   └─ Install dependencies in package.json
        ↓
3. Run Prepare Script
   └─ Run "prepare" script (TypeScript compile, build, etc.)
        ↓
4. Register Global Binary
   └─ Link executable from bin field to global path

Internal Operation

# What npm does internally
git clone https://github.com/owner/repo.git /tmp/npm-xxx
cd /tmp/npm-xxx
git checkout main
npm install
npm run prepare  # Run if exists
cp -r . /usr/local/lib/node_modules/repo/
ln -s ../lib/node_modules/repo/bin/cli.js /usr/local/bin/repo

3. Verify Installation Location

# Check global npm path
npm root -g
# macOS/Linux: /usr/local/lib/node_modules
# Windows: C:\Users\<username>\AppData\Roaming\npm\node_modules

# Check installed package
npm list -g <package-name>

# Check binary location
which <command>
# or
npm bin -g

Installation Locations by Platform

Platform	Package Location	Binary Location
macOS/Linux	`/usr/local/lib/node_modules/`	`/usr/local/bin/`
Windows	`%AppData%\npm\node_modules\`	`%AppData%\npm\`
nvm (macOS)	`~/.nvm/versions/node/vX.X.X/lib/node_modules/`	`~/.nvm/versions/node/vX.X.X/bin/`

4. Add Dependencies to package.json

Use Git URL in dependencies

{
  "dependencies": {
    "supercode": "git+https://github.com/JEO-tech-ai/supercode.git#main",
    "my-package": "git+ssh://git@github.com:owner/repo.git#v1.0.0",
    "another-pkg": "github:owner/repo#branch"
  }
}

Shorthand Syntax

{
  "dependencies": {
    "pkg1": "github:owner/repo",
    "pkg2": "github:owner/repo#branch",
    "pkg3": "github:owner/repo#v1.0.0",
    "pkg4": "github:owner/repo#commit-sha"
  }
}

5. Install from Private Repositories

SSH Key Method (Recommended)

# 1. Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# 2. Register public key on GitHub
cat ~/.ssh/id_ed25519.pub
# GitHub → Settings → SSH Keys → New SSH Key

# 3. Install via SSH method
npm install git+ssh://git@github.com:owner/private-repo.git

Personal Access Token Method

# 1. Create PAT on GitHub
# GitHub → Settings → Developer settings → Personal access tokens

# 2. Install with token in URL
npm install git+https://<token>@github.com/owner/private-repo.git

# 3. Use environment variable (recommended for security)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
npm install git+https://${GITHUB_TOKEN}@github.com/owner/private-repo.git

.npmrc Configuration

# ~/.npmrc
//github.com/:_authToken=${GITHUB_TOKEN}

6. Common Errors & Solutions

Permission denied (EACCES)

# Method 1: Change ownership
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Method 2: Change npm directory (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Git Not Installed

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows
# https://git-scm.com/download/win

GitHub Authentication Error

# Test SSH connection
ssh -T git@github.com

# Cache credentials
git config --global credential.helper store
# or macOS
git config --global credential.helper osxkeychain

prepare Script Failure

# For TypeScript projects
npm install -g typescript

# Verbose log on build failure
npm install git+https://... --verbose 2>&1 | tee npm-install.log

Cache Issues

# Clear npm cache
npm cache clean --force

# Reinstall
npm uninstall -g <package>
npm install -g git+https://...

7. Update & Manage

Update

# Update to latest version (reinstall)
npm uninstall -g <package>
npm install -g git+https://github.com/owner/repo.git#main

# Update package.json dependency
npm update <package>

Check Version

# Check installed version
npm list -g <package>

# Check remote latest commit
git ls-remote https://github.com/owner/repo.git HEAD

Remove

npm uninstall -g <package>

8. Cursor/VS Code Extension Integration Example

Supercode Installation Example

# Global install
npm install -g git+https://github.com/JEO-tech-ai/supercode.git#main

# Verify installation
supercode --version

Project Configuration File

// .supercoderc or supercode.config.json
{
  "aiRules": {
    "enabled": true,
    "techStack": ["TypeScript", "React", "Node.js"]
  },
  "smartActions": [
    {
      "name": "Generate Documentation",
      "icon": "docs",
      "prompt": "Generate comprehensive documentation"
    }
  ],
  "architectureMode": {
    "enabled": true,
    "detailLevel": "detailed"
  }
}

9. Best Practices

DO (Recommended)

Use Specific Version/Tag: Pin version with #v1.0.0 format
Prefer SSH Method: Use SSH key when accessing private repos
Manage Token via Environment Variables: Store PAT in env vars
Commit Lockfile: Ensure reproducibility by committing package-lock.json
Use Verbose Option: Check detailed logs when issues occur

npm-git-install