Lune

Build native desktop apps with Crystal and a web frontend.

Lune wraps a native WebView and lets you call Crystal code from JavaScript over a typed bridge — no servers, no IPC boilerplate. Think Wails or Tauri, but for Crystal.

v0.x notice: Both the library and CLI APIs may change before 1.0. If you use this now, expect occasional breaking changes.

Experimental Crystal flags: Lune requires -Dpreview_mt -Dexecution_context at compile time. The lune CLI passes these automatically. If you compile your app manually (crystal build), you must include both flags. These unlock Crystal's multi-threading execution context API — the mechanism Lune uses to run async: bindings on real OS threads without blocking the native GUI event loop.

Documentation

Full docs live at the project website folder

• visit Lune Docs, or
• run npm run docs:dev locally from the repo (also, make web)

Quick start

lune init my_app                  # vanilla JS + Vite
lune init my_app --template vue   # Vue 3 + Vite
cd my_app
lune dev

Pre-built CLI binaries are on the releases page. Or build from source: make setup && make deploy.

The demo/ directory in this repo is a Vue 3 showcase that exercises every Lune plugin. Run it with cd demo && lune dev. See Plugins for the full list of what's available.

Platform support

Windows

Lune runs on Windows today with a one-line manual patch to Crystal's stdlib (documented in WINDOWS_SETUP.md). The patch becomes unnecessary once Crystal 1.21.0 ships — crystal#16933 is merged on master and targets 1.21.

With the patch applied, the demo runs end-to-end via lune dev --debug. For per-plugin Windows status (verified, partial, not implemented), see the Platform notes section on each plugin page. ROADMAP.md tracks the path to full parity.

Development

make setup   # shards install + npm install
make test    # crystal spec
make deploy  # build release binary → /usr/local/bin/lune

On Windows, use ./make.ps1 <target> from PowerShell — same targets as the Makefile, plus MSVC env auto-bootstrap (./make.ps1 help lists them). See WINDOWS_SETUP.md for the one-time native-deps setup (sqlite3 + webview + Crystal stdlib patch).

Contributing

1. Fork it (https://github.com/aristorap/lune/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Add specs for your changes (crystal spec)
4. Commit and push and open a Pull Request

Contributors

• Aristotelis Rapai — creator and maintainer

License

MIT