Skip to content
Documentation

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
commandrequiredThe program to run, with its arguments
readysite.urlWhat proves the server is up: a URL, a port number, or { log: <pattern> }
cwdthe configuration file's folderWhere to run the command
env{}Extra environment variables for the command
timeout30000Milliseconds 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