Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
docs: carry the ESM build knowledge into the skills and CLAUDE.md
Elian Doran48e2964804db
diff --git a/.claude/skills/adding-llm-mcp-tools/SKILL.md b/.claude/skills/adding-llm-mcp-tools/SKILL.mdindex e54acd8b36..7580a158c5 100644--- a/.claude/skills/adding-llm-mcp-tools/SKILL.md+++ b/.claude/skills/adding-llm-mcp-tools/SKILL.md@@ -32,7 +32,7 @@ Rule: **any tool that writes** (`setContent`, `save`, `setAttribute`, `createNew## Footgun #3: a new *module* is invisible until registered-`allToolRegistries` (`packages/trilium-core/src/services/llm/tools/index.ts:33`) is the **single wiring point** iterated by both `mcp_server.ts:47` and `base_provider.ts:390` (`llm/providers/base_provider.ts`, `Object.assign(tools, registry.toToolSet())`). Adding a tool to an **existing** module (e.g. another entry in `note_tools.ts`) needs no wiring. Creating a **new** module means: `export const xTools = defineTools({...})`, add the `export`/`import` lines in `index.ts`, and append `xTools` to the `allToolRegistries` array. Miss the array and chat + MCP both never see it.+`allToolRegistries` (`packages/trilium-core/src/services/llm/tools/index.ts:34`) is the **single wiring point** iterated by both `mcp_server.ts:51` and `base_provider.ts:389` (`llm/providers/base_provider.ts`, `Object.assign(tools, registry.toToolSet())`). Adding a tool to an **existing** module (e.g. another entry in `note_tools.ts`) needs no wiring. Creating a **new** module means: `export const xTools = defineTools({...})`, add the `export`/`import` lines in `index.ts`, and append `xTools` to the `allToolRegistries` array. Miss the array and chat + MCP both never see it.**Node-only tools take the other door.** A tool that needs something core cannot have in the browser(the in-app documentation reader, for instance) lives in `apps/server/src/services/llm/tools/`@@ -105,7 +105,7 @@ The two harness patterns are spelled out fully in the reference — don't re-der- [ ] `execute` is not `async` and returns no Promise (typecheck rejects it otherwise — run `pnpm typecheck`).- [ ] Every write tool has `mutates: true`.-- [ ] A brand-new module is in `allToolRegistries` (`index.ts:33`).+- [ ] A brand-new module is in `allToolRegistries` (`index.ts:34`).- [ ] All failure branches `return { error }`; the only `throw`s are service calls wrapped in try/catch.- [ ] Protected/system-note guards present and ordered (table above).- [ ] Friendly name added under `llm.tools.<name>` in `en/translation.json`, imperative tense.diff --git a/.claude/skills/analyzing-backend-bundle/SKILL.md b/.claude/skills/analyzing-backend-bundle/SKILL.mdindex 752ff5fea0..997d1cd10a 100644--- a/.claude/skills/analyzing-backend-bundle/SKILL.md+++ b/.claude/skills/analyzing-backend-bundle/SKILL.md@@ -18,10 +18,14 @@ first needs it. Every megabyte the process loads at startup costs three ways, pe`NODE_COMPILE_CACHE` roughly halves it on warm starts.- **Bytecode and metadata** in the JS heap.-Reference points (2026-08, Node 22, real 146 MB DB): the monolithic 14.6 MB CJS bundle cost-221 MB RSS / 77 MB heap; the split ESM build loading 9 MB at startup cost 135 MB / 54 MB.-So the question that matters is never "how big is the bundle" but **"how much of it loads at-startup"** — and the tools here answer it with runtime evidence, not static guessing.+Reference points (2026-08, Node 22, real 146 MB DB, same source built both ways; the full+table is in PR #11111): the monolithic 14.8 MB CJS bundle cost 207 MB RSS / 64 MB heap+post-GC and 1 177 ms to first HTTP response; the split ESM build loaded 7.65 MB at startup+and cost 120 MB / 42 MB and 895 ms, with the V8 parser's native peak down from 78 MB to+21 MB. ESM *without* seams matched CJS on every metric — splitting only pays through+dynamic-import boundaries. So the question that matters is never "how big is the bundle" but+**"how much of it loads at startup"** — and the tools here answer it with runtime evidence,+not static guessing.## Tools@@ -58,6 +62,10 @@ node .claude/skills/analyzing-backend-bundle/check-dynamic-imports.mjs apps/servenv $ENV node --expose-gc .claude/skills/analyzing-backend-bundle/profile-bundle.cjs \apps/server/dist/main.mjs --port 8123 --snapshot /tmp/s.heapsnapshot+# Startup speed (spawn -> first HTTP response, median of N runs):+env $ENV node .claude/skills/analyzing-backend-bundle/bench-startup.mjs \+ apps/server/dist/main.mjs 5+# What the heap actually retains (proves which chunk sources are resident):node --max-old-space-size=8192 .claude/skills/analyzing-backend-bundle/heap-strings.mjs \/tmp/s.heapsnapshotdiff --git a/.claude/skills/analyzing-backend-bundle/bench-startup.mjs b/.claude/skills/analyzing-backend-bundle/bench-startup.mjsnew file mode 100644index 0000000000..725440aad7--- /dev/null+++ b/.claude/skills/analyzing-backend-bundle/bench-startup.mjs@@ -0,0 +1,42 @@+// Times spawn -> first HTTP response for a backend bundle, N runs, and prints+// the median. The caller supplies the TRILIUM_* environment; TRILIUM_PORT is+// also the probe target.+//+// env $ENV node bench-startup.mjs <bundle.mjs|bundle.cjs> [runs=5]+import { spawn } from "node:child_process";+import http from "node:http";++const [bundle, runsArg] = process.argv.slice(2);+const runs = Number(runsArg ?? "5");+const port = process.env.TRILIUM_PORT;++function probe() {+ return new Promise((resolve) => {+ const req = http.get({ host: "127.0.0.1", port, path: "/" }, (res) => {+ res.resume();+ resolve(true);+ });+ req.on("error", () => resolve(false));+ });+}++const times = [];+for (let i = 0; i < runs; i++) {+ const start = performance.now();+ const arg = bundle.endsWith(".mjs")+ ? ["--input-type=module", "-e", `import(${JSON.stringify("file://" + bundle)})`]+ : ["-e", `require(${JSON.stringify(bundle)})`];+ const child = spawn(process.execPath, arg, { stdio: "ignore", env: process.env });+ for (;;) {+ if (await probe()) break;+ await new Promise((r) => setTimeout(r, 25));+ }+ const elapsed = performance.now() - start;+ times.push(elapsed);+ child.kill("SIGKILL");+ await new Promise((r) => child.on("exit", r));+ await new Promise((r) => setTimeout(r, 500));+ console.error(` run ${i + 1}: ${elapsed.toFixed(0)} ms`);+}+times.sort((a, b) => a - b);+console.log(`median ${times[Math.floor(times.length / 2)].toFixed(0)} ms, min ${times[0].toFixed(0)}, max ${times[times.length - 1].toFixed(0)}`);diff --git a/.claude/skills/developing-electron-desktop/SKILL.md b/.claude/skills/developing-electron-desktop/SKILL.mdindex 72edfdc81e..e1bc98c1c7 100644--- a/.claude/skills/developing-electron-desktop/SKILL.md+++ b/.claude/skills/developing-electron-desktop/SKILL.md@@ -134,6 +134,27 @@ Add a validator for any new channel that takes a path, a URL, or anything else t- Platform checks in main use `process.platform`; code shared with core uses `isElectron()`/`isMac()`/`isWindows()` from `@triliumnext/core` utils (functions, only after `initializeCore()`).- The preload is compiled to **CJS** (`src/preload.compiled.cjs`, gitignored) — dev by `scripts/electron-start.mts`, prod by `apps/desktop/scripts/build.ts` — because Electron's sandboxed renderer can only load CJS preloads. Don't import ESM-only things into `preload.ts`.+## The main bundle is ESM with code splitting++`scripts/build.ts` builds `src/main.ts` with `buildBackend(..., { format: "esm" })`: the+production entry is **`dist/main.mjs`** plus lazy chunks under `dist/chunks/` (the generated+`dist/package.json` points Electron's `main` at it). The preload and `image_worker.cjs` stay+CJS — the sandboxed renderer can't load an ESM preload, and the worker is spawned by its+`.cjs` path. Three rules follow:++- **`__dirname` in bundled code means the bundle root, even inside a chunk** — the ESM banner+ in `scripts/build-utils.ts` resolves a chunk's `__dirname` one level up on purpose, because+ bundled code locates `preload.cjs`, `image_worker.cjs` and `assets/` as siblings of the+ entry. Don't "simplify" the banner, and don't path-math around it in app code.+- **Dynamically importing a CommonJS package needs the interop read**: `const mod = await+ import("cjs-pkg"); const { x } = mod.default ?? mod;`. Destructuring the namespace directly+ yields `undefined` in split ESM output, and unit tests mock past it. After adding a seam,+ run `node .claude/skills/analyzing-backend-bundle/check-dynamic-imports.mjs apps/desktop/dist`.+- A new heavy dependency belongs behind a dynamic `import()` at its (async) call site, so it+ lands in a lazy chunk instead of the startup path — measured on identical boots, ESM ++ seams took the desktop main process from 348 MB to 287 MB RSS. The+ **`analyzing-backend-bundle` skill** has the measurement tools and the seam patterns.+## Running| Command | What it does |@@ -141,7 +162,7 @@ Add a validator for any new channel that takes a path, a URL, or anything else t| `pnpm desktop:start` | dev app on port 37743, data in `apps/desktop/data`, Electron profile in `data-electron-37742`; HTTP cache disabled in dev so stale prod assets don't shadow fresh output || `pnpm desktop:start-prod` | `build` + run `dist/` like a release (port 37841, separate data dirs) || `pnpm --filter desktop electron-forge:make` / `:package` | full installers / unpacked app |-| `pnpm --filter desktop e2e` | Playwright against `dist/main.cjs` (builds first) |+| `pnpm --filter desktop e2e` | Playwright against `dist/main.mjs` (builds first) |Known launch-time noise and failures — do not "fix" these in app code:@@ -153,7 +174,7 @@ Known launch-time noise and failures — do not "fix" these in app code:- `pnpm --filter desktop test [pattern]` — Vitest, node environment, `src/**/*.spec.ts`. Specs `vi.mock("electron", …)` and assert on the recorded `ipcMain`/`ipcRenderer` calls (see `preload.spec.ts`, `services/shell.spec.ts` for the pattern). `vitest.config.mts` sets `ELECTRON_OVERRIDE_DIST_PATH` so a dynamic `import("electron")` doesn't blow up where the binary isn't installed — don't remove it.- The desktop suite also boots server pieces (`TRILIUM_INTEGRATION_TEST: "memory"`), so it is slower than a client spec; keep the pattern narrow.-- `spec/build-checks/artifacts.spec.ts` asserts the contents of a built `dist/` (client, assets, `better-sqlite3`, …). It is outside the default `include`, so run it explicitly after `pnpm desktop:build` when touching `scripts/build.ts` or the asset copies (`schema.sql`, `llm/skills`, `share-theme/templates`).+- `spec/build-checks/artifacts.spec.ts` asserts the contents of a built `dist/` (client, assets, `better-sqlite3`, …). It is outside the default `include`, so run it explicitly (`npx vitest run --config vitest.build.config.mts`) after `pnpm desktop:build` when touching `scripts/build.ts` or the asset copies (`schema.sql`, `llm/skills`, `share-theme/templates`). Known broken as of 2026-08: it dies at *import* time — `resource_dir.ts` calls `process.exit(1)` under vitest because `TRILIUM_RESOURCE_DIR` is unset in that config — before running any assertion, with or without your changes. Fix the harness env or verify the dist by hand; don't read the failure as caused by your change.## Debugging the protocol / WebContents boundarydiff --git a/CLAUDE.md b/CLAUDE.mdindex 5b03a075a2..65af2331aa 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -124,7 +124,7 @@ Shared components live in `apps/client/src/widgets/react/` — **always** reuse- **Binary conversions** go through `packages/trilium-core/src/services/utils/binary.ts` (`wrapStringOrBuffer`/`unwrapStringOrBuffer` for `string | Uint8Array`, `encodeBase64`/`decodeBase64`, `encodeUtf8`/`decodeUtf8`; also exported as `binary_utils`), not hand-rolled `TextEncoder`/`Buffer.from()`.### Electron Desktop App-`apps/desktop` runs server + client in one Electron process; the renderer loads over the `trilium-app://` custom protocol and talks to main only through the preload bridge (`window.electronApi`, typed by `packages/commons/src/lib/electron_api_interface.ts`). `nodeIntegration` is off, `contextIsolation` is on, `@electron/remote` is gone — never `require("electron")` in client code. Adding an API means interface + `preload.ts` + an `ipcMain` handler in the owning service + a spec. Load the **`developing-electron-desktop` skill** for the recipe, the security model, running/launch errors and testing.+`apps/desktop` runs server + client in one Electron process; the renderer loads over the `trilium-app://` custom protocol and talks to main only through the preload bridge (`window.electronApi`, typed by `packages/commons/src/lib/electron_api_interface.ts`). The main process bundles to **ESM with code splitting** (`dist/main.mjs` + lazy `chunks/`, via `buildBackend(..., { format: "esm" })`); the preload and `image_worker.cjs` stay CJS. `nodeIntegration` is off, `contextIsolation` is on, `@electron/remote` is gone — never `require("electron")` in client code. Adding an API means interface + `preload.ts` + an `ipcMain` handler in the owning service + a spec. Load the **`developing-electron-desktop` skill** for the recipe, the security model, running/launch errors and testing.### Standalone (in-browser) app`apps/standalone` runs the client on the page and `@triliumnext/core` — plain JS — in a dedicated Web Worker over `@sqlite.org/sqlite-wasm` persisted in OPFS; a Web Lock elects the one tab that owns the database and the service worker forwards other tabs' API calls to it. Every core provider has a browser twin in `apps/standalone/src/lightweight/` — **a new provider or Node import in core breaks this build first.** Load the **`developing-standalone` skill** before touching `sw.ts`, `main.ts`, `local-server-worker.ts`, `lightweight/*` or `vite.config.mts`.@@ -168,6 +168,7 @@ Use `note.getOwnedAttribute()` for direct, `note.getAttribute()` for inherited.- **Protected notes**: Check `note.isContentAvailable()` before accessing content; use `note.getTitleOrProtected()` for safe title access- **Long operations**: Use `TaskContext` for progress reporting via WebSocket- **Event system** (`packages/trilium-core/src/services/events.ts`): Events emitted in order (notes → branches → attributes) during load for referential integrity+- **Backend lazy loading**: a heavy or rarely-used dependency in server/desktop code loads via dynamic `import()` inside its (async) call site, so the ESM split build puts it in a lazy chunk instead of the startup path. When the target is a **CommonJS** package, read it through the interop — `const mod = await import("pkg"); const { x } = mod.default ?? mod;` — a plain destructure of the namespace silently yields `undefined` in split ESM output, and unit tests mock past it. Measure and verify with the **`analyzing-backend-bundle` skill** (`check-dynamic-imports.mjs` catches the interop break)- **Search**: Expression-based, scoring happens in-memory — cannot add SQL-level LIMIT/OFFSET without losing scoring- **Widget cleanup**: Unsubscribe from events in `cleanup()`/`doDestroy()` to prevent memory leaks