Build and inspect the site

Before deploying, I build the site and look at what came out. The build is the only honest answer to “what will visitors get?”.

npm run build
npm run preview

Fix every build error before looking at anything else. Development renders a page when you open it, so it can skip a broken route for weeks. The build has to list every dynamic path, validate every content entry, and resolve every import. It finds what dev never touched.

Start with dist/

The output folder is the first thing to check, and you don’t need a browser for it:

ls dist/notes

For the notes site you should see one folder per published note, plus index.html for the list. Count them. The draft must not be there.

A missing folder points to one of three things: getStaticPaths() didn’t return that path, the draft filter excluded it, or the filename doesn’t match the id you linked to. A folder that shouldn’t exist means a filter is missing somewhere.

Then click through the preview

Preview serves dist/ at http://localhost:4321. Use it like a visitor would:

• open one page of each type, including a dynamic note page and a URL that doesn’t exist
• follow the links on the page instead of pasting URLs you already know work
• check the title, the description, and that each page has one h1
• disable JavaScript and confirm the content and navigation are still there
• look at one image: real width and height, real alt text, a production asset URL under /_astro/

The unknown URL should show your 404 page. If preview returns the home page instead, the 404 file is missing or misnamed.

Explain every script

Open the Network panel, filter by JS, and reload. For each bundle, say out loud which component loads it and why. A script you can’t explain usually means a client:* directive on a component that doesn’t need one. Remove it and rebuild.

Endpoints too

If the site has an endpoint, don’t just read the body in the browser. Check the status and the headers:

curl -i http://localhost:4321/api/status

You want a 200 status line and the {"ok":true} body from the endpoints lesson. If you gave the route a .json extension, check the Content-Type header too.

Preview is not production

Preview is close to the real thing, but it’s a plain file server. Redirect status codes, caching headers, environment variables, and platform functions all belong to the host. We’ll verify those after deploying, in the next lesson.

Try this on the astro-notes project: build, list dist/notes, and compare the count against the number of published notes in src/content/notes/. If they don’t match, you already know where to look.