JavaScript API
import {
build,
createServer,
defineConfig,
ELECTRON_SUPPORT_SNAPSHOT,
inspect,
loadEnv,
mergeRsbuildConfig,
mergeRselectronConfig,
preview,
resolveProjectElectron,
RselectronError,
version,
} from '@rselectron/core';
CLI details: Command Line Interface. Config fields: Configuration.
defineConfig
Adds type hints for your config. Export an object, or a function that switches on command / mode:
rselectron.config.ts
import { defineConfig } from '@rselectron/core';
export default defineConfig({
main: {
root: './src/main',
source: { entry: { index: './index.ts' } },
},
preload: {
root: './src/preload',
source: { entry: { index: './index.ts' } },
},
renderer: {
root: './src/renderer',
source: { entry: { index: './index.ts' } },
},
});
rselectron.config.ts
import { defineConfig } from '@rselectron/core';
export default defineConfig(({ command, mode }) => {
const isDev = command === 'dev';
return {
main: {
root: './src/main',
source: { entry: { index: './index.ts' } },
electron: { watch: isDev },
},
preload: {
root: './src/preload',
source: { entry: { index: './index.ts' } },
},
renderer: {
root: './src/renderer',
source: { entry: { index: './index.ts' } },
},
};
});
The function receives command (dev | build | preview | inspect), mode, and envMode.
createServer
Starts a development session: builds main / preload, starts the renderer dev server, and launches Electron.
import { createServer } from '@rselectron/core';
const server = await createServer({
// cwd: process.cwd(),
// configPath: './rselectron.config.ts',
watch: true, // or { main: true, preload: true }
});
console.log(server.urls); // renderer dev-server URLs
// server.electronProcess — Electron child process
process.on('SIGINT', async () => {
await server.close();
process.exit(0);
});
Common options:
Returns urls, electronProcess, and an idempotent close().
build
Runs a finite production build for configured processes (no watch).
import { build } from '@rselectron/core';
const result = await build({
mode: 'production',
});
console.log(result.roles.main?.paths);
console.log(result.warnings);
await result.close();
Passing watch: true throws; use createServer or rselectron dev --watch for hot reload.
preview
Builds first (unless skipBuild), then launches Electron to preview production outputs.
import { preview } from '@rselectron/core';
const session = await preview({
skipBuild: false,
args: ['--trace-warnings'],
});
session.electronProcess.on('exit', async () => {
await session.close();
});
Returns an optional buildResult, electronProcess, and an idempotent close().
inspect
Resolves configuration without building or launching. For every configured process, inspect exposes three layers:
- normalized — Rselectron configuration after defaults and Electron normalization
- rsbuild — final Rsbuild configuration after presets and merges
- rspack — final Rspack / bundler configurations
Values that originate from sensitive environment variables are redacted in all layers. Human-readable and machine-readable output use the same redacted data model.
import { inspect } from '@rselectron/core';
const result = await inspect({ mode: 'development' });
console.log(result.format('human'));
// or result.format('json')
for (const warning of result.warnings) {
console.warn(`[${warning.code}] ${warning.message}`);
}
loadEnv
Loads environment files. Default prefixes include RSELECTRON_, MAIN_RSELECTRON_, PRELOAD_RSELECTRON_, and RENDERER_RSELECTRON_. Behavior matches CLI --env-mode.
import { defineConfig, loadEnv } from '@rselectron/core';
export default defineConfig(({ mode }) => {
const env = loadEnv({ mode });
return {
main: {
root: './src/main',
source: {
entry: { index: './index.ts' },
define: {
'process.env.APP_NAME': JSON.stringify(
env.parsed.RSELECTRON_APP_NAME,
),
},
},
},
};
});
More on prefixes: Environment.
mergeRselectronConfig / mergeRsbuildConfig
Merge multiple Rselectron configs (including per-process electron fields). mergeRsbuildConfig is re-exported from @rsbuild/core.
import { defineConfig, mergeRselectronConfig } from '@rselectron/core';
import { shared } from './rselectron.shared';
export default defineConfig(
mergeRselectronConfig(shared, {
renderer: {
root: './src/renderer',
source: { entry: { index: './index.ts' } },
},
}),
);
resolveProjectElectron / ELECTRON_SUPPORT_SNAPSHOT / version
import {
ELECTRON_SUPPORT_SNAPSHOT,
resolveProjectElectron,
version,
} from '@rselectron/core';
console.log(version);
console.log(ELECTRON_SUPPORT_SNAPSHOT);
// { majors: [28, …, 43], peerRange: '>=28 <44', ... }
const electron = resolveProjectElectron(process.cwd());
console.log(electron.version, electron.execPath, electron.major);
Missing project-local Electron, or a version outside the supported range, throws a RselectronError with a stable code.
RselectronError
Structured failures with a stable code and optional hint.
import { build, RselectronError } from '@rselectron/core';
try {
await build();
} catch (error) {
if (error instanceof RselectronError) {
console.error(error.code, error.message, error.hint);
}
throw error;
}
Node module shapes
In TypeScript, pull in ambient declarations with:
/// <reference types="@rselectron/core/node" />
Dev-server URL
During dev, the main process can read the renderer URL from the environment:
const url = process.env.RSELECTRON_RENDERER_URL;
Assets and workers
import icon from '../assets/icon.png?asset';
import unpack from '../assets/helper.bin?asset&asarUnpack';
import workerPath from './worker?modulePath';
import createWorker from './worker?nodeWorker';
import loadWasm from './add.wasm?loader';
import addon from './native.node';
import { Worker } from 'node:worker_threads';
new Worker(workerPath);
createWorker({ workerData: 'hello' });
await loadWasm();
