GitHub Token Setup for pnpm on Windows¶

CRITICAL: NEVER commit .npmrc files containing tokens to git!

The .npmrc file is in .gitignore for this reason. Always configure tokens in your global ~/.npmrc file (located at C:\Users\<YourUsername>\.npmrc), not in project directories.

If you accidentally commit a token, revoke it immediately on GitHub and generate a new one.

This guide explains how to configure a GitHub Personal Access Token (PAT) for pnpm on Windows to access private packages from GitHub Packages.

Table of Contents¶

Prerequisites
Step 1: Create a GitHub Personal Access Token
Step 2: Configure Global .npmrc
Step 3: Verify Configuration
Troubleshooting
Security Best Practices
References

Prerequisites¶

Windows 10 or later
pnpm installed globally (npm install -g pnpm)
A GitHub account with access to the LuckBox Studios organization
PowerShell or Command Prompt

Step 1: Create a GitHub Personal Access Token¶

1.1 Navigate to GitHub Token Settings¶

Go to GitHub.com and sign in
Click your profile picture (top-right) → Settings
Scroll down in the left sidebar → Developer settings
Click Personal access tokens → Tokens (classic)
Click Generate new token → Generate new token (classic)

Note: You can also use fine-grained tokens, but classic tokens are simpler for package access. See GitHub's token documentation for details.

1.2 Configure Token Permissions¶

Configure your token with the following settings:

Token Name (Note):

pnpm-github-packages-access

Expiration: - Recommended: 90 days (you'll get email reminders before expiration) - For CI/CD: No expiration (requires careful secret management)

Required Scopes:

Select these scopes: - read:packages - Download packages from GitHub Packages - write:packages - Publish packages to GitHub Packages (optional, only for SDK publishers) - repo - Access private repositories (if packages are in private repos)

Screenshot Reference

Your token configuration should look similar to this:

Note: pnpm-github-packages-access
Expiration: 90 days

Select scopes:
[x] repo
  [x] repo:status
  [x] repo_deployment
  [x] public_repo
  [x] repo:invite
  [x] security_events
[x] write:packages
  [x] read:packages

1.3 Generate and Copy Token¶

Scroll to the bottom and click Generate token
IMPORTANT: Copy the token immediately - you won't see it again!
Store it securely (we'll use it in the next step)

The token format looks like: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

References: - Creating a personal access token (classic) - About permissions for GitHub Packages

Step 2: Configure Global .npmrc¶

pnpm uses the same .npmrc configuration file as npm. We'll configure it globally so all projects can access GitHub Packages.

2.1 Locate Your Global .npmrc File¶

The global .npmrc file is located at:

C:\Users\<YourUsername>\.npmrc

For example:

C:\Users\JohnDoe\.npmrc

Note: This file may not exist yet - that's okay, we'll create it.

2.2 Option A: Configure Using PowerShell (Recommended)¶

Open PowerShell and run these commands:

# Navigate to your home directory
cd $HOME

# Add GitHub Packages registry for @luckboxstudios scope
Add-Content -Path .npmrc -Value "@luckboxstudios:registry=https://npm.pkg.github.com"

# Add your GitHub token (replace YOUR_GITHUB_TOKEN with the token from Step 1)
Add-Content -Path .npmrc -Value "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN"

# Verify the file was created
Get-Content .npmrc

Replace YOUR_GITHUB_TOKEN with the actual token you copied in Step 1.3.

2.3 Option B: Configure Using Command Prompt¶

Open Command Prompt and run:

cd %USERPROFILE%

echo @luckboxstudios:registry=https://npm.pkg.github.com >> .npmrc
echo //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN >> .npmrc

type .npmrc

Replace YOUR_GITHUB_TOKEN with the actual token you copied in Step 1.3.

2.4 Option C: Configure Manually¶

Open File Explorer
Navigate to C:\Users\<YourUsername>
Create a new file named .npmrc (note the leading dot)
Open .npmrc in Notepad or your preferred text editor
Add these lines:

@luckboxstudios:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Replace ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your actual token
Save and close the file

2.5 Verify File Contents¶

Your .npmrc should look like this:

@luckboxstudios:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Notes: - This file contains your secret token - never commit it to git - Keep file permissions restricted to your user account - Use different tokens for different machines/purposes

References: - pnpm .npmrc documentation - npm .npmrc documentation - GitHub Packages authentication

Step 3: Verify Configuration¶

3.1 Test pnpm Configuration¶

Run this command to verify pnpm can read your configuration:

pnpm config list

You should see output including:

@luckboxstudios:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=(protected)

Note: pnpm hides the actual token value for security.

3.2 Test Package Installation¶

Try installing the Foundry TypeScript SDK:

# Create a test directory
mkdir C:\Temp\pnpm-test
cd C:\Temp\pnpm-test

# Initialize a package.json
pnpm init

# Try installing the SDK
pnpm add @luckboxstudios/foundry-sdk

Expected Result:

Packages: +1
+
@luckboxstudios/foundry-sdk 2025.1012.2244.539

Done in 3.2s

If you see an error like:

ERR_PNPM_FETCH_401  GET https://npm.pkg.github.com/@luckboxstudios%2ffoundry-sdk:
Unauthorized - 401

This means authentication failed. Double-check: - Token has read:packages scope - Token is still valid (not expired) - .npmrc file has correct token (no extra spaces/newlines) - You have access to the LuckBox Studios organization

3.3 Clean Up Test¶

cd C:\Temp
Remove-Item -Recurse -Force pnpm-test

Troubleshooting¶

Problem: "401 Unauthorized" Error¶

Symptoms:

ERR_PNPM_FETCH_401  GET https://npm.pkg.github.com/... Unauthorized - 401

Solutions:

Verify token permissions:
Go to GitHub → Settings → Developer settings → Personal access tokens
Click on your token → Check that read:packages is enabled
If not, regenerate the token with correct scopes
Check token expiration:
Expired tokens show as "Expired" in GitHub settings
Generate a new token if expired

Verify .npmrc syntax:

# Check for syntax errors
Get-Content $HOME\.npmrc

Ensure no extra spaces around =
Ensure no quotes around the token
Ensure token starts with ghp_
Check organization access:
Verify you're a member of the LuckBox Studios organization
Ask an org admin to check your access level

Problem: ".npmrc Not Found" Error¶

Symptoms:

Cannot find path 'C:\Users\YourName\.npmrc'

Solution: The file doesn't exist yet. Follow Step 2.2 to create it.

Problem: "File Name Extension Required"¶

Symptoms: Windows won't let you create a file starting with a dot.

Solution: Use PowerShell or Command Prompt instead of File Explorer (see Step 2.2).

Problem: pnpm Uses Wrong Registry¶

Symptoms:

ERR_PNPM_FETCH_404  GET https://registry.npmjs.com/@luckboxstudios/foundry-sdk
Not found - 404

Solution: The scope configuration is missing or incorrect.

# Check current config
pnpm config get @luckboxstudios:registry

# Should output: https://npm.pkg.github.com
# If it doesn't, add the line to .npmrc:
Add-Content -Path $HOME\.npmrc -Value "@luckboxstudios:registry=https://npm.pkg.github.com"

Problem: Token Works in npm but not pnpm¶

Symptoms: npm install works but pnpm add fails with 401.

Solution: pnpm and npm share the same .npmrc file, so this shouldn't happen. Try:

# Force pnpm to re-read config
pnpm config list

# Verify both tools see the same config
npm config list
pnpm config list

If they differ, you might have a project-level .npmrc overriding the global one.

Security Best Practices¶

Token Security¶

DO: - Create tokens with minimal required scopes - Use 90-day expiration for personal tokens - Revoke tokens you're no longer using - Use different tokens for different machines - Store tokens in secure password managers

DON'T: - Commit .npmrc files with tokens to git - Share tokens between team members - Use write:packages scope unless you're publishing - Screenshot or email tokens - Use the same token for local dev and CI/CD

File Permissions¶

Your .npmrc file should only be readable by your user account:

# Check file permissions (PowerShell)
Get-Acl $HOME\.npmrc | Format-List

# Restrict access to your user only
icacls "$HOME\.npmrc" /inheritance:r /grant:r "$env:USERNAME:(R,W)"

Token Rotation¶

Set a calendar reminder to rotate your token every 90 days:

Generate a new token (same scopes)
Update .npmrc with new token
Test package installation
Revoke old token in GitHub

References: - GitHub token security best practices - Keeping your API credentials secure

References¶

Official Documentation¶

GitHub:
Managing your personal access tokens
Working with the npm registry
About permissions for GitHub Packages
pnpm:
.npmrc documentation
Using private packages
Configuration
npm:
.npmrc files
Using private packages in a CI/CD workflow

TypeScript SDK README - SDK usage and API reference
SDK Generation Process - How SDKs are generated and published
ADR-007: TypeScript SDK Auto-Generation - Architecture decisions

External Resources¶

Quick Reference Card¶

Create Token:

GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic)
Scopes: read:packages, write:packages (optional), repo

Configure pnpm (PowerShell):

cd $HOME
Add-Content -Path .npmrc -Value "@luckboxstudios:registry=https://npm.pkg.github.com"
Add-Content -Path .npmrc -Value "//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE"

Verify:

pnpm config list
pnpm add @luckboxstudios/foundry-sdk

File Location:

C:\Users\<YourUsername>\.npmrc

Token Format:

ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Support¶

If you encounter issues not covered in this guide:

Check the Troubleshooting section
Review the official pnpm documentation
Contact the LBS Foundry team
Open an issue in the repository

Last Updated: 2025-10-13 Version: 1.0.0 Maintained by: LBS Foundry Team

GitHub Token Setup for pnpm on Windows¶

Table of Contents¶

Prerequisites¶

Step 1: Create a GitHub Personal Access Token¶

1.1 Navigate to GitHub Token Settings¶

1.2 Configure Token Permissions¶

1.3 Generate and Copy Token¶

Step 2: Configure Global .npmrc¶

2.1 Locate Your Global .npmrc File¶

2.2 Option A: Configure Using PowerShell (Recommended)¶

2.3 Option B: Configure Using Command Prompt¶

2.4 Option C: Configure Manually¶

2.5 Verify File Contents¶

Step 3: Verify Configuration¶

3.1 Test pnpm Configuration¶

3.2 Test Package Installation¶

3.3 Clean Up Test¶

Troubleshooting¶

Problem: "401 Unauthorized" Error¶

Problem: ".npmrc Not Found" Error¶

Problem: "File Name Extension Required"¶

Problem: pnpm Uses Wrong Registry¶

Problem: Token Works in npm but not pnpm¶

Security Best Practices¶

Token Security¶

File Permissions¶

Token Rotation¶

References¶

Official Documentation¶

Related LBS Foundry Documentation¶

External Resources¶

Quick Reference Card¶

Support¶