# 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]]