Before Anything Else
Every command below acts on the folder the terminal is currently standing in. A command that behaves unexpectedly is very often a correct command run in the wrong place, so pwd is the first thing to check.
On Windows, these are the Git Bash forms. PowerShell and Command Prompt use different names for several of them and handle quote marks differently, which changes the behavior of npm scripts.
Moving Around
pwd print the folder the terminal is standing in
ls list what is in it
ls -a list it including hidden files
cd my-project move into my-project
cd .. move up one level
cd ~ move to your home folder
cd - move back to the previous folder
mkdir my-project make a folder
clear clear the screenTab completion
You can type the first few characters of a folder name and press Tab to let the shell finish it. This prevents typos in paths, which are the most common reason a command cannot find something.
Spaces in names
A folder called my project has to be quoted or the space is read as the end of the argument. Tab completion handles the escaping for you.
Opening the folder
open . on macOS and start . on Windows open the current folder in the file browser, which is useful for confirming you are where you think you are.
Getting there without typing
In VS Code, opening the project folder and then the integrated terminal starts the terminal already in the right place.
Paths
index.html relative: in the current folder
./index.html relative: the same thing, said explicitly
../index.html relative: one folder up
docs/notes.md relative: down into docs
~/projects/site absolute: from your home folder
/Users/you/site absolute: from the root of the diskA path starting with / or ~ is absolute and means the same thing from anywhere. Anything else is relative and depends on where the terminal is standing. Inside a web page, a path starting with / means the root of the site rather than the root of the disk, which is a separate meaning that happens to share the character.
Chaining And Redirecting
command && command run the second only if the first succeeded
command || command run the second only if the first failed
command > file write output into file, replacing it
command >> file write output onto the end of file
command | command feed the first command's output into the secondThese are shell features rather than npm features, which is why they work inside an npm script. Every command finishes with an exit code, a number where zero means success. That number is what && and || are testing.
A single > replaces the file's contents every time it runs. Two of them append instead. If you get these backward, the command silently destroys the file's previous contents, and there is no undo.
npm
npm init -y create a package.json with defaults
npm install install everything package.json lists
npm install name add a package to dependencies
npm install --save-dev name add a package to devDependencies
npm uninstall name remove a package and its entry
npm run list the scripts this project defines
npm run scriptname run one of them
npm start shorthand for npm run start
npm ls --depth=0 list the packages you asked for directly
npm outdated show which have newer versions available
npx name run a package once without installing itnpm install with no package name
This command reads package.json and package-lock.json to download everything listed. It is the first command to run after cloning a project.
npm ci
Like npm install, but it installs strictly from the lock file and deletes node_modules first. Deploy servers use it because it is reproducible.
npx
This utility runs a package without adding it to the project, which is handy for one-off generators. It downloads and executes code, so the name matters as much as it does for an install.
Global installs
-g installs a tool for your whole user account rather than for a project. Avoiding global installs for project dependencies is best, because they make the project unbuildable for anyone else.
Reading the output
A line like added 43 packages in 2s is the success message. A vulnerability count printed afterwards is a report about the packages, not a failure of the command.
When something is wrong
You can delete node_modules and run npm install again. This resolves a large share of problems and costs nothing, because the folder is fully rebuildable.
node
node --version print the Node version
node file.js run a JavaScript file
node open an interactive prompt (Ctrl+D to leave)Keys
Ctrl + C stop the running command
Ctrl + D close an interactive prompt
Up arrow recall the previous command
Tab complete a file or folder name
Ctrl + L clear the screenCtrl and C is the one that matters most. A development server holds the terminal on purpose and will keep holding it until stopped this way.
Errors And What They Mean
command not found
The shell has no program by that name on its path. Either the tool is not installed, or it is installed into node_modules and needs to be run through an npm script.
Missing script: "name"
This means there is no script by that name in package.json. Usually a typo, or the file has unsaved changes in the editor.
ENOENT: no such file or directory
A path pointed at something missing. You can check pwd first, and then the spelling.
EADDRINUSE
The port is already taken, nearly always by a server still running in another terminal tab. You must stop that server or use a different port.
EACCES
A permissions refusal. On a global install, this indicates that the package belongs in the project instead.
ERR_MODULE_NOT_FOUND
An import pointed at something Node cannot find. You can verify the path and ensure "type": "module" is set in package.json.