@pan.codes/utils

A collection of TypeScript utilities for Obsidian plugin development.

Installation

npm install @pan.codes/utils

Utilities

FileExplorerCustomizer

A utility for customizing file and folder display in Obsidian's file explorer.

Features:

• Change display names of files/folders
• Add custom icons to files/folders
• Customize icon colors
• Automatic DOM observation and reapplication
• Built-in infinite loop prevention

Usage:

import { FileExplorerCustomizer } from '@pan.codes/utils';

// Create customizer with auto-observing enabled
const customizer = new FileExplorerCustomizer({
  onBeforeApply: () => {
    // Optional: inject additional elements before applying customizations
  },
  autoObserve: true // default
});

// Customize a folder
customizer.addCustomization({
  path: '_tools',
  displayName: 'Tools',
  iconName: 'code',
  iconColor: '#ff6666',
  isFolder: true
});

// Customize a file
customizer.addCustomization({
  path: 'my-script.ts',
  displayName: 'My Script',
  iconName: 'play',
  iconColor: '#00ff00'
});

// Initialize and start observing
customizer.initialize();

// Later, when cleaning up (e.g., in plugin unload)
customizer.restore();

API:

• new FileExplorerCustomizer(options?) - Create a new customizer
  • options.onBeforeApply?: () => void - Callback before applying customizations
  • options.autoObserve?: boolean - Auto-observe DOM changes (default: true)
• addCustomization(config) - Add a customization
• removeCustomization(path) - Remove a customization
• clearCustomizations() - Clear all customizations
• initialize() - Initialize and start observing (if auto-observe enabled)
• startObserving() - Manually start observing DOM changes
• stopObserving() - Stop observing DOM changes
• applyCustomizations() - Manually reapply all customizations
• restore() - Restore original state and stop observing

Development

Building

npm run build

Watch mode

npm run watch

Publishing

# Bump patch version and publish
npm run publish-patch

# Or manually
npm run build
npm publish --access public

Local Development with npm link

To develop this package alongside a plugin that uses it:

1. In this package (ts-utils):

   npm run setup-link

2. In your plugin:

   npm link @pan.codes/utils --legacy-peer-deps

3. Development workflow:

   • Run npm run watch in ts-utils
   • Run npm run dev in your plugin
   • Changes to ts-utils will auto-compile

4. Return to npm version:

   npm unlink @pan.codes/utils
   npm install @pan.codes/utils --legacy-peer-deps

License

MIT