# Astro hosting: static output, server adapters and what your site actually needs

Astro hosting starts with the render mode. Ship dist when the HTML is built ahead. A page that needs each request uses a server adapter.

Canonical URL: https://unbroker.cloud/blog/astro-hosting
Published: 2026-11-09
Reviewed: 2026-11-09
Author: Timoteo Borgobello

## The short answer

To deploy an Astro site, start with the rendering mode. When the HTML can be generated at build time, host the `dist` files. Unbroker's Astro preset serves that build. When a page needs the visitor's data on each request, add a server adapter and deploy that output as a Node.js service or a Dockerfile.

Leave the static preset pointed at generated files. Set `site` to the public origin you will publish, so canonical URLs and the sitemap use it. The product page is [Deploy Astro](https://unbroker.cloud/deploy/astro). The steps are [Deploy an Astro website](https://docs.unbroker.cloud/guides/deploy-astro).

## Start with the rendering mode

The hosting choice is which pages exist before anyone asks for them. Astro's default `output` is `'static'`: pages are prerendered at build time, and the result is a static site when no page opts out. `output: 'server'` server-renders pages by default. On-demand rendering, also called server-side rendering, needs an adapter. The reference is [Astro's configuration](https://docs.astro.build/en/reference/configuration-reference/) and [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/).

| | Static output | Server adapter |
| --- | --- | --- |
| What the build writes | HTML, CSS, and JavaScript in `dist`, unless you change `outDir` | The server files that adapter needs. This is a different output from the static preset. |
| What runs in production | A file server for those files. Unbroker's Astro preset does this. | The adapter's server process: a Node.js service or a Dockerfile on Unbroker. |
| When it fits | Marketing pages, docs, and blogs whose HTML can be generated at build time. | A page that needs a logged-in user's data, or other data from the request, on each visit. |

You can keep the default static mode and opt one route out with `export const prerender = false` after an adapter is installed. The rest of the site stays static. `output: 'server'` switches the default. Astro's guide says to start with `'static'` until most pages need to be rendered on demand, and that `'server'` adds no extra features. It only changes which pages render on demand by default.

## Hosting static Astro output

Confirm the build with the package manager and lockfile the repository already uses. The Unbroker guide's example is `npm ci`, then `npm run build`. A standard Astro `build` script runs `astro build`. By default that writes `dist/`. `outDir` changes the directory. Astro's deploy guide lists the build command as `astro build` or `npm run build`, and the publish directory as `dist`. See [Deploy your Astro site](https://docs.astro.build/en/guides/deploy/).

In Cloud, create a repository service and choose **Astro**. Set the build command to the project's build script and the output directory to `dist`, unless you changed Astro's output directory.

Open the service URL. Request a nested page directly, refresh it, and follow links to images and stylesheets. If assets are missing, check the output directory and any configured `base` path. `base` is the path Astro uses as the root for pages and assets. If only the homepage exists, inspect the generated routes. Adding a server command to a static service does not create the missing pages.

`astro preview` starts a local server for the built static directory. Astro's CLI says it is for checking the build before you deploy, and that it is not designed to be run in production. Unbroker's guide says the same thing for the static preset: the local preview checks the output, and the preset is the production server for those files. The command reference is [astro preview](https://docs.astro.build/en/reference/cli-reference/#astro-preview).

## When you need a server adapter

A page that requires a logged-in user's data at request time cannot be supplied by static HTML alone. Add an adapter for the runtime that will render those routes. Astro maintains official adapters for Node.js, Netlify, Vercel, and Cloudflare. On Unbroker, deploy that output as a Node.js service or with a Dockerfile, and follow the adapter's build and start instructions. The static Astro preset serves a built static site, so server output stays on the Node.js or Dockerfile path.

The plans table includes managed Node.js on Free and lists Dockerfile builds as available on Pro. The Astro guide names the static preset as the path that runs on Free. Plan rows are in [Plans](https://docs.unbroker.cloud/billing/plans).

## Static Astro plus a separate API

If only a few interactions need a backend, keeping Astro static and adding a separate API can be simpler. Public frontend configuration is visible to visitors. Astro makes variables prefixed with `PUBLIC_` available to client code through `import.meta.env`. Unbroker selects public build prefixes, including `PUBLIC_`, `VITE_`, and `NEXT_PUBLIC_`, before the build. A value that lands in the bundle the visitor downloads is public, including one you typed in Variables.

Put database credentials and other secrets on the API service. Private variables stay runtime-only, except the documented package-registry credentials. How scopes work is [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

Deploy the API first and confirm an endpoint on its public URL. Point the frontend's public variable at that origin, then build the frontend. A change to a value embedded in the bundle needs a new build. Configure the API's CORS policy for the frontend's exact origin. A private project hostname is not reachable from a visitor's browser. Browser calls need a public route. The walkthrough is [Deploy a frontend and API together](https://docs.unbroker.cloud/guides/frontend-and-api). CORS, cookies, and a preview that must not call the production API are [deploy a frontend and an API separately](https://unbroker.cloud/blog/frontend-and-api). What Free can run for that API is [Free backend hosting](https://unbroker.cloud/blog/free-backend-hosting).

## Use the real production URL

Set Astro's `site` to the final deployed URL. Astro uses that full URL to generate the sitemap and canonical URLs in the build. The option is [`site`](https://docs.astro.build/en/reference/configuration-reference/#site). If the site is served under a path, `base` is the matching setting for pages and assets.

A custom domain is a later step, and it requires Pro. Once it is ready, check that canonical URLs and social images use that origin. Astro documents `site` for the sitemap and canonical URLs. The Unbroker guide also asks you to verify social images against the production origin, rather than a preview hostname. DNS and the certificate are [Custom domain and HTTPS](https://unbroker.cloud/blog/custom-domain-https).

Keep the Unbroker-provided hostname. It is how you tell a deployment problem from a DNS problem.

## How this works on Unbroker

The Astro preset serves a built static site. It is available on Free and on Pro. On Free it runs with Serverless: an idle service scales to zero and wakes on the next request. The first request after a sleep can take longer while the application starts. Pro apps do not sleep because of inactivity. They sleep only when Serverless is turned on. Custom domains and managed TLS are on Pro.

Create a repository service, select **Astro**, and set the build command and the output directory. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Current figures are on [pricing](https://unbroker.cloud/pricing) and in [Plans](https://docs.unbroker.cloud/billing/plans).

The product page is [Deploy Astro](https://unbroker.cloud/deploy/astro). Which push produced the revision is [Deploy on git push](https://unbroker.cloud/blog/deploy-on-git-push).

## Checklist

1. Decide whether each page can be generated at build time.
2. For that case, keep the default static output and build with the project's build script.
3. Confirm `dist`, or your `outDir`, contains the pages and assets you expect.
4. On Unbroker, choose the Astro preset and set the build command and the output directory.
5. Open a nested page, refresh it, and follow an image and a stylesheet.
6. Use `astro preview` to check the build locally. Leave it out of the production start command.
7. If a page needs the visitor's data on each request, add a server adapter and deploy that output as Node.js or a Dockerfile.
8. Put secrets on the API. Keep `PUBLIC_` values limited to configuration the visitor can see, and set CORS to the frontend origin.
9. Set `site` to the real public origin. After a custom domain, check canonical URLs, the sitemap, and social images. Keep the Unbroker hostname. Custom domains need Pro.

## FAQ

### Do I need a server to host an Astro site?

Not when the HTML can be generated at build time. Astro's default output is static, and Unbroker's Astro preset serves that build on Free and on Pro. A page that must render on each request, for example with a logged-in user's data, needs a server adapter. Deploy that output as a Node.js service or a Dockerfile. Leave the static preset for generated files.

### What is the difference between Astro static output and server rendering for hosting?

Static output prerenders pages at build time, and you host the files. Server rendering, which Astro also calls on-demand rendering, runs an adapter when the route is requested. output: 'static' is the default. output: 'server' makes on-demand the default. After you add an adapter, one route can opt out of prerendering with prerender = false, and the rest of the site stays static. The reference is [Astro's on-demand rendering guide](https://docs.astro.build/en/guides/on-demand-rendering/).

### Which output directory does Astro build to?

dist, unless you change outDir. Astro's deploy guide lists dist as the publish directory and the build command as astro build or npm run build. On Unbroker, set the Astro preset's output directory to dist unless you changed it, and set the build command to the project's build script.

### Can I use astro preview in production?

No. astro preview starts a local server for the built static directory so you can check that build. Astro's CLI says the command is not designed to be run in production. Unbroker's guide says the same for the static preset: the local preview checks the build, and the preset is what serves those files.

### Can I host an Astro site on Unbroker's Free plan?

Yes, with the static Astro preset. On Free it runs with Serverless: an idle service scales to zero and wakes on the next request. Custom domains require Pro. Server rendering deploys as a Node.js service or a Dockerfile. Managed Node.js is on Free. Dockerfile builds are Pro. The Astro guide names the static preset as the Free path.

### Do custom domains work on Free?

No. The plans table lists custom domains and managed TLS as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. See [pricing](https://unbroker.cloud/pricing) and [Plans](https://docs.unbroker.cloud/billing/plans).

### How do I deploy an Astro site that uses a server adapter on Unbroker?

Add the adapter, then deploy its output as a Node.js service or with a Dockerfile. Follow that adapter's build and start instructions. The static Astro preset serves generated files, so leave server output off that preset. Dockerfile builds require Pro. Managed Node.js is included on Free. Astro's official adapters include one for Node.js.

### Where should API keys go in an Astro site?

On the backend service, not in client code. Astro makes PUBLIC_ variables available to the browser, and Unbroker selects that prefix, along with VITE_ and NEXT_PUBLIC_, as a public build variable. A value in the bundle the visitor downloads is public. Private variables stay runtime-only, except documented package-registry credentials. The split is the [frontend and API guide](https://docs.unbroker.cloud/guides/frontend-and-api), and the scopes are [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets).

### Why are my canonical URLs pointing at a preview hostname?

Canonical URLs and the sitemap are generated from Astro's site value. Set site to the final public origin and rebuild. If they still show a preview hostname, that is the origin configured for that build. After a custom domain is ready, check canonical URLs, the sitemap, and social images against the production origin. Keep the Unbroker hostname so a DNS problem stays separate from the deploy. Custom domains require Pro.

## Related reading

- [Deploy Astro](https://unbroker.cloud/deploy/astro)
- [Custom domain and HTTPS](https://unbroker.cloud/blog/custom-domain-https)
- [Environment variables and secrets](https://unbroker.cloud/blog/environment-variables-and-secrets)
- [Free backend hosting](https://unbroker.cloud/blog/free-backend-hosting)
- [Deploy on git push](https://unbroker.cloud/blog/deploy-on-git-push)
- [Frontend and API](https://unbroker.cloud/solutions/frontend-and-api)
- [Pricing](https://unbroker.cloud/pricing)
