Static Site Preview (Web)

A small VS Code Web Extension for previewing static HTML/CSS/JavaScript sites without starting a local server. It is designed to run in desktop VS Code and in vscode.dev.

What works in v0.1

• Open .html / .htm from the Explorer context menu or editor title.
• Preview inside a normal VS Code webview panel.
• Multi-page static sites (./page.html, ../page.html, /page.html).
• Relative CSS, JavaScript, images, fonts, media and other resources through a page-local <base> URI.
• Root-relative src, <link href>, inline CSS url(...), and basic srcset rewriting.
• Back / Forward / Refresh commands in the preview title bar.
• Automatic full-page refresh whenever a file in the same workspace is saved.
• External http:, https:, mailto: and tel: links open through VS Code.
• Directory links try index.html; extensionless links also try .html.
• Basic GET-form navigation between static HTML pages.

Important limitations

This is a static-site previewer, not a real HTTP server.

• PHP, Node/Express, Python servers, Vite/Next dev servers, server-side routing, etc. do not run.
• The real browser window.location is the VS Code webview URL, not your site's logical URL. The logical location is exposed as window.__STATIC_SITE_PREVIEW_LOCATION__.
• Site-defined <base> and CSP meta tags are replaced for preview compatibility.
• Root-relative URLs inside external CSS files are not rewritten in v0.1. Relative CSS URLs work normally.
• POST forms and server endpoints are not supported.
• Some code that depends on a true HTTP origin, service workers, cross-origin isolation, or exact browser origin semantics will not behave like Live Server.
• Previewing code runs that page's JavaScript inside the VS Code webview sandbox. Treat untrusted projects as untrusted code.

Build

npm install
npm run build

The web extension bundle is written to dist/extension.js.

Test in a browser

npm run run-in-browser

This uses Microsoft's @vscode/test-web and opens the included sample-site in VS Code for the Web.

Test on actual vscode.dev

Do not use the GitHub Pages URL with "Developer: Install Extension From Location...". Although GitHub Pages serves package.json and dist/extension.js with HTTP 200 and CORS headers, VS Code for the Web restricts arbitrary network origins through its Content Security Policy. An external GitHub Pages origin is not a reliable/allowed installation location. See Microsoft's clarification on issue #201317.

For development, use the official localhost sideload procedure. On macOS with Homebrew and Node.js installed:

brew install mkcert
mkcert -install
git clone https://github.com/1112leo/static-site-preview-web.git
cd static-site-preview-web
npm ci
npm run build
mkdir -p .local-certs
mkcert -cert-file .local-certs/localhost.pem -key-file .local-certs/localhost-key.pem localhost
npx serve --cors -l 5000 --ssl-cert .local-certs/localhost.pem --ssl-key .local-certs/localhost-key.pem

Then open https://localhost:5000/ in your browser to confirm the local certificate is trusted. In vscode.dev, run Developer: Install Extension From Location... and enter https://localhost:5000/.

For permanent, no-local-server installation in vscode.dev, the normal route is to publish the web extension to the Visual Studio Marketplace under a registered publisher. A Marketplace publisher account and publish credential are required; deploying the extension files to GitHub Pages does not register it with the Marketplace.

Package VSIX

npm run package

This creates a .vsix package for normal VS Code installation/distribution. For actual vscode.dev testing before Marketplace publication, the documented "Install Extension From Location" sideload path is the reliable route.

Usage — v0.2.5

1. Open an .html or .htm file in the editor.
2. Press Cmd+Shift+V on macOS or Ctrl+Shift+V on Windows/Linux to toggle the preview. This shortcut only applies to HTML editors, so Markdown's preview shortcut still works.
3. Alternatively, right-click inside the HTML editor and choose Toggle Static Site Preview, or use the editor title-bar preview icon. The Explorer context-menu action is still available.
4. Default: expanded preview in the main editor. Opening from the shortcut or Open Static Site Preview in the Explorer moves the webview to the first editor group and expands it while leaving the Explorer and other sidebars exactly as they were. Other editor groups and source tabs remain intact. Open Static Site Preview Beside Editor is the explicit optional split-screen command and restores normal editor-group sizing. If a side preview is already open, the normal Open command moves it back to the fullscreen editor instead of reusing the narrow editor column. The previous staticSitePreview.openBeside setting no longer overrides the default: the two commands now have independent, predictable behavior.
5. Edit and save HTML, CSS, or JS: the preview refreshes automatically. Local page links navigate within the preview; Back, Forward, and Refresh commands are available.

Link behavior

The default is to open only genuinely external links in the browser:

• Local relative links (./about.html, ../about.html, /pages/about.html) navigate within the static HTML preview. No external-link confirmation is triggered.
• http://localhost:... and http://127.0.0.1:... links map to workspace HTML files.
• Full URLs matching the configured staticSitePreview.siteOrigin also resolve to workspace HTML files.
• Real external https://... and http://... links (including Google Forms) open in a normal browser tab through vscode.env.openExternal.
• For untrusted external sites, VS Code may ask for confirmation. The extension cannot bypass VS Code's security policies, but local HTML navigation does not use that API.

The optional staticSitePreview.externalLinks setting also allows preview to try a remote website inside the same webview via iframe. Remote sites may block iframe embedding via X-Frame-Options or CSP frame-ancestors. Use ignore if you prefer external links to do nothing.

GitHub Pages deployment

.github/workflows/pages.yml builds and tests the source and publishes package.json, dist/extension.js, and a landing page to GitHub Pages.

Important: This proves that the static hosting is working, not that the extension can be installed from that address in vscode.dev. The browser's CSP can prohibit arbitrary cross-origin extension installation even if the server returns HTTP 200 and Access-Control-Allow-Origin: *. Use the supported localhost sideload flow above, or distribute through the Visual Studio Marketplace.

Quick repository creation with GitHub CLI

After installing and signing in to GitHub CLI, open a terminal in the extracted project directory and run:

bash scripts/publish-github.sh

This creates a public repository named static-site-preview-web in the GitHub account authenticated to gh, commits the project, and pushes it to main. Existing repositories are not overwritten. Use bash scripts/publish-github.sh my-custom-repo-name for another name.

Automated checks

npm install
npm run build
npm test
npm run verify

npm test uses a small mocked VS Code API to verify that the bundled extension renders a site, navigates between pages, refreshes on save, blocks traversal, and opens external links safely. It is not a substitute for a real browser integration test with @vscode/test-web.