docuconf-js
JavaScript and TypeScript SDKs for docuconf: typed configuration contracts between an
application and the Kubernetes platform that runs it. Each SDK extends a configuration library you already use,
exports your declaration as a CUE contract, and validates the real environment and mounted files at boot.
Documentation: docuconf.dev · TypeScript guide · NestJS guide
Examples: the orders service with T3 Env and with NestJS, and a
Next.js app that validates at server start and shares env.ts with client components.
The packages are not on npm yet. Each SDK's README starts with how to install it from a checkout (npm pack, then
npm install of the tarballs); npm install @docuconf/t3 and npm install @docuconf/nestjs work from the first release.
Both SDKs implement spec v1alpha1, write contracts
with generator.language: "typescript", and report the same error codes. Neither has a config-file overlay API: Node
does not layer configuration files, so there is nothing for an overlay to slot into.
Every input's description comes from .describe() (T3 Env) or @Describe (NestJS); longer details come from the
property's TSDoc comment, or an explicit details option. docuconf docs in the docuconf CLI generates CONFIG.md and
CONFIG.agents.md from the exported contract.
Layout
packages/core @docuconf/core ESM + CommonJS
packages/t3 @docuconf/t3 ESM (CommonJS apps load it with require(), Node 22.12+), a browser build, /next
packages/nestjs @docuconf/nestjs ESM + CommonJS
examples/orders-t3 the orders example: a Node http service with T3 Env (workspace member)
examples/orders-nestjs the orders example: a NestJS app (workspace member)
examples/next-t3 a Next.js app (not a workspace member: its smoke.sh installs the packed packages)
examples/t3 test fixture: an HTTPS server with file inputs, against the t3 sources
examples/nestjs test fixture: a NestJS app with file inputs
Each example also commits CONFIG.md, CONFIG.agents.md and docs.json, generated from its contract.cue by
docuconf docs (for example examples/orders-t3/CONFIG.md and
CONFIG.agents.md); the examples' READMEs give the commands, and CI checks them.
The repository is an npm workspace. In development, the packages and tests resolve each other's TypeScript sources
through the @docuconf/source export condition (customConditions in tsconfig.base.json, aliases in
vitest.shared.ts); builds and published packages use dist.
Development
npm ci
npm run typecheck # every package
npm test # every package's tests (vitest projects); vets exported contracts with cue when installed
npm run build # core first, then the SDKs, then the orders examples
npm run smoke # installs the packed packages into clean projects; runs the orders examples' smoke.sh
bash examples/next-t3/smoke.sh # the Next.js example: installs Next.js and the packed packages in a temporary copy
The SDK CLIs are docuconf-t3 and docuconf-nestjs (the platform's Go CLI is docuconf). Every TypeScript block in a
package README is a file under that package's readme/ directory (or an example), compiled by the typecheck; a test
fails when a README block and its file differ.
npx vitest run --project nestjs runs one package's tests. The export tests run cue vet -c against the meta-schema
in a checkout of docuconf-go (default ../docuconf-go/spec/cue, or
DOCUCONF_SPEC_CUE), using cue from $CUE, ~/go/bin/cue or PATH. They are skipped when either is missing, unless
DOCUCONF_REQUIRE_VET=1. Regenerate golden files with UPDATE_GOLDEN=1 npm test.
Conformance
@docuconf/core's tests run the shared conformance suite
(SPEC §12) through contract-first mode (loadContract, see the core README), one test per case
named by its id. The cases come from DOCUCONF_CONFORMANCE (the path to cases.json), else
../docuconf-go/conformance/cases.json; the suite is skipped when neither exists, unless DOCUCONF_REQUIRE_CONFORMANCE=1,
as in CI:
DOCUCONF_CONFORMANCE=../docuconf-go/conformance/cases.json DOCUCONF_REQUIRE_CONFORMANCE=1 npx vitest run --project core
Capability tags skipped: none. The runner keeps an allow-list of the tags this SDK supports, which is every tag in
the suite: int64, json-schema, key-set, deprecated, strict-parsing, files, profiles and overlays. A case
with any other tag, such as one added to the suite later, is skipped, never run (SPEC §12), and the suite fails if any
case is skipped, so CI fails too.
int64: contract-first mode returns an int (or an int list item) as a number within ±Number.MAX_SAFE_INTEGER
and as an exact bigint beyond it, up to the signed 64-bit range, and compares bounds exactly.json-schema: contract-first mode checks json values against their schema with
Ajv (JSON Schema draft 2020-12), a dependency of @docuconf/core.key-set: the keySet type, in both SDKs (keySet() in @docuconf/t3, @KeySet() in @docuconf/nestjs) and in
contract-first mode. Its value is a KeySet.deprecated: a deprecated input that is set loads, and boot logs a warning with its name and message.strict-parsing: SPEC §5's exact grammars, in both SDKs and contract-first mode: nothing is trimmed (csv items
included), a bool is true or false in any case, numbers and durations follow their grammar, and anything a host
library would also accept is invalid_type.files: contract-first mode loads and checks file inputs under DOCUCONF_FILE_ROOT: config files in json, yaml
and toml, TLS key pairs, CA bundles, PKCS#12 keystores (through Node's OpenSSL) and text files.profiles and overlays: contract-first mode layers the base default, the profile, the overlay and the environment.
The SDKs' declaration APIs have neither: Node does not layer configuration files.
For each case the runner writes the case's files into a new temporary directory and loads with DOCUCONF_FILE_ROOT set
to it. The SDKs' export is checked against the shared fixture too: packages/t3/test/fixtures/conformance-fixture.ts
declares docuconf-go's conformance/export/fixture.yaml with @docuconf/t3, and the test exports it and runs
docuconf conformance export --golden conformance/export/golden.cue (the CLI from DOCUCONF_CLI, else PATH).
scripts/conformance.sh builds the CLI from the docuconf-go checkout.
A Zod or class-validator number holds integers exactly only up to 2^53 - 1, so @docuconf/t3 and @docuconf/nestjs
reject int values and list items beyond ±Number.MAX_SAFE_INTEGER (out_of_range) and export min/max and
itemMin/itemMax capped to that range. int64() in @docuconf/t3 holds the whole 64-bit range.
A key set, from the orders example, and the webhook check that uses it:
WEBHOOK_KEYS: keySet({ keyMinLength: 32, keyMaxLength: 256 }).optional().describe("Keys that verify the signature on incoming payment webhooks"),
return keys.verify((key) => timingSafeEqual(createHmac("sha256", key).update(body).digest(), got));
Releases are published to npm from CI, one package per tag; see RELEASING.md.
Report a vulnerability privately, through GitHub's private vulnerability reporting: see SECURITY.md.
Licence
MIT.
