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