Working with internal repositories and private package registries

Enterprise frontend projects often depend on two pieces of setup before local work feels normal:

• access to a private package registry
• connection to the correct remote Git repository

These notes are intentionally generic. The pattern matters more than the specific company, registry, or repository name.

1. When node_modules has been deleted

Use:

npm install

Not:

npm update

Why:

• npm install restores dependencies from package.json and the lockfile.
• npm update tries to update installed package versions within allowed ranges.
• If node_modules is missing, reinstall first.

Useful checks:

npm -v
npm config get registry
npm install --verbose

2. When npm returns E401 or ENEEDAUTH

These errors usually mean npm cannot authenticate with the registry.

Common causes:

• expired credentials
• missing auth token
• wrong registry URL
• missing project .npmrc
• expired SSO session
• VPN or proxy requirement
• account does not have package access

Useful checks:

npm whoami
npm config get registry
npm config list

Interpretation:

• If npm whoami fails, authentication is missing or expired.
• If the registry is not the expected one, the project may need a private registry config.
• If the registry is correct but install still fails, package access may be missing.

3. Public registry vs. private registry

Public npm registry:

https://registry.npmjs.org/

Private enterprise registry:

https://packages.example.com/npm/

Project-level .npmrc example:

registry=https://packages.example.com/npm/
//packages.example.com/npm/:_authToken=${NPM_TOKEN}
always-auth=true

Guidelines:

• never commit real tokens
• prefer environment variables for secrets
• keep project registry settings in project-level .npmrc
• keep personal credentials out of source control
• ask the owning team for the approved authentication flow

4. If login times out

A timeout during npm login can point to network configuration rather than package credentials.

Possible causes:

• VPN is required
• proxy settings are missing
• firewall rules block direct registry access
• browser SSO is required before CLI auth
• the registry URL is not reachable from the current network

Useful checks:

env | grep -i proxy
curl -I https://registry.npmjs.org/
npm config get proxy
npm config get https-proxy

Questions to ask:

• Should installs happen through a private registry?
• Is VPN required?
• Is there a company proxy?
• Is CLI auth token-based or username/password-based?
• Does the package registry use SSO?

5. Creating or updating .npmrc

Create the file in the project root:

touch .npmrc

Edit it with the approved registry and auth pattern:

registry=https://packages.example.com/npm/
//packages.example.com/npm/:_authToken=${NPM_TOKEN}
always-auth=true

Then verify:

npm config get registry
npm config list
npm install

Security reminder:

• do not paste real tokens into documentation
• do not share another developer's credentials
• do not commit personal .npmrc files if they contain secrets
• check .gitignore if local-only credential files are needed

6. Connecting a local folder to Git

First check whether Git is already tracking the folder:

git status

If it is not a Git repo:

git init

Add the remote:

git remote add origin https://github.com/example-org/example-project.git
git remote -v

Fetch remote branches:

git fetch origin
git branch -r

Check out the correct working branch:

git checkout -b develop origin/develop

Questions to ask before working:

• Which branch is the baseline?
• Which branch should design work target?
• Are feature branches named a certain way?
• Should commits be squashed?
• Is a pull request required?

7. Be careful with destructive Git commands

This command discards local changes:

git reset --hard origin/develop

Use it only when:

• local work is backed up
• the team has confirmed the correct branch
• you genuinely want to throw away local changes

Safer path:

git status
git stash
git fetch origin
git checkout -b develop origin/develop

8. Useful baseline checklist

Before starting design or frontend work:

• project builds locally
• dependencies install cleanly
• registry is correct
• auth token is valid
• VPN/proxy requirements are understood
• Git remote is configured
• local branch tracks the right remote branch
• no secrets are committed
• .gitignore covers local credential files

9. Public writing rule

When documenting this kind of setup publicly:

• say enterprise registry, not the real registry host
• say internal repository, not the real repo name
• say company SSO, not the provider-specific path
• use example.com or example-org
• never include usernames, emails, tokens, employee IDs, or internal hosts