New to Rust? Grab our free Rust for Beginners eBook Get it free →
Building a Desktop Search App with Electron

Putting a search page in its own desktop window starts with choosing a framework that can run it as an application. Electron lets a JavaScript interface run in a desktop window, with Chromium and Node.js included in the application.
I’ll show you how to create an Electron Forge project and add Google’s Programmable Search Element while keeping Node.js APIs out of the search page.
TL;DR
Electron combines Chromium and Node.js so a JavaScript project can run in a desktop window. Use an Electron Forge starter, keep privileged APIs out of the renderer, and load Google’s Programmable Search Element with your engine ID.
- Electron’s main process creates windows, and renderer processes display HTML.
- Use a narrow preload API with context isolation instead of enabling Node.js in page code.
- Google’s embed requires your own Programmable Search Engine ID, not the old tutorial’s public-looking value.
- Use Electron Forge to start, package and distribute the project.
What is an Electron desktop application?
Electron lets a JavaScript, HTML and CSS interface run in a desktop window with Chromium and Node.js as part of the application. In this example, a local HTML page hosts Google’s search widget, while the engine configuration and results come from Google.
The main process manages the application lifecycle and creates BrowserWindow instances. A renderer process handles each window’s page.
Electron can target several desktop operating systems, but native dependencies and permissions still need review for the targets you choose.
| Requirement | What Electron provides | What you still need to do |
|---|---|---|
| Desktop integration | Use main-process and Electron APIs for selected native capabilities. | Choose which desktop actions belong in the app. |
| Search experience | Display the configured Google search element in the app window. | Maintain network access and configure the engine outside the app. |
Electron’s open-source code can be inspected and adapted. Application maintainers still need to review their dependencies and licensing choices.
Choose Electron when desktop distribution or feature integration is a requirement, and weigh the release work if a browser tab already solves the task.
Electron’s APIs can add native behavior such as a menu or notifications. Each added capability brings code to maintain, so reserve extensions for features the desktop task needs.
| Release check | What to verify | Why it matters |
|---|---|---|
| End-user setup | Install the Forge artifact on a clean account without Node.js or npm. | Development files can hide missing package resources. |
| Supported targets | List tested OS versions and architectures, then label each download. | Framework reach does not guarantee every app configuration works. |
| Keyboard use | Check visible focus and a usable tab order. | HTML does not make desktop interaction accessible by default. |
| Assistive technology | Check control labels and screen-reader output. | People need to identify and operate the search controls. |
| Text scaling | Test the interface at larger text sizes. | The app window should remain usable when text is enlarged. |
Electron packages Chromium and Node.js with the application, so end users do not need separate installs. An upgrade changes that bundled runtime, so test it with the app’s dependencies before releasing a stable build.
How to build a desktop search app with Electron
Use the Electron Forge starter because it generates a project with development and packaging configuration. Avoid copying an Electron 0.x setup.
Step 1: Create an Electron Forge project
Install a supported Node.js release and Git first. In a terminal, create the starter with npm’s package runner. The command prompts to install the generator if needed and creates the project directory.
npx create-electron-app@latest desktop-search
Move into the generated directory and start the app using its package script. The starter provides the initial main process and renderer files. Keep the generated package metadata and scripts unless you have a reason to change them.
cd desktop-search
npm start
A window opening confirms the starter can launch, not that search is configured. Stop the development process before editing files, then locate the entry-point files in the generated template. Forge templates can organize their source differently, so use the paths in your project rather than copying a guessed path.
Step 2: Create a Programmable Search Engine
Open Google’s Programmable Search Engine control panel and create an engine for the sites it should search. Copy its identifier, called cx in Google’s embed URL. Do not reuse an ID from an unrelated tutorial because it is tied to a specific engine.
The engine’s site-selection rule determines which pages can match. Before adding the ID to the app, use the control panel’s preview to confirm that a query from the intended scope returns the expected type of result.
Google’s Programmable Search Element renders a combined search box and results region, loading its JavaScript asynchronously from Google’s cse.google.com host.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Desktop Search</title>
<script async src="https://cse.google.com/cse.js?cx=YOUR_ENGINE_ID"></script>
</head>
<body>
<main>
<h1>Search</h1>
<div class="gcse-search"></div>
</main>
</body>
</html>
Replace YOUR_ENGINE_ID with the value from your engine settings before starting the app. Google’s widget controls its result layout, so check the rendered page at the window size you intend to support.
Step 3: Load the local page in a secured window
The main process creates a BrowserWindow after Electron is ready. Keep Node integration disabled in the renderer and context isolation enabled. A local page that loads Google’s script remains a web renderer, so it should not receive unrestricted Node APIs.
const { app, BrowserWindow } = require('electron');
const path = require('node:path');
function createWindow() {
const win = new BrowserWindow({
width: 900,
height: 700,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
nodeIntegration: false,
contextIsolation: true,
sandbox: true
}
});
win.loadFile(path.join(__dirname, 'index.html'));
}
app.whenReady().then(() => {
createWindow();
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
});
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit();
});
This is the window-lifecycle core, not a replacement for the Forge starter’s configuration. Keep its existing entry point and adapt the function to the generated project.
The path.join call resolves index.html beside the main-process file rather than from the shell’s current directory. Keep preload.js in the matching location, or update both paths to match the generated template. If the window reports a load error, check these local files before investigating the remote search script.
On macOS, closing the last window usually leaves the application running. The activate handler creates a window when the user returns.
Step 4: Keep the preload bridge narrow
The example exposes a value through contextBridge to show a limited API, although the search page itself needs no privileged bridge.
const { contextBridge } = require('electron');
contextBridge.exposeInMainWorld('desktop', {
appName: 'Desktop Search'
});
The renderer can read the exposed value as window.desktop.appName. When a later feature accepts input, validate that input in the main process before acting on an IPC message.
Step 5: Run and package the app
Set your engine ID, then launch the project from its root. Search for a phrase that should match your configured sites and confirm the box renders and results load with a network connection.
npm start
When the development build behaves as expected, use the generated Forge make script to build platform-specific output. Its configured makers determine which artifact gets created.
npm run make
Install the artifact on a clean test account. Check first launch and window behavior. Confirm search works with an internet connection, then review the maker’s signing and distribution requirements.
The make step creates artifacts but does not establish an update channel. Configure a separate updater for in-app releases, or document where users can download later versions.
What should you check before sharing the app?
Before sharing a package, verify its engine configuration, renderer settings and behavior on the intended target.
| Check | What to verify | Why it matters |
|---|---|---|
| Engine ID | Replace the placeholder with your configured cx value. | The embed cannot identify your search engine without it. |
| Connectivity | Load the app with internet access and test a query. | The search script and results are served by Google. |
| Renderer settings | Keep Node integration off and context isolation on. | Page scripts should not inherit direct access to desktop APIs. |
| Distribution | Test the maker output on each target operating system. | Packaging is platform-specific and is separate from development launch. |
| Navigation and permissions | Review which links and system requests the app allows. | Unplanned navigation or permissions can expose functionality the app does not need. |
Use Electron’s security checklist to set a restrictive Content Security Policy (CSP) instead of a broad wildcard. If the policy blocks Google’s script, inspect the developer console and allow only the required resource origins.
Troubleshooting Electron search setup
Use the symptom to find the failing layer before changing security settings. This table separates engine configuration, network, renderer and packaging problems.
| Case | Symptom | Fix |
|---|---|---|
| Engine ID is missing or wrong | The search region is blank or the embed reports an engine error. | Check the cx value against the engine settings and confirm cse.js loads in the developer tools Network panel. |
| Engine scope excludes the query | The widget appears, but expected pages do not match. | Review the sites or whole-web setting in the Programmable Search Engine control panel. |
| No network connection | The local window opens, but the search service cannot return results. | Restore connectivity, then reload the page. This sample does not provide offline search. |
| Node module is unavailable in page code | Renderer JavaScript cannot import a Node.js module. | Put the required operation behind a named preload API. |
| Window does not return on macOS | Closing the last window leaves the application active with no window. | Use the activate event to create a BrowserWindow when none remain. |
| Forge make command fails | No distributable is created or the build stops with an error. | Read the first packaging error, check installed dependencies and confirm the configured maker supports the target. |
Conclusion
This example keeps the desktop shell small and the search integration explicit. Before adding features, check the Electron process model, the Electron security guide and Google’s Programmable Search Element documentation.
If you are packaging an existing Express project, CodeForGeek’s guide to converting an Express app into an Electron desktop app covers that starting point. For another desktop-framework route, see the site’s Node-Webkit desktop application tutorial and verify its APIs against that project’s documentation.
FAQ
Use these answers to check the engine configuration and runtime assumptions for this sample.
Can Electron run a Google search app offline?
No. The desktop window can open local files, but the Programmable Search Element and its results are served online by Google.
Where do I get the Google search engine ID?
Create or configure an engine in Google’s Programmable Search Engine control panel, then use its engine identifier as the cx parameter in the embed script URL.
Should I enable Node integration in the search page?
No. Keep Node integration disabled and context isolation enabled. Use a narrow preload API only when the interface needs a specific desktop capability.
How do I package an Electron app?
Electron Forge provides a make script for creating platform-specific distributables. Test the generated output on every operating system you plan to support.




