# flex-md consumption (library authors)

This document is for library/tool authors (gateways, SDK adapters, orchestrators), not end-user apps.

## Node support baseline

- `flex-md` supports Node LTS in the range `>=18`.
- Release validation should run `npm run build` then `npm run test:smoke`.

## Export map behavior

`flex-md` publishes conditional exports:

- `import` -> `./dist/index.js`
- `require` -> `./dist/index.cjs`
- `types` -> `./dist/index.d.ts`

Today, both runtime entries are CommonJS output. The `import` condition gives Node and bundlers a resolver path, but does not currently mean ESM syntax output.

## CJS bridge during publish

Build flow:

1. `tsc` emits CommonJS files into `dist/`
2. `tsc -p tsconfig.cjs.json` emits CommonJS files into `dist-cjs/`
3. `scripts/cjs-bridge.mjs` copies `dist-cjs/index.js` to `dist/index.cjs`

This keeps a stable `require` entry while preserving the package export conditions expected by consumers.

## Supported consumption patterns

- CommonJS: `const flex = require("flex-md")`
- ESM runtime: `import * as flex from "flex-md"`
- Dynamic fallback import: `const flex = await import("flex-md")`

For runtime confidence, use package-based smoke tests (install from tarball and load by package name) instead of importing local `dist/` paths only.

## Bundler caveats

Some bundlers treat the `import` condition as if it must point to ESM syntax. In those environments:

- prefer default package resolution first,
- then apply bundler-specific externalization/transpile settings if needed.

If a bug reproduces only under one bundler graph, treat that as a consumer integration issue and document the supported loader pattern for that environment.