Electron and Next.js 13.4 Integration: A Practical Guide to Building Desktop Applications

This tutorial is designed to address the challenge of lacking ready-made boilerplate in Electron integration with Next.js 13.4. The article explains in detail how to achieve the collaboration between the two through manual configuration, including migrating back-end services to the Electron main process, utilizing the Context API for inter-process communication, using electron-serve to implement client routing, and provides critical package.json scripts and next.config.js configuration examples. In addition, the potential compatibility issues of Next.js App Router in this integration are highlighted and it is recommended to prioritize Pages Router.

Challenges and core ideas

Integrating Next.js 13.4 in Electron desktop applications, the main challenge is the lack of mature boilerplate projects that directly support this combination. This makes it necessary for developers to make a lot of manual configuration. Unlike the Next.js API routing processing backend services in traditional web applications, in the Electron environment, we must transfer all backend services (such as CRUD operations and event processing) to the main process of Electron to execute. Data exchange and communication between the rendering process (i.e. Next.js application) and the main process should be used to build a bridge through the inter-process communication (IPC) mechanism provided by Electron, such as using the Context API. In order to implement a React Router-like client routing experience in Next.js front-end applications, the electron-serve npm package can be used.

Project structure suggestions

In order to clearly separate the code of Electron and Next.js, it is recommended to use the following directory structure:

 rootdir/
├──app/ # Store Next.js front-end application code└── main/ # Store Electron main process code

Configuration development and build scripts

In order to run Next.js and Electron at the same time during development and facilitate subsequent packaging and release, we need to configure the corresponding scripts in package.json. Concurrently execution of multiple commands can be easily implemented using the concurrently tool, which is especially useful during debugging.

 {
  "name": "electron-nextjs-app",
  "version": "1.0.0",
  "description": "Desktop app with Electron and Next.js",
  "main": "main/index.js", // Electron main process entry file "scripts": {
    "dev": "concurrently -n \"NEXT,ELECTRON\" -c \"yellow,blue\" --kill-others \"next dev app\" \"electron .\"",
    "build": "next build app && electron-builder"
  },
  "dependencies": {
    "electron-serve": "^1.2.0",
    "next": "^13.4.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "concurrently": "^8.2.0",
    "electron": "^26.0.0",
    "electron-builder": "^24.0.0"
  }
}

• dev script :
  • concurrently: Run multiple commands concurrently.
  • -n "NEXT,ELECTRON": Specify a name for each command to facilitate identification of log output.
  • -c "yellow,blue": Specify color for the output of different commands.
  • --kill-others: When one of the processes exits, all other processes are terminated.
  • "next dev app": Start Next.js development server and point to the app directory.
  • "electron .": Start the Electron application, representing the entry file specified in the main field in the package.json in the current directory.
• build script :
  • next build app: Build Next.js front-end application and generate optimized static files.
  • electron-builder: Use the electron-builder tool to package the Electron application.

Next.js configuration

In order for Electron to load and run static files built by Next.js, we need to make specific configurations in next.config.js.

 // app/next.config.js
const nextConfig = {
  // ...Other Next.js configuration output: "export", // Export Next.js application as static HTML, CSS, and JS files images: {
    unoptimized: true // In static export mode, disable Next.js image optimization to avoid problems}
  // ...
};

module.exports = nextConfig;

• output: "export" : This is the key to building Next.js apps as static websites. As a desktop application, Electron needs to load pre-built static resources, rather than relying on Next.js for development or production servers.
• images: { unoptimized: true } : In static export mode, Next.js' default image optimization feature may cause some problems. Disabling it ensures that the image is displayed properly in the Electron environment.

Electron main process configuration example

In the Electron main process, you need to load the static file built by Next.js. The electron-serve library can help us provide these files in a web server-like manner.

 // main/index.js
const { app, BrowserWindow } = require('electron');
const serve = require('electron-serve');
const path = require('path');

const loadURL = serve({ directory: 'app/out' }); // Next.js default output directory is `out`

let mainWindow;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      nodeIntegration: true, // Allows the use of Node.js API in the rendering process (note the security)
      contextIsolation: false, // Disable context isolation (To facilitate Context API communication, it is recommended to enable and use preload scripts in the production environment)
      preload: path.join(__dirname, 'preload.js') // Preload script for secure IPC communication}
  });

  // In development mode, the Next.js development server can be loaded directly // if (process.env.NODE_ENV === 'development') {
  // mainWindow.loadURL('http://localhost:3000');
  // } else {
  // loadURL(mainWindow); // Load static files in production mode// }

  //Use electron-serve to load uniformly, compatible with development and production// Note: In development mode, Next.js dev server runs on port 3000,
  // electron-serve will load from the 'app/out' directory by default.
  // In actual development, you may need to distinguish the loading method according to NODE_ENV.
  // For simplification here, assuming it runs after building.
  loadURL(mainWindow); 

  // Open Developer Tools// mainWindow.webContents.openDevTools();

  mainWindow.on('closed', () => {
    mainWindow = null;
  });
}

app.whenReady().then(createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (mainWindow === null) {
    createWindow();
  }
});

// Example: The main process communicates with the rendering process (safer through preloading scripts)
// app.on('ready', () => {
// // Set the IPC listener here // ipcMain.on('some-event-from-renderer', (event, arg) => {
// console.log(arg); // Print the data sent by the rendering process// event.reply('some-reply-to-renderer', 'Hello from main process!');
// });
// });

In preload.js, a secure IPC communication interface can be exposed to the rendering process:

 // main/preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  sendMessage: (message) => ipcRenderer.send('message-from-renderer', message),
  onReply: (callback) => ipcRenderer.on('reply-from-main', (event, arg) => callback(arg))
});

In the Next.js rendering process, these interfaces can be accessed through the window.electronAPI.

Notes and compatibility

• Next.js App Router Compatibility : The App Router introduced in Next.js 13.4, especially the server components (Server Components), may conflict with Electron's single-page application (SPA) expectations. Server components usually need to be rendered in a Node.js environment, while Electron's rendering process is based on Chromium, which may cause some features to not work properly or require complex adaptations. Therefore, it is recommended to prioritize building Electron applications using Next.js' Pages Router to ensure better compatibility and a simpler development process.
• Inter-process communication (IPC) : Although the original answer mentioned the Context API, in Electron, it is recommended to use the ipcMain and ipcRenderer modules combined with preload scripts (preload.js) for secure inter-process communication. This can avoid directly exposing the Node.js API in the rendering process, thereby improving application security.
• Security : Setting nodeIntegration: true and contextIsolation: false in webPreferences will reduce the security of the application. In production environments, it is strongly recommended to disable nodeIntegration and enable contextIsolation, and then safely expose the necessary APIs through the preload.js script.

Summarize

Combining Electron with Next.js 13.4 to build desktop applications, although there is currently no official ready-made boilerplate, it can be achieved through manual configuration and understanding the working principle of both. The core is to transfer the backend logic to the Electron main process, use the IPC mechanism to achieve inter-process communication, and export the Next.js application as a static file for Electron to load through the output: "export" configuration of next.config.js. At the same time, you need to pay attention to the compatibility issues of Next.js App Router and give priority to Pages Router to simplify development. Following these guidelines, developers can effectively build powerful desktop applications.

The above is the detailed content of Electron and Next.js 13.4 Integration: A Practical Guide to Building Desktop Applications. For more information, please follow other related articles on the PHP Chinese website!