Running Scripts

What scripts are for

The scripts section of package.json lets you give a short name to a command you run often. Instead of remembering a long incantation, you (and everyone on the project) run a simple, agreed-upon name. This site defines these: 

"scripts": {
  "dev": "astro dev",
  "build": "astro build",
  "preview": "astro preview",
  "deploy": "astro build && wrangler pages deploy dist"
}

So npm run dev is really just a nickname for astro dev. Let's run them.

The everyday one: npm run dev

npm run dev starts a local development server — a temporary web server on your own machine (usually at localhost:4321 for Astro) that rebuilds the page instantly as you edit. It's how you preview your work while you write it. Press Ctrl+C in the terminal to stop it.

Start the local dev server

Terminal 
$ npm run dev
In VS Code
  1. Open the terminal (Ctrl+`)
  2. Run npm run dev
  3. Ctrl+click the localhost link it prints to open the site in your browser
  4. Press Ctrl+C in the terminal to stop it

The dev server keeps running and watching your files. Leave it open while you work; stop it when you're done.

Building for release: npm run build

npm run build produces the final, optimised website as plain files in a dist/ folder — the version you actually publish. It runs once and exits. Running it is also the quickest way to confirm your whole project still compiles without errors.

Build the production site

Terminal 
$ npm run build
$ npm run preview   # then preview that build locally
In VS Code
  1. Run npm run build in the terminal
  2. When it finishes, a dist/ folder appears with the built site
  3. npm run preview serves that built folder so you can check it before publishing

dev = work on it (live-reloading). build = produce the final files. preview = view those final files.

Why "npm run" and not just the command?

You might wonder why it's npm run dev rather than typing astro dev directly. When npm runs a script, it temporarily adds your project's node_modules/.bin folder to the path — so the script uses the exact version of astro installed in this project. Type astro on its own and your computer probably won't find it at all (it isn't installed globally). Running through npm is what makes locally-installed tools "just work".

The shortcut names: start and test

A few script names are special: start, test, stop and restart can be run without the word run. So npm start and npm test work, while every other script still needs the full npm run <name>. (This project happens to use dev rather than start, so here you'd use npm run dev.)

Shortcut vs full form

Terminal 
$ npm start        # only works if a 'start' script exists
$ npm test         # shortcut for the 'test' script
$ npm run dev      # everything else needs 'run'
In VS Code
  1. VS Code shows an NPM Scripts view in the Explorer sidebar
  2. Expand it to see every script, and click the ▶ play icon to run one — no typing needed

Can't remember a project's script names? Open package.json and read the scripts block, or run 'npm run' with no name to list them.

Passing extra options with --

Sometimes you want to tweak how a script runs — say, use a different port. Put your extra options after a lone --, and npm passes everything after it straight to the underlying tool:

Forward an option to the tool

Terminal 
$ npm run dev -- --port 3001
In VS Code
  1. Run it in the terminal
  2. Everything after -- is handed to astro dev, so this starts the dev server on port 3001

Without the --, npm would try to interpret --port itself instead of forwarding it.

Bonus — automatic hooks: if you name a script predeploy, npm runs it automatically before deploy (and postdeploy runs after). It's a handy way to chain steps, though you won't need it on day one.

Up next: those ^4.3.0 version numbers — what they mean, and the lockfile that keeps everyone's install identical.

FAQ

Frequently Asked Questions

How do I run a script from package.json?
npm run <name> — for example npm run dev to start the dev server or npm run build to produce the production site in dist/.
Why "npm run dev" instead of just "dev"?
Running through npm temporarily adds the project's node_modules/.bin to the path, so the script finds locally-installed tools like astro without a global install.
What is the difference between npm start and npm run start?
A few names — start, test, stop, restart — have built-in shortcuts, so npm start works. Every other script needs the explicit npm run prefix.
How do I pass extra options to a script?
Put them after -- so npm forwards them to the underlying tool, e.g. npm run dev -- --port 3001.