@alokai/connect
API reference showcase, generated from the package source at build time.
@alokai/connect is the runtime backbone of an Alokai application: the
middleware server that talks to your backends, the type-safe SDK your
storefront calls it with, and the supporting config-switcher and
logger modules.
This section is a showcase of the new API reference experience. Every type table on these pages is generated at build time from the package's own type declarations - property names, types, defaults, and descriptions come straight from the JSDoc in the source code.
Modules
What changed compared to the current reference
The current reference renders one page per exported symbol - for
@alokai/connect alone that is 150+ sidebar entries of equal weight, where
createServer sits next to internal helper types and finding the API you
actually need means already knowing its name.
This showcase inverts that:
- Curated by task, not alphabet. Each module is one page organized around what you do with it - create a server, build an SDK module, handle errors. The important APIs are at the top; supporting types appear where they are used.
- JSDoc is the single source of truth. The tables are not hand-written
copies that drift from the code. They are compiled from the shipped
.d.tsfiles; when a property, default, or description changes in the source, the docs change on the next build - and the build fails if a documented type disappears. - Progressive disclosure. A type table shows the shape at a glance; each row expands into the full type signature, default value, and description, so a page with five documented types stays readable.
- Examples live with the code.
@exampleblocks in JSDoc are written by the package authors, reviewed in the same pull request as the code they describe, and surface here.
How it works
Document the source
Engineers write JSDoc on the public API in packages/connect - summaries,
@default, @example, @see. That is the only place documentation is
authored.
Roll up the declarations
api-extractor flattens the package's build output into one reviewable
.d.ts per entry point (middleware, sdk, logger, config-switcher),
JSDoc included.
Generate at build time
Pages reference types by name - <auto-type-table name="MiddlewareConfig" /> -
and the docs build compiles the table with the TypeScript compiler. No
generated files are committed, nothing to keep in sync by hand.