obsidian-plugin/banisterious_obsidian-charted-roots
1
0
Fork 0
mirror of https://github.com/banisterious/obsidian-charted-roots.git synced 2026-07-22 06:40:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
banisterious_obsidian-chart.../docs/developer/getting-started.md
John Banister 0e04ff548e docs: v0.22.75 release round-up
2026-06-25 17:30:38 -07:00

5.4 KiB
Raw Permalink Blame History

Getting Started with Development

This guide covers setting up your development environment, building, and testing the Charted Roots plugin.

Table of Contents

Project Setup

Installation

npm install

Build Commands

  • npm run dev - Start development mode with watch (builds to local main.js)
  • npm run build - Production build (fonts + esbuild + CSS; no type check — run type-check separately when needed)
  • npm run type-check - Standalone tsc -noEmit -skipLibCheck pass. Clean (zero errors) and gated in CI as of #704; run before pushing a tag.
  • npm test - Run the Vitest regression suite once (1618 tests across 140 suites as of v0.22.75, covering pure helpers for relationships, migrations, the sibling walker, event identity, date handling, and a large set of issue-specific regression suites)
  • npm run test:watch - Vitest in watch mode for iterative development
  • npm run lint - Check TypeScript code for linting errors
  • npm run lint:fix - Auto-fix TypeScript linting errors
  • npm run lint:css - Check CSS for linting errors
  • npm run lint:css:fix - Auto-fix CSS linting errors
  • npm run format:css - Format CSS with Prettier

Before committing code, always run linting and the test suite:

npm run lint && npm run lint:css && npm run type-check && npm test

Bug fixes that touch volatile code paths (relationship handling, migrations, cross-note writes, date parsing) should land with regression tests — see the existing tests/ files for the pure-helper extraction pattern.

See Coding Standards for detailed style guidelines.

Manual Deployment to Obsidian Vault

To deploy the plugin to your Obsidian vault for testing:

  1. Build the plugin:

    npm run build

  2. Manually copy the built files to your vault's plugin directory:

    cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/canvas-roots/

  3. Reload Obsidian (Ctrl+R or Cmd+R) to see changes

Note: You can create custom deploy scripts if needed. The package.json references deploy.sh and dev-deploy.sh scripts that are not currently in the repository.

Testing in Obsidian

  1. Build the plugin: npm run build
  2. Copy built files to your vault's plugin directory (see Manual Deployment section above)
  3. Open Obsidian
  4. Go to Settings → Community plugins
  5. Enable "Charted Roots"
  6. The plugin commands will be available in the Command Palette (Ctrl/Cmd+P):
    • "Charted Roots: Open Control Center"
    • "Charted Roots: Generate Tree for Current Note"
    • "Charted Roots: Re-Layout Current Canvas"
    • "Charted Roots: Create Person Note"

Reloading After Changes

After copying changes to your vault, reload Obsidian:

  • Quick reload: Press Ctrl+R (Windows/Linux) or Cmd+R (Mac)
  • Full reload: Settings → Community plugins → Toggle plugin off/on

Hot Reload (Advanced)

For instant plugin reloading without restarting Obsidian:

  1. Install the Hot Reload plugin
  2. It will automatically detect changes to main.js in your vault's plugin directory
  3. After running npm run build, copy the files to your vault
  4. Hot Reload will automatically reload the plugin

Debugging

Logging System

The plugin includes a structured logging system with persistent configuration:

Log Levels:

  • debug: Most verbose, shows all operations
  • info: Important events and state changes
  • warn: Warnings and non-critical issues
  • error: Errors and failures
  • off: Disable logging

Configuration:

  1. Open Settings → Charted Roots
  2. Navigate to "Logging" section
  3. Select desired log level from dropdown
  4. Changes apply immediately and persist across Obsidian restarts

Default Setting: Debug mode is enabled by default for development visibility.

Exporting Logs: The logging system captures structured log entries that can be exported via the Control Center's Status tab for debugging complex issues.

Console Logs

Open the Developer Console in Obsidian:

  • Windows/Linux: Ctrl+Shift+I
  • Mac: Cmd+Option+I

Look for:

  • "Loading Charted Roots plugin" when the plugin loads
  • Structured log entries with component names and operation contexts
  • Any error messages or stack traces

TypeScript Errors

The esbuild build does not type-check. Run the standalone type-checker:

npm run type-check

This runs tsc -noEmit and reports any TypeScript errors. It is clean (zero errors) and gated in CI as of #704.

Version Management

When ready to release a new version:

  1. Update the version in package.json
  2. Run the version bump script: 
    npm version patch  # or minor, or major

This will automatically update manifest.json and versions.json.

Related Documentation