Build Guide

Prerequisites

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

Installation

Install dependencies:

npm install

This will install:

• esbuild - Fast TypeScript / JavaScript bundler
• typescript - Strict type-checking and .d.ts emission
• clean-css - CSS minifier
• vitest + @playwright/test - Unit / e2e test runners

Build Commands

Build Everything

Build TypeScript bundles, type declarations and CSS:

npm run build

npm run build now cleans dist/ first to avoid stale files (e.g. old chunk names) when rebuilding.

This creates:

• 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)
• dist/types/**/*.d.ts - Per-module declarations
• dist/vidply.css - Unminified styles
• dist/vidply.min.css - Minified styles

Build JavaScript Only

Bundle TypeScript with esbuild:

npm run build:js

Build TypeScript Declarations Only

Emit .d.ts files via tsc --emitDeclarationOnly:

npm run build:types

Type-check (no emit)

npm run typecheck

Build CSS Only

npm run build:css

Clean Build Directory

npm run clean

Watch Mode (Development)

Auto-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 statements
• Tree-shakeable
• 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 traditional web pages

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

CSS Files

dist/vidply.css

• Unminified, readable styles
• Includes comments
• Good for development and customization

dist/vidply.min.css

• Minified and optimized
• ~60% smaller than unminified
• Use in production

Using Built 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 builds.

Build Scripts Explained

build/build.js

Main TypeScript bundling script (esbuild):

• Bundles all src/**/*.ts source files
• Creates ES Module and IIFE formats
• Generates both dev and production versions
• Adds license banner
• Creates source maps for debugging

tsc (build:types)

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

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

build/build-css.js

CSS build script:

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

build/watch.js

Development watch script:

• Monitors src/ for changes
• Auto-rebuilds on save
• Creates development builds with source maps
• Faster than full production build

build/clean.js

Cleanup script:

• Removes dist/ directory
• Prepares for fresh build

Customizing the Build

Change Target Browsers

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

GitHub Actions Example

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: 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-check failures:

If npm run typecheck reports errors, run:

npx tsc --noEmit --pretty

to see full TypeScript diagnostics with source context.

Source Maps Not Working

Symptom: Unable to debug minified code in browser dev tools

Solutions:

1. Ensure source maps are enabled in build config (build/build.js)
2. Check browser dev tools are configured to load source maps
3. Verify .map files exist in dist/ folder
4. Clear browser cache and reload

Large Bundle Size

Symptom: Bundle size is larger than expected

Explanation: The player includes:

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

Solutions:

• The minified + gzipped size (~18 KB) is already optimized for production
• Modern browsers will cache the files after first load
• Consider using a CDN for better caching across sites
• For custom builds excluding unused features, modify src/index.ts before building

Permission Denied on 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

Watch Mode Not Detecting Changes

Symptom: Files change but build doesn't trigger

Solutions:

1. Restart watch mode
2. Check if editor saves files properly (some editors use atomic writes)
3. Increase file watch timeout in build/watch.js if needed

ESM Import Errors in Browser

Symptom: Browser console shows module import errors

Solutions:

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

Development Workflow

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

Distribution

For production deployment, only include:

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

These are the only files users need.

License

Built files include license banner automatically.

Support

For build issues, check:

1. Node.js version (18+)
2. npm install completed successfully
3. No syntax errors in source files
4. Build scripts have execute permission

Happy building!