liufree_obsidian-querydash/AGENTS.md

AGENTS.md - Obsidian QueryDash Plugin

This document provides essential information for AI agents working on the Obsidian QueryDash plugin codebase.

Project Overview

Obsidian QueryDash is a plugin that provides enhanced views for Obsidian Bases and Dataview data, offering table, list, timeline, and memory card views with features similar to Notion databases.

Build Commands

Development

npm run dev          # Build with watch mode for development

Production

npm run build        # Build for production

Version Management

npm run version      # Bump version and update manifest.json

Code Quality & Linting

ESLint Configuration

• Uses TypeScript ESLint with recommended rules
• Run linting: npx eslint . --ext .ts,.tsx
• Configuration file: .eslintrc

Key ESLint Rules

• no-unused-vars: Off (handled by TypeScript version)
• @typescript-eslint/no-unused-vars: Error (except function arguments)
• @typescript-eslint/ban-ts-comment: Off (allows TypeScript directives)
• @typescript-eslint/no-empty-function: Off

Editor Configuration

• Indentation: Tabs (4 spaces width)
• Line Endings: LF
• Charset: UTF-8
• Final Newline: Required
• Configuration file: .editorconfig

TypeScript Configuration

Compiler Options (tsconfig.json)

• Target: ES6
• Module: ESNext
• JSX: React
• Strict: noImplicitAny, strictNullChecks
• Module Resolution: Node
• Allow Synthetic Default Imports: true
• Lib: DOM, ES5, ES6, ES7

Type Checking

npx tsc --noEmit    # Type check without emitting files

Code Style Guidelines

File Structure

• Source code in src/ directory
• Main entry point: src/main.tsx
• Pages/components in src/pages/
• Models in src/models/
• Components in src/components/

Naming Conventions

• Files: PascalCase for components (e.g., QueryDashView.tsx), camelCase for utilities
• Components: PascalCase (e.g., DashTableView, QueryDashView)
• Variables/Functions: camelCase
• Types/Interfaces: PascalCase
• Constants: UPPER_SNAKE_CASE

Import Organization

1. External dependencies (React, Obsidian)
2. Internal modules
3. Type imports
4. Style imports

Example:

import React, {useEffect, useState} from 'react';
import {App} from "obsidian";
import TableView from "./tableview/TableView";
import {ConfigProvider, theme} from "antd";

React Components

• Use functional components with TypeScript
• Define props interfaces with interface keyword
• Use React.FC<Props> type for components
• Prefer explicit return types for complex components

Example:

interface QueryDashViewProps {
    app: App;
    source: string;
}

const QueryDashView: React.FC<QueryDashViewProps> = ({app, source}) => {
    // Component implementation
};

TypeScript Usage

• Always use TypeScript strict mode
• Define explicit types for function parameters and return values
• Use interfaces for object shapes
• Avoid any type; use unknown or specific types
• Use optional chaining (?.) and nullish coalescing (??) for safe property access

Error Handling

• Use try-catch blocks for async operations
• Log errors with appropriate context
• Return meaningful error messages to users
• Validate inputs before processing

State Management

• Use React hooks (useState, useEffect)
• Keep state as local as possible
• Lift state up when shared between components
• Use proper dependency arrays in useEffect

Styling

• Use Ant Design components as primary UI library
• Theme follows Obsidian's dark/light mode
• Custom styles in CSS when needed
• Responsive design considerations

Testing

Current Status

• No formal test framework configured
• Manual testing through Obsidian plugin installation
• Consider adding Jest/Vitest for unit tests

Recommended Test Structure

tests/
├── unit/           # Unit tests
├── integration/    # Integration tests
└── e2e/           # End-to-end tests

Dependencies

Core Dependencies

• React: UI library
• Ant Design: Component library
• Obsidian API: Plugin framework
• Dataview: Data querying

Development Dependencies

• TypeScript: Type safety
• ESLint: Code linting
• Vite: Build tool
• Husky: Git hooks
• lint-staged: Pre-commit linting

Git Workflow

Commit Messages

• Use conventional commits format
• Start with type: feat:, fix:, docs:, style:, refactor:, test:, chore:
• Keep first line under 50 characters
• Provide detailed description in body

Branch Strategy

• main: Production releases
• dev: Development branch
• Feature branches: feature/description
• Bug fix branches: fix/issue-description

Pre-commit Hooks

• Husky configured for pre-commit hooks
• lint-staged runs ESLint on staged files
• Ensure code passes linting before commit

Plugin Development Notes

Obsidian Plugin API

• Extend Plugin class
• Register markdown code block processors
• Register Bases views when applicable
• Clean up resources in onunload()

Build Output

• Main file: main.js
• Styles: styles.css
• Manifest: manifest.json
• Source maps in development mode

Version Management

• Update manifest.json version
• Update versions.json for compatibility
• Use npm run version script

Performance Considerations

• Use React.memo for expensive components
• Implement virtualization for large lists
• Lazy load heavy components
• Optimize re-renders with proper dependency arrays
• Monitor bundle size with Vite build

Security Best Practices

• Sanitize user inputs
• Validate file paths and URLs
• Use Obsidian's safe APIs for file operations
• Avoid eval() or similar dangerous functions
• Keep dependencies updated

Troubleshooting

Common Issues

1. Build failures: Check TypeScript errors first
2. Plugin not loading: Verify manifest.json and main.js exist
3. UI not rendering: Check React component errors in console
4. Type errors: Ensure proper TypeScript configuration

Debugging

• Use console.log with appropriate context
• Check browser developer tools
• Enable source maps in development
• Test in Obsidian's developer mode

Contributing Guidelines

1. Follow existing code patterns and conventions
2. Add TypeScript types for new features
3. Update documentation when changing APIs
4. Test changes in Obsidian before committing
5. Keep bundle size minimal

Resources

• Obsidian Plugin Docs
• React Documentation
• TypeScript Handbook
• Ant Design Components
• Vite Documentation