localhost:codevre (VRE)

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.
• Isolated. The page runs on preview.codevre.dev, a different origin from the editor. See Security model.

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 only when you need real server code (APIs, Express, server-side rendering).

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.

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.

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:

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

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

// .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.

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.

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.

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.

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.

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.