Typesense DashboardTypesenseDashboard

The daily search workflow is not one task. It is a dozen small ones, usually scattered across tools. I wanted them adjacent: build a collection, import documents, tune a synonym, run the query, look at the metrics. Each Typesense resource gets one module under lib/typesense/, so collections.ts, documents.ts, synonyms.ts, search-overrides.ts and cluster-operations.ts each wrap one slice of the API. The pages under app/(app)/ stay thin over those wrappers. The interface keeps the API visible enough for a developer while giving destructive operations context and safer defaults.

Connection details come from environment variables first, then from an httpOnly cookie named typesense-connection-config that POST /api/save-connection writes. middleware.ts reads whichever it finds and calls the cluster /health endpoint behind a two second abort timeout. No configuration sends you to /setup. Configuration that will not answer sends you to /connection-error instead of into a half-broken screen. A healthy connection redirects / to /metrics. Server components then build a client per request through getServerTypesenseClient(), which reads the same cookie. Browser code shares one module-level singleton, and resetTypesenseClient() exists because that singleton has to be dropped when the connection changes.

Typesense gains capabilities between server releases, and showing every control to every user would create dead ends. The dashboard reads /debug, which returns the running version, and lib/typesense/version.ts compares it against a feature map.

export const FEATURE_MIN_VERSIONS: Record<string, string> = {
  stopwords: '26.0',
  conversationalSearch: '26.0',
  stemmingDictionaries: '28.0',
  naturalLanguageSearch: '29.0',
  synonymsGlobal: '30.0',
  diversifyResults: '30.0',
};

parseVersion handles both the old 0.25.2 scheme and the newer 27.1 one, so an old cluster still compares correctly. TypesenseVersionProvider puts hasFeature into context and the navigation hides what the server cannot do. When detection fails the provider is deliberately permissive and shows everything.

• The admin API key lives in a cookie. It is httpOnly, marked secure in production, and expires after fourteen days. A setup wizard becomes possible with no user database behind it. Anyone holding that browser profile also holds admin access to the cluster.
• Every wrapper in lib/typesense/ catches its own errors, logs to the console and returns null. Pages stay simple. A caller cannot tell an empty result from a failed call, and that is what I would change first.
• Monaco Editor is imported dynamically rather than bundled. JSON is the working surface for documents and schemas, and a textarea is the wrong tool for it. The first visit does not pay for an editor it may never open, at the cost of a visible pause when it does.
• The middleware health check runs on every request that is not exempt. Stale configuration surfaces immediately instead of as a failed page. It also adds a round trip to the cluster before anything renders.

Changing a live search schema should feel deliberate rather than dangerous, so aliases get a guided flow at /aliases. Create products_v3 with the new schema, load it from /collections/products_v3/documents/import, run the query in the search playground, then move the alias.

await createAlias('products', 'products_v2');
await updateAlias('products', 'products_v3');

The switch is atomic and products_v2 stays exactly where it was, so a rollback is one more updateAlias rather than an incident. The playground holds query, query_by, filters, timing, hit counts and per-result scores in one view, then copies the final request out as a curl command.

The version table in the README disagrees with FEATURE_MIN_VERSIONS in the code, and the code is what actually gates the navigation. Vitest covers version parsing and the resource wrappers under __tests__/, both against a mocked client, so nothing in the suite touches a real server. Cluster operations post straight to /operations/snapshot, /operations/db/compact and /operations/vote through an untyped apiCall escape hatch. Nothing authenticates the dashboard itself. It builds without a running cluster, works against Typesense Cloud or a self-hosted node, ships development and production Dockerfiles, and is MIT licensed.