feat!: deliver lazy bundle by default

[tsi]

Summary

The default player bundle is now lightweight (~10kb initial) and loads the full player core on demand. This is the new default behavior for v4.x - no configuration needed to get the small bundle.

How the player works in v4.x

Default behavior (lazy loading)

The default entry (player.js / import from 'cloudinary-video-player') ships a ~10kb stub that loads the full player core (~130kb) asynchronously on first use. The videoPlayer() API remains synchronous - it returns a deferred proxy that buffers calls (.source(), .on(), .playlist(), etc.) and replays them in order once the core finishes loading:

const player = cloudinary.videoPlayer('my-player', { cloudName: 'demo' });
player.source('elephants');       // buffered, replayed after core loads
player.on('play', handler);       // buffered, replayed after core loads

The proxy is also thenable, so consumers who need the real player instance can await it:

const player = await cloudinary.videoPlayer('my-player', { cloudName: 'demo' });
console.log(player.duration());   // real value, core is loaded

Full bundle (eager loading)

For consumers who need everything loaded upfront (SSR, legacy integrations), player-full.js loads the entire player synchronously (~140kb). videoPlayer() returns a real VideoPlayer instance immediately.

Backward compatibility

Old file	v4.x behavior
cld-video-player.js	Copy of player-full.js - same eager behavior as before
cld-video-player.css	Copy of player.css - identical CSS
cld-video-player.light.js	Deprecated - copy of player-full.js with console.warn

Bundles

File	Size	Loading	videoPlayer() returns
player.js (default)	~10kb + core chunk	Deferred	Proxy (sync-looking, buffers calls)
player-full.js	~140kb	Eager	Real VideoPlayer (sync)
cld-video-player.js	~140kb	Eager (copy of player-full)	Real VideoPlayer (sync)

npm imports

Import path	Resolves to
cloudinary-video-player	Default lazy entry (ESM: lib/index.js, CJS: dist/player.min.js)
cloudinary-video-player/all	All plugins included (ESM: lib/all.js, CJS: dist/player-full.min.js)
cloudinary-video-player/player.min.css	Player CSS
cloudinary-video-player/cld-video-player.min.css	Player CSS (old name)

Source structure

File	Purpose
src/index.js	Unified entry - deferred proxy, SCSS, Cloudinary.new() legacy wrapper
src/index.full.js	Full/sync entry - eager imports, sync videoPlayer()
src/index.all.js	All plugins bundled
src/utils/deferred-player.js	Proxy implementation

Breaking changes

• export { videojs } removed - use import videojs from 'video.js' directly
• Sub-path exports removed: ./lazy, ./player, ./videoPlayer, ./full
• dist/cld-video-player-lazy.js no longer produced (replaced by dist/player.js)
• Default bundle behavior changed from eager to deferred loading

How to Test

1. npm run test:unit - all 127 tests pass
2. npm start - dev server loads demo pages via player.js + player.css
3. Verify cld-video-player.js works for existing consumers (copy of player-full.js)
4. ESM: cd docs/es-modules && npx vite - verify examples load without errors

[netlify]

✅ Deploy Preview for cld-video-player ready!

Name	Link
🔨 Latest commit	6d582a7
🔍 Latest deploy log	https://app.netlify.com/projects/cld-video-player/deploys/69e0f8aca68c5800089a60ed
😎 Deploy Preview	https://deploy-preview-1032--cld-video-player.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

❌ Deploy Preview for cld-vp-esm-pages failed. Why did it fail? →

Name	Link
🔨 Latest commit	6d582a7
🔍 Latest deploy log	https://app.netlify.com/projects/cld-vp-esm-pages/deploys/69e0f8ac795a470008089762