98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Type
|
|
|
|
This is an Obsidian community plugin written in TypeScript and bundled to JavaScript using esbuild.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development mode (watch mode, auto-recompiles on changes)
|
|
npm run dev
|
|
|
|
# Production build (type checks, then bundles with minification)
|
|
npm run build
|
|
|
|
# Lint code
|
|
npm run lint
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Entry Points & Build Process
|
|
- Source code lives in `src/`
|
|
- Main entry point: `src/main.ts` (plugin lifecycle management)
|
|
- Build target: `main.js` (bundled output at root)
|
|
- Bundler: **esbuild** (configured in `esbuild.config.mjs`)
|
|
- Required release artifacts: `main.js`, `manifest.json`, `styles.css` (if present)
|
|
|
|
### Code Organization Pattern
|
|
- **Keep `main.ts` minimal**: Only plugin lifecycle (onload, onunload, command registration)
|
|
- Delegate feature logic to separate modules
|
|
- Settings are defined in `src/settings.ts`
|
|
- Organize larger features into subdirectories:
|
|
- `commands/` for command implementations
|
|
- `ui/` for modals, views, and UI components
|
|
- `utils/` for helper functions
|
|
|
|
### Plugin Architecture
|
|
- Extends `Plugin` class from `obsidian` package
|
|
- Settings are loaded/saved using `this.loadData()` / `this.saveData()`
|
|
- All event listeners, intervals, and DOM events must use `this.register*()` helpers for proper cleanup
|
|
- Commands are registered via `this.addCommand()` with stable IDs
|
|
|
|
## Key Constraints
|
|
|
|
### Obsidian-Specific
|
|
- **Bundle everything**: No external runtime dependencies (except `obsidian`, `electron`, CodeMirror packages)
|
|
- **External packages**: Listed in `esbuild.config.mjs` external array; never bundle these
|
|
- **Mobile compatibility**: Avoid Node/Electron APIs unless `isDesktopOnly: true` in manifest
|
|
- **Network requests**: Default to offline; require explicit user consent for any external calls
|
|
- **No remote code execution**: Never fetch/eval scripts or auto-update outside normal releases
|
|
|
|
### Manifest (`manifest.json`)
|
|
- Never change `id` after initial release
|
|
- Use semantic versioning for `version`
|
|
- Keep `minAppVersion` accurate when using newer Obsidian APIs
|
|
- Update both `manifest.json` and `versions.json` when bumping versions
|
|
|
|
## Development Workflow
|
|
|
|
### Testing Locally
|
|
1. Build the plugin: `npm run dev` or `npm run build`
|
|
2. Copy `main.js`, `manifest.json`, `styles.css` to:
|
|
```
|
|
<Vault>/.obsidian/plugins/<plugin-id>/
|
|
```
|
|
3. Reload Obsidian and enable plugin in Settings → Community plugins
|
|
|
|
### Type Checking
|
|
- TypeScript strict mode enabled in `tsconfig.json`
|
|
- Build command runs `tsc -noEmit -skipLibCheck` before bundling
|
|
- Fix type errors before considering build successful
|
|
|
|
## Important Files
|
|
|
|
- `src/main.ts` - Plugin class and lifecycle
|
|
- `src/settings.ts` - Settings interface, defaults, and settings tab UI
|
|
- `manifest.json` - Plugin metadata (never commit with wrong version)
|
|
- `esbuild.config.mjs` - Build configuration
|
|
- `eslint.config.mts` - ESLint configuration with Obsidian-specific rules
|
|
- `styles.css` - Optional plugin styles
|
|
|
|
## Code Quality Guidelines
|
|
|
|
From AGENTS.md and Obsidian best practices:
|
|
- Split files when they exceed ~200-300 lines
|
|
- Use clear module boundaries (single responsibility per file)
|
|
- Prefer `async/await` over promise chains
|
|
- Register all cleanup via `this.register*()` helpers to prevent memory leaks
|
|
- Keep startup lightweight; defer heavy work until needed
|
|
- Use stable command IDs (don't rename after release)
|
|
- Provide sensible defaults for all settings
|