# Start the site automatically

By default shotlist expects something to already be answering at `site.url`. This guide makes a run start the server itself, which is what you need in continuous integration and on a clean checkout.

## Name the command

Add `site.serve` to your configuration:

shotlist.config.yaml

```
site:
  url: http://localhost:4321
  serve: npm run dev
```

Before starting anything, shotlist requests `site.url`. If something answers, it uses that server and starts nothing, so you can leave this setting in place while you work with your own development server open in another terminal.

Whatever a run starts, it stops, including when you interrupt it with Ctrl-C. The command runs in its own process group, so stopping `npm run dev` also stops the server npm spawned.

## Control how it starts

Write `serve` as a mapping when you need more than the command:

shotlist.config.yaml

```
site:
  url: http://localhost:4321
  serve:
    command: npm run dev
    ready: 4321
    cwd: apps/web
    env: { PORT: '4321' }
    timeout: 30000
```

| Key | Default | Effect |
| --- | --- | --- |
| `command` | required | The program to run, with its arguments |
| `ready` | `site.url` | What proves the server is up: a URL, a port number, or `{ log: <pattern> }` |
| `cwd` | the configuration file's folder | Where to run the command |
| `env` | `{}` | Extra environment variables for the command |
| `timeout` | `30000` | Milliseconds to wait for it to answer |

## Wait for a line of output instead of a port

Some servers accept connections before they can serve anything. When that produces flaky runs, wait for the line the server prints when it is genuinely ready:

shotlist.config.yaml

```
site:
  serve:
    command: npm run preview
    ready: { log: 'Local:' }
```

The three forms of `ready` are satisfied by:

- a URL, when any HTTP response arrives, including a 404
- a port number, when the port accepts a connection
- `{ log: … }`, when the pattern matches the server's output

## Pass environment variables

The command runs directly, not through a shell, so `VAR=value npm run dev` will be rejected rather than interpreted. Put the variables under `env`:

shotlist.config.yaml

```
site:
  serve:
    command: npm run dev
    env:
      DATABASE_URL: postgres://localhost/demo
      SEED: fixtures
```

For the same reason, `&&`, `|` and redirection are rejected. If your start-up genuinely needs a shell, put it in a script and name the script here.

## Related

- [Configuration reference: `site`](/docs/reference/configuration/#site)
- [Run shotlist in CI](/docs/how-to/run-in-ci/)
- [What a configuration can do](/docs/explanation/security-model/), which covers why `--untrusted` refuses to start a process at all

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/how-to/start-the-site.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/how-to/start-the-site.astro)