@inkdropapp/types

TypeScript type definitions for Inkdrop plugin development.

This package provides ambient type declarations for the inkdrop global object (the Environment class) and the 'inkdrop' module, giving plugin authors full IntelliSense and type-checking support.

Installation

npm install --save-dev @inkdropapp/types

Setup

Add @inkdropapp/types to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "inkdrop": [
        "./node_modules/@inkdropapp/types/src/inkdrop-module/index.d.ts"
      ]
    },
    "types": ["@inkdropapp/types"]
  }
}

This enables two things:

1. The inkdrop global -- typed as the Environment class, available in any file without importing
2. The 'inkdrop' module -- typed ambient module for import { ... } from 'inkdrop'

Usage

Defining a plugin

A plugin's entry module should default-export an object that implements the IInkdropPlugin interface. Inkdrop's package manager calls its lifecycle methods as the plugin is loaded, activated, and deactivated. The only required method is activate, which receives the Environment (the same object as the inkdrop global).

import { Environment, IInkdropPlugin } from '@inkdropapp/types'

class MyPlugin implements IInkdropPlugin {
  private disposable: { dispose(): void } | null = null

  activate(inkdrop: Environment) {
    // Register commands, components, telescope sources, layout items, etc.
    this.disposable = inkdrop.commands.add(document.body, {
      'my-plugin:hello': () => console.log('Hello from my plugin')
    })
  }

  deactivate() {
    // Tear down everything created in activate()
    this.disposable?.dispose()
    this.disposable = null
  }
}

export default new MyPlugin()

Lifecycle methods

| Method | Required | Called when | | -------------------------- | -------- | -------------------------------------------------------------------------------------------- | | activate(app) | ✅ | The plugin is activated. Set up commands, components, sources, and layout items here. | | deactivate(app) | | The plugin is deactivated. Dispose subscriptions and unregister everything from activate. | | initialize() | | Once before activate, for setup that must run before deserializers and view providers. | | config | | A Record<string, ConfigSchema> registering config options (alternative to package.json). | | activateConfig(config) | | During activation, when config setup needs to run separately from activate. | | deactivateConfig(config) | | On deactivation, to tear down anything registered in activateConfig. |

activate, deactivate, activateConfig, and deactivateConfig may be synchronous or return a Promise. The app argument is the Environment; the config argument is the Config manager.

Declaring config options

Config can be declared on the plugin object so the settings UI can render editors for each option:

import { ConfigSchema, Environment, IInkdropPlugin } from '@inkdropapp/types'

class MyPlugin implements IInkdropPlugin {
  config: Record<string, ConfigSchema> = {
    greeting: {
      title: 'Greeting',
      type: 'string',
      default: 'Hello'
    }
  }

  activate(inkdrop: Environment) {
    const greeting = inkdrop.config.get('my-plugin.greeting')
    console.log(greeting)
  }
}

export default new MyPlugin()

The inkdrop global

[!WARNING] Deprecated. Relying on the global inkdrop is discouraged. Prefer the Environment passed to your plugin's activate(app) (and other lifecycle) methods. The global remains available for backwards compatibility.

The inkdrop global provides access to the application environment -- managers for commands, keymaps, packages, notifications, the local database, and more.

// Access the config
const fontSize = inkdrop.config.get('editor.fontSize')

// Register a command
inkdrop.commands.add(document.body, {
  'my-plugin:do-something': () => {
    // ...
  }
})

// Query the local database
const note = await inkdrop.localDB.notes.get('note:abc123')

// Run code with the active editor, waiting for one if needed
inkdrop.ensureEditorLoaded(editor => {
  console.log('Editor ready:', editor)
})

The 'inkdrop' module

Plugins can import utilities and models from the 'inkdrop' module. These are provided by Inkdrop at runtime and should not be bundled into your plugin.

import { models, logger, useModal, createLogger } from 'inkdrop'

// ORM models
const note = await models.Note.loadWithId('note:abc123')
note.title = 'Updated Title'
await note.save()

// Logging
logger.debug('Processing:', data)

const myLogger = createLogger('my-plugin')
myLogger.info('Plugin initialized')

// React hook for modals
function MyDialog() {
  const modal = useModal()
  return (
    <>
      <button onClick={modal.show}>Open</button>
      {modal.state.visible && <Dialog onClose={modal.close} />}
    </>
  )
}

Other exports from the 'inkdrop' module include:

• actions -- Redux action creators (typed as any)
• AssistiveError -- Error class with detail and debugInfo properties
• html2markdown -- Convert HTML strings to Markdown
• markdownRenderer -- The application's Markdown renderer
• exportUtils -- Export notes as HTML or Markdown
• importUtils -- Import Markdown or HTML files as notes

Command types

The package provides typed command maps for every scope in the application. Use these to get type-safe command dispatching:

import type {
  EnvironmentCommands,
  EditorCommands,
  MDELocalCommands
} from '@inkdropapp/types'

Each command map is a record of command names to their parameter types. Commands that take no parameters use undefined:

// EnvironmentCommands
'core:new-note': undefined
'core:open-note': { noteId: string; revision?: string; viewMode?: EditorViewMode }

// EditorCommands
'core:save-note': undefined
'editor:insert-text': { text: string; selection?: { anchor: number; head?: number } }

Available command scopes: EnvironmentCommands, WindowCommands, ApplicationCommands, EditorCommands, MDECommands, MDELocalCommands, MDEPreviewCommands, MDEPreviewLocalCommands, FindInNoteGlobalCommands, FindInNoteOnEditorLocalCommands, FindInNoteOnPreviewLocalCommands, NoteListBarLayoutCommands, NoteListBarCommands, NoteListSearchBarCommands, SidebarNavigationCommands, SidebarMenuCommands, SidebarMenuLocalCommands, SideBarMenuItemCommands, SidebarWorkspaceMenuCommands, SidebarWorkspaceMenuLocalCommands, EditorDrawerCommands, MainLayoutCommands, MDESearchBarLocalCommands, PreviewFindBarLocalCommands.

Importing individual types

All type definitions are also importable from @inkdropapp/types directly:

import type {
  Environment,
  Config,
  CommandRegistry,
  NotificationManager,
  IPCLocalDatabase,
  KeymapManager,
  PackageManager,
  MarkdownRenderer,
  ModelNote,
  ModelBook,
  Logger,
  EnvironmentCommands,
  EditorCommands
} from '@inkdropapp/types'

What's included

Environment & managers

| Type | Description | | --------------------- | -------------------------------------------------------- | | Environment | The main application environment (inkdrop global) | | IInkdropPlugin | The lifecycle contract a plugin's main module implements | | Config | Application configuration with schema enforcement | | CommandRegistry | Register and dispatch commands | | KeymapManager | Keybinding management | | NotificationManager | User notifications | | PackageManager | Plugin lifecycle management | | ThemeManager | Theme management | | ComponentManager | Custom React component registry | | LayoutManager | UI layout management | | StyleManager | Stylesheet management | | MenuManager | Application menu management | | ContextMenuManager | Context menu management | | TelescopeManager | Telescope (command palette) sources | | MarkdownRenderer | Markdown-to-React rendering pipeline | | ApplicationDelegate | Platform-specific application delegate |

Commands

| Type | Description | | --------------------------- | ------------------------------------------------------------------------------------- | | EnvironmentCommands | Commands on the global scope (core:new-note, core:open-note, etc.) | | WindowCommands | Window management commands (window:reload, window:close, etc.) | | ApplicationCommands | Application-level commands (application:quit, application:open-preferences, etc.) | | EditorCommands | Editor component commands (core:save-note, editor:insert-images, etc.) | | MDECommands | Markdown editor global commands (editor:focus-mde, editor:add-extension, etc.) | | MDELocalCommands | Markdown editor local commands (cursor movement, text formatting, etc.) | | MDEPreviewCommands | Preview pane commands | | FindInNoteGlobalCommands | Find/replace commands (global) | | NoteListBarLayoutCommands | Note list navigation commands | | SidebarMenuCommands | Sidebar commands | | MainLayoutCommands | Layout toggle commands | | EditorViewMode | Editor view mode union type ('preview' \| 'sideBySide' \| 'edit') |

IPC (Inter-Process Communication)

| Type | Description | | ------------------ | --------------------------------------------------------- | | IPCLocalDatabase | Local PouchDB database access (notes, books, tags, files) | | IPCWindow | Window management | | IPCDialog | Native dialog access | | IPCClipboard | Clipboard access |

'inkdrop' module types

| Type | Description | | ------------------------------------------------- | --------------------- | | ModelNote, ModelBook, ModelTag, ModelFile | ORM model classes | | Logger | Logger interface | | NoteExportHelper, NoteExporter | Note export utilities | | NoteImportHelper, NoteImporter | Note import utilities | | UseModalResult, ModalState | Modal hook types |

Dependencies

This package depends on the following for their type definitions. Inkdrop provides these at runtime -- plugins should externalize them in their bundler config:

• @codemirror/commands, @codemirror/language, @codemirror/search, @codemirror/state, @codemirror/view
• inkdrop-model
• redux
• glob

Links

• Inkdrop Plugin Development Guide
• Inkdrop SDK Repository