# Neutralinojs — Lightweight Cross-Platform Desktop Apps

> Build desktop applications with HTML, CSS, and JavaScript using a tiny native runtime instead of bundling Chromium.

## Install

Save in your project root:

# Neutralinojs — Lightweight Cross-Platform Desktop Apps

## Quick Use
```bash
npm i -g @neutralinojs/neu
neu create my-app
cd my-app
neu run    # launch dev window
neu build  # produce binaries for all platforms
```

## Introduction
Neutralinojs lets you build cross-platform desktop applications using standard web technologies while keeping the binary size under 5 MB. Instead of shipping Chromium, it talks to the operating system's native webview, producing dramatically smaller and faster apps than Electron.

## What Neutralinojs Does
- Provides a lightweight runtime that uses the OS-native webview (WebKitGTK, Cocoa WKWebView, or Edge WebView2)
- Exposes file system, OS shell, clipboard, and window APIs through a JavaScript client library
- Produces self-contained binaries for Windows, macOS, and Linux from a single codebase
- Supports a hot-reload development workflow with the `neu run` command
- Offers both window and Chrome mode (opens in the default browser) for flexible UI rendering

## Architecture Overview
The Neutralinojs runtime is a small C++ binary that starts an HTTP server on localhost and opens the OS webview pointed at it. The frontend communicates with the runtime over WebSockets using a JSON-RPC protocol. Native operations (file I/O, process spawning, system info) are handled by the C++ backend and exposed as async JavaScript functions via the `Neutralino` global object. Extensions allow running background processes in any language that speaks the same WebSocket protocol.

## Self-Hosting & Configuration
- Install the CLI globally: `npm i -g @neutralinojs/neu`
- Configure app metadata, permissions, and window settings in `neutralino.config.json`
- Use `neu update` to download the latest runtime binaries
- Enable only the native APIs your app needs via the `nativeAllowList` setting
- Build for all three platforms at once with `neu build` (cross-compilation from any host)

## Key Features
- Sub-5 MB binary size versus 150+ MB for Electron apps
- OS-native webview eliminates Chromium overhead and memory bloat
- Secure permission model — APIs are opt-in via an allowlist
- Extension system for running backend processes in Node.js, Python, or any language
- Hot-reload development with automatic frontend refresh

## Comparison with Similar Tools
- **Electron** — bundles Chromium for full browser compatibility but produces large binaries and high RAM usage
- **Tauri** — Rust-based, also uses native webview; richer API surface but requires Rust toolchain
- **Wails** — Go backend with native webview; best when backend logic is written in Go
- **NW.js** — Chromium-based like Electron; similar size and memory tradeoffs
- **Progressive Web Apps** — no installation needed but limited access to native OS APIs

## FAQ
**Q: Does Neutralinojs support React, Vue, or Svelte?**
A: Yes. Any frontend framework that outputs HTML/CSS/JS works. Point the framework build output to the Neutralinojs resources directory.

**Q: How small are the output binaries?**
A: Typically 2-5 MB for the runtime plus your frontend assets, compared to 150+ MB for Electron.

**Q: Can I access the file system and run shell commands?**
A: Yes. The `Neutralino.filesystem` and `Neutralino.os` APIs provide full access, gated by the config allowlist.

**Q: Is there a way to run backend code?**
A: Yes. The extensions API lets you spawn a sidecar process (Node.js, Python, etc.) that communicates with the frontend via WebSockets.

## Sources
- https://github.com/neutralinojs/neutralinojs
- https://neutralino.js.org/docs

---
Source: https://tokrepo.com/en/workflows/9508a25d-4211-11f1-9bc6-00163e2b0d79
Author: AI Open Source