Developing Web Clipper

Developing the web clipper

apps/web-clipper is a browser extension built with WXT (0.21, on Vite 8). One source tree produces two builds: Chrome, Manifest V3 (pnpm build, .output/chrome-mv3) and Firefox, Manifest V2 (pnpm build:firefox, .output/firefox-mv2). There is no Safari or Edge target. The manifest is generated from wxt.config.ts; there is no manifest.json in the repository.

The parts and how they talk

Everything goes through browser.runtime.sendMessage / browser.tabs.sendMessage, keyed by a name field:

• popup → background: save-cropped-screenshot, save-whole-screenshot, save-whole-page, save-link-with-note (title, content), save-tabs, trigger-trilium-search, send-trilium-search-status, trigger-trilium-search-note-url, openNoteInTrilium (noteId), closeTabs.
• background → popup: trilium-search-status (triliumSearch: TriliumSearchStatus, which starts as searching) and trilium-previously-visited (searchNote). Both types are exported from trilium_server_facade.ts; the popup imports them.
• background → content script: trilium-save-selection, trilium-save-page, trilium-get-rectangle-for-screenshot (the content script answers with the payload), and toast (message, noteId, tabIds).
• background → offscreen: { type: "CROP_IMAGE" }, the one message keyed by type.

Every user action in the background runs inside showFailures(), which turns an exception into a toast. A new action belongs inside it too, or it fails silently. A toast cannot show on browser pages or the extension stores, where no content script runs.

Finding and authenticating to Trilium

• Desktop first. getPort() returns the port from the options page, or 37840 (production) / 37743 (development build, the port pnpm desktop:start uses). It tries that one port — there is no port scan — with GET http://127.0.0.1:<port>/api/clipper/handshake, then falls back to the configured server. It repeats every 60 seconds, and on the popup's check button.
• Version check. The handshake returns protocolVersion (CLIPPER_PROTOCOL_VERSION in packages/trilium-core/src/services/app_info.ts); the extension compares the major version and reports version-mismatch.
• Desktop needs no auth; the routes rely on the loopback bind and the Host-header check in apps/server/src/services/desktop_network_gate.ts. A server needs an ETAPI token: the options page posts the password and the optional TOTP code to POST /api/login/token, which creates a token named "Trilium Sender / Web Clipper", stored in browser.storage.sync.
• Server routes are in apps/server/src/routes/routes.ts (/api/clipper/*) with the handlers in apps/server/src/routes/api/clipper.ts (spec: clipper.spec.ts). They are server-only, not in packages/trilium-core, so the standalone and mobile builds cannot receive clippings.
• The dev port must match TRILIUM_PORT in apps/desktop/package.json's dev script; when one changes, change getPort() and the Developer Guide's Web Clipper page with it.

Compatibility: the extension outlives the server version

Users update the extension and Trilium independently, so a change on one side must keep working against older versions of the other. Prefer changes that need nothing new from the server.

• /api/login/token has verified TOTP since v0.99.0, but only recent servers report which factor failed ({ message, factor }); older ones answer a 401 with a plain string. That is why the options page always shows the optional code field and sends it on the first try, and treats the factor only as a hint for the error message (requestToken() catches the JSON parse failure). Asking for the code only after a reported failure would have locked out every older 2FA server.
• The image-failure fix put a failed image's original URL back into the content instead of adding a server field, so the server's existing downloadImages() retries it on every version.
• /api/sender/login (Trilium Sender) shares the token handler; keep its 401 status unchanged.
• A server-side change reaches beyond the clipper spec: apps/server/src/routes/transport.spec.ts used /api/login/token to check plain-text tuple results, and the JSON body broke it. Grep the server specs for the route (grep -rn "api/login/token" apps/server/src apps/server/spec) and run every hit, not only the route's own spec.

Content and images

• The content script replaces each <img src> with a random 20-character placeholder (randomString(20)) and lists the images; the background fetches each one into a data URL; the server stores them as attachments and rewrites the placeholder. downloadImages() in core skips 20-character URLs on purpose, so an image left with its placeholder is a broken image. postProcessImages() therefore restores the original URL (escaped with escapeHtml()) for every image it cannot download and reports the count in the toast.
• A replaceAll()/replace() replacement built from page data is a callback (replaceAll(id, () => escapeHtml(src))). A string replacement reads $&, $$, $` and $' as patterns, so an image URL containing $& came back with the placeholder inside it.
• HTML built by concatenation escapes every page-derived value with escapeHtml() — the save-tabs list once put tab titles in raw. Tabs can also lack a url (still loading), and new URL("") throws, so saveTabs() filters them out.
• fetchImage() rejects a non-OK response and a non-image Content-Type — otherwise an error page gets saved as the "image".
• Readability is @mozilla/readability, installed from npm; Firefox review flags its innerHTML use, which the README explains to the reviewer.

The popup and options page: Preact in the Next theme

Both pages are Preact 11 (preact, preact/hooks), with JSX compiled by oxc.jsx in wxt.config.ts and jsx/jsxImportSource in tsconfig.json. Each index.html is only a #root and a <script src="main.tsx">; main.tsx renders the component and also exports it and its pure helpers (parseLinkNote, textToHtml, requestToken) for the specs.

Styling follows the share theme's approach (packages/share-theme/src/content/app_globals.ts, base.css): import the client's own stylesheets, carry the Next theme's colors.

• assets/theme.css, imported first by both pages, imports @triliumnext/client/src/stylesheets/theme-next/forms.css (which imports buttons.css). Those rules style elements by class, so use the app's markup:
  • command buttons: <button className="btn btn-secondary">, btn-primary for the main action, btn btn-sm for small ones. They only match button.btn — an <input type="submit"> stays unstyled.
  • text boxes: plain <input type="text|password"> and <textarea> are styled as they are.
  • check boxes: <label className="tn-checkbox"><input type="checkbox" /> text</label>.
• Colors are copied, not imported. theme.css carries the values of theme-next-light.css and theme-next-dark.css that those stylesheets read, under :root and @media (prefers-color-scheme: dark) — an extension page has no Trilium theme setting. A rule reading a new --variable needs its light and dark value added there, copied from those files. The connection status uses --status-ok/warning/error-color, the app's log status colors.
• theme.css also adds the bits of Bootstrap's reboot the app relies on (font: inherit on form controls, button cursor and line height) and the Inter font from apps/client/src/fonts/Inter/.
• Per-page CSS (popup.css, options.css) is nested under the page's root class (.popup, .options) and uses the tokens; no inline styles.
• Do not expect the client's Preact components to work. Only dependency-free ones (FormTextBox, FormSelect) can be imported; Button, FormCheckbox, NoteAutocomplete and the like pull in appContext, froca, i18n or Bootstrap's JS, which an extension page does not have. Build the small component the page needs on the same classes.
• Never href="javascript:" — Manifest V3's CSP can block it. Use href="#" with an onClick that calls preventDefault().

The cost of the theme: Inter is 349 kB and the shared CSS chunk 24 kB of the build.