ContextQMD
Back to Etherpad Lite

Admin UI

admin/README.md

3.2.04.4 KB
Original Source

Admin UI

Vite + React 19 single-page app served at /admin. Talks to the backend over socket.io for the existing settings / plugins / pads pages, and (when endpoints are added to the OpenAPI spec) over a typed REST client.

Scripts

ScriptWhat it does
pnpm devgen:api + Vite dev server (expects backend on :9001).
pnpm gen:apiRegenerates src/api/{schema.d.ts,version.ts} from the OpenAPI spec.
pnpm buildgen:api + tsc + vite build.
pnpm build-copySame, but writes into ../src/templates/admin.
pnpm testgen:api + smoke tests for the API client wiring.
pnpm lintESLint.

Typed API client

The admin uses openapi-typescript to generate types from src/node/hooks/express/openapi.ts, openapi-fetch for typed requests, and openapi-react-query for TanStack Query bindings.

Generated files

admin/src/api/schema.d.ts and admin/src/api/version.ts are generated by gen:api and gitignored — never commit them. They are produced by:

sh
pnpm --filter admin gen:api

admin/scripts/gen-api.mjs loads src/node/hooks/express/openapi.ts, calls generateDefinitionForVersion for the latest API version, pipes the JSON through openapi-typescript to produce schema.d.ts, and emits a runtime constant LATEST_API_VERSION (read from info.version in the spec) to version.ts so client.ts can build the right /api/<version>/ baseUrl.

gen:api runs as the first step of dev, build, build-copy, and test, so a fresh checkout produces the generated files automatically when any of those scripts is invoked. After modifying any of the following, the next pnpm <dev|build|test> will refresh the generated files; you can also run gen:api directly:

  • src/node/hooks/express/openapi.ts
  • src/node/handler/APIHandler.ts (changes to latestApiVersion)
  • the resource definitions referenced by openapi.ts

Using the client

tsx
import { $api } from './api/client';

const SettingsPanel = () => {
  const { data } = $api.useQuery('get', '/admin/settings'); // example
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
};

The admin endpoints are not yet present in the OpenAPI spec — this client is in place to support upcoming work (see issue #7638 follow-up). For now, it is exercised only by the smoke test.

Socket.io: padLoad query shape

The admin /settings namespace's padLoad event accepts a PadSearchQuery defined in src/node/types/PadSearchQuery.ts:

fieldtyperequirednotes
patternstringyesSubstring match on pad name.
offsetnumberyesPagination start, in items. Clamped server-side.
limitnumberyesPage size. Capped at 12.
ascendingbooleanyesSort direction.
sortBy"padName" | "lastEdited" | "userCount" | "revisionNumber"yesColumn to sort by.
filter"all" | "active" | "recent" | "empty" | "stale" (opt.)noFilter chip; defaults to "all". Applied before pagination so total and the page slice both reflect the filtered universe. Older clients that omit the field get the unchanged "all" behaviour.

Filter semantics — applied after pattern matching, before sort + slice:

  • active: userCount > 0
  • recent: edited within the last 7 days
  • empty: revisionNumber === 0
  • stale: not edited in the last 365 days
  • all / missing: no further filtering