# Sites

> Static files served from the edge with an HTTPS hostname, redirects, rewrites, headers and an SPA fallback

URL: https://pier.run/docs/resources/sites

```yaml title="pier.yaml"
environments:
  prod:
    sites:
      - name: www
        build_context: ./www
        targets:
          - name: primary
            framework: vite                 # detected when omitted
            build_command: npm run build
            output_dir: dist
            spa_fallback: true
            routes:
              redirects:
                - { source: /old, destination: /new, status: 308 }
              headers:
                - { path: /assets/*, headers: { Cache-Control: "public, max-age=31536000" } }
```

```bash
pier ls sites
```

```text title="output"
                                                     
 NAME STATUS URL                                     
                                                     
 www  active https://6aeqkcz34yr.site.pier.run 
                                                     

```

A site is a directory of files. Pier builds it (a detected framework, or `build_command`)
or uploads it unchanged (`--skip-build`), then serves the output from the edge. A site has
no container, no port and no plan. Each [target](/docs/concepts#target) has its own
hostname and its own published bundle.

## Configuration

| Key                                     | On           | Meaning                                                                                                  |
| --------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| `build_context`                         | site         | Directory to build, relative to `pier.yaml`                                                              |
| `template`                              | site         | Start from a starter (`site_nextjs`, `site_astro`, `site_vite`, `site_hugo`, `site_html`)                |
| `env`                                   | site, target | Build-time variables                                                                                     |
| `previews`                              | site         | Preview targets per branch                                                                               |
| `targets[].framework`                   | target       | `vite`, `nextjs-static`, `astro`, `sveltekit-static`, `hugo`, `static`, `custom` — detected when omitted |
| `targets[].build_command`, `output_dir` | target       | Override the detected build and its output directory                                                     |
| `targets[].index_document`              | target       | Document served for `/` (default `index.html`)                                                           |
| `targets[].spa_fallback`                | target       | Serve `index.html` for unknown paths                                                                     |
| `targets[].routes`                      | target       | `redirects`, `rewrites`, `headers`, `fallback` — also `pier routes`                                      |
| `targets[].deploy.branch`               | target       | Branch that publishes this target on push                                                                |
| `targets[].domains`                     | target       | Custom domains — [Domains](/docs/resources/domains)                                                      |

## Commands

| Command                                                                          | Does                                                                     |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `pier add site`, `pier set site www`, `pier rm site www`                         | declare, change, remove                                                  |
| `pier deploy www --path ./www [--skip-build]`                                    | build and publish; `--build-cmd`, `--output-dir` override for one deploy |
| `pier info www`, `pier deploys ls www`                                           | hostname, published bundles                                              |
| `pier rollback www`                                                              | serve the previous bundle                                                |
| `pier routes ls www`, `pier routes add www redirect`, `pier routes fallback www` | edge rules without editing the file                                      |
| `pier add target www preview --branch develop`, `pier promote www/preview`       | more targets; change the primary                                         |

## Behaviour

* A publish is atomic: the new bundle replaces the old one for every path at once.
* Unchanged files are not re-uploaded, so a publish after a small change transfers only
  the changed files.
* Redirects default to `308`; rules apply in order: redirects, rewrites, then the file
  lookup with its fallback.

## Tasks

[Deploy a static site](/docs/guides/deploy-a-static-site) · [Add a custom domain](/docs/guides/add-a-custom-domain) ·
[Deploy from GitHub](/docs/guides/deploy-from-github) · [Preview deployments](/docs/guides/preview-deployments)