Building and deploying

Deploying means moving the site from your computer to a server everyone can reach. First Astro builds the project into the dist/ folder, then its contents are uploaded to a hosting service. What exactly you upload depends on the mode: a purely static site or a site with on-demand pages.

Building

npm run build
npm run preview

The first command builds the site into dist/ and prints the list of created pages in the terminal. The second serves the built version at http://localhost:4321; click through it before publishing to see the site exactly as visitors will.

A static site

Without an adapter, dist/ contains only HTML, CSS, images and scripts:

dist/
├── index.html
├── about/index.html
├── posts/first-post/index.html
├── rss.xml
├── sitemap-index.xml
└── _astro/

This folder can go to any static hosting: GitHub Pages, Netlify, Cloudflare Pages, Vercel or an ordinary nginx web server. Services such as Netlify run npm run build themselves after every commit; in their settings you set the build command npm run build and the folder dist.

A site with a server

If you added the Node.js adapter and the site has pages with prerender = false, the build produces two parts:

Folder	What is inside
`dist/client/`	Static files and prebuilt pages
`dist/server/`	Server code for on-demand pages, endpoints and actions

The server is started on the host with:

HOST=0.0.0.0 PORT=8080 node ./dist/server/entry.mjs

The HOST and PORT variables set the address and port to listen on. You copy the project to the server, run npm ci and npm run build, then this command, usually through a process manager that restarts the site if it crashes.

Other platforms

Cloud platforms have their own adapters: npx astro add netlify, npx astro add vercel, npx astro add cloudflare. The site code stays the same; only the adapter in astro.config.mjs changes.

A site in a subfolder

If the site will live not at the domain root but, say, at https://example.com/blog/, set base: '/blog' in the config. Build internal links with import.meta.env.BASE_URL in mind.

Common mistake

People upload the whole project with src/ and node_modules/ and open index.astro, and the browser shows source code or an error. Upload only the contents of dist/ after npm run build to static hosting, and set secrets from .env in the hosting settings.

Thanks for reading!