Set show: false and show windows once on ready-to-show in first-party templates #4436

Pre-flight checklist

• I have read the contribution documentation for this project.
• I agree to follow the code of conduct that this project uses.
• I have searched the issue tracker for a feature request that matches the one I want to file, without success.

Problem description

A window created with the default BrowserWindow visibility can appear before its renderer has painted the initial page. Users may briefly see an empty window or incremental loading, and newcomers need to discover and add the documented show: false / ready-to-show pattern themselves.

In my Forge Vite + TypeScript project, I added this pattern manually. I would like it included in the generated template as a small improvement to the initial window display experience.

A related report, #3256, describes the window appearing before the React content is displayed. The maintainer's reply points to Electron's graceful-window-display documentation and treats the report as application behavior rather than a Forge bug. This request proposes improving the generated example so new projects start with that documented pattern; it does not seek to reopen #3256 as a Forge runtime bug.

Proposed solution

Please add the following to first-party templates that generate an initially visible main BrowserWindow

1. Set show: false in the window options.
2. Register mainWindow.once('ready-to-show', ...) and call mainWindow.show() inside the callback.
3. Add a short comment linking to the Electron documentation and explaining that this waits for the initial render before showing the window.

For example, retaining the existing preload configuration and other window options:

const mainWindow = new BrowserWindow({
  width: 800,
  height: 600,
  show: false,
  webPreferences: {
    preload: path.join(__dirname, 'preload.cjs'),
  },
});

// Show the window after its initial render to reduce startup flashing.
mainWindow.once('ready-to-show', () => {
  mainWindow.show();
});

// Keep the existing development/production loadURL/loadFile logic here.

Alternatives considered

• Keep immediate display and set a backgroundColor matching the page. Electron explicitly documents this alternative for complex applications where waiting for ready-to-show would make startup feel slow. A comment can explain how to opt back into this behavior.
• Add only a comment or documentation link to the template. This would improve discoverability, but each new project would still need to implement the same small listener manually.
• Add an opt-in scaffold flag. This would provide a choice, but seems like extra configuration for a change that can be represented directly in the generated window code.

The requested default is show: false plus the one-time ready-to-show listener. Immediate display remains a valid application-specific choice.

Additional information

References:

• Electron: Showing the window gracefully includes the exact show: false + once('ready-to-show') pattern.
• Electron: ready-to-show event explains the initial-render condition.
• Related Forge discussion: #3256, closed as not planned; the proposed change here is to the scaffold's example code.

Important boundaries to document:

• ready-to-show concerns the first render. It does not guarantee completion of API requests or framework-specific business initialization.
• Keep paintWhenInitiallyHidden at its default true; setting it to false prevents ready-to-show from firing.
• Waiting for the first render changes startup timing. The template should explain the immediate-display alternative rather than imply that hidden-first startup is mandatory for every application.

Local project context, verified from installed package manifests:

My local src/main.ts already contains the manually added show: false and one-time listener. This is a request to include the pattern in the starter template, not a report of a failing local application. No cross-platform validation of the proposed upstream template change has been performed.