# Installing and running a project

Course: Terminal Basics — https://zero2vibecode.com/learn/terminal-basics
Canonical URL: https://zero2vibecode.com/learn/terminal-basics/4-2-installing-and-running-things

package.json lists what a project needs and what it can do. `npm install` fetches the first, `npm run` triggers the second.

You have a project folder. Now what?

## package.json — the project's description

Almost every JavaScript project has a file called `package.json` at its root. Read it first:

```
cat package.json
```

```
{"name": "site", "scripts": {"start": "node app.js", "build": "node build.js"}}
```

Two things matter to you right now:

- **dependencies** — the libraries this project needs to work
- **scripts** — named shortcuts for commands the project runs often

## npm install — get what it needs

```
npm install
```

npm reads the dependency list and downloads every package into a folder called `node_modules`.

That folder gets big — thousands of files — which is exactly why it is never committed to a repository. The list of dependencies is shared; the downloaded copies are rebuilt on each machine by running `npm install`.

This explains the most common first-run failure. You download a project, run it straight away, and get an error about a missing module. Nothing is broken: you just skipped the install step. Dependencies do not travel with the code.

## npm run — do what it offers

Scripts are commands the project's authors named for convenience. See what exists:

```
npm run
```

```
Lifecycle scripts:
  start
    node app.js
  build
    node build.js
```

Then run one by name:

```
npm run start
```

The key thing to understand: `npm run build` does not have a fixed meaning. It runs whatever *this* project defined under `build`. In one project that compiles a website; in another it packages a library. `cat package.json` is how you find out which.

A few names are special enough that npm lets you drop the `run`: `npm start` and `npm test` work as shorthand. Every other script needs the full `npm run <name>`.

## The shape of every project setup

It is always these three steps, in this order:

1. `cat package.json` — see what you are dealing with.
2. `npm install` — get the dependencies.
3. `npm run <something>` — start it.

When an AI agent sets up a project for you, this is what it is doing. Recognising the pattern is what lets you tell "normal setup" from "wait, why is it doing that".

## Try it

The simulator prints believable npm output without downloading anything. The commands and the workflow are real; the network is not.

1. `cat package.json` — read the scripts.
2. `npm install` — fetch the dependencies.
3. `npm run` — list what the project offers.
4. `npm run start` — run one.

Step 3 is the habit worth keeping. Ask the project what it can do before guessing at command names.