# localhost:codevre (VRE)

> Codevre's built-in preview for static sites. It works like VS Code's Live Server, with DevTools, and runs entirely in your browser.

Last updated: October 17, 2026
Source: https://codevre.com/docs/ide/localhost-codevre

## What it is

**VRE** (Virtual Runtime Engine) is Codevre's preview for front-end projects. It always lives in the first Browser tab, labelled **localhost:codevre**. Once a page is running, the tab shows the page's own title and favicon.

It's like VS Code's **Live Server**, with differences that come from running in the browser:

- **No server process.** VRE takes the project's files from the editor, builds an in-memory file system, and serves your pages from it. There's no port to pick and nothing to install.
- **DevTools built in:** Elements, Console, Sources and Network, right under the page. See [DevTools](devtools.md).
- **Isolated.** The page runs on `preview.codevre.dev`, a different origin from the editor. See [Security model](security-model.md).

Use localhost:codevre for HTML, CSS and JavaScript, ES modules, canvas, WebGL and Three.js, p5/q5 sketches, and CDN libraries. Use a [dev server](dev-servers.md) only when you need real server code (APIs, Express, server-side rendering).

## Start the preview

Any of these start or rerun it:

- run **`vre run`** in the terminal, or `vre run about.html` for another page
- **Terminal ▸ Run Preview (VRE)**
- right-click an `.html` file ▸ **Preview in VRE**
- **Run Active File** on an HTML file
- the **Run** button in the preview toolbar

After that, every save reruns the page (see `vre.preview.autoRun`). Uploading a folder into an empty workspace starts the preview automatically.

### Which page opens

With no page given, VRE picks, in order:

1. `index.html` in the root (or the `vre.settings.root` folder)
2. `public/index.html`
3. the shallowest `index.html` outside build folders (`dist`, `build`, `out`, `.next`…)
4. any `index.html`
5. any page in the root
6. a page in `dist/`, `public/` or `build/`
7. the first `.html` file

Once a page is running, saves keep you on that page. Type a path like `/about.html` in the preview's URL bar to switch.

## The `vre` command

`vre` is a real command in the runtime (installed at `/usr/local/bin/vre`, outside your project), so it works in the terminal, in npm scripts, in `&&` chains and from `execSync()`.

```
vre run [entry.html]     start or rerun the preview  (aliases: dev, preview, start, serve)
vre reload [entry.html]  rerun without saving the active editor first  (aliases: refresh, restart)
vre stop                 stop the preview  (aliases: end, kill, close)
vre status               log the preview status to the browser console
```

`run` saves the active editor first. `reload`/`refresh`/`restart` don't, so a build tool can call them after writing output without triggering another rebuild.

The entry must be inside the project. A typical build script:

```json
{
  "scripts": {
    "build": "node build.js",
    "start": "npm run build && vre run index.html"
  }
}
```

## Configure the preview

Put these in `.codevre/settings.json` (Workspace), not in your User settings:

| Setting | Default | Meaning |
|---|---|---|
| `vre.preview.autoRun` | `true` | Rerun a running preview when files change |
| `vre.settings.root` | `""` | Serve a subfolder as `/`, e.g. `"public"`. The folder must exist |
| `vre.settings.Wait` | `100` | Milliseconds to wait after a change before rerunning (0–10000) |
| `vre.settings.ignoreFiles` | `[]` | Globs whose changes don't trigger a rerun |

```jsonc
// .codevre/settings.json
{
  "vre.settings.root": "public",
  "vre.settings.Wait": 200,
  "vre.settings.ignoreFiles": ["**/*.md", "notes/**"]
}
```

The VS Code Live Server keys `liveServer.settings.root`, `liveServer.settings.Wait` and `liveServer.settings.ignoreFiles` are read as aliases.

If `vre.settings.root` matches nothing, the status bar says *VRE root "X" has no files* and the preview is empty.

For projects with a build step, set `"vre.preview.autoRun": false` so the preview doesn't rerun on every source save, and let your build call `vre run` or `vre reload`.

## How reloading works

VRE doesn't do hot module replacement. A change works like this:

1. The editor writes your change to the runtime (about 500 ms after you stop typing).
2. VRE waits `vre.settings.Wait` ms, rebuilds its file set, and, if the preview is running and `autoRun` is on, reloads the whole page.

It skips a rebuild when nothing actually changed. Changes in `node_modules`, `.git` and `.codevre`, and paths matching `ignoreFiles`, never trigger one. CSS edits you make in DevTools apply live without a reload. They aren't saved to your files.

## What it supports

VRE intercepts the ways a page loads files and serves them from your project:

- `<script>`, `<link>` (stylesheets, icons, manifest, preload), `<img>`, `<audio>`, `<video>`, `<source srcset>`, `<object>`, SVG `<image>`, CSS `url(...)` and inline `background-image`
- `fetch()`, `XMLHttpRequest` (models, audio and video load as binary), `new Worker()`, `importScripts()`, `new URL('./x', import.meta.url)`
- elements added later by your scripts
- **ES modules:** relative and absolute imports resolve to project files, and Node-style lookups work (`./utils` finds `./utils.js` or `./utils/index.js`). Your own `<script type="importmap">` is merged in, but project files win.
- **Module imports of non-JS files:** `import './style.css'` injects the styles (and `?raw` gives the text), `import data from './data.json'` gives the data, and importing an image or shader gives its URL
- **Links between pages:** clicking a relative link loads that page. Back and Forward work. A missing page shows your `404.html` if you have one.
- **Query strings:** `?level=2` reaches your page as normal (also as `window.__APP_QUERY__`)
- **Python in the page** via Brython (`<script type="text/python">`)

Not supported:

- **No compiling.** TypeScript (`.ts`, `.tsx`) and JSX aren't transpiled. Use a build step (the React template uses esbuild) or load React from esm.sh with the Babel runner.
- **Bare npm imports** such as `import confetti from 'canvas-confetti'` aren't resolved from `node_modules`. Use an import map or a full CDN URL (`https://esm.sh/canvas-confetti`), or bundle with esbuild.
- `iframe.srcdoc` is blocked inside previews.
- No server code. Requests to API routes 404 here. Use a [dev server](dev-servers.md).

### Storage in the preview

Pages run on `preview.codevre.dev`, so `localStorage` and IndexedDB belong to that origin, not to codevre.com. Data your page stores survives reruns. It's in this browser only, and may be visible to other previews you run on the same origin, so don't rely on it being private to one project.

## The preview toolbar

**Back**, **Forward**, **Run / Refresh**, **Stop**, a URL bar for project paths, **Open in external window**, and the **DevTools** toggle. The toggle shows a dot when there's console output.

- **Open in external window** opens the page in its own window, connected through a relay on the editor's origin. **Switch back to embedded preview** returns it.
- Typing a full `https://` URL loads that site in a plain frame, without DevTools.
- The camera button in the Browser saves a screenshot to the project.

## For your page's code: `codevre.*`

Pages in VRE can call:

- `codevre.capture({ type: 'save', name: 'myImage' })` downloads a PNG of the first `<canvas>` (or the largest SVG). Handy for generative art.
- `codevre.renderDone()` signals that rendering has finished.