V6 Roadmap: ESM Only distribution #2363

The JavaScript ecosystem keeps moving forward, and more and more projects are switching to ESM-only distribution.

I’ve tried to make this change a few times already, but each time I was blocked by various incompatibilities. LinguiJS is a complex project consisting of multiple parts — runtime, CLI, and plugins for different tools.

Switching to ESM-only requires ensuring interoperability across all these tools. The main roadblock was usually supporting ESM in the babel-plugin-macros. I even contributed to Babel itself babel/babel#16860 to make this possible in the future.

However, the babel-plugin-macros codebase is quite outdated, and before working on the original issue, a lot of maintenance work was needed just to bring everything up to date. Because of that, I had to postpone this task for a long time.

Fortunately, the ecosystem has evolved, and with recent Node.js improvements — such as require(esm) backported to Node.js 20 — this workaround is no longer necessary. That means we can now distribute LinguiJS as pure ESM.

I expect no major changes will be required from users unless they rely on very specific or non-standard setups. Still, since this is a significant shift, it should be released as a new major version, similar to what Storybook 10 did.

I don’t plan to include any other major changes in this release — this breaking change will be big enough on its own.

Testing checklist:

• Ensure support for webpack
• Ensure support for babel-plugin-macros
• Ensure support for metro

Bump minimal nodejs version requirement to 20.16+, 22.19+, or 24+

Blockers:

• fix: generate correct typings for ESM, bump unbuild MartinCerny-awin/pseudolocale#27
• Package is not compatible with NodeJS ESM andywer/threads.js#496

Another fixes to be included in the V6 release

• Generate Lingui ID with URL and filename safe alphabet Generate Lingui ID with URL and filename safe alphabet #2207
• Replace cosmiconfig with lilconfig in configuration handling chore!: replace cosmiconfig with lilconfig in configuration handling #2286

To do List:

• Merge ESM Conversion feat!: ESM-only conversion #2368
• typecript's strict: true & "strictNullChecks": false, for most of packages (cli + core + react) refactor!: strictNullChecks for cli lib packages #2412
• rename jest-mocks package into test-utils chore: rename jest-mocks to test-utils, vitest@4, prettier@3 #2413
• test on a REAL projects with all supported tooling integrations (webpack, metro, babel-macros)
• spike: extract cli api from cli package to separate cli-lib.
• reconsider @lingui peerDependencies
• Use different threading library chore(cli): replace threads with tinypool #2420
• Bump the minimum required Node.js version to 22.19+ chore: set the minimum required node version to 22.19 #2435
• Documentation changes (migration guide, release notes blog post) (docs: v6 migration guide #2424, docs: v6 release blog post + docs enhancement #2427)
• modernize po-gettext package.

Bump previously blocked by ESM deps (nice to have, but not blocker)

• Commander
• chore: bump chokidar@5 & ora@9 #2416 chore: bump pseudololocalize, cli-table, glob #2415

Remove deprecations:

• "./api/extractors/typescript" feat!: remove deprecated typescript extractor #2417
• LinguiConfig.format: string && formatOptions?: CatalogFormatOptions feat!: remove deprecated format as string and formatOptions #2419
• drop deprecated @lingui/macro package chore: remove deprecated @lingui/macro package #2422

Post-release

• spike: implement NX for better DX and package build/test orchestration
• Try to enable windows tests
• Set up Dependabot updates