1 files changed, 105 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f74d4fc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# minimal-electron-bsql
+
+A bare-bones Electron + TypeScript + [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) app.  
+No forge, no boilerplate, no scaffolding. Just the absolute minimum setup that:
+
+- Runs in dev mode on macOS/Linux/Windows
+- Uses `better-sqlite3` from the **main process**
+- Creates a SQLite DB at startup, inserts + selects a row
+- Displays a trivial HTML UI
+- Can be packaged for distribution (SQLite included)
+
+---
+
+## Project structure
+
+```
+minimal-electron-bsql/
+├── src/
+│ └── main/
+│ └── index.ts # Electron main process
+├── renderer/
+│ └── index.html # Minimal UI
+├── package.json
+├── tsconfig.json
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- macOS (Apple Silicon or Intel). Windows & Linux should work with native build tools installed.
+- Xcode Command Line Tools (macOS) or MSVC Build Tools (Windows) for native rebuilds
+
+---
+
+## Install
+
+```bash
+git clone <this-repo>
+cd minimal-electron-bsql
+npm install
+```
+
+ℹ️ On install, native modules are rebuilt for your Electron version via `@electron/rebuild`.
+
+⸻
+
+Scripts
+
+- npm run dev → compile TS and start Electron in dev mode
+- npm run build → compile TypeScript only
+- npm run start → start Electron with compiled code
+- npm run rebuild → force-rebuild native modules (better-sqlite3)
+- npm run dist → create distributable builds via electron-builder
+- npm run pack → package into unpacked app directory
+
+## What happens on startup
+
+In src/main/index.ts:
+
+1. Database file created at app.getPath('userData')/app.db
+2. A table messages is created (if not exists)
+3. One row "hello from better-sqlite3" is inserted
+4. A SELECT runs and the row is logged to console
+5. Window shows renderer/index.html → just <main>hi</main>
+
+⸻
+
+Packaging notes
+• Native modules: better-sqlite3.node must live outside app.asar. This is handled via:
+
+```
+"asarUnpack": ["node_modules/better-sqlite3/**/*"]
+```
+
+- Cross-arch builds (macOS):
+- Build separately for arm64 and x64:
+
+```bash
+npm run dist -- --mac arm64
+npm run dist -- --mac x64
+```
+
+- Optionally merge into a universal binary:
+
+```bash
+npx electron-builder --universal
+```
+
+- Database location: Always use app.getPath('userData'). Do not write next to your code files, since those are inside app.asar when packaged.
+
+⸻
+
+Common pitfalls & fixes
+
+- was compiled against a different Node.js version error
+- Run npm run rebuild after npm install or upgrading Electron.
+- .node module not found after packaging
+- Check asarUnpack includes better-sqlite3.
+- Windows/Linux builds
+- Windows: install Build Tools for Visual Studio + Python
+- Linux: sudo apt install build-essential python3
+
+## License
+
+MIT