How-to
Desktop / phone
Make a desktop app with Electron
This recipe ships a WebFluent project as an Electron app: the build runs in a Chromium shipped inside the app, and a page calls a Node.js side for what a browser cannot do — open a folder dialog, read a file on disk, start a process. Nothing in the language changes; a page reaches Node through a plain script under src/, with one typed function per thing it asks for (Call your own JavaScript). For a native side in Rust and the system's own web view instead, see Make a desktop or phone app with Tauri. You need a WebFluent project that builds with wf build, and Node.js with npm. These are the files of an Electron app, beside src/. First, the build settings in webfluent.app.json:
{
"build": { "compress": false },
"meta": { "sitemap": false }
}
Install Electron and electron-builder in the project's folder:
$ npm init -y
$ npm install --save-dev electron electron-builder
Point package.json at the main process, and add the scripts that run and package the app:
{
"main": "electron/main.js",
"scripts": {
"start": "electron .",
"dist": "wf build && electron-builder"
},
"build": { "files": ["electron/**", "build/**"] }
}
The main process opens the window, serves the build to it, and answers the page's calls:
// electron/main.js
const { app, BrowserWindow, dialog, ipcMain, net, protocol } = require("electron");
const fs = require("node:fs");
const path = require("node:path");
const { pathToFileURL } = require("node:url");
const BUILD = path.join(__dirname, "..", "build");
// To the page, app://localhost is an ordinary origin: absolute paths,
// fetch and its security policy work as they do on a site.
protocol.registerSchemesAsPrivileged([
{ scheme: "app", privileges: { standard: true, secure: true, supportFetchAPI: true } },
]);
const isFile = (p) => fs.statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
// A file of the build; a route the router draws gets index.html.
function serve(request) {
const file = path.join(BUILD, decodeURIComponent(new URL(request.url).pathname));
const found =
file.startsWith(BUILD + path.sep) &&
([file, path.join(file, "index.html")].find(isFile) ??
(path.extname(file) ? null : path.join(BUILD, "index.html")));
return found
? net.fetch(pathToFileURL(found).href)
: new Response("Not found", { status: 404 });
}
function openWindow() {
const win = new BrowserWindow({
width: 1000,
height: 700,
webPreferences: { preload: path.join(__dirname, "preload.js") },
});
// Packaged, the window shows the build; while you work, `wf serve`.
win.loadURL(app.isPackaged ? "app://localhost/" : "http://localhost:3000/");
}
app.whenReady().then(() => {
protocol.handle("app", serve);
ipcMain.handle("greet", (_event, name) => `Hello, ${name}!`);
ipcMain.handle("start-sync", (event) => {
for (const done of [25, 50, 75, 100]) {
// … a quarter of the work …
event.sender.send("sync-progress", done);
}
});
ipcMain.handle("pick-folder", async (event) => {
const win = BrowserWindow.fromWebContents(event.sender);
const { canceled, filePaths } = await dialog.showOpenDialog(win, {
properties: ["openDirectory"],
});
return canceled ? null : filePaths[0];
});
openWindow();
app.on("activate", () => {
if (BrowserWindow.getAllWindows().length === 0) openWindow();
});
});
app.on("window-all-closed", () => {
if (process.platform !== "darwin") app.quit();
});
The preload script hands the page exactly what it may ask for:
// electron/preload.js
const { contextBridge, ipcRenderer } = require("electron");
const events = ["sync-progress"];
contextBridge.exposeInMainWorld("native", {
greet: (name) => ipcRenderer.invoke("greet", name),
startSync: () => ipcRenderer.invoke("start-sync"),
pickFolder: () => ipcRenderer.invoke("pick-folder"),
onEvent: (name, handler) => {
if (!events.includes(name)) throw new Error(`No event called ${name}`);
const listener = (_event, payload) => handler(payload);
ipcRenderer.on(name, listener);
return () => ipcRenderer.removeListener(name, listener);
},
});
And one script under src/ gives the pages typed names for each call:
// src/native.js — what electron/preload.js exposed, under the names the pages call.
/**
* Whether the page is inside the app, rather than a browser tab.
* @returns {boolean}
*/
function inApp() {
return "native" in window;
}
const outside = () => Promise.reject(new Error("This needs the desktop app."));
/**
* @param {string} name
* @returns {Promise<string>}
*/
function greet(name) {
return inApp() ? window.native.greet(name) : outside();
}
/** Start syncing; how far it has got arrives as `sync-progress`. */
function startSync() {
return inApp() ? window.native.startSync() : outside();
}
/**
* Ask for a folder; `null` when the reader cancels.
* @returns {Promise<?string>}
*/
function pickFolder() {
return inApp() ? window.native.pickFolder() : Promise.resolve(null);
}
/**
* Hear an event the native side emits, until the function it returns is called.
* @param {string} name
* @param {(payload: number) => void} handler
* @returns {() => void}
*/
function onEvent(name, handler) {
return inApp() ? window.native.onEvent(name, handler) : () => {};
}
How it works
Prepare the build for a desktop
The same project builds for the web and for a desktop. Two keys in webfluent.app.json, and one to leave out, drop what only a website needs:
build.compress: false— the shell packs the folder into the app, so a.gzfile beside every file would ship every file twice.meta.sitemap: false— writes nositemap.xmlorrobots.txt; nothing crawls an app. You can leavemeta.site_urland the link-preview tags unset too.- Leave
offlineout — the files are already on the machine, so a service worker has nothing to keep.
A single-page build and a static build both work (Static sites and SPAs), and addresses stay as they are. The main process answers a path the build has no file for with index.html, so reloading the window on /settings shows the settings page.
An app is often used with no network, and a font named in meta.fonts comes from another origin. To make a font always available, put the file in public/ and declare it with @font-face in a .css file under src/ (Styling).
Set up Electron
npm init -ywrites apackage.json, andnpm installadds Electron and electron-builder to it as development dependencies.- Electron's two files go in a folder called
electron/. Do not put them undersrc/: every.jsfile undersrc/is linked into the pages, and these files run in Node, outside the pages. "main"inpackage.jsonpoints Electron at the main process, andnpm startrunselectron ..- The main process opens the window and serves the build to it. A
file://address would break the build's absolute addresses (there,/app.jsis the root of the disk), so the build is served from anapp://origin of its own.protocol.handle("app", serve)answers each request with the file ofbuild/it names, the folder'sindex.html, or — for a path with no extension, a route the router draws —build/index.html. Packaged, the window loadsapp://localhost/; while you work,http://localhost:3000/.
Call Node from a page
A page has no Node in it. The preload script runs beside the page and hands it exactly what it may ask for: one function per channel, never ipcRenderer itself. Each ipcMain.handle in the main process answers one channel: greet returns a value, start-sync reports its progress as sync-progress events, and pick-folder opens the system's folder dialog. onEvent lets a page hear only the events the preload script lists.
src/native.js takes the place of the three scripts of the Tauri recipe. It keeps their names, so the Hello, Sync and Library pages of Make a desktop or phone app with Tauri run in Electron without a change. inApp() is false in a browser tab — wf serve opened in a browser, wf test, wf verify — and each function answers there instead of throwing, so every page still loads.
Run the Electron app while you work
Run the dev server and the app in two terminals. In the first:
$ wf serve
In the second:
$ npm start
Saving a .wf file rebuilds and reloads the window. A change under electron/ needs the app restarted.
The page's security policy needs nothing added: app://localhost is the page's own origin, as http://localhost:3000 is while you work.
Package the Electron app
Electron Forge and electron-builder both package an app from package.json. Whichever you use, run wf build first, and make sure the package holds electron/ and build/; src/ is not needed at run time. With electron-builder, npm run dist does both: its dist script runs wf build, then electron-builder, and build.files names the two folders the package holds.
Troubleshooting
| What you see | What to check |
|---|---|
|
Every native call fails with |
The page is open in a browser tab, not the app |
| A packaged Electron app shows an empty window |
The package is missing |
| The app's text falls back to another font offline |
The font comes from |