Develop, build, and preview

An Astro project comes with three commands. Each one answers a different question.

npm run dev

npm run dev

This is the one you’ll run most. It starts the development server and watches your files. Save a change, and the browser updates.

The question it answers is “what does this page look like right now?”. It renders a route when you open it in the browser, and only that route. It favors fast feedback over completeness.

npm run build

npm run build

This is the production build. Astro checks every import, renders every route it knows about, and writes the result under dist/. In a static project that means one HTML file per route, plus the bundled scripts, styles, and images.

At the end you see a summary like this:

[build] 3 page(s) built in 1.42s
[build] Complete!

The question it answers is “can this site be deployed?”. This is the command your host runs.

npm run preview

npm run preview

Preview serves the dist/ folder locally, as a static file server would. It doesn’t rebuild anything. You use it to click through the generated site before you deploy it.

Dev success is not build success

This trips up a lot of people. A page works in development, then the build fails.

It happens because development is lazy. It renders what you ask for, when you ask for it. The build has to render everything up front, so it finds problems dev never touched:

• a dynamic route that’s missing a path, so one page is never generated
• a content entry that fails its schema
• a filename that differs only by case, which works on macOS and breaks on Linux

My advice is to run npm run build often. Before every commit is a good habit. A build takes seconds and saves you from finding out on the deploy log.

Preview is not the real host

Preview is close to production, but it’s not production. Redirect status codes, custom headers, and server routes depend on the platform you deploy to. Check those on the deployed site, not only in preview.

Try this on the astro-notes project: run all three commands, one after the other. For each one, write down when the code in index.astro ran. In dev it ran when you opened the page. In build it ran once, during the build. In preview it didn’t run at all.