# Astro hosting

Host a static Astro site: run astro build, then npx lobsite deploys dist/ and uploads only the files that changed. HTTPS, forms and previews included.

On the web at https://lobsite.com/hosting/astro

```sh
npm run build && npx lobsite
```

Builds the site, then deploys dist/. public/ is left alone: Astro copies it into dist/ for you.

Astro builds a static site by default: every page becomes an HTML file in `dist/`, with only the JavaScript your islands need. That folder is all Lobsite needs. Run `npm run build`, then `npx lobsite` in the project, and the site is live at a `*.lobsite.app` address with HTTPS. You can also drop `dist/` in the box above.

## How it works

1. **Build the site** with `npm run build` (that's `astro build`). The pages, images and scripts land in `dist/`.
2. **Run `npx lobsite`** in the project. It deploys `dist/`, not `public/`, which Astro has already copied into the build. The first deploy needs no account and lasts 6 hours.
3. **Keep it** with the claim link, in a free account. The folder is saved in `lobsite.toml`, so the next build deploys with the same `npx lobsite`.

## Settings worth checking in astro.config.mjs

```js
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://my-site.lobsite.app",
  trailingSlash: "ignore",
});
```

- **`site`** is your full address. Astro uses it for canonical URLs, `Astro.site`, and the sitemap from `@astrojs/sitemap`. Set it to your `*.lobsite.app` address, and change it when you move to your own domain.
- **`base`** stays unset: the site is served from the top of its address, not a subfolder as on a GitHub Pages project site.
- **`build.format`** can stay at its default. `about/index.html` opens at `/about/`, and an `about.html` file opens at `/about`.

## What works, and what needs a server

Everything Astro renders at build time works: content collections, Markdown and MDX, `astro:assets` images (optimised during the build), and islands from React, Vue, Svelte or Solid, which run in the browser. Anything that runs per request doesn't: pages with `export const prerender = false`, `output: "server"`, Astro Actions and API endpoints that aren't prerendered. Those need a server adapter, and Lobsite only serves files. For a contact form, point it at `/_lobsite/forms/contact` instead of an Astro Action; see [forms](https://lobsite.com/features/forms).

## Astro hosts compared

| | Lobsite | Netlify | Vercel | GitHub Pages |
|---|---|---|---|---|
| Static Astro sites | Yes | Yes | Yes | Yes, with Astro's GitHub Action |
| Server rendering (adapter) | No | Yes | Yes | No |
| Builds on the server | No: you deploy `dist/` | Yes | Yes | In GitHub Actions |
| Account before the first deploy | No: live 6 hours, then keep it free | Yes | Yes | Yes, and a repository |
| Forms without a backend | Yes, once the site is in an account | Yes | No | No |
| Custom domain | Yes, free | Yes | Yes | Yes |

If parts of your site render on request, choose a host with an Astro adapter. If the site is static, which is Astro's default, Lobsite deploys it in seconds from your machine, CI or an AI agent, and only the files a build changed are uploaded.

## Frequently asked questions

### Do I need an adapter to host Astro on Lobsite?

No. Adapters are for server rendering. A static Astro site, the default, needs no adapter: deploy the `dist/` folder.

### Why does npx lobsite deploy dist/ and not public/?

In an Astro project, `public/` holds files the build copies as they are, such as `favicon.svg`. The built site is `dist/`. Lobsite sees `astro` in `package.json` and skips `public/` for you.

### Can I add a custom 404 page to my Astro site?

Yes. Create `src/pages/404.astro`; Astro builds it as `404.html`, and Lobsite serves it with a 404 status for any address that doesn't exist.

### Does Astro's image optimisation work?

Yes. `astro:assets` resizes and converts images during `astro build`, so the optimised files are already in `dist/` when you deploy. Only on-demand image services that run per request need a server.