Build-Anleitung

Voraussetzungen

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

Installation

Installieren Sie die Abhängigkeiten:

npm install

Dadurch werden folgende Komponenten 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-Test-Runner

Build-Befehle

Alles erstellen

TypeScript-Bundles, Typdeklarationen und CSS erstellen:

npm run build

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

Dadurch werden erstellt:

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

Typüberprü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

Anschließend 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 eine 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
• Einsatz in der Produktion

Verwendung vorgefertigter 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 (herkömmlich)

<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

Hauptskript für die TypeScript-Bündelung (esbuild):

• Bündelt alle src/**/*.ts Quelldateien
• Erstellt ES-Modul- und IIFE-Formate
• Erzeugt sowohl Entwicklungs- als auch Produktionsversionen
• Fügt ein Lizenzbanner hinzu
• Erstellt Source-Maps 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/
• Wird von IDEs, tsc Anwender und Bundler (vite, webpack, rollup) zur Bereitstellung von Typinformationen
• Wird referenziert von package.json#types

build/build-css.js

CSS-Build-Skript:

• Kopiert das nicht minimierte CSS in den Ordner „dist“
• Minimiert das CSS für die Produktion
• Liefert Komprimierungsstatistiken
• Optimiert die Leistung

build/watch.js

Watch-Skript für die Entwicklung:

• Überwacht „src/“ auf Änderungen
• Führt beim Speichern einen automatischen Neuaufbau durch
• 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 Produktionsumgebung 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 gemeldet werden, führen Sie Folgendes aus:

npx tsc --noEmit --pretty

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

Source Maps funktionieren nicht

Symptom: Minifizierter Code lässt sich in den Entwicklertools des Browsers nicht debuggen

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 Bundle-Größe ist größer als erwartet

Erklärung: Der Player enthält:

• Vollständige Benutzeroberfläche mit allen Schaltflächen und Menüs (einschließlich Download, Puffer-Indikator)
• 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 Größe der minimierten und gzip-komprimierten Dateien (~18 KB) ist bereits für den Produktiveinsatz optimiert
• Moderne Browser speichern die Dateien nach dem ersten Laden im Cache
• Erwägen Sie die Verwendung eines CDN für eine bessere Caching-Leistung ü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 (manche Editoren verwenden atomare Schreibvorgänge)
3. Erhöhen Sie bei Bedarf das Timeout für die Dateiüberwachung build/watch.js falls erforderlich

ESM-Importfehler im Browser

Symptom: In der Browserkonsole werden Fehler beim Importieren von Modulen angezeigt

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"> korrekt eingestellt ist
4. Überprüfen Sie, ob der Browser ES6-Module unterstützt (Chrome 61+, Firefox 60+, Safari 11+)

Entwicklungsablauf

1. Nehmen Sie Änderungen an den Dateien in „src/“ vor
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. Die Build-Skripte verfügen über Ausführungsrechte

Viel Erfolg beim Kompilieren!