fix: unblock the admin build on TypeScript 7

[JohnMcLear]

Supersedes #8142, which rolled TypeScript back to 6. This keeps us on 7 and fixes the actual incompatibility instead.

Problem

develop has been red since #8132 bumped typescript to ^7.0.2 — every PR fails at "Build admin ui":

node_modules/.pnpm/openapi-typescript@7.13.0_typescript@7.0.2/node_modules/openapi-typescript/dist/lib/ts.mjs:11
const BOOLEAN = ts.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
                           ^
TypeError: Cannot read properties of undefined (reading 'createKeywordTypeNode')

openapi-typescript builds its output with the TypeScript compiler API (ts.factory, ts.SyntaxKind, the printer). TypeScript 7 is the native port, and its main export is only ./lib/version.cjs:

"exports": {
  ".": "./lib/version.cjs",
  "./unstable/ast": "./dist/ast/index.js",
  ...
}

The compiler API isn't there at all. openapi-typescript's declared peer range is typescript: ^5.x and 7.13.0 is the newest published release, so there is nothing to upgrade to yet.

Why the obvious fixes don't work

openapi-typescript takes typescript as a peer dependency, so pnpm satisfies it from whichever package depends on it. While admin both depended on openapi-typescript and declared typescript: ^7.0.2, the peer always resolved to 7.

I tried both root-level mechanisms and verified neither works — pnpm still linked the _typescript@7.0.2 variant into admin:

overrides:
  openapi-typescript>typescript: ^6.0.3        # no effect on the peer
packageExtensions:
  openapi-typescript:
    peerDependencies: {typescript: ^6.0.3}     # no effect either

Fix

Isolate the one tool that can't move. openapi-typescript goes into a private, build-time-only workspace package — admin/tools/openapi-codegen — whose only TypeScript is 6.x. The peer then resolves to a version with a working compiler API, and admin keeps typescript: ^7.0.2 like every other workspace. gen-api.mjs invokes the tool through that package.

The codegen only runs at build time to emit admin/src/api/schema.d.ts, and that output is plain text which tsc 7 consumes normally. The regenerated file is byte-identical to the committed one, so there's no downstream churn.

The package's README records the reasoning and says to delete it once openapi-typescript supports the native compiler.

Verified locally

• all four workspaces report tsc 7.0.2 and typecheck clean (src, ui, bin, admin)
• admin gen:api succeeds; full pnpm build succeeds
• pnpm install --frozen-lockfile consistent (CI uses this)
• regenerated schema.d.ts byte-identical to the committed file
• backend suite: 1621 passing, 0 failing

Follow-up

Worth making the admin build a required check, so a dependency bump that breaks it can't land red again.

🤖 Generated with Claude Code

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Unblock admin OpenAPI codegen on TypeScript 7 by isolating TS6 toolchain

🐞 Bug fix ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Move OpenAPI type generation to a dedicated workspace package pinned to TypeScript 6.x.
• Update admin codegen script to run openapi-typescript via the isolated package.
• Adjust pnpm workspace/lockfile so admin keeps TypeScript ^7.0.2 without build failures.

Diagram

graph TD
  A["admin/scripts/gen-api.mjs"] --> B["@etherpad/openapi-codegen"] --> C["openapi-typescript (CLI)"] --> D["admin/src/api/schema.d.ts"] --> E["admin tsc (TypeScript 7)"] --> F["vite build"]
  C --> G["TypeScript 6.x (compiler API)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Downgrade TypeScript to 6.x across the workspace

• ➕ Simplest dependency graph; no extra workspace package needed
• ➕ Avoids TS7 export-map incompatibility everywhere
• ➖ Blocks adoption of TypeScript 7 across all packages
• ➖ Broader blast radius; risk of missing TS7-specific issues elsewhere

2. Run codegen via a one-off isolated runner (e.g., pnpm dlx / docker)

• ➕ Avoids adding a permanent workspace package
• ➕ Keeps isolation to the codegen invocation
• ➖ Harder to make reproducible/offline in CI
• ➖ More moving parts and less discoverable than a workspace tool package

3. Patch/fork openapi-typescript to support TypeScript 7’s exports

• ➕ Removes need for TS6 pinning once implemented
• ➕ Keeps codegen dependencies local to admin
• ➖ High maintenance until upstream releases; diverges from upstream
• ➖ Requires deep changes around TypeScript compiler API imports/packaging

Recommendation: Keep the PR’s approach: a private, build-time workspace package is the most reproducible and lowest-risk way to force openapi-typescript’s TypeScript peer to a compiler-API-compatible version while allowing the rest of the monorepo (including admin) to remain on TypeScript 7. Revisit and delete the package once openapi-typescript adds TS7 compatibility.

Files changed (6) +68 / -7

Bug fix (2) +6 / -2

package.jsonRemove openapi-typescript from admin devDependencies +0/-1

Remove openapi-typescript from admin devDependencies

• Drops openapi-typescript from the admin package so it no longer resolves the TypeScript 7 peer dependency that breaks codegen. Admin remains on TypeScript ^7.0.2 for normal builds.

admin/package.json

gen-api.mjsRun openapi-typescript via filtered workspace tool package +6/-1

Run openapi-typescript via filtered workspace tool package

• Changes the codegen invocation to 'pnpm --filter @etherpad/openapi-codegen exec openapi-typescript ...' so the CLI runs in a context where TypeScript is pinned to 6.x. Adds inline documentation explaining the TypeScript 7 compiler API incompatibility and pointing to the tool README.

admin/scripts/gen-api.mjs

Documentation (1) +31 / -0

README.mdDocument rationale for the isolated OpenAPI codegen package +31/-0

Document rationale for the isolated OpenAPI codegen package

• Introduces a README explaining why openapi-typescript must run against TypeScript 6.x (peer dependency + missing compiler API in TS7 exports). Includes explicit guidance to remove the package once upstream supports the native compiler setup.

admin/tools/openapi-codegen/README.md

Other (3) +31 / -5

package.jsonAdd private build-time codegen package pinning TypeScript 6.x +10/-0

Add private build-time codegen package pinning TypeScript 6.x

• Adds a private workspace package that depends on openapi-typescript and pins TypeScript to ^6.0.3 so the peer resolution provides a working compiler API. Intended for build-time use only; nothing ships at runtime.

admin/tools/openapi-codegen/package.json

pnpm-lock.yamlLock openapi-typescript against TypeScript 6.0.3 in the new tool package +18/-5

Lock openapi-typescript against TypeScript 6.0.3 in the new tool package

• Updates the lockfile to remove openapi-typescript from the admin importer and add it under admin/tools/openapi-codegen, resolving its TypeScript peer to 6.0.3. Adds the TypeScript 6.0.3 package entry and snapshot adjustments accordingly.

pnpm-lock.yaml

pnpm-workspace.yamlRegister admin/tools/openapi-codegen as a workspace package +3/-0

Register admin/tools/openapi-codegen as a workspace package

• Adds the new build-time-only openapi-codegen package to the pnpm workspace so it can be filtered/executed during admin code generation. Includes comments documenting why it exists.

pnpm-workspace.yaml

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗