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://[email protected]: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://[email protected]: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 "[email protected]"

# 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://[email protected]: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 [email protected]

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

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

DON'T (Prohibited)

1. Hardcode Tokens: Do not input tokens directly in package.json
2. Depend on Latest Commit: Use tags instead of #main in production
3. Abuse sudo: Resolve permission issues with directory configuration
4. Ignore Cache: Clear cache when experiencing unusual behavior

---

Constraints

Required Rules (MUST)