> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tempo.new/llms.txt
> Use this file to discover all available pages before exploring further.
# Setup & Run Scripts
> Configure workspace setup scripts and run actions for your projects in Tempo.
# Setup & Run Scripts
Tempo lets you configure **setup scripts** and **run scripts** for each project. Setup scripts run automatically when a new workspace is created, and run scripts are quick actions you can trigger from the header.
Scripts are split into two categories based on where they're stored:
* **Repo scripts** are stored in `tempo/tempo.config.json` (the canonical config location) and shared with your team when committed. This includes the Workspace Setup Script and Repo Run Scripts.
* **Private scripts** are stored only on your device and are never shared. This includes the Private Setup Script and Private Run Scripts.
***
## Setup Scripts
A **setup script** runs automatically every time a new workspace is created for a project. This is useful for tasks like symlinking environment files, installing dependencies, or any other initialization your project needs.
There are two flavors:
* **Workspace Setup Script** — stored in `tempo.config.json`. When committed, every team member gets the same setup script automatically.
* **Private Setup Script** — stored only on your device. Runs *after* the Workspace Setup Script. Use for personal symlinks (e.g. `.env.local`) you don't want to share with the team.
If both scripts are configured, the Workspace Setup Script runs first, then the Private Setup Script runs in a second terminal tab. Each is independent — a failure in one doesn't block the other.
### Configuring a setup script
1. Open **Settings** from the sidebar
2. In the **Projects** section, click the project you want to configure
3. Enter your shared script in the **Workspace Setup Script** textarea, or your per-device script in the **Private Setup Script** textarea
4. The script saves automatically when you click away
### The `TEMPO_SOURCE_PATH` environment variable
When a setup script runs, Tempo injects the `TEMPO_SOURCE_PATH` environment variable. This contains the absolute path to your project's original source directory (where you first imported the project from).
This is especially useful for symlinking files that shouldn't be committed to git:
```bash theme={null}
ln -sf $TEMPO_SOURCE_PATH/.env .env
ln -sf $TEMPO_SOURCE_PATH/.env.local .env.local
```
### How it works
* The Workspace Setup Script is read from the `tempo.config.json` **inside the workspace** at creation time
* The Private Setup Script is read from your device's local storage at the same moment
* Each runs in its own **background terminal tab** (they won't steal focus from your current work)
* The tabs are titled **"Setup Script"** and **"Private Setup Script"** respectively
* If a script exits with a non-zero code, a toast notification appears to alert you
***
## Run Scripts
**Run scripts** are named commands you can trigger from the header button. Use them for common tasks like starting a dev server, running tests, or building your project.
### Repo Run Scripts
Repo run scripts are stored in `tempo.config.json` alongside the setup script. When committed, they're shared with your entire team — everyone gets the same set of commands.
Great choices for repo run scripts:
* **Dev Server**: `pnpm dev` or `npm run dev`
* **Build**: `pnpm build`
* **Test**: `pnpm test`
* **Lint**: `pnpm lint`
* **Type Check**: `pnpm tsc --noEmit`
### Private Run Scripts
Private run scripts are stored only on your machine. Use these for personal workflows that don't need to be shared:
* **Debug mode**: `DEBUG=true pnpm dev`
* **Dev with specific port**: `PORT=4000 pnpm dev`
* **Watch tests**: `pnpm test --watch`
### Configuring run scripts
1. Open **Settings** and select your project
2. Under **Repo Run Scripts**, click **Add Script** to add a shared script
3. Under **Private Run Scripts**, click **Add Script** to add a personal script
4. Enter a **name** (e.g., "Dev Server") and a **command** (e.g., `pnpm dev`)
5. Click the **star icon** to set a script as the **default** action
You can only have one default script across both tables. Click the star on any script — repo or private — to make it the default.
### The generated "App dev server" script
If your project has an app dev command configured in `tempo/tempo.config.json` — canonically `apps[0].appStart` (the command Tempo uses to power route storyboards on the canvas; the legacy `scripts.appStart` spelling still works) — it automatically appears in the run-script dropdown as a read-only **App dev server** entry labeled *Generated by Tempo*. It can't be edited or deleted from settings — change the app dev command to change it — and it acts as the default action unless you star another script. When run, its `${PORT}` placeholder is resolved to the same port the canvas uses, so you never end up with two copies of your dev server.
### Running scripts
Once you have at least one run script configured (generated, repo, or private), a **play button** appears in the workspace header (to the left of the Commit button).
* **Click the play button** to run the default script
* **Click the dropdown arrow** to see all configured scripts, grouped by Repo and Private
* **Click the star icon** in the dropdown to change the default without opening settings
* The dropdown also includes an **"Add action"** row that takes you to project settings
Each run script opens in a new, focused terminal tab with the script name as the title. The `TEMPO_SOURCE_PATH` environment variable is also available in run scripts.
***
## Where scripts are stored
| Script Type | Location | Shared? |
| ---------------------- | -------------------- | ------------------- |
| Workspace Setup Script | `tempo.config.json` | Yes, when committed |
| Private Setup Script | Browser localStorage | No, personal only |
| Repo Run Scripts | `tempo.config.json` | Yes, when committed |
| Private Run Scripts | Browser localStorage | No, personal only |
### `tempo.config.json` example
```json theme={null}
{
"scripts": {
"install": "pnpm install",
"start": "pnpm dev"
},
"setupScript": "pnpm install && ln -sf $TEMPO_SOURCE_PATH/.env .env",
"runScripts": [
{ "name": "Dev Server", "command": "pnpm dev" },
{ "name": "Build", "command": "pnpm build" },
{ "name": "Test", "command": "pnpm test" }
]
}
```
***
## Recommended Script Examples
### Setup Scripts
| Use Case | Command |
| -------------------- | ------------------------------------------------------- |
| Symlink env files | `ln -sf $TEMPO_SOURCE_PATH/.env .env` |
| Install dependencies | `pnpm install` |
| Full setup | `pnpm install && ln -sf $TEMPO_SOURCE_PATH/.env .env` |
| Copy config files | `cp $TEMPO_SOURCE_PATH/config.local.js config.local.js` |
### Repo Run Scripts (shared with team)
| Name | Command | Description |
| ---------- | ------------------- | ---------------------------- |
| Dev Server | `pnpm dev` | Start the development server |
| Build | `pnpm build` | Production build |
| Test | `pnpm test` | Run the test suite |
| Lint | `pnpm lint` | Run linter checks |
| Type Check | `pnpm tsc --noEmit` | TypeScript type checking |
| Storybook | `pnpm storybook` | Launch Storybook |
### Private Run Scripts (personal)
| Name | Command | Description |
| --------------- | ------------------------- | -------------------------- |
| Dev (debug) | `DEBUG=* pnpm dev` | Dev server with debug logs |
| Test Watch | `pnpm test --watch` | Watch mode for tests |
| Dev (port 4000) | `PORT=4000 pnpm dev` | Custom port |
| Profile Build | `ANALYZE=true pnpm build` | Build with bundle analysis |
### Private Setup Scripts (personal)
| Use Case | Command |
| ----------------------------- | ------------------------------------------------- |
| Symlink personal env override | `ln -sf $TEMPO_SOURCE_PATH/.env.local .env.local` |
| Install personal dev tooling | `pnpm add -D my-personal-debug-tool` |