# Deployment

> Deploy a sitelo site to Netlify, Vercel, Cloudflare, AWS, Azure, Google Cloud, GitHub Pages, GitLab Pages, Render, DigitalOcean, Railway, Fly.io, Heroku, or any static host.

A sitelo build is plain static files: `sitelo build` writes HTML, CSS, and JS to `dist/`. Any static host works — the configs below only assume `npm run build` → `dist/`.

Clean URLs are directories with `index.html` (`/about/index.html` → `/about`), so pretty URLs work out of the box with no redirect rules. A `404.html` is emitted automatically — the convention Netlify, Cloudflare Pages, and GitHub Pages all understand.

Ready-to-copy versions of all of these ship in the [basic example](https://sitelo.dev/examples/basic) ([examples/basic](https://github.com/paul-browne/sitelo/tree/main/examples/basic) in the repo).

## Static hosts

These hosts build the site and serve `dist/` from their own CDN.

[Netlify](https://sitelo.dev/docs/deployment#netlify) · [Vercel](https://sitelo.dev/docs/deployment#vercel) · [Cloudflare](https://sitelo.dev/docs/deployment#cloudflare) · [AWS Amplify](https://sitelo.dev/docs/deployment#aws-amplify) · [AWS S3 + CloudFront](https://sitelo.dev/docs/deployment#aws-s3-cloudfront) · [Azure Static Web Apps](https://sitelo.dev/docs/deployment#azure-static-web-apps) · [Firebase Hosting](https://sitelo.dev/docs/deployment#firebase-hosting) · [GitHub Pages](https://sitelo.dev/docs/deployment#github-pages) · [GitLab Pages](https://sitelo.dev/docs/deployment#gitlab-pages) · [Render](https://sitelo.dev/docs/deployment#render) · [DigitalOcean App Platform](https://sitelo.dev/docs/deployment#digitalocean-app-platform)

### Netlify

`netlify.toml`

```bash
[build]
  command = "npm run build"
  publish = "dist"
```

### Vercel

`vercel.json`

```javascript
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install"
}
```

### Cloudflare

Cloudflare now points new projects at Workers rather than Pages. With this config, `npx wrangler deploy` builds the site and uploads `dist/`, and connecting the repo in the Cloudflare dashboard runs the same command on every push. `html_handling: "drop-trailing-slash"` serves `/about` without a redirect, and unknown URLs get `404.html`.

`wrangler.jsonc`

```javascript
// Cloudflare Workers
{
  "name": "my-site",
  "compatibility_date": "2026-10-01",
  "build": {
    "command": "npm run build"
  },
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
    "html_handling": "drop-trailing-slash"
  }
}
```

Still on Pages? Set the build command to `npm run build` and the output directory to `dist`, or upload a local build with `npx wrangler pages deploy dist`.

### AWS Amplify

`amplify.yml`

```bash
# AWS Amplify Hosting
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm install
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
```

### AWS S3 + CloudFront

Keep the bucket private and put CloudFront in front of it with origin access control. CloudFront maps only `/` to `index.html`, so attach this function to the distribution’s viewer requests to serve sitelo’s clean URLs.

`cloudfront-function.js`

```javascript
function handler(event) {
  var request = event.request
  var uri = request.uri

  if (uri.endsWith('/')) {
    request.uri += 'index.html'
  } else if (uri.slice(uri.lastIndexOf('/') + 1).indexOf('.') === -1) {
    request.uri += '/index.html'
  }

  return request
}
```

A private bucket answers a missing file with 403, so add custom error responses for 403 and 404 that return `/404.html` with status 404. Then upload each build and clear the cache:

`shell`

```bash
npm run build
aws s3 sync dist/ s3://my-bucket --delete
aws cloudfront create-invalidation --distribution-id MY_DISTRIBUTION_ID --paths "/*"
```

### Azure Static Web Apps

Create the Static Web App in the Azure portal with app location `/` and output location `dist`; Azure commits a GitHub Actions workflow that runs `npm run build`. Put this file in `public/` so the build copies it into `dist/` — without it, Azure answers unknown URLs with its own error page instead of `404.html`.

`public/staticwebapp.config.json`

```javascript
{
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}
```

### Firebase Hosting

On Firebase Hosting, pick a project with `firebase use --add`, then run `firebase deploy` — the predeploy hook builds first. Unknown URLs get `404.html` automatically, and `trailingSlash: false` serves `/about` without a redirect.

`firebase.json`

```javascript
{
  "hosting": {
    "public": "dist",
    "predeploy": "npm run build",
    "trailingSlash": false
  }
}
```

### GitHub Pages

`.github/workflows/deploy.yml`

```bash
# GitHub Pages
name: Deploy
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist
      - uses: actions/deploy-pages@v5
```

Deploying under a subpath (`user.github.io/repo`)? Build with `--base /repo/`.

### GitLab Pages

GitLab serves `404.html` and directory URLs on its own, so the job only builds and publishes `dist/`.

`.gitlab-ci.yml`

```bash
# GitLab Pages
deploy-pages:
  image: node:24
  script:
    - npm ci
    - npm run build
  pages:
    publish: dist
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### Render

Add the Blueprint below to the repo, or create a static site in the dashboard with the same build command and publish directory. Clean URLs and `404.html` work with no redirect rules.

`render.yaml`

```bash
# Render
services:
  - type: web
    name: my-site
    runtime: static
    buildCommand: npm install && npm run build
    staticPublishPath: ./dist
```

### DigitalOcean App Platform

Set `github.repo` to your repository, then create the app with `doctl apps create --spec .do/app.yaml` — or paste the spec into the dashboard. App Platform resolves directory URLs and serves `404.html` by default.

`.do/app.yaml`

```bash
# DigitalOcean App Platform
name: my-site
static_sites:
  - name: site
    github:
      repo: your-name/your-site
      branch: main
      deploy_on_push: true
    build_command: npm run build
    output_dir: dist
```

## Container hosts

These hosts run a container, and one `Dockerfile` covers them all: Node builds the site, then Caddy serves `dist/` with clean URLs and answers unknown ones with `404.html`. Caddy listens on `PORT` when the host sets it, and on port 80 otherwise. Add all three files to the project root.

[Railway](https://sitelo.dev/docs/deployment#railway) · [Fly.io](https://sitelo.dev/docs/deployment#fly-io) · [Heroku](https://sitelo.dev/docs/deployment#heroku) · [Google Cloud Run](https://sitelo.dev/docs/deployment#google-cloud-run)

`Dockerfile`

```bash
FROM node:24-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM caddy:2-alpine
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/dist /app/dist
```

`.dockerignore`

```bash
node_modules
dist
.git
```

`Caddyfile`

```bash
:{$PORT:80} {
  root * /app/dist
  encode zstd gzip
  try_files {path} {path}/index.html
  file_server
  handle_errors {
    rewrite * /{err.status_code}.html
    file_server
  }
}
```

### Railway

Railway builds the `Dockerfile` whenever it finds one, so there’s nothing to set. Without the Dockerfile, add the service variable `RAILPACK_SPA_OUTPUT_DIR=dist` and keep the `Caddyfile`: Railpack then serves `dist/` through it instead of its single-page-app default, which answers unknown URLs with the home page.

### Fly.io

Run `fly launch` to create the app, then `fly deploy`.

`fly.toml`

```bash
# Fly.io
app = "my-site"

[http_service]
  internal_port = 80
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0
```

### Heroku

Heroku builds the `Dockerfile` through `heroku.yml`. Switch the app to the container stack once with `heroku stack:set container`, then `git push heroku main`.

`heroku.yml`

```bash
# Heroku
build:
  docker:
    web: Dockerfile
```

### Google Cloud Run

Run `gcloud run deploy --source .` from the project root: Cloud Build builds the `Dockerfile` and Cloud Run serves it.

## Your own server

Copy the build to the server with `rsync -a --delete dist/ you@server:/var/www/my-site/` and serve it with Caddy or nginx — clean URLs and `404.html` work the same as on the hosts above. Caddy fetches an HTTPS certificate for the domain on its own; with nginx, add one with certbot.

`Caddyfile`

```bash
example.com {
  root * /var/www/my-site
  encode zstd gzip
  try_files {path} {path}/index.html
  file_server
  handle_errors {
    rewrite * /{err.status_code}.html
    file_server
  }
}
```

`nginx.conf`

```bash
server {
  listen 80;
  server_name example.com;
  root /var/www/my-site;

  location / {
    try_files $uri $uri/index.html =404;
  }

  error_page 404 /404.html;
}
```

## Before you ship

- Set `site` in `sitelo.config.js` so `sitemap.xml` is generated — see [Configuration](https://sitelo.dev/docs/configuration)
- Add a `src/404.ht.js` for a branded not-found page (a clean default is emitted otherwise)
- `sitelo preview` serves the production build locally for a final check
