Knuckle: SQLite-Powered Self-Contained Desktop Application Framework
Knuckle reimagines SQLite not just as an embedded database, but as a fully self-contained, executable desktop application container (.knuckleApp). Powered by Bun for fast JavaScript/TypeScript execution and Slint for native, GPU-accelerated UI rendering, Knuckle delivers native desktop performance with an ultra-low memory footprint (~77MB) and zero IPC overhead.
- SQLite as an App Container: Pack UI templates (Slint DSL), bundled logic (ESM), SQL queries (YAML), and live data into a single, portable
.knuckleAppfile. - Portability: The application itself and all its data are stored within a single
.knuckleAppfile. You can simply copy the Knocked file to another PC and resume your work without needing to perform an installation. like FileMaker. - Zero IPC Overhead: UI, business logic, and database operations run within the same in-memory process, eliminating the serializing overhead found in Electron or Webview-based frameworks.
- Ultra-Lightweight Footprint: Native GPU vector rendering without Chromium baggage—idles at ~77MB of RAM.
- Zero Black Box Data Architecture: All SQL operations are centralized in declarative
queries.yamlfiles, cleanly separating UI, business logic, and database access. - Effortless Scalability: Migrate from single-file local SQLite to enterprise PostgreSQL simply by tweaking queries in YAML—without touching UI components or MVC routing.
Prerequisites
- Bun (v1.1 or later)
- Git
1. Clone & Setup Knuckle CLI
git clone https://github.com/kanryu/Knuckle.git
cd Knuckle
bun install
2. Setup Example Project
cd example
bun install
cd ..
3. Test CLI Commands
- Development Mode (
dev) Run the application directly from source files:
bun run src/index.ts dev ./example
- Package Application (
pack) Bundle Slint app and SQLite into a single.knuckleAppcontainer:
bun run src/index.ts pack ./example
- Execute Container (
run) Launch the packed standalone container:
bun run src/index.ts run ./example/example.knuckleApp
Since its introduction in the 1990s, Microsoft Access has powered countless internal tools, small-to-medium enterprise databases, and departmental line-of-business applications. However, modern engineering standards have exposed critical architectural limitations that turn legacy Access databases into severe technical debt:
- Platform Lock-in & Phasing Out: Microsoft has steadily deprioritized Access, leaving organizations reliant on proprietary binary formats with dwindling ecosystem support.
- The 2GB Limit & File Corruption Risk: Access database files (
.mdb/.accdb) cannot exceed 2GB. Hitting this limit often results in severe database corruption and data loss. - VBA Limitations & Lack of Version Control: VBA code is tightly coupled inside monolithic binary files, making modern Git workflows, continuous integration, and code reviews virtually impossible.
- Hidden I/O via Bound Forms: Bound forms write to tables implicitly in the background without explicit SQL statements. This black-box behavior makes business logic difficult to audit, debug, or refactor.
- High Migration Barriers: Because logic, schema, and implicit queries are tightly intertwined, migrating away from Access typically requires a complete, high-risk rebuild from scratch.
Knuckle provides a modern, open, and future-proof desktop architecture that replaces the RAD ease of Access without inheriting its technical debt:
- Portable & Limit-Free Storage (SQLite): Backed by SQLite, Knuckle offers virtually limitless capacity (up to 140TB), bulletproof crash-recovery (WAL mode), and an open public-domain storage format.
- Git-Native Development (TypeScript & ESM): Code in standard JavaScript/TypeScript and Slint markup. Every view, route, and query exists as plain text, fully compatible with Git, npm, and modern CI/CD.
- IDE Using Visual Studio Code provides a comfortable development environment featuring powerful code completion, debugging capabilities, and Git-based version control. If you find a better environment, you can always switch to it.
- Zero Black-Box Data Access (
queries.yaml): Every single database interaction is cataloged declaratively in YAML. Developers and auditors can inspect all queries at a glance. - Seamless Scalability: Start as a standalone, single-file
.knuckleApp. When business volume scales, transition to client-server databases (e.g., PostgreSQL) simply by updating queries in YAML—without touching UI components or business controllers.
Current Support (Desktop) Knuckle runs seamlessly across all major desktop operating systems using the same codebase:
- Windows (x64 / arm64)
- macOS (Apple Silicon / Intel)
- Linux (x64 / arm64)
Because Bun and Slint compile and execute natively on POSIX and Windows environments, .knuckleApp packages remain fully portable and behave identically across platforms without recompilation.
Future Roadmap (Mobile & Tablets) Thanks to Slint's native vector rendering architecture and multi-target compilation, Knuckle is designed to expand beyond desktop systems. Future releases aim to support:
- iOS / iPadOS
- Android
- Embedded Displays & Touch Terminals
This will enable a single .knuckleApp logic and UI definition to scale from desktop workstations down to mobile field devices and tablets.
Most modern projects attempting to replace Microsoft Access rely on Electron or Webview-based stacks. However, developing web-based desktop applications demands specialized frontend toolchains, complex CSS layout models, dedicated web designers, and engineers proficient in frameworks like React or Vue.
Knuckle adopts Slint, offering distinct advantages for business desktop software:
- Declarative & Clean UI Syntax: Inheriting proven design concepts from over a decade of QML (Qt Modeling Language), Slint provides a declarative markup language tailored specifically for native user interfaces—far simpler, more intuitive, and less bloated than HTML/CSS.
- Instant Live Preview in VS Code: With the official Slint extension for Visual Studio Code, developers get instantaneous, real-time GUI previews side-by-side as they edit UI files.
- Streamlined Team Composition: You do not need large frontend engineering teams or heavy web bundling setups. A clean syntax allows full-stack and backend engineers to craft polished UIs effortlessly.
- Built-in MVC Architecture: Knuckle standardizes page routing, models, and controllers, making it straightforward to build multi-page, complex line-of-business applications with structured separation of concerns.
You can integrate Knuckle directly into your Windows environment to enable seamless, double-click execution of .knuckleApp files with custom icons and zero console flicker.
Installation
Open PowerShell in the project root and run:
cd knuckle-installer
.\install.ps1
What the installer does:
- Deploys the standalone Bun runtime, Knuckle CLI, and native dependencies to
%LOCALAPPDATA%\Programs\Knuckle. - Registers the custom Knuckle fist icon and
.knuckleAppfile association in the Windows Registry. - Configures silent background launching using
wscript.exe(eliminating console window flashes). - Adds the
knucklecommand to your userPATH.
Once installed, simply double-click any .knuckleApp file in Windows Explorer to launch the application.
Uninstallation
To cleanly revert all system changes:
cd knuckle-installer
.\uninstall.ps1
This removes the .knuckleApp file associations, deletes user PATH entries, and cleans up the installed runtime directory.
Knuckle is licensed under the MIT License.
Applications built with Knuckle utilize Slint as their GUI rendering engine. When distributing compiled applications created with Knuckle, you must comply with one of Slint's licensing options in addition to the MIT License:
- Slint Royalty-Free Desktop License: Allows royalty-free desktop proprietary/commercial distribution.
- GNU GPLv3: For open-source projects.
- Slint Commercial License: For custom enterprise/embedded requirements.
For further details, please refer to the Slint Licensing Documentation.