Compilation instructions

Prerequisites

• Node.js 18+ (for build tools)
• npm or yarn

Installation

Install the dependencies:

npm install

This will install the following:

• esbuild - Fast TypeScript/JavaScript bundler
• typescript - Strict type checking and .d.ts output
• clean-css - CSS minifier
• vitest + @playwright/test - Unit and end-to-end test runner

Build commands

Build all

Generate TypeScript bundles, type declarations and CSS:

npm run build

npm run build Now first cleans up ‘dist/’ to avoid obsolete files (e.g. old chunk names) during the rebuild.

This generates:

• dist/dev/vidply.esm.js - ES module (development)
• dist/prod/vidply.esm.min.js - ES module (production, minified)
• dist/legacy/vidply.js - IIFE bundle (development)
• dist/legacy/vidply.min.js - IIFE bundle (production, minified)
• dist/types/index.d.ts - TypeScript declarations (entry-level)
• dist/types/**/*.d.ts - Module-related declarations
• dist/vidply.css - Unminified styles
• dist/vidply.min.css - Minified styles

Build JavaScript only

Bundle TypeScript with esbuild:

npm run build:js

Generate TypeScript declarations only

Files .d.ts Files via tsc --emitDeclarationOnly:

npm run build:types

Type checking (no output)

npm run typecheck

Generate CSS only

npm run build:css

Clean up build directory

npm run clean

Watch mode (development)

Automatic rebuild on file changes:

npm run watch

Then in another terminal:

npm run dev

This starts a local server at http://localhost:3000

Build output

JavaScript bundles

ESM format (dist/vidply.esm.js and .min.js)

• Modern ES6 module format
• Use with import Instructions
• Tree-shake-compatible
• Recommended for modern projects

import Player from './dist/prod/vidply.esm.min.js';

IIFE format (dist/vidply.js and .min.js)

• Immediately Invoked Function Expression
• Works with <script> tags
• Creates global VidPly variable
• For conventional websites

<script src="dist/legacy/vidply.min.js"></script>
<script>
  const player = new VidPly.Player('#video');
</script>

CSS files

dist/vidply.css

• Unminified, readable styles
• Contains comments
• Well suited for development and customisation

dist/vidply.min.css

• Minified and optimised
• ~60% smaller than the unminified version
• Use in production

Using compiled files

Option 1: ES module (recommended)

<link rel="stylesheet" href="dist/vidply.min.css">

<video data-vidply src="video.mp4"></video>

<script type="module">
  import Player from './dist/prod/vidply.esm.min.js';
  // Player auto-initializes with data-vidply
</script>

Option 2: IIFE (traditional)

<link rel="stylesheet" href="dist/vidply.min.css">
<script src="dist/legacy/vidply.min.js"></script>

<video id="my-video" src="video.mp4"></video>

<script>
  const player = new VidPly.Player('#my-video', {
    controls: true,
    autoplay: false
  });
</script>

File sizes

Approximate sizes (minified + gzip):

Note: Actual file sizes may vary depending on the version and features included. These are approximate values for the production versions.

Explanation of the build scripts

build/build.js

Main TypeScript bundling script (esbuild):

• Bundles all src/**/*.ts source files
• Creates ES Module and IIFE formats
• Generates both development and production versions
• Adds licence banners
• Creates source mappings for debugging

tsc (build:types)

Runs the TypeScript compiler in pure declaration mode using tsconfig.build.json:

• Outputs .d.ts files dist/types/
• Used by IDEs, tsc users and bundlers (vite, webpack, rollup) for type information
• Referenced by package.json#types

build/build-css.js

CSS build script:

• Copies unminified CSS to dist
• Minifies CSS for production
• Reports compression statistics
• Optimises performance

build/watch.js

Development watch script:

• Monitors src/ for changes
• Automatically creates a new build on save
• Creates development builds with source maps
• Faster than the full production build

build/clean.js

Clean-up script:

• Removes the “dist/” directory
• Prepares a new build

Customising the build

Change target browser

Edit build/build.js:

target: ['es2020', 'chrome90', 'firefox88', 'safari14']

Add source maps to production

Edit build/build.js:

{
  name: 'ESM Bundle (Minified)',
  sourcemap: true,  // Enable source maps
  minify: true
}

Change global name

Edit build/build.js:

{
  format: 'iife',
  globalName: 'MyPlayer',  // Change from VidPly
}

CI/CD integration

Example of GitHub Actions

name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

Troubleshooting

Build fails

Symptom: The build command fails with errors

Solutions:

# 1. Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

# 2. Check Node.js version (requires 18+)
node --version

# 3. Try using npx directly
npx esbuild src/index.ts --bundle --outfile=dist/vidply.js

Type checking error:

If npm run typecheck reports an error, do the following:

npx tsc --noEmit --pretty

to view the full TypeScript diagnostic with source context.

Source mappings are not working

Symptom: Minified code cannot be debugged in the browser’s developer tools

Solutions:

1. Ensure that source maps are enabled in the build configuration (build/build.js)
2. Check that the browser’s developer tools are configured to load source maps
3. Check .map the files in the dist/ folder
4. Clear the browser cache and reload the page

Large bundle size

Symptom: The package size is larger than expected

Explanation: The player contains:

• Full UI controls with all buttons and menus (including download, buffer spinner)
• Multiple renderers (HTML5, YouTube, Vimeo, SoundCloud, HLS, DASH)
• i18n system with 5 built-in languages
• Comprehensive accessibility features (ARIA, keyboard navigation)
• Transcript, playlist and sign language features

Solutions:

• The minified + gzip size (~18 KB) is already optimised for production
• Modern browsers cache the files after the initial load
• Consider using a CDN for better caching across different websites
• For custom builds without unused features, change src/index.ts before building

Access denied for build scripts

Symptom: EACCES or permission errors

Solutions:

# On Linux/macOS, ensure scripts have execute permission
chmod +x build/*.js

# Or run with node explicitly
node build/build.js

Monitoring mode does not detect changes

Symptom: Files change, but the build is not triggered

Solutions:

1. Restart watch mode
2. Check that the editor is saving files correctly (some editors use atomic write operations)
3. Increase the file watch timeout in build/watch.js if necessary

ESM import errors in the browser

Symptom: The browser console displays errors when importing modules

Solutions:

1. Ensure you are using a local server (not file:// protocol)
2. Check that the file paths are correct and relative to the HTML file
3. Check <script type="module"> whether
4. Check whether the browser supports ES6 modules (Chrome 61+, Firefox 60+, Safari 11+)

Development process

1. Make changes to the src/ files
2. Start watch mode: npm run watch
3. Test in the browser: npm run dev
4. View demo: http://localhost:3000/demo/
5. Build production version: npm run build

Deployment

For production deployment, include only the following:

• dist/prod/vidply.esm.min.js or dist/legacy/vidply.min.js
• dist/vidply.min.css

These are the only files users need.

Licence

The files created automatically contain a licence notice.

Support

If you encounter any issues with the build, please check:

1. Node.js version (18+)
2. npm installation completed successfully
3. No syntax errors in the source files
4. Build scripts have execution permissions

Good luck with the build!