Kompilierungsanleitung

Voraussetzungen

• Node.js 18+ (für Build-Tools)
• npm oder yarn

Installation

Installieren Sie die Abhängigkeiten:

npm install

Dadurch wird Folgendes installiert:

• esbuild - Schneller TypeScript-/JavaScript-Bundler
• typescript - Strenge Typprüfung und .d.ts Ausgabe
• clean-css - CSS-Minifier
• vitest + @playwright/test - Unit- und End-to-End-Testrunner

Build-Befehle

Alles erstellen

TypeScript-Bundles, Typdeklarationen und CSS erstellen:

npm run build

npm run build bereinigt nun zunächst „dist/“, um veraltete Dateien (z. B. alte Chunk-Namen) beim Neuaufbau zu vermeiden.

Dies erzeugt:

• dist/dev/vidply.esm.js - ES-Modul (Entwicklung)
• dist/prod/vidply.esm.min.js - ES-Modul (Produktion, minimiert)
• dist/legacy/vidply.js - IIFE-Bundle (Entwicklung)
• dist/legacy/vidply.min.js - IIFE-Bundle (Produktion, minimiert)
• dist/types/index.d.ts - TypeScript-Deklarationen (Einstieg)
• dist/types/**/*.d.ts - Modulbezogene Deklarationen
• dist/vidply.css - Nicht minimierte Stile
• dist/vidply.min.css - Minimierte Stile

Nur JavaScript erstellen

TypeScript mit esbuild bündeln:

npm run build:js

Nur TypeScript-Deklarationen erstellen

Dateien .d.ts Dateien über tsc --emitDeclarationOnly:

npm run build:types

Typprüfung (keine Ausgabe)

npm run typecheck

Nur CSS erstellen

npm run build:css

Build-Verzeichnis bereinigen

npm run clean

Überwachungsmodus (Entwicklung)

Automatischer Neuaufbau bei Dateiänderungen:

npm run watch

Dann in einem anderen Terminal:

npm run dev

Dadurch wird ein lokaler Server unter http://localhost:3000 gestartet

Build-Ausgabe

JavaScript-Bundles

ESM-Format (dist/vidply.esm.js und .min.js)

• Modernes ES6-Modulformat
• Verwendung mit import Anweisungen
• Tree-shake-fähig
• Empfohlen für moderne Projekte

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

IIFE-Format (dist/vidply.js und .min.js)

• Sofort aufgerufener Funktionsausdruck
• Funktioniert mit <script> Tags
• Erzeugt globale VidPly Variable
• Für herkömmliche Webseiten

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

CSS-Dateien

dist/vidply.css

• Unminifizierte, lesbare Stile
• Enthält Kommentare
• Gut geeignet für Entwicklung und Anpassung

dist/vidply.min.css

• Minimiert und optimiert
• ~60 % kleiner als die unminifizierte Version
• Verwendung in der Produktion

Verwendung von kompilierten Dateien

Option 1: ES-Modul (empfohlen)

<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 (traditionell)

<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>

Dateigrößen

Ungefähre Größen (minifiziert + gzip):

Hinweis: Die tatsächlichen Dateigrößen können je nach Version und enthaltenen Funktionen variieren. Dies sind ungefähre Werte für die Produktionsversionen.

Erläuterung der Build-Skripte

build/build.js

Haupt-TypeScript-Bundling-Skript (esbuild):

• Bündelt alle src/**/*.ts Quelldateien
• Erstellt ES-Modul- und IIFE-Formate
• Erzeugt sowohl Entwicklungs- als auch Produktionsversionen
• Fügt Lizenzbanner hinzu
• Erstellt Quellzuordnungen für die Fehlersuche

tsc (build:types)

Führt den TypeScript-Compiler im reinen Deklarationsmodus aus unter Verwendung von tsconfig.build.json:

• Gibt .d.ts Dateien an dist/types/
• Verwendet von IDEs, tsc Anwendern und Bundlern (vite, webpack, rollup) für Typinformationen
• Referenziert von package.json#types

build/build-css.js

CSS-Build-Skript:

• Kopiert unminifiziertes CSS nach dist
• Minifiziert CSS für die Produktion
• Meldet Komprimierungsstatistiken
• Optimiert die Leistung

build/watch.js

Entwicklungs-Watch-Skript:

• Überwacht src/ auf Änderungen
• Erstellt beim Speichern automatisch einen neuen Build
• Erstellt Entwicklungs-Builds mit Source Maps
• Schneller als der vollständige Produktions-Build

build/clean.js

Bereinigungsskript:

• Entfernt das Verzeichnis „dist/“
• Bereitet einen neuen Build vor

Anpassen des Builds

Zielbrowser ändern

Bearbeiten build/build.js:

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

Quellkarten zur Produktion hinzufügen

Bearbeiten build/build.js:

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

Globalen Namen ändern

Bearbeiten build/build.js:

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

CI/CD-Integration

Beispiel für 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/

Fehlerbehebung

Build schlägt fehl

Symptom: Der Build-Befehl schlägt mit Fehlern fehl

Lösungen:

# 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

Fehler bei der Typprüfung:

Wenn npm run typecheck Fehler meldet, führen Sie Folgendes aus:

npx tsc --noEmit --pretty

um die vollständige TypeScript-Diagnose mit Quellkontext anzuzeigen.

Quellzuordnungen funktionieren nicht

Symptom: Minifizierter Code kann in den Entwicklertools des Browsers nicht debuggt werden

Lösungen:

1. Stellen Sie sicher, dass Source Maps in der Build-Konfiguration aktiviert sind (build/build.js)
2. Überprüfen Sie, ob die Entwicklertools des Browsers so konfiguriert sind, dass sie Source Maps laden
3. Überprüfen Sie, ob .map , ob die Dateien im dist/ Ordner
4. Leeren Sie den Browser-Cache und laden Sie die Seite neu

Große Bundle-Größe

Symptom: Die Paketgröße ist größer als erwartet

Erklärung: Der Player enthält:

• Vollständige UI-Steuerelemente mit allen Schaltflächen und Menüs (einschließlich Download, Puffer-Spinner)
• Mehrere Renderer (HTML5, YouTube, Vimeo, SoundCloud, HLS, DASH)
• i18n-System mit 5 integrierten Sprachen
• Umfassende Barrierefreiheitsfunktionen (ARIA, Tastaturnavigation)
• Transkript-, Wiedergabelisten- und Gebärdensprachfunktionen

Lösungen:

• Die minifizierte + gzip-Größe (~18 KB) ist bereits für die Produktion optimiert
• Moderne Browser speichern die Dateien nach dem ersten Laden im Cache
• Erwägen Sie die Verwendung eines CDN für eine bessere Zwischenspeicherung über verschiedene Websites hinweg
• Für benutzerdefinierte Builds ohne ungenutzte Funktionen ändern Sie src/index.ts vor dem Erstellen

Zugriff verweigert bei Build-Skripten

Symptom: EACCES oder Berechtigungsfehler

Lösungen:

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

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

Der Überwachungsmodus erkennt keine Änderungen

Symptom: Dateien ändern sich, aber der Build wird nicht ausgelöst

Lösungen:

1. Watch-Modus neu starten
2. Überprüfen Sie, ob der Editor Dateien ordnungsgemäß speichert (einige Editoren verwenden atomare Schreibvorgänge)
3. Erhöhen Sie die Zeitüberschreitung für die Dateibewachung in build/watch.js , falls erforderlich

ESM-Importfehler im Browser

Symptom: Die Browserkonsole zeigt Fehler beim Importieren von Modulen an

Lösungen:

1. Stellen Sie sicher, dass Sie einen lokalen Server verwenden (nicht file:// Protokoll)
2. Überprüfen Sie, ob die Dateipfade korrekt sind und sich relativ zur HTML-Datei beziehen
3. Überprüfen Sie, <script type="module"> , ob
4. Überprüfen Sie, ob der Browser ES6-Module unterstützt (Chrome 61+, Firefox 60+, Safari 11+)

Entwicklungsablauf

1. Änderungen an den src/Dateien vornehmen
2. Watch-Modus starten: npm run watch
3. Im Browser testen: npm run dev
4. Demo anzeigen: http://localhost:3000/demo/
5. Produktionsversion erstellen: npm run build

Bereitstellung

Für die Produktionsbereitstellung nur Folgendes einbinden:

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

Dies sind die einzigen Dateien, die Benutzer benötigen.

Lizenz

Die erstellten Dateien enthalten automatisch einen Lizenzhinweis.

Support

Bei Problemen mit dem Build überprüfen Sie bitte:

1. Node.js-Version (18+)
2. npm-Installation erfolgreich abgeschlossen
3. Keine Syntaxfehler in den Quelldateien
4. Build-Skripte verfügen über Ausführungsrechte

Viel Erfolg beim Erstellen!