Shared platform utilities for Lilith services. This package provides the common Fastify factory, middleware, auth helpers, logging, tracing, configuration loaders, and supporting types consumed by the service fleet.
Supported entrypoints#
index.js: primary re-export surface for common helpers.create-fastify-server.cjs: baseline Fastify factory used by lightweight services.middleware/common.cjs: common web middleware (CORS, compression, helmet).auth-middleware.js: auth helpers and constants.lilith-logger.js: structured logger with JSON output.vault-config-loader.js: helper to fetch secrets/config from Vault.apm-exporter.js: optional APM exporter wiring (best-effort).
Prefer importing from the top-level package (@lilith/service-lib) or the entrypoints above rather than deep paths that are not part of the supported surface. If you need a new exported helper, add it to index.js and document it here.
Module system#
- Package uses ESM (
"type": "module") and NodeNext resolution. Keep relative imports with explicit extensions. - Jest configs should treat
.jsand.tsas ESM (see rootjest.config.base.cjs). - Compatibility shims that must stay CommonJS live in
.cjsfiles; keep them isolated.
Generated type artifacts#
- Thousands of
.d.ts/.d.ts.map/.js.mapfiles can be produced by tooling—treat them as build artifacts. - Only the curated type surfaces in the root and
types/directory are tracked. Everything else is ignored by.gitignore. - Use
npm run clean:typesto delete stray generated artifacts and keep the workspace lean. - Use
npm run analyze:typesto get a quick count of type artifacts present in this package.
Maintenance checklist#
- Add new helpers to
index.jsand note the entrypoint above so downstream services import consistently. - Keep tests in
__tests__/and prefer Fastify injection over listening on a port. - When adding new build outputs, update
.gitignoreto prevent accidental commits.