Deploy an Astro site

An Astro project deploys as one of two quite different things, and your config decides which. Knowing which one you are getting is most of what there is to know.

npm create astro@latest my-site

Push it to GitHub and connect it as in the quickstart, or fork zeitlos/astro-example(opens in a new tab), which is the minimal template unchanged.

Static by default

A stock Astro project has no adapter and no output: 'server'. The build runs npm run build, produces dist/, and Lucity serves those files from a small static web server. No Node process runs at all.

That is the cheapest way to run a site here. It also means anything that executes per request is unavailable: no API endpoints, no server islands, no session handling, no reading a database on page load. Content is fixed at build time, so publishing new content means a new build.

If your astro.config.mjs sets outDir, the builder reads it rather than assuming dist/.

Server rendering when you need it

Add the Node adapter and the deployment changes shape:

npx astro add node

That writes an adapter into your config and switches the build to produce a server. Detection then starts it through your start script, so make sure you have one:

{
  "scripts": {
    "start": "node ./dist/server/entry.mjs"
  }
}

The adapter reads the PORT Lucity injects. From that point on you have API routes, per-request rendering and everything else a server can do, and you are paying for a running container.

Use output: 'static' with selected pages marked export const prerender = false, or output: 'server' with the reverse, depending on which side the majority of your pages fall on.

Content, images and data

A static Astro build talks to APIs at build time, so any database or CMS it reads must be reachable from the build. For a PostgreSQL database on Lucity, that means the static path will not work: the database is only reachable from inside the environment at runtime. Use the Node adapter if your pages need live data.

Images processed by astro:assets are optimized during the build, which is memory-hungry on large sites. If a build dies without an error message, that is usually why.

User uploads belong in a bucket regardless of which mode you choose, since neither a static server nor a container keeps files between rollouts.

Next steps

• Builds for detection and build caching
• Domains to put the site on your own hostname
• Object storage for anything users upload