Commonplace

Commonplace is an open-source, local-first Markdown vault inspired by tools like Obsidian.

It is designed around a simple promise:

• your notes are plain Markdown files on your machine,
• the app is a viewer / editor / indexer on top of them,
• nothing about the experience requires a backend, an account, or a cloud.

What Commonplace is

• An Electron desktop app (primary direction) with a React/Vite renderer and a Node main process that owns all filesystem and SQLite work.
• A browser fallback that still runs the same renderer with either the File System Access API (Chromium-family desktops) or localStorage.
• A personal knowledge base with safe preview, wiki links, backlinks, graph view, full-text search, and a Related Notes panel (currently powered by a deterministic placeholder embedding — see docs/HANDOFF.md §10).

What Commonplace is not

• Not a backend SaaS.
• Not an account/login product.
• Not a native cloud sync service.
• Not a real-time collaboration system.
• Not a database-first note model.

Local-first philosophy

Commonplace does not own or upload your notes. In local-folder mode, your notes are plain Markdown files in a normal folder that you control. For multi-device workflows, Commonplace uses a bring-your-own-sync model: place that folder inside a sync tool you already trust.

Storage modes

1) Local-folder vault mode (recommended)

• Uses File System Access API in supported desktop browsers.
• Reads/writes real Markdown files directly.
• Scaffolds common folders (Notes/, Daily/, Attachments/, Templates/, .commonplace/).
• Supports local-folder attachments, including image preview resolution at render time.

2) Browser-local fallback mode

• Stores notes in browser-local storage.
• Useful for unsupported browsers, demos, and quick trials.
• Import/export exists so data is portable and not trapped.
• Browser-local attachments are intentionally unsupported today.

Current feature set

Desktop (Electron) — primary direction:

• Markdown notes with live editing, preview, and split view.
• Native folder picker; all filesystem operations owned by the Electron main process behind a narrow IPC bridge.
• File watching via chokidar with debounced batched events; stale-note banner on external edits; optimistic-concurrency WriteConflictError on save races.
• SQLite metadata index (.commonplace/index.sqlite) covering files, frontmatter, wiki-links, headings, and FTS5 search rows. Fully rebuildable derived data.
• Desktop full-text search via SQLite FTS5 with a punctuation-safe query tokenizer.
• Backlinks + graph derived from the SQLite index (browser mode keeps the in-memory implementation).
• Semantic Related Notes panel: chunker, embedding-provider abstraction, deterministic placeholder embedding, enable/disable toggle, rebuild/clear commands, stats grid, debounced refresh, AbortSignal-based stale-request protection.
• Attachments copied into Attachments/ with duplicate filename handling; safe image preview via main-process IPC.
• Import / export ZIP flows.
• Vault settings (theme, default folders, daily-notes folder, semantic-indexing flag).

Browser modes:

• Local-folder mode (Chromium-family desktops) via the File System Access API.
• Browser-local fallback via localStorage with import/export.
• Search/backlinks/graph still work via the in-memory MiniSearch + wiki-links utilities.

Browser support expectations

Best experience:

• Chrome desktop
• Edge desktop

Fallback:

• Firefox/Safari and other unsupported environments can use browser-local mode.

Bring-your-own-sync model

Commonplace has no native sync engine today.

Recommended approach: put your vault folder inside a folder managed by one of:

• Syncthing
• iCloud Drive
• Dropbox
• Google Drive for Desktop
• OneDrive
• Nextcloud
• Git (power-user workflow)

Development

Install

npm ci

Run locally

npm run dev

Test

npm run test

Lint

npm run lint

Build

npm run build

Deployment

Commonplace is a static Vite app and can be deployed to static hosting providers such as Cloudflare Pages, GitHub Pages, Netlify, etc.

Security & privacy model

• No backend server required for core product behavior
• No user accounts or authentication layer
• No app-owned cloud sync
• User data remains local to the selected folder or browser storage
• Safe markdown rendering rules intentionally block unsafe URL/script vectors

Docs for contributors

• Handoff (start here) — comprehensive snapshot of where the project is right now (post-E5b).
• Architecture
• Electron details
• Development environment
• Roadmap
• Contributing
• PR History

License

MIT