Skip to content
Run BunYour friendly Bun playground

Running code and the debugger

Run starts your code in a Web Worker. The debugger pauses it at a line so you can look around.

It runs the first of:

  1. module or main in package.json
  2. the file in scripts.dev or scripts.start ("dev": "bun --watch src/index.ts" works, and so does "dev": "bun --preload ./setup.ts src/index.ts", which runs through Bun’s shell)
  3. index.ts, index.tsx, index.js or src/index.ts
  • Press Run (Ctrl/Cmd+Enter) again to restart. Stop with Ctrl/Cmd+., or Ctrl+C in the console.

  • Watch (on by default, the refresh icon next to Run) restarts the running program when you save, and clears the console, like bun --watch.

    What restarts and what reloads

    • In the browser, a save that only changes files the page loads (its scripts, stylesheets and what they import) and the program doesn’t import reloads the preview and keeps the program running.
    • If the program watches those files itself (fs.watch, as Vite’s dev server does), the preview is not reloaded either: the program updates the page, so hot module replacement keeps the page’s state.
    • package.json, installed packages, the program’s own imports and files it reads at run time still restart it.

    Crashes, syntax errors and exits

    • A crash doesn’t end it: the status says so and the next save runs the program again.
    • A save that leaves an open file with a syntax error (half-typed, as auto-save saves it) keeps the program running as it was until a save parses.
    • Stop, or a program that exits by itself, ends it until the next Run.

    A restart has no gap (in the browser)

    • The edited program starts next to the running one, which keeps answering the preview until the new one is up, then finishes the requests it had begun (up to 5 seconds); the preview’s WebSockets reconnect to the new one.
    • If the edited program throws while starting, or doesn’t start within 15 seconds, the running one keeps going and the status says the last save didn’t start.
    • Lines the previous program logs in the meantime start with [previous].
    • Database writes the previous program makes while both run are not carried over.

    With Local Bun

    The program restarts, and the preview’s requests wait for it.

  • With Watch off, edits still reach the running code: the next import or request sees them, and fs.watch fires. A script’s --watch and --hot flags are ignored either way.

  • A file location in the console (index.ts:3:7 in an error or a stack trace) is a link: click it to open the file there.

  • Scripts run when they are bun <file> or call one installed package's bin; with no entry file, Run starts the dev (else start) script.

    So "dev": "vite" runs Vite’s CLI with its arguments. Scripts that chain commands (tsc && …), pipe, set variables or use npx can’t run; start those tools from a file instead (see Frameworks).

Pause your program at a line and look around, without leaving the playground.

  1. Turn on Debug, the bug icon in the header or the status bar. A Debug panel opens above the console.
  2. Click a line number to set a breakpoint, a small red dot beside the number. Click again to remove it. A debugger; statement in your code pauses there too.
  3. Press Run. Debug applies to runs started after you turn it on.

When the program reaches a breakpoint, the line is highlighted and the file opens there. While it’s paused, the server doesn’t answer the preview, which waits. The panel shows:

  • Call stack: the functions that led there. Click one to open its line.
  • Variables: the paused function’s own variables, those of the blocks around the line, and the file’s top-level ones.
  • Evaluate: type an expression and press Enter. It runs where the program is paused, with its variables in scope.

Resume (F8), Step over (F10), Step into (F11) and Step out (Shift+F11) continue from there. Step out stops at the next statement after the function returns.

Breakpoints work in your project’s own files, including files loaded with require(), but not in node_modules. A debug run is slower, up to several times in tight loops, so turn Debug off when you’re done. Debug needs a cross-origin isolated page, which runbun.dev is in Chrome, Edge and Firefox (see Browsers). An embed shows no Debug button.

Was this page helpful?

Sends the rating and this page's address; nothing else unless you write it. Privacy

runbun is an independent project, not affiliated with or endorsed by Oven or Bun.