# Preview HTML Electron

> Create a lightweight Electron preview shell around an existing static HTML/CSS/JavaScript prototype while keeping the original HTML directory as the live source of truth. Use when designers or frontend engineers want to 把 HTML 套进 App 外壳、保留 macOS/Windows/Linux 原生窗口按钮、直接编辑桌面标题栏与安全区样式、自动刷新并用 DevTools 调试, or optionally package a local review snapshot without converting the prototype to another frontend framework.

- Skill: `migoxlab/preview-html-electron` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add migoxlab/preview-html-electron`
- Raw SKILL.md: https://api.skillmd.com/api/skills/migoxlab/preview-html-electron/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: migoxlab (https://skillmd.com/u/migoxlab)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/migoxlab/preview-html-electron

---


# Preview HTML in Electron

Create a separate, disposable Electron shell for design review. Keep the original HTML as the editable source; do not convert it to React, move it into an Electron codebase, or require designers to edit generated files.

Resolve this Skill's directory from the loaded `SKILL.md`. Never assume where the Skill is installed.

## Keep the boundary narrow

Use a directory that already works as a browser-deliverable static site and contains its HTML entry and assets. Plain multi-page prototypes are the primary case. A built static output is acceptable, but edits must be made in the directory configured as the live source.

The shell provides only:

- a native desktop window with either a standard system title bar or a native-controls overlay;
- a loopback-only local static server;
- automatic reload when source files change;
- DevTools on startup and standard reload/inspect shortcuts;
- secure renderer defaults with no Node.js access;
- an optional local package snapshot.

Do not add IPC, filesystem access, native menus, auto-update, authentication, backend services, signing, or release infrastructure unless the user separately requests them. Do not modify the prototype merely to generate a shell. If the user asks to adapt desktop window chrome, make the smallest changes in the original HTML/CSS and keep its browser preview usable.

## Choose the window chrome

Use `system` for ordinary pages, unknown layouts, or prototypes without a dedicated top chrome area. It preserves the operating system's complete title bar and is the compatibility default.

Use `native-overlay` for App-shaped prototypes that own their top title bar or safe area. It removes the extra title strip while retaining native macOS traffic lights and Windows/Linux window controls. Before selecting or adapting this mode, read [references/window-chrome.md](references/window-chrome.md) completely.

Never infer business selectors such as `.sidebar` or inject fixed layout rules into arbitrary pages. The Electron shell owns native window behavior; the live HTML source owns spacing, colors, drag regions, and interactive controls.

## Generate the preview shell

Determine an absolute source directory, a relative entry (default `index.html`), a new shell output directory outside the source, a product title, optional icon, window dimensions, and window chrome mode.

Run a dry run first:

```shell
node <skill-dir>/scripts/create-electron-app.mjs \
  --source <html-prototype-dir> \
  --output <new-preview-shell-dir> \
  --name <kebab-case-name> \
  --title "<window-title>" \
  --entry index.html \
  --chrome <system-or-native-overlay> \
  --icon <optional-relative-icon-path> \
  --dry-run
```

Check the reported live source, entry, output, title, icon, window size, and chrome mode, then rerun without `--dry-run`. Enable `--spa` only for a history-routed SPA; leave it off for multi-page HTML. For a custom overlay, use `--chrome-height`, `--traffic-light-x`, and `--traffic-light-y` only when the prototype's title-bar geometry requires them.

The generator must:

- leave the source unchanged;
- refuse an existing output or an output nested inside the source;
- store the absolute live-source link in `electron-dev.json`;
- copy an initial packaging snapshot into `site/` without making it the editing target;
- reject symlinks, credentials, private keys, and environment-secret files;
- keep `contextIsolation`, Chromium sandboxing, web security, and navigation guards enabled;
- expose only `data-runtime`, `data-platform`, and `data-window-chrome` DOM markers through the preload script.

## Start the design loop

Require Node.js 22.12 or newer. Check `node --version`; use an already available newer runtime or report the prerequisite rather than ignoring `EBADENGINE` warnings.

Install once and launch the preview:

```shell
cd <new-preview-shell-dir>
npm install
npm start
```

`npm start` must serve the original source directory, open DevTools, and reload every open preview window when HTML, CSS, JavaScript, images, or other source assets change. The first run can download the Electron binary.

Tell the designer to keep editing only the original HTML directory. Do not edit `site/`; it is a generated snapshot. Use `Cmd/Ctrl+R` for a manual hard reload and `Cmd+Option+I` / `Ctrl+Shift+I` or `F12` to toggle DevTools. If the source directory moves, update the absolute `source` field in `electron-dev.json` and run `npm run verify`.

For `native-overlay`, verify all of the following in the actual Electron window:

1. Native window controls appear once and do not overlap product chrome.
2. The source-owned title bar reserves the platform safe area.
3. Empty title-bar space drags the window.
4. Buttons, links, inputs, and other controls remain clickable through `app-region: no-drag`.
5. Browser preview still works and may show source-owned simulated controls.

Debug prototype problems in this order:

1. Check the Console for JavaScript, CSP, and network errors.
2. Check the Network panel for missing assets and case-sensitive paths.
3. Confirm that the configured entry and live-source directory are correct.
4. Confirm whether the HTML expects a backend or development server that is outside this static-shell scope.

Avoid weakening Electron security settings to hide a prototype error.

## Create an optional review snapshot

Only package when the user wants a locally openable snapshot. Packaging is not the primary design loop.

```shell
npm run package
npm run smoke:package
```

`npm run package` must first synchronize the current live source into `site/`, then create an unpacked app for the current OS. The smoke test must print `ELECTRON_WRAPPER_SMOKE_OK` and confirm the runtime/chrome DOM markers. Use `npm run dist` only when the user explicitly asks for an installer.

Treat the result as a local review artifact, not a signed production release. Do not claim cross-platform testing, signing, notarization, or installer validation unless each was actually performed.

## Handoff

Report:

- the unchanged HTML source and generated shell paths;
- the command designers use for their daily loop (`npm start`);
- whether live reload and DevTools were verified;
- the configured title, entry, icon, window size, and chrome mode;
- whether native controls, drag, no-drag, and safe-area behavior were visually verified;
- optional package and smoke-test results separately;
- any backend-dependent behavior the static shell cannot reproduce.