Skip to content

Drop CJS build in favor of ESM-only output #108

Description

@nickytonline

Background

TypeScript 6.0.3 (shipped via #106) introduced two breaking changes that required fixes to our build config:

  1. TS6059/TS5011rootDir must now be explicitly set when a tsconfig.json lives in a different directory from its source files. Fixed by adding "rootDir": "../src" to both tsconfig.esm.json and tsconfig.cjs.json.
  2. TS5107moduleResolution: "Node" (node10) is now a hard deprecation error in TS 6. Currently worked around with "ignoreDeprecations": "6.0" in tsconfig.cjs.json.

The ignoreDeprecations workaround is an explicit escape hatch, but it will need to be updated again when TypeScript 7 drops support. The root cause is that our CJS build uses moduleResolution: "Node" — the only non-deprecated option that tolerates importing an ESM-only package like jose via require(). All modern alternatives (Node16, NodeNext, Bundler) enforce ESM/CJS boundaries strictly and reject require()-ing a pure-ESM package.

Proposal

Drop the CJS build entirely and ship ESM only.

Reasons:

  • jose (our only runtime dependency) is itself ESM-only — no CJS build, "type": "module". We are already swimming upstream.
  • Node.js 22 (our current runtime) has full native ESM support.
  • ESM-only is increasingly the standard for modern JS libraries (see: jose, sindresorhus/*, etc.).
  • It eliminates the ignoreDeprecations workaround and the ongoing maintenance burden of the dual build.

What would need to change:

  • Remove build:cjs script and configs/tsconfig.cjs.json
  • Update package.json exports to remove the require condition
  • Remove or update the main field for legacy tooling
  • Verify any known consumers can handle ESM-only

Discussion

  • Are there known consumers (internal or external) that require CJS?
  • Should we do a major version bump (2.0.0) given this is a breaking change for CJS consumers?

This issue was drafted by Devin (AI coding assistant) based on analysis of the TypeScript 6.0.3 upgrade and its impact on the build configuration.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions