@crossplatformai/skills/skills/post-build-ship/references/esm-first.md

Reusable Agent Skills for CrossPlatform.ai projects.

# ESM First; CommonJS by Proven Exception

This is a narrowly routed Post.Build.Ship reference, not a standalone skill.

Use this reference when `post`, `build`, or `ship` is already active and the task crosses a
Node/tooling configuration, script, package module-format or export, configuration-discovery,
bundler-transform, or other ESM/CommonJS boundary. When no module boundary is in scope, keep the
normal workflow and do not add ESM-first planning or QA ceremony.

This reference supplements Post.Build.Ship. Existing evidence, fallback approval, material drift,
proportionate QA, ownership, and Ship contracts remain authoritative. This reference adds no
process, review requirement, receipt, fingerprint, or universal checklist.

## ESM Default

Default newly authored JavaScript and TypeScript modules, Node scripts, package exports, and tooling
configuration to repository-supported modern ESM. Prefer:

1. explicit imports
2. `.mjs` and `.mts`, or repository-native ESM `.js` and `.ts`
3. adjacent `.d.mts` declarations when declarations are required
4. explicit configuration objects passed through supported APIs
5. package exports and entrypoints that preserve ESM

Do not infer that CommonJS is required from an official CommonJS example, a synchronous discovery
convention, convenience, or historical documentation. Establish the exact installed consumer's
ESM support from authoritative documentation for that installed version, its type declarations,
its exported APIs, or its implementation source.

Treat each of these as an explicit CommonJS choice, not an implicit fallback:

1. `.cjs`
2. `.cts`
3. `module.exports`
4. `exports.*`
5. `require`
6. `createRequire`
7. compatibility wrappers
8. unjustified dual exports
9. avoidable CommonJS-discoverable configuration

If ESM support cannot be established from the installed consumer, stop and report the evidence rather than silently creating .cjs.

## Proven Exception

Permit the smallest CommonJS exception only after reporting the exact consumer constraint,
proposing the narrow exception, obtaining explicit approval through Post, and documenting and
testing the approved exception. A CommonJS artifact or interoperability mechanism remains an
implementation fallback unless the approved handoff proves and approves it.

Preserve legacy CommonJS outside the task scope. When in-scope work touches legacy CommonJS, use
`engineering-judgment.md` for the explicit keep-versus-cutover decision instead of preserving,
extending, or deleting the path on assumption.

## Shared ESM Options Pattern

When several consumers need the same options, prefer one non-discoverable shared ESM options
module. Every consumer imports that module explicitly, ambient or config-file discovery is disabled
when the supported API permits it, and verification establishes that every consumer accepts the
explicit configuration.

## Phase Cross-Checks

`post` records the repository module format, installed-consumer evidence, selected ESM path,
rejected CommonJS alternatives, and any approved exception in existing handoff fields. An unresolved
format or unapproved CommonJS fallback is `changes required`, not Build-ready.

`build` enforces the approved ESM path and never introduces an unapproved CommonJS fallback.
Contradictory installed-consumer evidence is material drift and returns through the existing Post
review and binding path rather than prompting improvised interoperability.

`ship` makes no module-format architecture decision. It uses this reference only as a read-only
cross-check, rejects and returns unapproved CommonJS artifacts or interoperability inconsistent
with the approved handoff, and never repairs them in Ship.