Project setup

1. Copy the contents of the source/ directory into src/ (or any source root) of your Node.js TypeScript project.

2. In tsconfig.json, enable ESM and set the module resolution to bundler or node16:

   {
     "compilerOptions": {
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "target": "ES2022",
       "outDir": "dist",
       "rootDir": "src",
       "esModuleInterop": true,
       "strict": true
     }
   }
   

3. Set "type": "module" in your package.json so Node.js treats .js output files as ESM.

4. Provide a data/ directory (configurable via env) that Trilium uses for its SQLite database and config:

   export TRILIUM_DATA_DIR=/absolute/path/to/data
   export TRILIUM_NETWORK_ACCESS=true   # expose to non-localhost
   export TRILIUM_PORT=8080
   

5. If you have a package.json sibling to source/, ensure it has a version field — routes/index.ts imports it directly via ../../package.json.

6. Run the application:

   node --experimental-vm-modules dist/main.js
   

Public API

startApplication (main.ts default export pattern)

// src/main.ts
async function startApplication(): Promise<void>;

Called once at process start. Initializes translations via initializeTranslations(), then dynamically imports and calls the default export of www.ts. Use this as your sole entry point; do not import www.ts directly before translations are ready.

initializeTranslations (services/i18n.ts)

import { initializeTranslations } from "./services/i18n.js";
await initializeTranslations(): Promise<void>;

Sets up i18next with filesystem backend and HTTP middleware integration. Must be awaited before any route handler that returns localized strings. Called automatically by startApplication().

getSemanticContext (services/llm/context/index.ts)

async function getSemanticContext(
  noteId: string,
  options?: { maxSimilarNotes?: number }
): Promise<string>;

Returns a plain-text semantic context string for the given note ID by delegating to the AI service manager's context service. Use when building LLM prompts that need surrounding note content. Returns a safe fallback string on error rather than throwing.

restChatService (services/llm/chat/index.ts — default export)

import restChatService from "./services/llm/chat/index.js";

Handles REST-based LLM chat sessions. Exported as the default from the chat module. Use when you need to create or continue a ChatSession against any configured LLM backend (OpenAI, Anthropic, etc.).

contextService (services/llm/context/services/index.ts — default export)

import contextService from "./services/llm/context/services/index.js";

Central entry point for context extraction. Wraps ContextService and QueryProcessor. Use directly when you need to call processQuery outside the normal chat flow, e.g., a custom search route.

Working examples

Scenario - Start the server programmatically

Embed the Trilium server inside another Node.js process, wait for it to be ready before continuing.

import { initializeTranslations } from "./src/services/i18n.js";

async function main() {
  // Must happen before any module that uses translated strings
  await initializeTranslations();

  // Dynamically import avoids loading Express before i18n is ready
  const startTriliumServer = (await import("./src/www.js")).default;
  await startTriliumServer();

  console.log("Trilium server is running");
}

main().catch((err) => {
  console.error("Failed to start Trilium:", err);
  process.exit(1);
});

Scenario - Retrieve semantic context for a note in a custom route

Add a custom Express route that returns LLM-ready context for a note by ID.

import express from "express";
import { getSemanticContext } from "./src/services/llm/context/index.js";

const router = express.Router();

router.get("/api/custom/note-context/:noteId", async (req, res) => {
  const { noteId } = req.params;
  const maxSimilarNotes = parseInt(req.query.max as string) || 5;

  try {
    const context = await getSemanticContext(noteId, { maxSimilarNotes });
    res.json({ noteId, context });
  } catch (err) {
    res.status(500).json({ error: "Context retrieval failed" });
  }
});

export default router;

Scenario - Use the context service's query processor directly

Decompose a user query into sub-queries before sending them to an LLM.

import { queryProcessor, contextService } from "./src/services/llm/context/services/index.js";
import type { DecomposedQuery } from "./src/services/llm/context/services/index.js";

async function buildAugmentedPrompt(userQuery: string, noteId: string): Promise<string> {
  // contextService.processQuery accepts a query string, an LLM service, and options
  const { default: aiServiceManager } = await import("./src/services/llm/ai_service_manager.js");
  const llmService = await aiServiceManager.getInstance().getService();

  const result = await contextService.processQuery(userQuery, llmService, {
    maxResults: 8,
    contextNoteId: noteId
  });

  return `Context:\n${result.context}\n\nUser question: ${userQuery}`;
}

File walkthrough

• main.ts - Sole process entry point; sequences i18n init before server boot.
• www.ts - Creates the Node.js HTTP(S) server, binds port, attaches WebSocket handlers.
• app.ts - Builds and exports the Express Application; registers all routers and middleware.
• anonymize.ts - Strips personal data from the SQLite database for bug reports.
• docker_healthcheck.ts - Tiny script that exits non-zero if the server does not respond.
• express.d.ts - Augments Express's Request interface with Trilium session/user fields.
• types.d.ts - Project-wide ambient declarations (e.g., global config shape).
• becca/ - Live in-memory entity cache; the source of truth for notes, branches, attributes at runtime.
• errors/ - Typed error subclasses (e.g., NotFoundError, ValidationError) consumed by route handlers.
• etapi/ - ETAPI v1 REST handlers; each file maps to a resource (notes, attachments, branches, etc.).
• migrations/ - Ordered SQL/TS migration files applied at startup when the DB version is behind.
• routes/ - Express routers for the main SPA index, login, custom JS/CSS, and API endpoints.
• services/ - All business logic: sql.ts (DB), sync/, search/, llm/, options.ts, log.ts, and more.
• share/ - Standalone share-page router and asset pipeline for publicly shared notes.
• assets/ - EJS view templates, schema.sql, static images, i18n JSON files, and sample config.

Common pitfalls and fixes

• better-sqlite3 build failure: Ensure node-gyp and a matching C++ toolchain are installed; run npm rebuild better-sqlite3 after switching Node.js versions.
• ESM .js extension required in imports: All internal imports use explicit .js extensions (e.g., ./services/i18n.js). Your tsconfig must use "moduleResolution": "NodeNext" or TypeScript will not resolve them.
• package.json version field missing: routes/index.ts does import packageJson from "../../package.json". If your layout differs, update the relative path or you will get a runtime import error.
• TRILIUM_DATA_DIR not set: The server will default to ~/trilium-data; in containerized or multi-tenant environments always set this explicitly to avoid data collisions.
• i18n imported before initializeTranslations(): Any module that calls t() before the await in main.ts will return empty strings. Keep initializeTranslations() as the very first await in your entry point.
• Dynamic import of www.js inside startApplication: This pattern is intentional to prevent module-level side effects before i18n is ready. Do not hoist the import to the top of main.ts.

Vibe-coding prompt template

I have a copy of the TriliumNext server backend source at `./source/` and its
integration guide at `./USAGE.md`. The upstream package is
`@triliumnext/source@0.95.0`.

Please help me integrate this backend into my existing Node.js TypeScript project:

1. Read USAGE.md fully before writing any code.
2. Identify which parts of `source/` I need to copy and where they should live
   in my project layout (describe the directory mapping).
3. Update my `tsconfig.json` and `package.json` to support ESM NodeNext resolution
   as described in USAGE.md.
4. Wire the server entry point (`source/main.ts`) so it starts after my own
   initialization logic completes.
5. Add a custom Express route that calls `getSemanticContext` from
   `source/services/llm/context/index.ts` and returns JSON.
6. Show me how to set required environment variables (`TRILIUM_DATA_DIR`,
   `TRILIUM_PORT`) in a `.env` file and load them before the server starts.
7. Provide a working `docker-compose.yml` snippet that mounts a data volume and
   sets those env vars.

Use only the exports documented in USAGE.md and visible in the source files.
Do not invent any module paths or function signatures.

License and credit

TriliumNext is a fork of the original zadam/trilium project, now maintained at https://github.com/TriliumNext/Trilium. The upstream license applies to all files in source/; see source/LICENSE if present, or refer to the repository for the full AGPL-3.0 license text. Credit the TriliumNext contributors when redistributing or embedding this code.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。