electron-serve
Static file serving for Electron apps
Normally you would just use win.loadURL('file://…'), but that doesn't work when you're making a single-page web app, which most Electron apps are today, as history.pushState()'ed URLs don't exist on disk. It serves files if they exist, and falls back to index.html if not, which means you can use router modules like react-router, vue-router, etc.
Install
npm install electron-serve
Requires Electron 37 or later.
Usage
import {app, BrowserWindow} from 'electron';
import serve from 'electron-serve';
const loadURL = serve({directory: 'renderer'});
let mainWindow;
(async () => {
await app.whenReady();
mainWindow = new BrowserWindow();
await loadURL(mainWindow);
// Or optionally with search parameters.
await loadURL(mainWindow, {id: 4, foo: 'bar'});
// The above is equivalent to this:
await mainWindow.loadURL('app://-');
// The `-` is just the required hostname
})();
API
loadUrl = serve(options?)
options
Type: object
directory
Type: string
Default: '.'
The directory to serve, relative to the app root directory.
scheme
Type: string
Default: 'app'
Custom scheme. For example, foo results in your directory being available at foo://-.
hostname
Type: string
Default: '-'
Custom hostname.
file
Type: string
Default: 'index'
Custom HTML filename. This gets appended with '.html'.
isCorsEnabled
Type: boolean
Default: true
Whether CORS should be enabled.
Useful for testing purposes.
partition
Type: string
Default: electron.session.defaultSession
The partition where the protocol should be installed, if not using Electron's default partition.
loadUrl(window, searchParameters?)
The serve function returns a loadUrl function, which you use to serve your HTML file in that window.
window
Required
Type: BrowserWindow
The window to load the file in.
searchParameters
Type: object | URLSearchParams
Key value pairs or an URLSearchParams instance to set as the search parameters.
Notes
ES modules support
ES modules (ES2015+ modules) work out of the box. JavaScript files are served with the correct text/javascript MIME type, allowing you to use ES6 import/export syntax:
<script type="module">
import {myFunction} from './my-module.js';
</script>
Source maps support
Source maps are fully supported for debugging. .map files are served with the correct MIME type, enabling Chrome DevTools to load them properly for debugging minified code.
Relative require() paths
Since files are served via a custom protocol, Node.js require() calls with relative paths won't work as expected. Use <script src="..."> tags, bundlers like Webpack, or <script>require('./file.js')</script> instead of <script src="./file.js">.
Multiple windows with different content
To serve different directories or files for different windows, use unique scheme names:
const loadMain = serve({directory: 'main', scheme: 'app'});
const loadSettings = serve({directory: 'settings', scheme: 'settings'});
// Or different files from the same directory
const loadMain = serve({directory: 'dist', file: 'main', scheme: 'main'});
const loadPopup = serve({directory: 'dist', file: 'popup', scheme: 'popup'});
Note: If you are using custom partition in BrowserWindow, it must match the partition in the serve options.
Related
- electron-util - Useful utilities for developing Electron apps and modules
- electron-reloader - Simple auto-reloading for Electron apps during development
- electron-debug - Adds useful debug features to your Electron app
- electron-context-menu - Context menu for your Electron app
- electron-dl - Simplified file downloads for your Electron app
- electron-unhandled - Catch unhandled errors and promise rejections in your Electron app