{"id":13112,"library":"electron-next","title":"Integrate Next.js with Electron","description":"electron-next is a utility package designed to seamlessly integrate Next.js into Electron applications, primarily for powering the renderer process. It handles both development and production workflows, ensuring that Next.js bundles are correctly served within Electron's file:// protocol environment in production, and managing the development server in development. The current stable version is 3.1.5. Based on recent activity, the package has a moderate release cadence, focusing on patches, dependency upgrades, and minor features rather than major breaking changes. Its key differentiator is simplifying the often-complex setup of using a modern web framework like Next.js within a desktop application shell, abstracting away much of the configuration required for renderer process bundling and serving.","status":"active","version":"3.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/leo/electron-next","tags":["javascript","electron","next","electron.js","next.js"],"install":[{"cmd":"npm install electron-next","lang":"bash","label":"npm"},{"cmd":"yarn add electron-next","lang":"bash","label":"yarn"},{"cmd":"pnpm add electron-next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the host application framework for desktop applications.","package":"electron","optional":false},{"reason":"The web framework electron-next integrates for the renderer process.","package":"next","optional":false}],"imports":[{"note":"The package primarily uses CommonJS exports; direct ESM import syntax without a build step may not work as expected in all environments.","wrong":"import prepareRenderer from 'electron-next'","symbol":"prepareRenderer","correct":"const prepareRenderer = require('electron-next')"},{"note":"The main export is a function assigned directly to `module.exports`, not a named export from a module. Use the CommonJS default import pattern.","wrong":"import { prepareRenderer } from 'electron-next'","symbol":"prepareRenderer (named)","correct":"const prepareRenderer = require('electron-next')"}],"quickstart":{"code":"const prepareRenderer = require('electron-next');\nconst { app, BrowserWindow } = require('electron');\nconst path = require('path');\n\nconst PORT = process.env.ELECTRON_NEXT_PORT ? parseInt(process.env.ELECTRON_NEXT_PORT, 10) : 8000;\nconst RENDERER_PATH = path.join(__dirname, 'renderer'); // Adjust if your Next.js app is elsewhere\n\nasync function createWindow () {\n  // Prepare the Next.js renderer process\n  await prepareRenderer(RENDERER_PATH, PORT);\n  \n  const win = new BrowserWindow({\n    width: 800,\n    height: 600,\n    webPreferences: {\n      nodeIntegration: true, // Be cautious with nodeIntegration, consider contextBridge for security\n      contextIsolation: false // For simplicity, but consider true with preload scripts\n    }\n  });\n\n  // Load the Next.js app\n  if (process.env.NODE_ENV === 'development') {\n    // In development, load from the Next.js development server\n    await win.loadURL(`http://localhost:${PORT}`);\n  } else {\n    // In production, load the static 'out' directory generated by 'next export'\n    await win.loadFile(path.join(RENDERER_PATH, 'out', 'index.html'));\n  }\n}\n\n// Electron app lifecycle events\napp.whenReady().then(createWindow);\n\napp.on('window-all-closed', () => {\n  if (process.platform !== 'darwin') {\n    app.quit();\n  }\n});\n\napp.on('activate', () => {\n  if (BrowserWindow.getAllWindows().length === 0) {\n    createWindow();\n  }\n});","lang":"javascript","description":"This code demonstrates the basic setup for an Electron application using electron-next. It initializes the Next.js renderer, creates an Electron window, and correctly loads the Next.js application based on the `NODE_ENV` (development server or production build)."},"warnings":[{"fix":"Ensure `electron` and `next` are listed in your project's `package.json` dependencies and installed (e.g., `npm install electron next` or `yarn add electron next`).","message":"As of version 3.0.4, `electron-next` no longer uses `peerDependencies`. Users must explicitly install `electron` and `next` in their project's `dependencies`.","severity":"gotcha","affected_versions":">=3.0.4"},{"fix":"Pass a specific, unused port number as the second argument to `prepareRenderer(path, myCustomPort)` or set `process.env.ELECTRON_NEXT_PORT`.","message":"When initializing `prepareRenderer`, the `port` argument defaults to `8000`. If this port is already in use, the Next.js development server will fail to start.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade to `electron-next@3.1.1` or newer to ensure full compatibility and stability on Windows operating systems.","message":"Versions prior to 3.1.1 had known issues running on Windows, potentially causing application failures or unexpected behavior.","severity":"gotcha","affected_versions":"<3.1.1"},{"fix":"Upgrade to `electron-next@3.1.2` or newer. If stuck on an older version, avoid spaces in your application's directory or name.","message":"Versions prior to 3.1.2 did not properly handle spaces in the application name, which could lead to build or runtime errors.","severity":"gotcha","affected_versions":"<3.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install electron-next` or `yarn add electron-next` in your project's root directory.","cause":"The `electron-next` package has not been installed or is not correctly linked in the project.","error":"Error: Cannot find module 'electron-next'"},{"fix":"Specify an alternative port for `prepareRenderer` (e.g., `await prepareRenderer(path, 8001)`) or ensure no other applications are using port 8000.","cause":"Another process is already using the default port 8000, preventing the Next.js development server from starting.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"fix":"Ensure you have run `next build && next export` in your Next.js renderer directory and that the `path` argument points to the correct location of your Next.js application.","cause":"In production mode, Electron cannot find the built Next.js application files. This usually means `next export` was not run or the `path` argument to `prepareRenderer` is incorrect.","error":"Error: ENOENT: no such file or directory, stat '/path/to/your/app/renderer/out/index.html'"},{"fix":"For Electron's main process, `require()` is standard. For renderer processes, if `nodeIntegration` is false and `contextIsolation` is true, use a preload script and `contextBridge` to expose Node.js APIs or switch to ESM imports if your project is configured for it.","cause":"Attempting to use `require()` in an Electron renderer process where `nodeIntegration` is disabled and `contextIsolation` is enabled, or attempting to use `import` without proper module configuration.","error":"ReferenceError: require is not defined (in a browser-like context)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}