Repository navigation
feat: ship ESM, CommonJS and UMD builds with TypeScript types - #113
Merged
Merged
Conversation
Port the library from concatenated ES3 files to TypeScript modules and
build it with Vite+ (vp pack, i.e. tsdown/Rolldown):
- dist/index.mjs + index.d.mts: ESM, default export (the playerjs
namespace) plus named exports
- dist/index.cjs + index.d.cts: CommonJS, module.exports is the playerjs
namespace, as require('player.js') has always returned
- dist/player.js, player.min.js: UMD for the CDN and <script>, setting
window.playerjs (or AMD define / module.exports)
The public API and wire protocol are unchanged: window.playerjs keeps the
same keys, Player and the adapters still work with or without `new`, and
playerjs.DEBUG / VERSION / CONTEXT are still read live. VERSION now comes
from package.json at build time. Importing without a window (SSR) no longer
throws. A ready or other message whose JSON is `null` is now ignored
instead of throwing. Receiver and Keeper can also be called without `new`.
The JW Player adapter's loop bug (getLoop/setLoop use the receiver instead
of the adapter, so looping never takes effect) is ported as-is and marked.
Tooling:
- vite.config.mts: pack, fmt (Oxfmt), lint (Oxlint, type-aware with type
checks) and test (Vitest) config; `npm run check` runs vp check
- Vitest tests (test/package.test.ts) for the published package: require
and import through package.json exports, and the UMD bundles as a script
global, AMD module and CommonJS module, all without a DOM
- Playwright now tests the built bundle (dist/player.js, or
PLAYERJS_BUNDLE=dist/player.min.js); the test server is TypeScript
(e2e/server.mts) run directly by Node
- scripts/release-cdn.mts replaces `grunt release`: uploads
player-<version>.js / .min.js and source maps to the CDN bucket, refuses
to overwrite a released version without --force, has --dry-run
- package.json: exports map, types, unpkg/jsdelivr, files, npm scripts
- Remove Gruntfile.js, bower.json, the QUnit tests in test/ (replaced by
e2e/), and the src/*.js sources; move the demo video to e2e/fixtures
- dist/player-0.1.0*.js stay committed (people may link to them) but are
not published in the npm package; other dist/ output is git-ignored
Removing Grunt drops all 55 npm audit findings.
Formatting only, from `vp fmt`, plus a compare function for Array#sort in one test (require-array-sort-compare).
- check: format, lint and type checks (npm run check) - test: build (with publint), Vitest package tests, then the Playwright suite against dist/player.js and again against dist/player.min.js npm ci no longer needs --ignore-scripts now that Grunt's phantomjs is gone.
Show ESM and CommonJS imports, note the bundled types and SSR-safe import, and add a Development section for the npm scripts and the CDN release.
Every published entry already has an explicit extension (index.mjs, index.cjs, .d.mts, .d.cts), so consumers see no difference. The UMD bundle (dist/player.js) is not in the exports map, so Node never loads it as a module. In the repo, config and scripts go back to plain .ts (vite.config.ts, e2e/server.ts, scripts/release-cdn.ts), and the protocol spec reads the version from package.json instead of require().
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
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.
Modernizes the toolchain: the library is now TypeScript, built, formatted, linted, type-checked and unit-tested with Vite+ 1.4. Grunt and Bower are gone. The public API and wire protocol are unchanged. The existing Playwright suite (72 tests) passes against both the new readable and minified bundles.
Commits, best reviewed one at a time:
build:the TypeScript port and the new toolingstyle:Oxfmt formatting of tests, fixtures and README (formatting only)ci:check job and minified-bundle testsdocs:README for npm usage and developmentbuild:"type": "module". Every published file has an explicit extension (.mjs,.cjs,.d.mts,.d.cts), so consumers see no difference. The UMDdist/player.jsisn't in theexportsmap, so Node never loads it as a module. Config and scripts are plain.ts.Build output
dist/index.mjs+.d.mtsimportplayerjsnamespace, plus named exports (Player,Receiver, …)dist/index.cjs+.d.ctsrequiremodule.exportsis theplayerjsnamespace, asrequire('player.js')has always returneddist/player.js,player.min.js<script>window.playerjs, AMDdefine, ormodule.exportspackage.jsongets anexportsmap,types,unpkg/jsdelivrpointing at the minified UMD, andfiles. publint runs on every build. The minified bundle is 13.0 KB, compared with 13.9 KB forplayer-0.1.0.min.js.Release
This counts as a feature (minor release). It adds TypeScript types, ES module and CommonJS builds, and SSR-safe imports. The new
exportsmap also limits imports toplayer.jsandplayer.js/package.json: deep imports of files inside the package, such asplayer.js/dist/player-0.1.0.js, no longer resolve, and the 0.1.0 files aren't in the npm package anymore.Compatibility
Kept as-is on purpose:
window.playerjshas exactly the same keys. The browser tests and new Node tests both check this.Playerand the adapters work with or withoutnew.playerjs.DEBUG,VERSIONandCONTEXTare still read live, so changing them at runtime still works.bufferedevent.getLoop/setLoopuse the receiver instead of the adapter, so looping never takes effect. Fixing it is a separate behavior change.dist/player-0.1.0*.jsstay committed, since people may link to them directly, but they're no longer published in the npm package. Otherdist/output is git-ignored.Small additive changes:
window(SSR, e.g. Next.js in setCurrentTime method is not working properly #100) no longer throws.nullis ignored instead of throwing.ReceiverandKeepercan also be called withoutnew.VERSIONis injected frompackage.jsonat build time.Tooling and npm scripts
npm run buildvp pack: all of the above, plus publintnpm run devnpm run check/fixvp check: Oxfmt, Oxlint (type-aware) and type checks, with no warningsnpm testvp test(Vitest) and Playwrightnpm run test:e2e/test:uiPLAYERJS_BUNDLE=dist/player.min.jstests the minified bundlenpm run release:cdngrunt release, see belowtest/package.test.ts, 8 tests) covers what the browser suite can't: the published package in Node. It checksrequire()andimportthrough theexportsmap, and the UMD bundles as a script global, an AMD module and a CommonJS module, all without a DOM.src/. The test server is TypeScript (e2e/server.ts), run directly by Node 22.18+.scripts/release-cdn.tsuploadsplayer-<version>.js/.min.jsand their source maps tocdn-embed-ly, with the samepublic-readandmax-age=300settings as the Grunt task. It refuses to overwrite a version that already exists unless you pass--force, and--dry-runshows the plan. I haven't tested a real upload, only the dry run and the no-credentials failure path, which fails before uploading anything.Gruntfile.js,bower.json, the QUnit tests intest/(replaced bye2e/), the JSHint config, and thesrc/*.jssources. The demo video moved toe2e/fixtures/.npm auditfindings.CI
CI / checkruns format, lint and type checks.CI / testruns the build with publint, the Vitest tests, and Playwright againstplayer.jsand thenplayer.min.js.npm cino longer needs--ignore-scripts.I ran the whole pipeline from a clean copy locally before pushing (
npm ci,check,build, unit tests, and both browser runs).