Native Desktop Template: React + C++

A production-oriented starter for small, fast, cross-platform desktop applications. Build the UI with React and TypeScript, keep privileged or compute-intensive work in C++17, and render everything inside the operating system's webview.

No Electron runtime. No bundled Chromium. No localhost server in production.

Why this stack?

• Native-sized distribution: the application reuses WKWebView on macOS, WebView2 on Windows, and WebKitGTK on Linux.
• A familiar frontend: React 19, strict TypeScript, Vite, Vitest, and a Feature-Sliced Design directory structure.
• A real native backend: C++ owns file dialogs, filesystem access, operating system integrations, and background work.
• A stable boundary: one typed, Promise-based RPC bridge keeps React independent from the host implementation.
• Native window behavior: integrated title bars, native caption buttons, resizing, and a draggable top region are configured on all three platforms; macOS also receives the standard application menu and keyboard shortcuts.
• One-source application branding: replace one PNG and generate the native macOS, Windows, and Linux icons plus matching installer artwork with a single command.
• Polished installers: a drag-to-Applications DMG, branded NSIS/WiX artwork, Linux software-center metadata, and SHA-256 checksums are configured by default.
• Reproducible delivery: CMake presets, CPack, packaging scripts, Dependabot, and a macOS/Windows/Linux GitHub Actions matrix are included.

This is a focused alternative to Electron, not a browser compatibility layer. System webviews can differ between operating systems, and features such as automatic updates, code signing, notarization, and crash reporting still need product-specific configuration.

Create an application

Prerequisites for the generator are Python 3.9+ and Git. The generated application also needs Node.js 22+, CMake 3.24+, and the platform toolchain listed below.

git clone https://github.com/legal-machines/react-cpp-desktop.git
cd react-cpp-desktop

python3 create-project.py ../matter-desk \
  --name "Matter Desk" \
  --bundle-id com.example.matterdesk \
  --vendor "Example Studio" \
  --contact "maintainers@example.com" \
  --description "A focused desktop workspace"

cd ../matter-desk
npm --prefix frontend install
python3 scripts/dev.py

The generator derives a slug and C++ namespace, renders application metadata, creates a clean main branch, and refuses to write into a non-empty directory. Run python3 create-project.py --help for every option.

Applications migrating from the historical LM Node Electron preload contract can add --legacy-lm-node-api. This opt-in facade exposes only window.lmNode.platform and window.lmNode.chooseFolder(); new projects receive only the generic window.nativeApp API.

Generated repository

frontend/   React, strict TypeScript, Vite, Vitest, FSD layers
backend/    C++17 host, RPC registry, bounded worker pool, platform code
deploy/     CPack configuration, platform metadata, release scripts
contracts/  Versioned native API manifest
docs/       Architecture and native-method extension guides
scripts/    One-command development and contract verification

The generated screen intentionally stays small: a centered Hello world! card and a button that exercises the complete React → C++ → native folder-dialog path.

Replace assets/app-icon.png, then run python3 scripts/generate_icons.py to update all application icons and installer artwork. Generated apps prevent page-level rubber-band scrolling and text selection by default; explicit opt-in attributes are documented in their architecture guide.

Native bridge

Frontend code uses a typed API and never sees the internal webview binding:

const folder = await window.nativeApp.chooseFolder();
const runtime = await window.nativeApp.getRuntimeInfo();

const unsubscribe = window.nativeApp.on('backend.ready', payload => {
  console.log(payload.platform, payload.appVersion);
});

Internally, a single __nativeInvoke(method, params) transport routes calls through a C++ registry. Each handler declares an execution policy:

• UiThread for native dialogs and main-thread-only operating system APIs.
• Worker for bounded CPU or I/O work that must not freeze the UI.

The raw transport is removed from window after initialization, the public API is frozen, unknown methods are rejected, external navigation is HTTPS-only, and the production page ships with a Content Security Policy. See the architecture guide for the complete boundary.

Platform requirements

Platform	Toolchain	Runtime webview	Package
macOS 11+	Xcode command-line tools	WKWebView	.dmg
Windows 10/11	Visual Studio 2022 Desktop C++	WebView2 Runtime	NSIS or WiX
Debian/Ubuntu	GCC/Clang, GTK 3, WebKitGTK 4.1	WebKitGTK	.deb

Dependencies are pinned in CMake to webview 0.12.0, nativefiledialog-extended v1.3.0, and nlohmann/json v3.12.0.

Validate the template

python3 -m unittest discover -s tests -v

CI generates a fresh application, builds its frontend and native host, runs tests, and creates the actual package on macOS, Windows, and Linux. The generated project includes the same cross-platform CI matrix.

Project policy

• Contributing
• Security policy
• Code of conduct
• Third-party components

Released under the MIT License.