Development Guide

Overview

This page describes the technical foundation of the Obsidian Tasks Sync plugin. It includes details on the folder structure, development setup, tools used, and testing practices.

The plugin is written in TypeScript and built with ESBuild, with testing powered by Vitest. CI is handled via GitHub Actions.

---

Folder Structure

obsidian-tasks-sync/
├── src/
│   ├── commands/          # Command Palette functions
│   ├── models/            # Type definitions, data models
│   ├── repositories/      # Task Model Store
│   ├── libs/              # Library Methods
│   ├── main.ts            # Plugin entry point
├── test/                  # Unit tests with mocks
│   └── __mock__/obsidian.ts
├── .github/               # Issue and PR templates
├── esbuild.config.mjs     # Build configuration
├── vitest.config.ts       # Test configuration
├── package.json           # Project metadata and scripts

---

Build and Run

To develop locally:

pnpm install
pnpm run dev

This uses esbuild to bundle the plugin and watches for changes. Output will be displayed in the terminal.

If you encounter errors:

pnpm add -D builtin-modules
pnpm run dev

---

Command Palette Registration

New plugin features are exposed through the Command Palette using addCommand. Example:

plugin.addCommand({
  id: 'turn-into-google-task',
  name: 'Turn into Google Task',
  callback: () => { ... }
});

These commands are invoked by name or keybinding.

---

Code Style & Linting

• Linter: ESLint
• Formatter: Prettier
• Hook manager: Husky

Run locally:

pnpm lint
pnpm format

Pre-commit hooks ensure consistent formatting and error prevention.

---

Testing

We use Vitest for fast, Vite-native unit testing.

Mocking Obsidian

Since Obsidian is not available outside the app, tests use a mocked interface:

// test/__mock__/obsidian.ts
export class Notice {
  constructor(msg: string) {
    console.log('Mock Notice:', msg);
  }
}

Test files import this version instead of the real Obsidian API.

Running Tests

pnpm test

Example Test

describe('TurnIntoGoogleTaskCommand', () => {
  it('creates a task', () => {
    const result = turnIntoGoogleTask('Write blog post');
    expect(result).toContain('[ ]');
  });
});

---

CI with GitHub Actions

On every pull request:

• Install dependencies
• Lint
• Run tests
• Block merge if tests fail

Workflow file: .github/workflows/test.yml

---

Contribution Setup

To contribute:

1. Fork the repo
2. Create a branch: git checkout -b feature/your-feature
3. Make changes
4. Run tests & lint
5. Open a Pull Request with description and link to relevant issue

See Contributing Guide for more.