simple-browser-preview

Open VS Code's Simple Browser as a preview for the currently active file, using a configurable path pattern → URL mapping.

When enabled and configured, this extension lets you:

• Open a Simple Browser preview for the current file with a command or editor toolbar button.
• Keep the preview URL in sync with a specific file path (e.g. HTML built from a source file).
• Automatically refresh the preview when you save files, while tracking is enabled.

How it works

The extension watches the active text editor and saved files in your first workspace folder.

1. It converts the absolute file path to a workspace-relative path.
2. It checks that this relative path matches a configured regular expression.
3. It builds a preview URL by replacing the matched part of the path with a URL pattern.
4. It opens or refreshes VS Code's built-in Simple Browser with that URL, in a side-by-side column.

Only files whose relative paths match your pattern are considered "previewable" and get preview-related UI.

Requirements

• VS Code 1.108.1 or later (per engines in package.json).
• A folder workspace (the extension ignores files outside the first workspace folder).
• VS Code's built-in Simple Browser feature (simpleBrowser.api.open command).

Configuration

All settings live under the simple-browser-preview configuration section.

This extension contributes the following settings:

• simple-browser-preview.enable (boolean, default: false)

  • Master switch. Must be set to true for the extension to activate its preview behavior.

• simple-browser-preview.pattern (string)

  • A JavaScript regular expression applied to the workspace-relative file path.
  • If the active file path does not match this pattern, the file is not previewable.
  • Example: ^src/(.*).ts$ to match any TypeScript file under src/.

• simple-browser-preview.url (string)

  • Replacement pattern used to build the URL from the matched path.
  • You can use $1, $2, ... to reference capturing groups from pattern.
  • Example: http://localhost:3000/$1 to preview files served from a local dev server.

• simple-browser-preview.external (boolean, default: false)

  • If true, opens the preview URL in your system's default browser instead of VS Code's built-in Simple Browser.

Example configuration

Preview compiled HTML for source files under src/pages using a local dev server:

// settings.json
{
	"simple-browser-preview.enable": true,
	"simple-browser-preview.pattern": "^src/pages/(.*)\\.ts$",
	"simple-browser-preview.url": "http://localhost:3000/$1"
}

With this configuration, opening src/pages/home.ts and running the Open Preview command will open:

• http://localhost:3000/home

Commands

The extension contributes these commands:

• simple-browser-preview.openPreview

  • Title: simple-browser-preview Open Preview
  • Action: Opens the Simple Browser for the current file, using the configured pattern → URL mapping.
  • If the current file does not match simple-browser-preview.pattern, a message is shown instead of opening the browser.

• simple-browser-preview.trackingOn

  • Title: simple-browser-preview Tracking On
  • Action: Turns tracking on. When tracking is on and a preview is open for a file, saving that file (or other related files) triggers the preview to refresh.

• simple-browser-preview.trackingOff

  • Title: simple-browser-preview Tracking Off
  • Action: Turns tracking off. The existing preview stays open but will no longer auto-refresh on save.

You can run these commands from the Command Palette or via the editor title bar buttons (see below).

Editor toolbar integration

In the editor title bar, additional buttons appear when:

• The current file path is previewable (matches simple-browser-preview.pattern), and
• The extension has recorded it as a preview path.

Depending on the tracking state, you may see:

• simple-browser-preview Tracking On (eye-closed icon) when tracking is currently off.
• simple-browser-preview Tracking Off (eye icon) when tracking is currently on.
• simple-browser-preview Open Preview (open-preview icon) for opening the preview for this file.

These buttons are only visible for files that are eligible for preview.

Behavior details

• Only the first workspace folder is used to compute relative paths.
• Files outside the workspace are ignored.
• A file is considered previewable only if its workspace-relative path matches simple-browser-preview.pattern.
• The Simple Browser always opens beside the current editor (ViewColumn.Beside) and tries to preserve focus in the editor.
• The extension tracks which file last opened the preview to know which URL to refresh on save.

Known issues / limitations

• Multi-root workspaces: only the first workspace folder is considered.
• The preview URL logic is simple pattern replacement; it does not check whether the resulting URL is reachable.
• If VS Code's Simple Browser is not available, the open command will fail silently.

Development

• Build once: npm run compile
• Watch build: npm run watch
• Lint: npm run lint
• Tests: npm test

See esbuild.js, tsconfig.json, and src/extension.ts for implementation details.

Release notes

0.0.4

• Added simple-browser-preview.external setting to optionally open preview in the system default external browser.

0.0.1

• Initial release with pattern-based Simple Browser preview and tracking commands.