---
title: Overview
---

# Scripts

Yeet scripts run inside a V8 isolate with a curated set of globals: the [`yeet` object](./yeet-global), the [terminal](./terminal), timers and `console` from the [runtime reference](./runtime-reference), and [`Worker` and `SharedWorker`](./workers) for talking to other isolates. The runtime is intentionally minimal — it is not Node.js, not Deno, and not a browser.

## Running a script

```sh
yeet run script.js        # run once, exit when done
yeet run -w script.js     # watch mode — re-runs automatically when the file changes
```

Press **Ctrl+C** to cancel a running script at any time.

See [Running scripts](../cli/run) for the full `yeet run` reference, including `-p` for serving a script's screen or logs over WebSocket and HTTP.

## Module system

Scripts are evaluated as ES modules. `import` / `export` syntax works. `require()` / CommonJS is **not** supported.

```js
import myQuery from './my-query.graphql';
```

### Special import rules

| File extension | What you get |
|---|---|
| `.gql`, `.graphql` | A function `(vars?) => { query, subscribe, unsubscribe }` — see [GraphQL modules](./graphql-modules) |
| `.bpf.o` | A default-exported `BpfObject` pointing at that ELF — see [eBPF](./ebpf) |
| Everything else | Normal ES module |

### Built-in modules

| Import | Contents |
|---|---|
| `yeet:tui` | Declarative terminal UI — `Box`, `Text`, `Layer`, `CellBuffer`, `Disposal`, `mount`, `signal`, `computed`, `from`, `effect`, face helpers — see [TUI](./tui) |
| `yeet:tui/jsx-runtime` | JSX runtime (`jsx`, `jsxs`, `Fragment`) |
| `yeet:tui:layout` | Layout engine (`Node`, `Size`, `layout`) |
| `yeet:tui:face` | Styled-string and color primitives |
| `yeet:tui:text` | Text measurement utilities |
| `yeet:signal` | TC39-style signals (`Signal.State`, `Signal.Computed`, `Signal.subtle`) |
| `yeet:worker` | The `Worker` and `SharedWorker` globals, as an explicit import — see [Workers](./workers) |
| `yeet:messaging` | `MessageChannel`, `MessagePort`, `MessageEvent`: the port surface workers use — see [Ports and channels](./workers#ports) |

### JSX

Scripts can use JSX syntax in `.jsx` and `.tsx` files. The runtime transpiles it automatically — no pragma or build step required.

```jsx
import { Box, Text, mount } from 'yeet:tui';

mount(size => (
  <Box border="round" padding={1}>
    <Text>hello</Text>
  </Box>
));
```

JSX element types must be component functions. String tag names (`<div>`, etc.) are not supported.

## Execution model

- Scripts run as ES modules inside a single-threaded V8 isolate.
- Async/await and promises work — the event loop runs timers and resolves pending promises between turns.
- The isolate terminates when the top-level module finishes and no pending timers or unresolved promises remain, or when `yeet.exit()` is called.
- Uncaught exceptions and unhandled promise rejections are reported to the daemon and terminate the isolate. A [worker](./workers#errors) reports its own errors first, and outlives an unhandled rejection.