# Add a Splash Screen to an Electron App

Yes. An agent adds a frameless splash window that shows while the main window loads, closes it on ready-to-show, keeps the smoke test green and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-splash-screen/electron/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the first window appears before it puts one in front of it. In an app shaped like electron-react-boilerplate/electron-react-boilerplate, `package.json` pins `electron` ^44.4.0, `electron-vite` ^5, `electron-builder` ^26 and `jest` 30 with `jsdom`, and its scripts run `electron-vite dev --watch` for `start`, `electron-vite build`, `electron-builder build --publish never` for `package`, `jest` and `node .erb/scripts/smoke-test.cjs`. `src/main/main.ts` creates the `BrowserWindow` with `show: false`, 1024 by 728, the preload from `../preload/preload.js`, shows it on `ready-to-show` unless `START_MINIMIZED` is set, builds the menu, sends external links to the browser, and loads `resolveHtmlPath('index.html')`, which `src/main/util.ts` resolves to `ELECTRON_RENDERER_URL` in development and a `file:` URL under `../renderer` when packaged. `app.whenReady()` awaits `createWindow()` and then `startAutoUpdates()`, and `reportWindowError` destroys the window on failure. `electron.vite.config.ts` gives the renderer one Rollup input, `src/renderer/index.html`, and names its output `renderer.js`. `src/renderer/index.html` sets a `Content-Security-Policy` of `script-src 'self' 'unsafe-inline'`. `assets/` holds `icon.png` and `icon.svg`, and `extraResources` copies `./assets/**` into the package. `.github/workflows/test.yml` runs `npm run package`, `npm run lint`, `tsc --noEmit`, `npm test` and the smoke test on macOS, Windows and Linux.

The splash is a second, smaller window with no preload and no script. `src/renderer/splash.html` is a static page with the icon and the product name, styled inline, and `electron.vite.config.ts` lists it as a second Rollup input beside `index.html`, with `entryFileNames` changed to a per-entry name so the two bundles do not collide; in development the Vite server serves it at the same `ELECTRON_RENDERER_URL`. `src/main/splash.ts` exports `createSplashWindow()`: a `BrowserWindow` of 360 by 240, `frame: false`, `resizable: false`, `alwaysOnTop: true`, centred, with `sandbox: true` in its `webPreferences`, that loads `resolveHtmlPath('splash.html')`. `createWindow` in `main.ts` opens the splash first, then the main window as before; the `ready-to-show` handler closes the splash before it shows or minimises the main window, and `reportWindowError` closes it too, so a failed main window never leaves a splash on screen. No minimum display time is added: the splash lives exactly as long as the main window takes, and the pull request notes where a floor would go.

`src/__tests__/updates.test.ts` shows the project's main-process test style: `jest.mock('electron', ...)` with a small object, `jest.resetModules()` in `beforeEach` and a plain `require` of the module under test. The agent adds `src/__tests__/splash.test.ts` the same way, with a fake `BrowserWindow` class that records its options and its `loadURL` argument: one test asserts the options above and that the URL ends in `splash.html`, another emits `ready-to-show` on the fake main window and asserts the splash was closed before `show` was called. `.erb/scripts/smoke-test.cjs` starts `npm start` with a remote debugging port and looks the window up through `/json/list`, so the agent reads its target predicate and checks that a second page target does not change which one it picks. Then it runs `npm run lint`, `npm exec tsc -- --noEmit`, `npm test`, `npm run package` and `xvfb-run --auto-servernum npm run test:smoke`, the Linux steps of the workflow, and pastes the output in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a splash screen to this Electron app and open a pull request. Read package.json, electron.vite.config.ts, src/main/main.ts, src/main/util.ts, src/main/preload.ts, src/renderer/index.html, src/__tests__/updates.test.ts, jest.config.js, .erb/scripts/smoke-test.cjs and .github/workflows/test.yml first. Add src/renderer/splash.html as a static page with the icon and product name and no script, and register it as a second renderer input in electron.vite.config.ts with per-entry output names. Add src/main/splash.ts exporting createSplashWindow(): a 360 by 240 frameless, non-resizable, always-on-top, centred BrowserWindow with sandbox enabled and no preload, loading resolveHtmlPath('splash.html'). In createWindow open the splash before the main window, close it in the ready-to-show handler before show or minimize, and close it in reportWindowError. Add src/__tests__/splash.test.ts in the style of updates.test.ts covering the window options, the loaded URL and the close on ready-to-show. Check the smoke test still finds the main window. Run npm run lint, npm exec tsc -- --noEmit, npm test, npm run package and the smoke test under xvfb-run, and paste the output in the pull request. Do not change the preload, the menu or the updater.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `src/renderer/splash.html`, `src/main/splash.ts` and `src/__tests__/splash.test.ts`, edits `src/main/main.ts` and `electron.vite.config.ts`, and leaves the preload, the menu and `updates.ts` alone. The description describes the window, lists its options and pastes the `jest`, `tsc`, `lint`, `package` and smoke-test output.

On a repository with the `Test` workflow, the pull request packages the app and runs the smoke test on macOS, Windows and Linux, so a splash that kept the main window from being found would fail on all three.

A reviewer checks that the splash closes on every path, `ready-to-show`, `START_MINIMIZED` and `reportWindowError`, that `alwaysOnTop` is acceptable on macOS where another app may be full screen, that the second renderer entry lands in `release/app/dist/renderer`, and that the splash page carries the same content security policy as `index.html`. Then they decide whether a minimum display time is wanted.

## Run it on every Electron app with a slow first window

A team with several Electron apps sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `main.ts` and bundler config, so an app on Webpack gets a second entry there and an app that already shows its window at once gets the splash wired to `did-finish-load` instead, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and the test output from.

## Why run it on Rush?

A splash is only right when it closes on every path the main window can take, including the one where the window fails, and that is a main-process behaviour a browser test cannot see. In a Rush sandbox the agent runs the jest tests against a fake `BrowserWindow`, packages the app and starts the real binary under `xvfb-run` the way CI does, keeping the output in the run's record.

The change adds one static page, one module and one test and reuses `resolveHtmlPath` and the existing build, so there is no new dependency. The same request works on any electron-vite app with a single main window.

## Frequently asked questions

### Why does the splash have no preload and no script?

It has nothing to do but be visible. With `sandbox: true`, no preload and a static page, it cannot reach Node or IPC, and the content security policy from `index.html` holds without an `unsafe-inline` script. The main process decides when it closes.

### What if the main window never becomes ready?

`createWindow` rejects, `reportWindowError` logs the error through `electron-log`, destroys the main window and closes the splash, and `app.quit()` runs as it does today. There is no timeout in this change; the pull request notes where one would go if the team wants it.

### Does the splash show in development too?

Yes. `resolveHtmlPath` points at the Vite dev server when `ELECTRON_RENDERER_URL` is set and at the built file otherwise, and the second Rollup input makes `splash.html` available in both, so `npm start` and the packaged app behave the same.

### Will the smoke test keep passing?

The smoke test lists page targets over the remote debugging port and picks the main window's. The agent reads that predicate and runs the smoke test under `xvfb-run` before it pushes, so a second target that changed the pick would show in the run.

## More Electron jobs

- [Add a System Tray Icon to an Electron App](https://getrush.ai/run/add-tray-icon/electron/)
- [Fix a Failing CI Run for an Electron App](https://getrush.ai/run/fix-failing-ci/electron/)
- [Turn Sentry Errors Into Fix Pull Requests for an Electron App](https://getrush.ai/run/fix-sentry-errors/electron/)

## The same job on other stacks

- [Add a Native Splash Screen to a Flutter App](https://getrush.ai/run/add-splash-screen/flutter/)

## More jobs like this: Hand off a long task

- [Add SpotBugs to a Maven Build](https://getrush.ai/run/add-spotbugs/maven/)
- [Add SQLFluff Linting to a dbt Project](https://getrush.ai/run/add-sqlfluff-linting/dbt/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
