====== Understanding package and package-lock ======

NEVER manually update ''package-lock.json''

Both ''package.json'' and ''package-lock.json'' update automatically when you install or update a package via the terminal inside your repo.

These changes should be tracked in Git. You can revert these files in GitHub Desktop like any other text file; however, your local ''node_modules'' folder will not automatically revert its code. To sync your local code back to the version specified in your ''package-lock.json'', run ''npm install'' (or ''npm ci'' for a guaranteed clean slate).

===== Merge Conflict =====

If you see a merge conflict in your ''package-lock.json'' in GitHub Desktop, don't try to fix the text manually. This is the best way to fix:

1. Accept one version of the file (doesn't matter which one)
2. Run ''npm install'' in terminal inside your repo
3. npm will automatically rewrite the file to be correct and conflict-free. **Here's how that works:**
	- npm reads ''package.json'' to see what you want to install (package versions have ranges instead of specific versions)
	- npm reads ''package-lock.json'' to see what was previously successful
	- npm checks the conflict, if the two files disagree, ''package.json'' wins
	- The result: npm recalculates the match, downloads the necessary code into ''node_modules'', and then completely regenerates a fresh, non-conflicting ''package-lock.json'' that is perfectly synced.

===== Making Sure All Team Members Have the Same Setup =====

If I have everything set up on my computer; the ''package.json'' and ''package-lock.json'' files are in sync and looking good, but my coworker's computer is still out of date. Here's the course of action:

1. **I Push:** I commit and push my ''package.json'' and ''package-lock.json'' to the shared Git repository.
2. **They Pull:** My coworker pulls the latest changes from Git. Now their files match yours, but their ''node_modules'' folder is still full of the old code.
3. **They Sync:** My coworker runs ''npm install'' (or even better, ''npm ci'') to update their ''node_modules'' folder to match ''package-lock.json''.

> NOTE: Never commit or share the ''node_modules'' folder itself; it should always stay in your ''.gitignore'' file.

===== Important Nuance Between npm install and npm ci =====

If you want npm to follow the ''package-lock.json'' file exactly, use ''npm ci''. If you want npm to "fix" the ''package-lock.json'' file to match ''package.json'', use ''npm install'' (this only fixes/updates the lockfile IF ''package.json'' has changed. If ''package.json'' and ''package-lock.json'' are already in sync, ''npm install'' just checks the ''node_modules'' folder and does nothing.)