Obsidian Plugin Template (Bun)

Canonical version: Obsidian Plugin Template (Bun).

Opinionated GitHub template for building Obsidian Community Plugins on top of Bun and TypeScript. Wraps the full toolchain (bundler, linter, formatter, test runner, commit tooling, release workflow) and a structured AGENTS.md so coding agents can ship features end-to-end without guesswork.

Created by Sébastien Dubois. Licensed under MIT.

How It Works

• Click "Use this template" on GitHub; clone; run bun install && bun run init
• The init script prompts for plugin id, name, description, repo, author, funding URL and rewrites manifest.json, package.json, CHANGELOG.md, versions.json to a clean 0.0.0 state. Prevents template leakage (stale versions, wrong repo URLs, the my-plugin id) into the first release
• After init, the maintainer deletes TEMPLATE_USAGE.md, scripts/init-from-template.ts, and the init script entry. Their presence is the signal that initialization is incomplete
• bun run dev watches sources and writes main.js / styles.css to the vault path set via OBSIDIAN_VAULT_LOCATION
• Releases are cut by pushing a SemVer tag; GitHub Actions builds, generates the changelog, and attaches main.js, manifest.json, styles.css to the release

Features

• Bun as package manager and bundler (no npm, no webpack, no esbuild)
• TypeScript with super-strict config (noUnusedLocals, noUncheckedIndexedAccess, noImplicitReturns, noImplicitOverride, ...)
• Tailwind CSS v4 via src/styles.src.css; build compiles to the root styles.css
• ESLint + Prettier with --max-warnings 0
• Husky + lint-staged pre-commit checks
• Commitizen + cz-customizable + commitlint enforcing Conventional Commits
• Bun test with co-located .spec.ts files
• Immer for immutable state; Zod for runtime validation
• GitHub Actions for CI on push/PR and tag-driven releases
• Three documentation surfaces separated by audience: README.md (GitHub), docs/ (end-users via Jekyll/GitHub Pages), documentation/ (agents and maintainers)

AI-Enabled Workflow

What makes this template more than a bundler bootstrap is AGENTS.md plus TEMPLATE_USAGE.md; together they turn a generic template into a repeatable contract for coding agents.

• Template vs. downstream detection: agents check the git remote. If origin is the template repo, they leave initialization tooling alone; otherwise they run bun run init and complete manual follow-ups before touching features
• Session-start checklist: every session reads documentation/Business Rules.md, the latest documentation/history/yyyy-mm-dd.md, active documentation/plans/, and the relevant sections of node_modules/obsidian/obsidian.d.ts before editing
• Definition of done: a change is done only when bun run tsc, bun run lint, bun test, and bun run build all pass, the day's history file is updated, plans are updated or closed, and any user-visible change is reflected in README.md / docs/
• Business Rules as invariants: documentation/Business Rules.md is treated as mandatory; any new rule the user mentions is captured there immediately
• Explicit ignore list: agents never read/modify TODO.md, documentation/archived/, main.js, styles.css, dist/, node_modules/, or release zips
• Commit hygiene: bun run cm drives Commitizen; hooks are never bypassed
• No UI self-verification: agents are told to flag any change that needs manual runtime verification in Obsidian rather than claim success on a passing build
• No timing in plans: plans under documentation/plans/ describe what, not when
• Watch-first development: bun run tsc:watch is mandatory before any code change so type errors surface immediately
• Encoded Bun defaults: agents prefer bun <file>, bun test, bun build, bun install, bun run, bunx over Node/npm equivalents; no dotenv (Bun loads .env natively)
• Tailwind + Obsidian CSS-var convention: utilities via @apply or inline; Obsidian theme colors only through var(--...)
• File-structure guidance: keep main.ts minimal (lifecycle only), split by responsibility (settings/, commands/, ui/, utils/, types.ts), test files co-located as .spec.ts

The net effect: a cold-start agent can open a plugin generated from this template and become productive in one read of AGENTS.md, without inventing conventions or leaking template state into the product.

Prerequisites

• Bun (latest)
• Git and a GitHub account
• An Obsidian vault for local testing
• OBSIDIAN_VAULT_LOCATION env var pointing at that vault

Versioning & Releases

• SemVer in manifest.json; versions.json maps plugin version to minimum Obsidian version
• Tag names match manifest.json version exactly; no leading v
• First release is manual; subsequent releases via tag push or Actions → Release → Run workflow
• Release assets: manifest.json, main.js, styles.css (if present)

References

• Source code: https://github.com/dsebastien/obsidian-plugin-template
• Upstream sample this template draws from: https://github.com/rzbin/obsidian-plugin-template-bun
• Obsidian API docs: https://docs.obsidian.md
• Developer policies: https://docs.obsidian.md/Developer+policies
• Plugin guidelines: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Related

• Obsidian
• Obsidian Community Plugins
• Bun
• TypeScript
• Sébastien Dubois

My plugins built on top of / around this template

• Bookshelf plugin for Obsidian
• Dataview Serializer plugin for Obsidian
• Expander plugin for Obsidian
• Graph Explorer Base View plugin for Obsidian
• Hidden Folders Access plugin for Obsidian
• Journal Bases plugin for Obsidian
• Life Tracker plugin for Obsidian
• Note Village plugin for Obsidian
• Obsidian CLI REST MCP plugin for Obsidian
• reMarkable Sync plugin for Obsidian
• Replicate plugin for Obsidian
• Time Machine plugin for Obsidian
• Transcriber plugin for Obsidian
• Typefully plugin for Obsidian
• Update time plugin for Obsidian

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

• 📚 KM for Beginners — 10+ hours of structured video lessons
• 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
• 💼 Knowledge Worker Kit — Complete guides + lifetime community
• 🦉 1-on-1 Coaching — Personalized guidance
• 🎯 Join Knowii — Community + ALL courses & tools