Backend esm vitest

.github/workflows/backend-tests.yml

@@ -84,9 +84,6 @@ jobs:
           path: node-report/
           if-no-files-found: ignore
           retention-days: 7
-      - name: Run the new vitest tests
-        working-directory: src
-        run: pnpm run test:vitest
 
   withpluginsLinux:
     env:
@@ -134,6 +131,14 @@ jobs:
       - name: Build admin ui
         working-directory: admin
         run: pnpm build
+      -
+        name: Build ep_etherpad-lite (dist + dist-cjs)
+        working-directory: src
+        run: pnpm run build
+      -
+        name: Verify exports map
+        working-directory: src
+        run: pnpm run check:exports
       -
         name: Install Etherpad plugins
         run: >
@@ -166,9 +171,6 @@ jobs:
           path: node-report/
           if-no-files-found: ignore
           retention-days: 7
-      - name: Run the new vitest tests
-        working-directory: src
-        run: pnpm run test:vitest
 
   # Windows tests only run on push to develop/master, not on PRs
   withoutpluginsWindows:
@@ -222,11 +224,7 @@ jobs:
           NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
         run: |
           mkdir -p "${{ github.workspace }}/node-report"
-          # --exit forces process.exit(failures) after the suite completes,
-          # closing the post-suite event-loop drain window where Windows +
-          # Node 24 hard-kills the process. Scoped to Windows so Linux/local
-          # runs still surface real handle leaks via natural drain.
-          pnpm test -- --exit
+          pnpm test
       - name: Upload Node diagnostic reports on failure
         if: ${{ failure() }}
         uses: actions/upload-artifact@v7
@@ -235,9 +233,6 @@ jobs:
           path: node-report/
           if-no-files-found: ignore
           retention-days: 7
-      - name: Run the new vitest tests
-        working-directory: src
-        run: pnpm run test:vitest
 
   withpluginsWindows:
     env:
@@ -277,6 +272,14 @@ jobs:
       - name: Build admin ui
         working-directory: admin
         run: pnpm build
+      -
+        name: Build ep_etherpad-lite (dist + dist-cjs)
+        working-directory: src
+        run: pnpm run build
+      -
+        name: Verify exports map
+        working-directory: src
+        run: pnpm run check:exports
       -
         name: Install Etherpad plugins
         run: >
@@ -319,11 +322,7 @@ jobs:
           NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
         run: |
           mkdir -p "${{ github.workspace }}/node-report"
-          # --exit forces process.exit(failures) after the suite completes,
-          # closing the post-suite event-loop drain window where Windows +
-          # Node 24 hard-kills the process. Scoped to Windows so Linux/local
-          # runs still surface real handle leaks via natural drain.
-          pnpm test -- --exit
+          pnpm test
       - name: Upload Node diagnostic reports on failure
         if: ${{ failure() }}
         uses: actions/upload-artifact@v7
@@ -332,6 +331,3 @@ jobs:
           path: node-report/
           if-no-files-found: ignore
           retention-days: 7
-      - name: Run the new vitest tests
-        working-directory: src
-        run: pnpm run test:vitest

.gitignore

@@ -46,3 +46,7 @@ prime/
 
 # Local git worktrees used by /release-review and similar workflows.
 /.worktrees/
+
+# tsdown dual-emit build outputs.
+src/dist/
+src/dist-cjs/

CHANGELOG.md

@@ -72,7 +72,7 @@ A bundle of defence-in-depth tightening picked up during an internal audit pass
 
 # 3.0.0
 
-3.0 is a feature-heavy release that closes out the self-update programme (Tiers 2 and 3 land alongside Tier 1 from 2.7.3), removes the last identified upstream telemetry vector, and ships a parsed JSONC settings editor, native DOCX export, in-place pad history scrubbing, and an admin UI for GDPR author erasure. It also marks the start of the broader Etherpad app ecosystem (see *Companion apps* below).
+3.0 is a feature-heavy release that closes out the self-update programme (Tiers 2 and 3 land alongside Tier 1 from 2.7.3), removes the last identified upstream telemetry vector, and ships a parsed JSONC settings editor, native DOCX export, in-place pad history scrubbing, and an admin UI for GDPR author erasure. It also completes the backend ESM migration and replaces mocha with vitest as the backend test runner, and marks the start of the broader Etherpad app ecosystem (see *Companion apps* below).
 
 ### Breaking changes
 
@@ -81,6 +81,11 @@ A bundle of defence-in-depth tightening picked up during an internal audit pass
 - **`swagger-ui-express` removed.** `/api-docs` now serves a vendored, telemetry-free copy of [Scalar](https://github.com/scalar/scalar) (see the privacy item below). The route, the OpenAPI document, and the rendered output are unchanged for downstream consumers, but anything that introspected `swagger-ui-express` internals will need updating.
 - **Debian package depends on `nodejs (>= 24)`.** The signed apt repository at `etherpad.org/apt` is rebuilt against this floor; older Node packages are no longer acceptable as a dependency (#7754).
 
+### Breaking changes for plugin authors
+
+- Migrated the Etherpad backend (everything under `src/node/` and the server-side parts of `src/static/js/pluginfw/`) from CommonJS to ECMAScript modules. **Existing CommonJS plugins continue to load unchanged** — the plugin loader now uses Node's `createRequire` to keep `require()` working synchronously against CJS plugin entry files. ESM plugins are also supported (use `"type": "module"` or `.mjs`, export hooks with `export const`). One contract change: the accessor-property shim that exposed `Settings` top-level fields directly on the `require()` result has been removed (it was dead code under ESM). Plugins reading core settings via `require('ep_etherpad-lite/node/utils/Settings').toolbar` must now use `import settings from '...'` (ESM) or `require('...').default.toolbar` (CJS via the bridge). See `doc/plugins.md` for the full updated contract.
+- Replaced mocha with vitest as the backend test runner. `pnpm test` now runs vitest. Plugin authors with backend test suites that ran under the core mocha runner via `../node_modules/ep_*/static/tests/backend/specs/**` should expect to migrate their tests to vitest.
+
 ### Companion apps
 
 This release coincides with the launch of two ecosystem projects, both maintained under the [`ether` org](https://github.com/ether) and able to talk to any 3.x Etherpad server over its existing HTTP / WebSocket API:

Dockerfile

@@ -23,6 +23,10 @@ WORKDIR /opt/etherpad-lite
 COPY . .
 RUN pnpm install
 RUN pnpm run build:ui
+# tsdown lives in src/'s devDependencies, which the production stage
+# below strips via installDeps.sh. Run the build here (where devDeps
+# are intact) and COPY dist + dist-cjs into the production image.
+RUN cd src && pnpm run build
 
 
 FROM node:24-alpine AS build
@@ -187,6 +191,14 @@ RUN printf 'packages:\n  - src\n  - bin\nonlyBuiltDependencies:\n  - esbuild\nig
 COPY --chown=etherpad:etherpad ./src ./src
 COPY --chown=etherpad:etherpad --from=adminbuild /opt/etherpad-lite/src/templates/admin ./src/templates/admin
 COPY --chown=etherpad:etherpad --from=adminbuild /opt/etherpad-lite/src/static/oidc ./src/static/oidc
+# Reuse the dual ESM/CJS surface produced by the adminbuild stage. The
+# runtime esbuild-bundles the client JS at server startup and resolves
+# `ep_etherpad-lite/static/js/*` through the package's exports map,
+# which now points at dist/ + dist-cjs/. tsdown only exists in src/'s
+# devDependencies and installDeps.sh below strips those, so we can't
+# build here — instead pick up what adminbuild already built.
+COPY --chown=etherpad:etherpad --from=adminbuild /opt/etherpad-lite/src/dist ./src/dist
+COPY --chown=etherpad:etherpad --from=adminbuild /opt/etherpad-lite/src/dist-cjs ./src/dist-cjs
 
 COPY --chown=etherpad:etherpad ./local_plugin[s] ./local_plugins/
 
@@ -222,4 +234,9 @@ EXPOSE 9001
 # verified during build. See ether/etherpad#7718.
 # `exec` makes node PID 1 so it receives SIGTERM directly and shuts down
 # cleanly.
-CMD ["sh", "-c", "cd src && exec node --require tsx/cjs node/server.ts"]
+# server.ts is loaded as an ESM module (uses `import`/`export` syntax),
+# so the ESM-aware tsx hook (`--import tsx`) is required. `--require
+# tsx/cjs` only intercepts CJS resolution and would leave Node's native
+# ESM resolver to crash on the first `import './foo.js'` that lacks a
+# matching file on disk (sources are .ts).
+CMD ["sh", "-c", "cd src && exec node --import tsx node/server.ts"]

bin/tsconfig.json

@@ -40,6 +40,11 @@
     // "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
     // "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
     "resolveJsonModule": true,                        /* Enable importing .json files. */
+    "baseUrl": ".",
+    "paths": {
+      "ep_etherpad-lite/*.js": ["../src/*.ts"],
+      "ep_etherpad-lite/*":    ["../src/*.ts", "../src/*"]
+    },
     // "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
     // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
 

doc/api/pluginfw.adoc

@@ -20,3 +20,63 @@ reference (filename for require() plus function name)
 ?
 
 === ...
+
+== Importing from `ep_etherpad-lite`
+
+Etherpad ships dual entry points so plugins authored in either CommonJS
+or ECMAScript Modules can consume core APIs.
+
+=== CJS plugins (default — most existing plugins)
+
+Use `require()` against extensionless or `.js` subpaths:
+
+[source,js]
+----
+const eejs        = require('ep_etherpad-lite/node/eejs');
+const PadManager  = require('ep_etherpad-lite/node/db/PadManager');
+const API         = require('ep_etherpad-lite/node/db/API.js');
+const padUtils    = require('ep_etherpad-lite/static/js/pad_utils');
+----
+
+These resolve through the package's `exports` map under the `require`
+condition and load CJS twins from `dist-cjs/`.
+
+NOTE: `require('ep_etherpad-lite/node/eejs/')` with a trailing slash is
+**not** supported. Drop the slash: `require('ep_etherpad-lite/node/eejs')`.
+
+NOTE: Some core modules (database modules under `node/db/*`) transitively
+depend on `ueberdb2` which is ESM-only. They can be resolved by
+`require.resolve` but cannot be synchronously loaded from CJS contexts.
+Plugins that actually use these modules at runtime must migrate to ESM
+(see below) or stop depending on them.
+
+=== ESM plugins (opt-in)
+
+Set `"type": "module"` in your plugin's `package.json`. Use `import` with
+explicit `.js` extensions:
+
+[source,js]
+----
+import * as eejs       from 'ep_etherpad-lite/node/eejs/index.js';
+import { getPad }      from 'ep_etherpad-lite/node/db/PadManager.js';
+import { randomString } from 'ep_etherpad-lite/static/js/pad_utils.js';
+----
+
+These resolve through the `import` condition and load ESM modules from
+`dist/`.
+
+=== Supported subpaths
+
+* `ep_etherpad-lite/node/*`         — server-side modules
+* `ep_etherpad-lite/node/eejs`      — template engine (no trailing slash)
+* `ep_etherpad-lite/static/js/*`    — code shared with the browser
+* `ep_etherpad-lite/tests/backend/*` — test helpers (only useful in plugin
+  tests; ESM only)
+
+=== What is NOT supported
+
+* Reaching into `src/...` or `dist/...` paths directly — only the subpaths
+  above are stable API.
+* Mixing `require()` and `import` inside the same plugin file. Pick one.
+* `require('ep_etherpad-lite/node/eejs/')` with trailing slash.
+* `require()` of database modules from CJS (use ESM imports instead).

doc/plugins.md

@@ -90,6 +90,18 @@ name of a function exported by the named module. See
 [`module.exports`](https://nodejs.org/docs/latest/api/modules.html#modules_module_exports)
 for how to export a function.
 
+> **Note (Etherpad ≥ 2.7.x):** the core was migrated to ECMAScript modules,
+> but the plugin loader uses Node's `createRequire` so existing CommonJS
+> plugins (the documented format above) continue to load unchanged. ESM
+> plugins are also supported — name your hook entry file with a `.mjs`
+> extension or set `"type": "module"` in your plugin's `package.json`, and
+> export hook functions with `export const`. One contract change: plugins
+> that previously read core settings via `require('ep_etherpad-lite/node/utils/Settings').toolbar`
+> must now use either `import settings from 'ep_etherpad-lite/node/utils/Settings'`
+> (ESM) or `require('ep_etherpad-lite/node/utils/Settings').default.toolbar`
+> (CJS via the bridge). The accessor-property shim that exposed top-level
+> fields directly on the require() result is gone.
+
 For the module name you can omit the `.js` suffix, and if the file is `index.js`
 you can use just the directory name. You can also omit the module name entirely,
 in which case it defaults to the plugin name (e.g., `ep_example`).