feat(bundlers): opt-in app:// protocol for serving packaged renderers

[erickzhao]

• I have read the contribution documentation for this project.
• I agree to follow the code of conduct that this project follows, as appropriate.
• The changes are appropriately documented (if applicable).
• The changes have sufficient test coverage (if applicable).
• The testsuite passes successfully on my local machine (if applicable).

Summarize your changes:

Adds an opt-in appProtocol option to plugin-vite and plugin-webpack that serves packaged renderer files over a privileged custom scheme (default app://) instead of file://, per Electron's security recommendations — file:// pages get an opaque origin, which breaks fetch() of local resources and origin-scoped storage.

// forge.config.js
{
  name: '@electron-forge/plugin-vite', // or plugin-webpack
  config: {
    build: [/* ... */],
    renderer: [/* ... */],

    // simplest form: serve renderers over app:// in packaged apps
    appProtocol: true,

    // or the object form:
    appProtocol: {
      scheme: 'myapp', // default: 'app' — validated at build time
      additionalPrivilegedSchemes: [
        { scheme: 'media', privileges: { stream: true } },
      ],
    },
  },
}

The protocol boilerplate (scheme registration, protocol.handle with a renderer-name allowlist and path traversal guard) lives once in @electron-forge/core-utils and is injected into production main-process bundles as a banner, rather than being duplicated into every scaffolded app where it would drift. Templates stay minimal: the Vite templates collapse to a single mainWindow.loadURL(MAIN_WINDOW_VITE_ENTRY) (new define: dev-server URL in dev, app:// URL in prod); the webpack templates only add appProtocol: true.

Notes:

• Opt-in only — existing apps are unaffected. Dev mode keeps dev-server URLs; webpack JS-only entries keep file://; the base template is untouched.
• The banner runs before any user code, so registerSchemesAsPrivileged happens before ready and the handler is registered ahead of any user loadURL. Since that call is once-per-app, additionalPrivilegedSchemes folds an app's own privileged schemes into it.
• scheme is validated at build time (lowercase RFC 3986 syntax, not a scheme Chromium/Electron claim). It becomes part of the renderer's origin, so renaming after release orphans origin-scoped data — documented accordingly.

Verified by unit specs, real builds through both pipelines, and a new Verdaccio e2e test that packages each bundler template, launches the binary, and asserts the renderer was served from app:// (it caught a real config-plumbing bug during development, fixed here). The custom-scheme path is also verified in a packaged asar app.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JHmXuuGMGg1bcCCYDNVSKW

[MarshallOfSound]

Comments inline. The webpack publicPath one is the big one, I think packaged webpack template apps do not load their JS at all with this. The rest is smaller.

[erickzhao]

Thanks for the thorough review — all ten findings are addressed in c9d72b0.

The big one (webpack publicPath): confirmed real. Served renderers now share the .webpack/renderer/ origin root with publicPath: '/' (Web-target compilations only, mirroring how the dev server already serves them), and entry URLs carry the per-entry subdirectory (app://main_window/main_window/index.html). Per-entry publicPath can't work since one compilation serves multiple entries, so the shared root was the viable option of the two you sketched. The Verdaccio probe now proves the renderer bundle executed — the renderer script posts a message, the preload forwards it with window.location.href over IPC — so an app whose subresources 404 fails the test; all four bundler templates pass it packaged.

The rest, briefly:

• Non-browser main-target bundles: if (process.type !== 'browser') return; guard (took the cheap fix — the plugin config can't distinguish the real main entry from workers).
• output.banner fragility: moved to a Forge-owned Vite plugin whose outputOptions hook composes with a user's banner, and the runtime carries its own leading 'use strict'; so the bundle's prologue stays effective (also applies to the webpack BannerPlugin path).
• Dev/prod privilege parity: both plugins now emit a registration-only runtime in dev (schemes registered, no handler), which also makes webpack validate the config under start like vite does.
• nodeIntegration renderers stay on file:// (kept AssetRelocatorPatch untouched).
• *_VITE_ENTRY resolves to a file:// expression in builds without appProtocol, so it's always a valid URL.
• Serving-scheme privileges: defaults now include stream + codeCache, and the object form accepts a privileges override merged over them.
• Validation: scheme syntax applies to additionalPrivilegedSchemes entries; renderer names are validated as URL hosts with a message pointing at the constraint.
• decodeURIComponent wrapped, malformed escapes return 400; the mangled timeout comment is fixed (vitest options-object form so the formatter can't collapse it again).

---

Generated by Claude Code

[felixrieseberg]

I suspect this to end up being a little unergonomic and believe some apps will want to handle protocol registration themselves while still wanting app:// for Vite resources.

Not a blocker though, just something I'm noticing.

[erickzhao]

@felixrieseberg on apps wanting to own registration while keeping app:// serving — agreed that funneling every privileged scheme through Forge config is the least ergonomic part of this design. It follows from registerSchemesAsPrivileged being once-per-app and needing to run before ready, which forces a single owner; the injected runtime claimed that role so the common case stays zero-config.

A clean escape hatch would be an opt-out like appProtocol: { registerSchemes: false }: Forge injects only the protocol.handle serving part, and the app makes its own registerSchemesAsPrivileged call (which must then include the serving scheme — we'd export the default privileges so that's one spread rather than folklore). That splits ownership exactly along the line you're describing: the app owns the registration call, Forge owns serving. Happy to add it to this PR if you and @MarshallOfSound think it's worth the extra surface now, or leave it as a documented follow-up since the current object form covers the known cases.

---

Generated by Claude Code

[felixrieseberg]

Seems fine. Some bike-shedding things that I don't think deserve blocking on:

• I'd love an easy way for apps to not get locked out of using registerSchemesAsPrivileged themselves when using the plugin.
• Some minor worries about the API contract but I doubt we'll change it anytime soon

Couldn't find any individual code I'd write differently!

[MarshallOfSound]

Second pass on c9d72b0 and e57a3c5. The earlier stuff looks fixed. A few of these are new from the fix commit itself: the webpack publicPath: '/' on JS-only entries, the file-level 'use strict' on the webpack main bundle, and the *_VITE_ENTRY define breaking Vite < 8.

[MarshallOfSound]

This sets publicPath: '/' for the whole Web-target compilation in prod when appProtocol is on. That compilation also contains the JS-only (isNoWindow) entries, and rendererEntryPoint() keeps those on file:// on purpose. A JS-only bundle now gets __webpack_require__.p = '/', so any asset module, lazy import() chunk, or new URL(..., import.meta.url) in it resolves to file:///<hash>.ext at the filesystem root instead of the old 'auto' script-relative URL. Packaged only.

Either put JS-only entries on the scheme too, split served and unserved entries into separate compilations, or only set publicPath: '/' when every entry in the compilation is served.

[MarshallOfSound]

This list is every non-preload-only entry, and the banner validates each one as a URL host. But rendererEntryPoint() only puts isLocalWindow && !nodeIntegration entries on the scheme. JS-only and nodeIntegration entries stay on file://. So a config that was valid before, like { name: 'background worker', js: 'worker.js' } (toEnvironmentVariable supports names with spaces), now throws "cannot be used with appProtocol" in start and package for an entry the scheme never serves. Filter this with the same predicate rendererEntryPoint uses. That also keeps the handler host allowlist to origins that are actually served.

[MarshallOfSound]

This still says app://<entry-name>/index.html. After c9d72b0 rendererEntryPoint() returns app://<name>/<name>/index.html because all origins share the .webpack/renderer/ root. It also does not say that nodeIntegration entries stay on file://. Someone writing a CSP or will-navigate allowlist from this gets the wrong path. Update it to the new URL shape and mention the nodeIntegration exception.

[MarshallOfSound]

net.fetch(fileUrl, { bypassCustomProtocolHandlers: true }) does not forward request.headers, so the Range header from the media pipeline is dropped and every response is a full 200 with no Content-Range or Accept-Ranges. This is the known protocol.handle + net.fetch(file:) gap, electron/electron#38749. <video>/<audio> load but cannot seek. That is a regression from file:// and it contradicts the APP_PROTOCOL_DEFAULT_PRIVILEGES comment that says stream "keeps <video>/<audio> working". The serving handler is injected and apps cannot patch it. Either handle Range here (parse it, return a 206 with Content-Range) or drop the claim and document the limitation.

[MarshallOfSound]

Pre-existing on next, but this PR rewrites the comment. It says hotRestart is moot because workers only run when packaging. The dev branch of build() also runs every main and preload target through spawnViteBuildWatch(this.serializableConfig, ...). hotRestart is not in the serialized config, so the worker vite.main.config.ts never installs pluginHotRestart, and the worker IPC has no restart message anyway. hotRestart: true is a silent no-op under start. At minimum the comment is wrong. Real fix is to include hotRestart in serializableConfig and bridge requestAppRestart from the worker to the parent like reload-renderers. Fine as a follow up.

[MarshallOfSound]

The new fallback (no appProtocol, the default path) is a template literal with require('node:path').join(...) in it. Vite 5 to 7 do build-time define through esbuild. esbuild only accepts JSON literals or identifier/member expressions there and fails with "Invalid define value" for the whole define map as soon as any define key (e.g. MAIN_WINDOW_VITE_NAME) is used in a file. plugin-vite has no vite peer range and imports the project's Vite, so an existing Vite 7 project that upgrades Forge without opting in can no longer build its main target. Only Vite 8 (oxc define) is exercised by the specs.

Keep this JSON-serializable or undefined, or gate the expression on Vite >= 8, or declare Vite 8 as the minimum. If the expression stays, use require('node:url').pathToFileURL(...).href instead of 'file://' + path so install paths with #, ? or % are encoded the same way the loadFile call this replaces did.

[MarshallOfSound]

The banner now starts with a file-level 'use strict';. On the Vite path that is a no-op, Rollup CJS output is already strict. plugin-webpack prepends the same string with BannerPlugin({ raw: true }) as the first statement of .webpack/main/index.js, in dev and prod. So the whole webpack main bundle is now strict, including the webpack runtime and every bundled sloppy-mode CJS dep. webpack keeps CJS modules sloppy on purpose unless every module is strict. With appProtocol on (the webpack template default now), one dep with a legacy octal escape or with makes the whole file a SyntaxError, and implicit globals and this change silently.

Keep the directive inside the IIFE for the webpack path and only add the file-level one in pluginAppProtocolRuntime, or inject via Rollup output.intro which lands after Rollup's own 'use strict'.

[MarshallOfSound]

Two configs pass resolveAppProtocolConfig and validateRendererNameForAppProtocol but cannot work at runtime, which breaks the "throws rather than emitting a runtime that could never serve a window" contract:

• privileges is spread over the defaults (which now include codeCache: true) with no validation. privileges: { standard: false }, or an additionalPrivilegedSchemes entry with codeCache and no standard, emits a registerSchemesAsPrivileged call that Electron rejects ("Code cache can only be enabled when the custom scheme is registered as standard scheme"). That throws synchronously in the IIFE at the top of the main bundle. standard: false on the serving scheme cannot work with host-based renderer matching anyway. Force or reject it, and reject codeCache without standard.
• RENDERER_NAME_AS_HOST accepts all-numeric names (1, 2024, 1.2, 0x10). standard: true schemes get Chromium IPv4 host canonicalisation, app://1/ becomes app://0.0.0.1/, so the handler rendererName.toLowerCase() === url.hostname check never matches and the window 404s, packaged only. Require at least one letter, or compare against the canonicalised host.