Skip to content

Build your personal knowledge base with Trilium Notes

fix(web-clipper): make the Firefox sources zip build on its own

Elian Doran18b6617cf6ea
diff --git a/.claude/skills/developing-web-clipper/SKILL.md b/.claude/skills/developing-web-clipper/SKILL.md
index 111adf3d52..a0d467cd55 100644
--- a/.claude/skills/developing-web-clipper/SKILL.md
+++ b/.claude/skills/developing-web-clipper/SKILL.md
@@ -210,11 +210,15 @@ Check a manifest change in the built `manifest.json`, e.g.
CI (`.github/workflows/web-clipper.yml`) builds both zips; it runs no tests, so a
`web-clipper-v*` tag ships whatever the tagged commit holds — the tests run only in `dev.yml`, on
-pushes and pull requests. **Mozilla's review rebuilds from the
-sources zip**, which the `zip:sources:*` hooks assemble from `apps/web-clipper` plus a copied
-`tsconfig.base.json` and the Chrome-only offscreen page. Since the pages import
-`@triliumnext/client` stylesheets and fonts, those files must go into the sources zip as well — the
-hook does not do that yet, so fix it before the next Firefox submission.
+pushes and pull requests.
+
+**Mozilla's review rebuilds from the sources zip.** `zip.sourcesRoot` is the repository root and
+`zip.includeSources` an allowlist (WXT 0.21): the workspace files and lockfile, `apps/web-clipper`,
+and the `apps/client` stylesheets and fonts the pages import. A new import from outside
+`apps/web-clipper` goes on that list. The `zip:sources:done` hook adds the Chrome-only offscreen
+page, which WXT leaves out, and copies `README.md` (the reviewer's build instructions) to the
+archive root. WXT prints "Could not get stats of '…'" for every file of the sources zip, because it
+looks the paths up from the package directory rather than `sourcesRoot`; the archive is complete.
To compare bundle sizes with `main`, build it in a temporary `git worktree` (never stash). `main`
may still need dependencies the branch removed (`cash-dom`): give the worktree its own
diff --git a/apps/web-clipper/README.md b/apps/web-clipper/README.md
index 1f7cdc5768..03df10fccd 100644
--- a/apps/web-clipper/README.md
+++ b/apps/web-clipper/README.md
@@ -4,20 +4,25 @@
The Web Clipper is an extension for the Trilium Notes application, an open-source note-taking application that can be used either in standalone mode via the desktop application or connected to a server.
-The source is extracted from the official monorepo, where it can be found under `apps/web-clipper`. The only change made to the provided source code is to have `tsconfig.base.json` in the same directory as the Web Clipper. The submitted source code is a snapshot of the following commit: [https://github.com/TriliumNext/Trilium/commit/1cf93ff0dec89ee1a80654934cb30fad74920043](https://github.com/TriliumNext/Trilium/commit/1cf93ff0dec89ee1a80654934cb30fad74920043) 
+The extension lives in the official monorepo, [TriliumNext/Trilium](https://github.com/TriliumNext/Trilium), under `apps/web-clipper`. The sources archive holds the monorepo files the build reads, unchanged and at the same paths:
+
+- `apps/web-clipper`, the extension;
+- a few stylesheets and fonts from `apps/client`, the Trilium application, whose styles the popup and options page share;
+- the workspace files: `package.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, `tsconfig.base.json` and `patches/`.
+
+Each release is a snapshot of the commit tagged `web-clipper-v` followed by the version in `apps/web-clipper/package.json`.
There are some warnings regarding the use of `innerHTML`. They come from [`defuddle`](https://github.com/kepano/defuddle), the article extraction library behind the Obsidian Web Clipper, which the extension installs unmodified from npm. It runs only when the user opens the popup or saves a page, and it removes scripts, event handler attributes and `javascript:` URLs from the article it returns.
## Building from source
-To build from the provided sources:
+Requirements: Node.js 24 and pnpm 12.10.1 (`npm install -g [email protected]`).
-1. `pnpm i` to install the dependencies.
-2. `pnpm build:firefox` to trigger the Firefox build.
-3. The output will be available in `.output/firefox-mv2`.
+From the root of the sources archive:
-> [!NOTE]
-> To generate the ZIP instead that can be imported into Firefox, run `pnpm zip;firefox` which will generate `.output\triliumnextweb-clipper-1.0.1-sources.zip`.
+1. `pnpm install --filter web-clipper --frozen-lockfile` to install the dependencies.
+2. `pnpm --filter web-clipper build:firefox` to build the Firefox extension.
+3. The output will be available in `apps/web-clipper/.output/firefox-mv2`.
## Testing
@@ -28,4 +33,4 @@ To test it, a functional Trilium Notes desktop application is required:
3. Allow the Firewall port if asked.
4. Install the Web Clipper extension into the browser.
5. The extension should be able to see the Trilium instance and become active.
-6. Web pages can now be clipped and they will appear in the local Trilium instance.
\ No newline at end of file
+6. Web pages can now be clipped and they will appear in the local Trilium instance.
diff --git a/apps/web-clipper/wxt.config.ts b/apps/web-clipper/wxt.config.ts
index 4a27b5c8fb..e81d21dcd0 100644
--- a/apps/web-clipper/wxt.config.ts
+++ b/apps/web-clipper/wxt.config.ts
@@ -1,11 +1,9 @@
import { mkdirSync } from "fs";
-import { copyFile, readFile, rm, writeFile } from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
import JSZip from "jszip";
import { resolve } from "path";
import { defineConfig } from "wxt";
-let originalTsConfig: object;
-
export default defineConfig({
webExt: {
// A persistent profile keeps the toolbar pin and the extension's settings across dev runs.
@@ -80,7 +78,29 @@ export default defineConfig({
}
}),
zip: {
- artifactTemplate: "trilium-web-clipper-{{version}}-{{browser}}.zip"
+ artifactTemplate: "trilium-web-clipper-{{version}}-{{browser}}.zip",
+ sourcesTemplate: "trilium-web-clipper-{{version}}-sources.zip",
+ // AMO rebuilds the extension from the sources zip, so it holds the monorepo files the
+ // build reads: the workspace and lockfile, the clipper, and the client styles and fonts.
+ sourcesRoot: resolve("../.."),
+ includeSources: [
+ "package.json",
+ "pnpm-workspace.yaml",
+ "pnpm-lock.yaml",
+ "tsconfig.base.json",
+ "patches/**",
+ "apps/web-clipper/**",
+ "apps/client/package.json",
+ "apps/client/src/stylesheets/buttons.css",
+ "apps/client/src/stylesheets/theme-next/buttons.css",
+ "apps/client/src/stylesheets/theme-next/forms.css",
+ "apps/client/src/fonts/Inter/**",
+ "apps/client/src/fonts/JetBrainsMono-Light.woff2"
+ ],
+ excludeSources: [
+ "apps/web-clipper/test-output/**",
+ "apps/web-clipper/*.tsbuildinfo"
+ ]
},
hooks: {
"build:manifestGenerated": (wxt, manifest) => {
@@ -90,29 +110,14 @@ export default defineConfig({
Object.assign(action, { default_area: "navbar" });
}
},
- 'zip:sources:start': async () => {
- // Rewrite tsconfig.base.json into the web-clipper app folder
- await copyFile("../../tsconfig.base.json", "./tsconfig.base.json");
-
- originalTsConfig = JSON.parse(await readFile("./tsconfig.json", "utf-8"));
- const adjustedTsConfig = {
- ...originalTsConfig,
- extends: ["./tsconfig.base.json", "./.wxt/tsconfig.json"]
- };
-
- await writeFile("./tsconfig.json", JSON.stringify(adjustedTsConfig, null, 4), 'utf-8');
- },
"zip:sources:done": async (_wxt, sourcesZipPath) => {
- // Restore original tsconfig.json
- await writeFile("./tsconfig.json", JSON.stringify(originalTsConfig, null, 4), 'utf-8');
-
- // Remove the copied tsconfig.base.json
- await rm("./tsconfig.base.json");
-
// wxt always excludes skipped entrypoints (offscreen is Chrome-only) from the
// sources zip, but AMO needs complete sources to reproduce the build.
const archive = await JSZip.loadAsync(await readFile(sourcesZipPath));
- archive.file("entrypoints/offscreen/index.html", await readFile("entrypoints/offscreen/index.html"));
+ archive.file("apps/web-clipper/entrypoints/offscreen/index.html",
+ await readFile("entrypoints/offscreen/index.html"));
+ // The reviewer's build instructions, where the archive opens.
+ archive.file("README.md", await readFile("README.md"));
await writeFile(sourcesZipPath, await archive.generateAsync({
type: "nodebuffer",
compression: "DEFLATE"
diff --git a/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md b/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
index bcad932b41..fbe26ffc75 100644
--- a/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
+++ b/docs/Developer Guide/Developer Guide/Concepts/Web Clipper.md
@@ -33,7 +33,9 @@ The default port is:
## Building
* Run `build` (Chrome) or `build:firefox` to generate the output files, which will be in `.output/[browser]`.
-* Run `zip` or `zip:firefox` to generate the ZIP files.
+* Run `zip` or `zip:firefox` to generate the ZIP files. `zip:firefox` also generates the sources ZIP that Mozilla's reviewers build the extension from.
+
+The sources ZIP has the monorepo's layout: the workspace files and lockfile, `apps/web-clipper`, and the stylesheets and fonts the Clipper imports from `apps/client`, listed in `zip.includeSources` in `wxt.config.ts`. A new import from outside `apps/web-clipper` must be added to that list. `apps/web-clipper/README.md`, which tells the reviewers how to build, is copied to the root of the ZIP.
## CI