obsidian-codex AGENTS.md

Obsidian community plugin

Project overview

• Target: Obsidian Community Plugin (React & TypeScript → bundled JavaScript).
• Entry point: main.ts compiled to main.js and loaded by Obsidian.
• Required release artifacts: main.js, manifest.json, and optional styles.css.

Environment & tooling

• Node.js: use current LTS (Node 18+ recommended).
• Package manager: npm (required for this sample - package.json defines npm scripts and dependencies).
• Bundler: esbuild (required for this sample - esbuild.config.mjs and build scripts depend on it). Alternative bundlers like Rollup or webpack are acceptable for other projects if they bundle all external dependencies into main.js.
• Types: obsidian type definitions.

Note: This sample project has specific technical dependencies on npm and esbuild. If you're creating a plugin from scratch, you can choose different tools, but you'll need to replace the build configuration accordingly.

Install

npm install

Dev (watch)

npm run dev

Production build

npm run build

Linting

• To use eslint install eslint from terminal: npm install -g eslint
• To use eslint to analyze this project use this command: eslint main.ts
• eslint will then create a report with suggestions for code improvement by file and line number.
• If your source code is in a folder, such as src, you can use eslint with this command to analyze all files in that folder: eslint ./src/

File & folder conventions

• Organize code into multiple files: Split functionality across separate modules rather than putting everything in main.ts.
• Source lives in src/. Keep main.ts small and focused on plugin lifecycle (loading, unloading, registering commands).
• Example file structure:

  src/
    main.ts           # Plugin entry point, lifecycle management
    settings.ts       # Settings interface and defaults
    commands/         # Command implementations
      command1.ts
      command2.ts
    ui/              # UI components, modals, views
      modal.ts
      view.ts
    utils/           # Utility functions, helpers
      helpers.ts
      constants.ts
    types.ts         # TypeScript interfaces and types
  

• Do not commit build artifacts: Never commit node_modules/, main.js, or other generated files to version control.
• Keep the plugin small. Avoid large dependencies. Prefer browser-compatible packages.
• Generated output should be placed at the plugin root or dist/ depending on your build setup. Release artifacts must end up at the top level of the plugin folder in the vault (main.js, manifest.json, styles.css).