Electron React Boilerplate

To package your application for the local platform you are currently running on, use the package script.

npm run package

Run the following command to start your application in the dev environment. This typically enables features like React Fast Refresh for a smoother development experience.

npm start

To set up a new project using the Electron React Boilerplate, clone the repository and install the dependencies using npm.

If you encounter issues during installation, refer to the debugging guide.

git clone --depth 1 --branch main https://github.com/electron-react-boilerplate/electron-react-boilerplate.git your-project-name
cd your-project-name
npm install

The boilerplate uses a dynamic path resolution strategy to ensure assets (like icons) are found whether the app is running in development mode or is packaged for production.

• In Production: Assets are resolved from process.resourcesPath/assets.
• In Development: Assets are resolved from the local ../../assets directory relative to the compiled main file.

Use the internal getAssetPath helper to retrieve these paths reliably.

const RESOURCES_PATH = app.isPackaged
    ? path.join(process.resourcesPath, 'assets')
    : path.join(__dirname, '../../assets');

const getAssetPath = (...paths: string[]): string => {
    return path.join(RESOURCES_PATH, ...paths);
  };

// Usage example:
// icon: getAssetPath('icon.png')

The renderer process entrypoint (src/renderer/index.tsx) mounts the React application into the DOM element with the ID root. It also demonstrates how to interact with the Electron IPC (Inter-Process Communication) layer via the window.electron object, which is exposed by the preload script.

import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.getElementById('root') as HTMLElement;
const root = createRoot(container);
root.render(<App />);

The main process uses ipcMain to listen for messages sent from the renderer process. You can define custom listeners to handle specific events and reply back to the sender.

In this boilerplate, an example listener is provided for the ipc-example channel. It receives an argument, logs it, and replies with a 'pong' message.

import { ipcMain } from 'electron';

ipcMain.on('ipc-example', async (event, arg) => {
  const msgTemplate = (pingPong: string) => `IPC test: ${pingPong}`;
  console.log(msgTemplate(arg));
  event.reply('ipc-example', msgTemplate('pong'));
});

The application's UI structure and routing are defined in the App component located in src/renderer/App.tsx. It uses react-router-dom with a MemoryRouter to manage navigation within the Electron renderer process. To add new pages or views, you should define new components and register them as Route elements within the Routes component inside App.

import { MemoryRouter as Router, Routes, Route } from 'react-router-dom';

export default function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Hello />} />
        {/* Add new routes here */}
      </Routes>
    </Router>
  );
}

The boilerplate exposes Electron's ipcRenderer through a window.electron object (provided by the preload script). You can use this to listen for one-time events or send messages to the main process.

Available methods shown in the entrypoint:

• window.electron.ipcRenderer.once(channel, callback): Listens for a single occurrence of a specific IPC channel.
• window.electron.ipcRenderer.sendMessage(channel, args): Sends data to a specific IPC channel.

// Listening for a one-time event
window.electron?.ipcRenderer.once('ipc-example', (arg) => {
  console.log(arg);
});

// Sending a message
window.electron?.ipcRenderer.sendMessage('ipc-example', ['ping']);