mirrors/TidGi-Desktop
1
Fork 0
mirror of https://github.com/tiddly-gittly/TidGi-Desktop.git synced 2026-03-07 22:40:40 -08:00
Code Issues Projects Releases Packages Wiki Activity
TidGi-Desktop/docs/TidGiServiceAPI.md
linonetwo b677088a48 Expose TidGi services to $tw.tidgi and add types 
Make TidGi IPC service proxies available inside the TiddlyWiki sandbox and provide typings for plugin authors. Added docs (docs/TidGiServiceAPI.md), bumped tidgi-shared to 0.1.2, and introduced shared type files (packages/tidgi-shared/src/{global.d.ts,tidgiGlobal.ts}) and tsconfig include for .d.ts files. Preload now exposes service via contextBridge and attaches it to $tw.tidgi.service (with DOMContentLoaded retry). Updated various wiki plugin files to use $tw.tidgi.service instead of window.service, adjusted worker-side service exports (no automatic global attach), and updated startNodeJSWiki to safely inject service into the wiki sandbox with proper typing. Added runtime TiddlyWiki type augmentations (src/types/tidgi-tw.d.ts). These changes ensure plugins running in the VM can reliably access typed service proxies.
2026-02-10 02:41:32 +08:00

1.6 KiB
Raw Blame History

TidGi Service API Usage

This document explains how TW plugins can call TidGi services and how the API is exposed across front-end and back-end.

Where services are exposed

TidGi exposes the same service proxies in two places:

  • Plugin runtime (TW sandbox): $tw.tidgi.service
  • Frontend runtime (renderer): window.service

Usage in plugins (TiddlyWiki route modules)

Route modules run inside TiddlyWiki’s VM sandbox, so globalThis is not the worker’s real global. Use $tw.tidgi.service.

Example:

import type { ITidGiGlobalService } from 'tidgi-shared';

const tidgiService = ($tw as typeof $tw & { tidgi?: { service?: ITidGiGlobalService } }).tidgi?.service;

Usage in renderer / WebView

Frontend UI code should keep using window.service.

await window.service.workspace.getActiveWorkspace();

How the API is wired

  • Service proxies are created in the wiki worker and preload using electron-ipc-cat.
  • Renderer (WebView): src/preload/common/exportServices.ts exposes proxies via contextBridge, assigns window.service, and attaches $tw.tidgi.service after $tw is ready.
  • Wiki worker: startNodeJSWiki.ts attaches the same proxies to $tw.tidgi.service before TiddlyWiki boot, so route modules can access them inside the sandbox.

Types for plugins

Use tidgi-shared for type-safe access. It also augments the global $tw shape so editors can resolve $tw.tidgi.service:

import type { IWorkspaceService } from 'tidgi-shared';

This package re-exports all service interfaces and IPC descriptors used by TidGi.