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

DON'T (Prohibited)

• Hardcode Tokens: Do not input tokens directly in package.json

• Depend on Latest Commit: Use tags instead of #main in production

• Abuse sudo: Resolve permission issues with directory configuration

• Ignore Cache: Clear cache when experiencing unusual behavior

Constraints

Required Rules (MUST)

• Git Must Be Installed: Verify git is installed before npm git URL install

• Network Access: Environment with access to GitHub required

• Node.js Version: Check engines field in package.json

Prohibited (MUST NOT)

• Expose Auth Tokens: Do not expose tokens in logs or code

• Indiscriminate sudo: Resolve permission issues with configuration

• Use #main in Production: Pin to specific version/tag

References

• npm-install Official Documentation

• How To Install NPM Packages Directly From GitHub

• npm install from GitHub - Stack Overflow

• Working with the npm registry - GitHub Docs

Metadata

Version

• Current Version: 1.0.0

• Last Updated: 2026-01-10

• Compatible Platforms: Claude, ChatGPT, Gemini, Opencode

Related Skills

• environment-setup

• git-workflow

Tags

#npm #git #github #install #package-management #node