feat!: ESM-first browser bundles #225
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
BREAKING CHANGE: UMD bundle renamed from `dist/n2words.js` to `dist/n2words.umd.cjs`
- Add ESM bundle at `dist/n2words.js` (CDN default)
- Add UMD bundle at `dist/n2words.umd.cjs` (legacy script tags + CJS)
- Add individual language bundles in both formats
- Add conditional exports for `require('n2words')` support
- Rename test/umd/ to test/bundles/ with ESM and CJS tests
- Update README with new CDN usage examples
- Update release workflow for new bundle structure
Migration for CDN users:
- ESM: `<script type="module">` with dist/n2words.js
- UMD: `<script>` with dist/n2words.umd.cjs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename build:umd to build:dist (builds both ESM and UMD) - Remove sourcemap generation from all bundles - Update release workflow and tests accordingly 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The FalseESM warning occurs because ESM type declarations are used for CJS runtime code (UMD bundles). This is standard practice for libraries that ship ESM source with UMD/CJS bundles - the types work correctly, TypeScript just notes the module format mismatch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Playwright browser tests provide stronger compatibility guarantees than es-check's syntax parsing. Real browser engines (Chrome, Firefox, WebKit) validate that dist bundles work correctly in target environments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Rename test/browsers to test/e2e and properly test both bundle types: - UMD bundle via <script> tag (umd-runner.html) - ESM bundle via <script type="module"> (esm-runner.html) Add local HTTP server (serve) to avoid CORS issues with ES module imports. Update commitlint to use 'e2e' scope instead of 'browser'. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove redundant content already covered in README.md: - Usage examples (ESM, UMD, CDN, CommonJS) - Package exports documentation Focus on technical details for contributors: - Browser version matrix with release dates - Build configuration (browserslist, verification commands) - ES2020 as hard floor (BigInt constraint) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
BREAKING CHANGE: Removes the recently added require() interop via UMD bundles. Use ESM imports or dynamic import() instead. - Remove main all-languages ESM bundle (dist/n2words.js) - Remove main all-languages UMD bundle (dist/n2words.umd.cjs) - Remove require conditions from package.json exports - Change UMD extension from .umd.cjs to .umd.js (browser-only bundles) - Simplify ESM bundles to export toWords directly (no virtual entry) - Update README to remove CommonJS section and update CDN examples - Update tests for new bundle structure Individual language bundles remain available for browsers: - dist/languages/*.js (ESM, ~2.8KB each) - dist/languages/*.umd.js (UMD for <script> tags, ~3KB each) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
BREAKING CHANGE: Package structure has changed following date-fns pattern.
- Rename lib/ to src/
- Flatten lib/languages/*.js to src/*.js (no subdirectory)
- Move lib/n2words.js to root index.js
- Flatten dist/languages/*.js to dist/*.js
Consumer import paths unchanged:
- `import { en } from 'n2words'` still works
- `import { toWords } from 'n2words/en'` still works
CDN paths improved:
- Before: dist/languages/en.js
- After: dist/en.js
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove 'build' from PROJECT_SCOPES (use type 'build' for general changes) - Add 'esm' scope for ESM bundle-specific changes (dist/*.js) - Add 'umd' scope for UMD bundle-specific changes (dist/*.umd.js) - Update utils comment to reflect src/ path - Add examples in header for build(esm) and build(umd) usage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
No longer needed - local testing now matches CI behavior. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove redundant COMPATIBILITY.md (info already in README) - Update dist paths: dist/languages/*.js → dist/*.js - Update source path: lib/ → src/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove cjs-require.test.cjs (referenced deleted dist files) - Remove commonjs-compatibility.test.cjs (tests Node 20+ built-in require() interop - unnecessary since we only support Node 20+) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Flatten fixtures/languages/ to fixtures/ - Rename test/utils/ to test/helpers/ (avoid confusion with src/utils) - Move unit/api.test.js to index.test.js - Move integration/languages.test.js to languages.test.js - Move unit/utils/ to utils/ - Merge test:unit and test:integration into single test script - Alphabetize package.json scripts - Remove --verbose from AVA commands - Update all import paths and documentation references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Popular libraries (axios, lodash, date-fns) don't include .npmrc. The settings were contributor-only preferences, not requirements: - engine-strict: already enforced by CI - save-exact: opinionated, contributors may prefer semver ranges - prefer-offline: minor optimization 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- scripts/add-language.js: import paths and fixture directory - .vscode/debug-converter.js: import path to test helpers - Documentation: CLAUDE.md, CONTRIBUTING.md, PR template, scripts/README.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move normalizeCode to language-naming.js (BCP 47 operations) - Move isValidNumericInput to value-utils.js (was stringify.js) - Rename stringify.js → value-utils.js (handles serialization + validation) - Update imports in test files and scripts/add-language.js 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously set to 10 which never triggered (lowest fixture has 19). Now warns for sv (19), pa (24), and ur (24). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…cript Merge bench/perf.js and bench/memory.js into bench/index.js with: - Unified configuration section at top with all Benchmark.js options - Quick and full mode configs for both perf and memory testing - Improved memory accuracy via median, warmup rounds, and higher iterations - Humanized output (1.9M ops/sec instead of 1900000) - History tracking with value-based filtering for --compare - Per-language history pruning (maxHistoryPerLanguage: 10) - Incremental saves allowing early script termination 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
TylerVigario
changed the title
TylerVigario
changed the title
- release.yml: fix lib/ → src/ and dist/languages/ → dist/ - README.md: update CDN paths and bench commands - CLAUDE.md: update bench commands with full options - bench/index.js: flatten results to bench/results.json - Delete outdated bench/README.md (script has --help) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add "Functional API" to highlights - Update language count from 52 to 54 (added ka, yo) - Consolidate CDN examples (single ESM/UMD block each) - Remove redundant Examples section - Expand Language Options to complete reference with examples - Simplify Performance table Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add JSDoc @param/@returns to language file pattern (required for type generation) - Add complete JSDoc example to Options Pattern section - Simplify bench commands to essential two-liner Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix bundle paths in HTML test runners (dist/languages/ -> dist/) - Replace serve with http-server for simpler static file serving - Update Chinese test expectation to match formal numeral output - Update .browserslistrc comment to reference src/ instead of lib/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Combine E2E browser tests with package verification - Single build step runs all verification (types, exports, bundles, e2e) - Reduces redundant builds and simplifies workflow Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove ci and docs from scopes (they are types, not scopes) - Add required section property to hidden changelog entries - Update bench scope comment for consolidated script Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add positional argument support for language codes (e.g., `npm run bench -- en,fr`) - Restructure results.json to per-language arrays with sequential IDs - Add --remove flag to delete history entries by ID (single or comma-separated) - Expand --history to show multi-language summary or single language detail - Simplify data model: unified entries with both perf and memory metrics - Improve history display with formatted timestamps and test values Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Extract parseLanguageCodes() helper to deduplicate parsing logic - Add GC warning when --expose-gc flag not used - Reuse loadResultsData() in compare logic instead of duplicating - Add Runs column to history summary showing entry count per language Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Import getLanguageCodes and normalizeCode from test helpers instead of duplicating the logic in rollup.config.js. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add getLanguageName() and isInCLDR() helpers using Intl.DisplayNames - Prompt for language name when code is not in CLDR (e.g., hbo) - Check if language exists before prompting for name - Simplify template generators (name is now always provided) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Breaking Changes:
dist/*.js)dist/*.umd.js)dist/n2words.js) - use per-language importsConsumer impact: None for Node.js usage
import { en } from 'n2words'still worksimport { toWords } from 'n2words/en'still worksCDN migration:
Other changes:
lib/→src/,lib/languages/→src/)Test plan
npm test- all unit/integration tests pass (149 tests)npm run build- ESM and UMD bundles generatednpm run test:bundles- bundle tests pass (12 tests)npm run bench- benchmark runs successfully🤖 Generated with Claude Code