@meshqljs/docs (@meshql/docs)

Interactive API docs and query playground for MeshQL — like Swagger UI or GraphQL Playground, served from your app.

Install

npmJSR

npm install @meshqljs/docs

npx jsr add @meshql/docs

Quick start (Express)

npmJSR

import express from "express";
import { createMesh } from "@meshqljs/core";
import { withDocs } from "@meshqljs/docs";
import { meshDocsExpressRouter } from "@meshqljs/docs/express";
import { meshExpressRouter } from "@meshqljs/http/express";

const mesh = createMesh(schema);
// ... resolvers, plugins

export const appMesh = withDocs(mesh, {
  path: "/docs",
  title: "My API",
  sql: "dev",
});

const app = express();
app.use(meshDocsExpressRouter(appMesh, appMesh.docs, "/docs"));
app.use("/api", meshExpressRouter(appMesh, "/api"));
app.listen(3000);

import express from "express";
import { createMesh } from "@meshql/core";
import { withDocs } from "@meshql/docs";
import { meshDocsExpressRouter } from "@meshql/docs/express";
import { meshExpressRouter } from "@meshql/http/express";

const mesh = createMesh(schema);
// ... resolvers, plugins

export const appMesh = withDocs(mesh, {
  path: "/docs",
  title: "My API",
  sql: "dev",
});

const app = express();
app.use(meshDocsExpressRouter(appMesh, appMesh.docs, "/docs"));
app.use("/api", meshExpressRouter(appMesh, "/api"));
app.listen(3000);

Open http://localhost:3000/docs — entity browser, query builder, live responses, and SQL trace (dev mode).

Routes

Route	Description
GET /docs	Playground UI
GET /docs/schema	JSON introspection (SchemaDoc)
POST /docs/execute	Run a query ({ data, meta })

Options

Option	Default	Description
path	/docs	URL prefix
title	—	Shown in playground header + schema doc
theme	dark	dark or light
auth	false	false, "admin", or (ctx) => boolean
sql	dev-only	"dev" shows SQL panel; false hides it
entities	all	Allowlist of entity names

SQL trace

Enable sql: "dev" and use recordPlanSql in SQL resolvers (or @meshql/kysely / showcase patterns):

npmJSR

import { recordPlanSql } from "@meshqljs/core";

mesh.resolve("*", async (plan) => {
  const { sql, params } = buildSelectSql(plan, schema);
  recordPlanSql(plan, { sql, params });
  return db.query(sql, params);
});

import { recordPlanSql } from "@meshql/core";

mesh.resolve("*", async (plan) => {
  const { sql, params } = buildSelectSql(plan, schema);
  recordPlanSql(plan, { sql, params });
  return db.query(sql, params);
});

See examples/showcase for a full demo at /docs.

Integrity

@meshql/integrity verifies signed HTTP wire requests. Docs execute is in-process (no transport), so signature checks are skipped; gate access with auth instead. Signed client calls still go through your integrity HTTP adapter as usual.

Do not leave auth: false or sql: "dev" on a public production URL. See playground security and the threat model.