Build A Desktop App With Electron SPA

Jan 18, 2026 by Editorial Team 38 views

Electron SPA Shell: Desktop Packaging, Secure Preload Bridge, and Popout Entrypoint

Hey everyone, let's dive into creating a desktop application using Electron for our SPA (Single Page Application). We'll be focusing on packaging, ensuring security with a preload bridge, and making it popout-capable. This guide breaks down the process, making it easy to follow along. So, let's get started, guys!

Feature Request: Packaging AutoArt as an Electron App

The Goal: Electron-Delivered SPA

Alright, imagine we want to package our AutoArt application as an Electron-delivered SPA. The key here is a clear separation between the UI and the core engines. Think of it like this: on one side, we have our UI surfaces – Mail, Calendar, Gantt, Collector, SelectionInspector – all the visual elements. On the other side, we have our core engines: the AutoArt backend and AutoHelper integration. This separation helps keep everything organized and makes it easier to manage and update different parts of the application. It also makes debugging and testing much smoother. We're aiming for a modular design, so changes in one area won't necessarily break another. It’s all about creating a robust, scalable, and maintainable desktop application. The overall goal is to transform our existing React SPA into a fully functional desktop application, leveraging the power of Electron to provide a native desktop experience while keeping our codebase streamlined and efficient.

This approach lets us leverage the existing frontend code while benefiting from Electron's capabilities. This allows us to deliver a desktop app using familiar web technologies and a clear separation between the UI and core backend, simplifying development and maintenance.

Core Engines and UI Surfaces

The separation of concerns is a vital part of this project. UI surfaces, such as the mail, calendar, Gantt, collector, and selection inspector, handle user interaction and presentation. These surfaces display the data and allow users to interact with it. The core engines, including the AutoArt backend and AutoHelper integration, manage the data processing, logic, and integration with other services. This modular architecture makes it easier to update individual components without affecting the entire application. It also promotes code reuse and maintainability, ensuring that changes or additions to specific features don't require reworking the entire system. By clearly defining the responsibilities of each part, we can develop a more robust and scalable application. This approach will also simplify testing and debugging, as issues can be isolated to specific components.

Benefits of Electron for Desktop Applications

Using Electron offers a lot of advantages for desktop app development. We can reuse our existing frontend skills and code base, reduce the learning curve, and make apps that are cross-platform (Windows, macOS, Linux) with minimal code changes. Electron also provides access to native desktop features, such as notifications and system menus. This integration is crucial for creating applications that feel integrated with the user's operating system. Moreover, Electron is supported by a large community, which means it has a lot of resources, libraries, and examples. Electron is perfect for creating modern desktop apps quickly.

Scope: From SPA to Electron App Shell

Implementing the Electron App Shell

Our task is to introduce an Electron app shell comprising the main and preload scripts to load our existing React SPA. This shell will act as the foundation for our desktop application, managing the window creation, security settings, and communication between the frontend and the backend. The Electron app shell will ensure that our SPA runs smoothly within a desktop environment. This is more than just wrapping the web app in a desktop container; it is about providing the full functionality that users expect from a native desktop application. The implementation of the app shell ensures that the SPA loads correctly in an Electron BrowserWindow and that the necessary security configurations are in place to protect the app.

Development Workflow and Production Packaging

We'll set up a development workflow that combines Electron with Vite. This combination allows for fast development cycles. Vite's hot module replacement (HMR) will enable rapid iteration and testing. For production, we'll create packaging scripts that build the app into an installable format. The packaging process transforms our application into an installable format for different operating systems (Windows, macOS, and Linux). It includes creating executable files, setting up necessary dependencies, and configuring app icons. By integrating Vite, we ensure a smooth development and production process, making it easier to build, test, and deploy our desktop application.

We'll cover how to get the SPA running inside Electron, ensuring secure communication between the frontend and backend using a preload bridge, and packaging everything up for distribution. This process will involve setting up development environments, writing code for the Electron app shell, integrating the Vite development server, and building the final application package. By the end, we'll have a fully functional desktop application ready for use.

Requirements: Ensuring Security and Functionality

Loading the SPA in Electron BrowserWindow

The SPA must load within an Electron BrowserWindow. This is our primary display container for the application. Electron's BrowserWindow offers a way to embed web content within a native application window. The setup involves initializing an Electron app, creating the BrowserWindow, and loading the URL of our SPA. We will handle things like window size, position, and any custom options. Making sure the SPA loads and runs smoothly in this environment is a crucial first step. We need to correctly configure the BrowserWindow, so the application displays correctly and functions as expected within a desktop environment.

Security Defaults

For security, we'll implement these settings:

contextIsolation: true: This enables the context isolation, which separates the renderer process (where our SPA runs) from the Electron's main process. This prevents the renderer process from directly accessing the Node.js APIs, adding an extra layer of security.
nodeIntegration: false: This disables Node.js integration in the renderer process. Doing this stops the renderer process from using require() to access Node.js modules directly. This limits the potential attack surface. By default, Electron apps often have Node.js integration enabled, which can expose vulnerabilities if the renderer process is compromised. Disabling it is a crucial step towards creating a more secure application.
IPC Exposed via Preload Bridge: IPC (Inter-Process Communication) will be exposed through a preload bridge. The preload script serves as an intermediary between the renderer and the main processes. It allows the renderer process to securely communicate with the main process using a well-defined API. The preload bridge handles all IPC communications, making sure that sensitive data remains protected. It's a key component in securing our application, especially when using Node.js modules.

These defaults are essential for securing our application, preventing potential security vulnerabilities.

The App Shell Entrypoint

We'll make the app shell act as a single entry point for our application, capable of rendering in two modes:

Normal Mode: The full workspace is displayed.
Popout Mode: A single panel surface pops out.

This setup allows users to switch between the standard and popout views. The single entry point simplifies the app structure and makes the application more flexible and adaptable. Handling normal and popout modes through a single entry point ensures that our application is consistent and easy to manage.

Tasks: Setting Up the App

Adding the Electron Directory

We'll create an /electron (or /apps/desktop) directory that will contain:

main.ts: This file handles window creation and all the essential Electron application logic. It manages the Electron app lifecycle and creates and manages the main window.
preload.ts: This file will create the IPC bridge to securely expose functionality to the renderer process. The preload script securely exposes functionality from the main process to the renderer process, such as system calls or access to native features, by providing a controlled API.
Dev/Prod URL handling: This script takes care of switching between the development server's URL and the production build's URL. The configuration makes it easier to test the application in different environments.

These components are fundamental for our Electron application. The main script manages Electron's lifecycle and windows. The preload script is used for secure communication. The configuration ensures that the app loads the correct content during development and in production.

Integrating Vite Dev Server

Next, we'll integrate the Vite dev server with Electron for a streamlined developer experience (DX). This will enable rapid development cycles with hot-module replacement and quick feedback. This setup makes development much more efficient, allowing developers to see the changes instantly. With Vite, our application will rebuild automatically whenever we change the source code, making the development process quicker and more efficient.

Adding Build Scripts for Packaging

Then, we'll set up build scripts for packaging. These scripts use tools like electron-builder to bundle the application into installable packages for different operating systems. These steps produce installable artifacts for various platforms like Windows, macOS, and Linux. The packaging scripts will handle all the necessary steps, ensuring the final application is ready for deployment.

Defining the Window Launch Protocol

We'll define a window launch protocol for popouts using query parameters or a hash route. This will allow the application to open specific panels in a separate window. We'll use either query parameters or hash routes to pass the necessary information, such as the panel's configuration or the data it needs to display. This functionality allows the user to display parts of the application in separate windows, enhancing the user experience.

Acceptance Criteria: What Success Looks Like

Running the Application in Development

When we run npm run dev (or a similar command), it should start Electron and load our SPA. This means we can develop and test our application using a familiar development workflow. The npm run dev command is the main entry point for the development process. The application must run in a desktop environment, where we can test the features and fix any bugs. It will verify that all components are working as designed. The ability to launch the application with a single command makes it easy to test changes and ensures that everything is working as expected.

Producing Installable Artifacts

Running npm run build should generate an installable artifact. This means we can build packages for different operating systems. This step transforms our application into an installable format that users can download and run on their desktop. The build process creates packages ready for distribution. Successfully building an installable artifact is crucial for the deployment of the application. Once built, the artifact can be distributed to users for installation on their respective operating systems. This process ensures that the desktop app is ready for deployment.

Opening the SPA in Normal and Popout Modes

Finally, the SPA should open in both normal and popout modes. This is a critical functionality check. It makes sure that the application works as intended and that the popout feature is functional. This validates that all the configuration and implementation steps are successful. This part is about verifying the key functionalities of the application. Successfully opening the SPA in both modes confirms that the application is running correctly and that its primary features are fully functional. This is the final validation before release.

By following these steps, you'll successfully build a desktop application using Electron for your SPA, leveraging the power of modern web technologies to create a native-like experience. Good luck, and happy coding, everyone!