Skip to content

feat: ship ESM, CommonJS and UMD builds with TypeScript types - #113

Merged
luwes merged 5 commits into
masterfrom
build/vite-plus-typescript
Nov 3, 2026
Merged

luwes merged 5 commits into
masterfrom
build/vite-plus-typescript

Conversation

@luwes

@luwes luwes commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

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:

  1. build: the TypeScript port and the new tooling
  2. style: Oxfmt formatting of tests, fixtures and README (formatting only)
  3. ci: check job and minified-bundle tests
  4. docs: README for npm usage and development
  5. build: "type": "module". Every published file has an explicit extension (.mjs, .cjs, .d.mts, .d.cts), so consumers see no difference. The UMD dist/player.js isn't in the exports map, so Node never loads it as a module. Config and scripts are plain .ts.

Build output

File For Notes
dist/index.mjs + .d.mts import default export is the playerjs namespace, plus named exports (Player, Receiver, …)
dist/index.cjs + .d.cts require module.exports is the playerjs namespace, as require('player.js') has always returned
dist/player.js, player.min.js CDN / <script> UMD: window.playerjs, AMD define, or module.exports

package.json gets an exports map, types, unpkg/jsdelivr pointing at the minified UMD, and files. publint runs on every build. The minified bundle is 13.0 KB, compared with 13.9 KB for player-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 exports map also limits imports to player.js and player.js/package.json: deep imports of files inside the package, such as player.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.playerjs has exactly the same keys. The browser tests and new Node tests both check this.
  • Player and the adapters work with or without new.
  • playerjs.DEBUG, VERSION and CONTEXT are still read live, so changing them at runtime still works.
  • Messages are unchanged: same fields, JSON strings, and the legacy buffered event.
  • The JW Player adapter's loop bug is ported as-is and marked with a comment: getLoop/setLoop use the receiver instead of the adapter, so looping never takes effect. Fixing it is a separate behavior change.
  • dist/player-0.1.0*.js stay committed, since people may link to them directly, but they're no longer published in the npm package. Other dist/ output is git-ignored.

Small additive changes:

  • Importing without a window (SSR, e.g. Next.js in setCurrentTime method is not working properly #100) no longer throws.
  • A message whose JSON is null is ignored instead of throwing.
  • Receiver and Keeper can also be called without new.
  • VERSION is injected from package.json at build time.
  • Bundled TypeScript types.
  • Output targets ES2017, so IE11 is not supported. It already didn't work (Doesn't work on IE11 #73).

Tooling and npm scripts

Script Does
npm run build vp pack: all of the above, plus publint
npm run dev rebuild on change
npm run check / fix vp check: Oxfmt, Oxlint (type-aware) and type checks, with no warnings
npm test build, then vp test (Vitest) and Playwright
npm run test:e2e / test:ui Playwright only. PLAYERJS_BUNDLE=dist/player.min.js tests the minified bundle
npm run release:cdn replaces grunt release, see below
  • Vitest (test/package.test.ts, 8 tests) covers what the browser suite can't: the published package in Node. It checks require() and import through the exports map, and the UMD bundles as a script global, an AMD module and a CommonJS module, all without a DOM.
  • Playwright now tests the built bundle instead of concatenating src/. The test server is TypeScript (e2e/server.ts), run directly by Node 22.18+.
  • scripts/release-cdn.ts uploads player-<version>.js/.min.js and their source maps to cdn-embed-ly, with the same public-read and max-age=300 settings as the Grunt task. It refuses to overwrite a version that already exists unless you pass --force, and --dry-run shows the plan. I haven't tested a real upload, only the dry run and the no-credentials failure path, which fails before uploading anything.
  • Removed: Gruntfile.js, bower.json, the QUnit tests in test/ (replaced by e2e/), the JSHint config, and the src/*.js sources. The demo video moved to e2e/fixtures/.
  • Removing Grunt drops all 55 npm audit findings.

CI

CI / check runs format, lint and type checks. CI / test runs the build with publint, the Vitest tests, and Playwright against player.js and then player.min.js. npm ci no 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).

luwes added 5 commits November 2, 2026 22:22
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().
@luwes luwes changed the title build: replace Grunt and Bower with Vite+ and TypeScript feat: ship ESM, CommonJS and UMD builds with TypeScript types Nov 3, 2026
@luwes
luwes merged commit 8c7bb06 into master Nov 3, 2026
2 checks passed
@luwes
luwes deleted the build/vite-plus-typescript branch November 3, 2026 06:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant