tsup für TypeScript: Komplettguide mit Beispielen

1. Was ist tsup und warum braucht man es?

tsup ist ein moderner, schneller und einfach zu bedienender Bundler für TypeScript, der auf esbuild basiert. Seine Hauptaufgabe ist es, Ihre TypeScript-Bibliothek in eine oder mehrere Dateien zu bündeln, die bereit für die Veröffentlichung auf npm oder die Verwendung in anderen Projekten sind. Im Gegensatz zu komplexen Konfigurationen von Webpack oder Rollup bietet tsup eine "Out-of-the-Box"-Konfiguration, die in den meisten Fällen keine Einrichtung erfordert.

Warum tsup? Bei der Entwicklung von Bibliotheken in TypeScript stehen Sie vor mehreren Herausforderungen: Sie müssen TypeScript in JavaScript kompilieren, Typdeklarationen (.d.ts) generieren, mehrere Dateien zu einer einzigen (Bundle) zusammenfassen und dies für verschiedene Modulformate (CommonJS, ESM) tun. tsup löst all diese Aufgaben mit einem einzigen Befehl. Es verarbeitet Importe automatisch, minimiert den Code (optional), generiert Source Maps und unterstützt Tree-Shaking.

tsup ist ideal für: die Erstellung von npm-Paketen, Utility-Bibliotheken, React/Vue-Komponenten, API-Clients und alle anderen Projekte, die ein schnelles und einfaches TypeScript-Bündeln erfordern. Dank der Nutzung von esbuild ist tsup 10- bis 100-mal schneller als traditionelle Bundler, was besonders bei großen Projekten auffällt.

2. Installation

tsup wird über npm oder yarn als dev-Abhängigkeit installiert:

# npm
npm install --save-dev tsup

# yarn
yarn add --dev tsup

# pnpm
pnpm add --save-dev tsup

Nach der Installation können Sie tsup über npx ausführen oder ein Skript in Ihrer package.json hinzufügen.

3. Schnellstart – ein minimales Arbeitsbeispiel

Erstellen wir eine einfache Bibliothek und bündeln sie mit tsup.

Schritt 1: Erstellen Sie die Datei src/index.ts:

// src/index.ts
export function greet(name: string): string {
    return `Hallo, ${name}! Willkommen bei tsup.`;
}

export function add(a: number, b: number): number {
    return a + b;
}

Schritt 2: Erstellen Sie eine Konfigurationsdatei tsup.config.ts (oder verwenden Sie Kommandozeilenargumente):

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],        // Einstiegspunkt
    format: ['cjs', 'esm'],         // Ausgabeformate
    dts: true,                      // .d.ts-Dateien generieren
    splitting: false,               // Nicht in Chunks aufteilen
    sourcemap: true,                // Source Maps generieren
    clean: true,                    // dist-Ordner vor dem Build leeren
});

Schritt 3: Fügen Sie ein Skript in der package.json hinzu:

{
    "scripts": {
        "build": "tsup"
    }
}

Schritt 4: Führen Sie den Build aus:

npm run build

Das Ergebnis erscheint im Ordner dist/:

dist/
├── index.js          (CommonJS)
├── index.mjs         (ESM)
├── index.d.ts        (Typdeklarationen)
├── index.d.mts       (Deklarationen für ESM)
└── index.js.map      (Source Map)

4. Wichtige Methoden/Funktionen/Klassen

tsup hat keine Klassen im traditionellen Sinne. Die Haupt-API ist die Funktion defineConfig und das Konfigurationsobjekt. Hier sind 8 wichtige Konfigurationsoptionen.

4.1. `entry`

Signatur: entry: string | string[] | Record<string, string>

Definiert die Einstiegspunkte Ihrer Bibliothek. Sie können einen einzelnen String, ein Array von Strings oder ein Objekt angeben, um benannte Ausgaben zu erzeugen.

// Einzelner Einstiegspunkt
entry: ['src/index.ts']

// Mehrere Einstiegspunkte
entry: ['src/index.ts', 'src/utils.ts']

// Benannte Ausgaben
entry: {
    main: 'src/index.ts',
    utils: 'src/utils.ts',
}

4.2. `format`

Signatur: format: ('cjs' | 'esm' | 'iife')[]

Legt die Ausgabeformate fest. 'cjs' für CommonJS (Node.js), 'esm' für ES-Module (moderne Browser/Node.js) und 'iife' für direkt im Browser ausführbare Skripte.

// Nur CommonJS
format: ['cjs']

// CommonJS und ESM (Standard)
format: ['cjs', 'esm']

// Alle Formate
format: ['cjs', 'esm', 'iife']

4.3. `dts`

Signatur: dts: boolean | { entry?: string | string[]; resolve?: boolean }

Aktiviert die Generierung von TypeScript-Deklarationsdateien (.d.ts). Wenn aktiviert, erstellt tsup automatisch Typdefinitionen aus Ihrem Quellcode.

// Einfach aktivieren
dts: true

// Mit benutzerdefinierten Einstiegspunkten
dts: {
    entry: 'src/index.ts',
    resolve: true, // Externe Typen auflösen
}

4.4. `splitting`

Signatur: splitting: boolean

Aktiviert oder deaktiviert die Aufteilung des Codes in mehrere Chunks. Dies ist nützlich für große Anwendungen, bei denen Sie die Ladezeiten optimieren möchten. Für Bibliotheken ist es in der Regel besser, diese Option auf false zu setzen.

// Für Bibliotheken deaktivieren
splitting: false

// Für Anwendungen aktivieren
splitting: true

4.5. `sourcemap`

Signatur: sourcemap: boolean | 'inline' | 'external'

Generiert Source Maps, die das Debuggen des gebündelten Codes erleichtern. Sie können externe .map-Dateien oder inline Source Maps erstellen.

// Externe Source Maps (Standard)
sourcemap: true

// Inline Source Maps
sourcemap: 'inline'

// Keine Source Maps
sourcemap: false

4.6. `clean`

Signatur: clean: boolean

Löscht das Ausgabeverzeichnis (standardmäßig dist) vor jedem Build. Dies verhindert, dass alte Dateien im Build-Ordner zurückbleiben.

// Immer bereinigen
clean: true

4.7. `minify`

Signatur: minify: boolean | 'terser'

Aktiviert die Minifizierung des Ausgabecodes. Standardmäßig verwendet tsup den integrierten Minifier von esbuild. Sie können auch Terser für eine aggressivere Minifizierung wählen.

// Mit esbuild minifizieren
minify: true

// Mit Terser minifizieren
minify: 'terser'

4.8. `external`

Signatur: external: string[]

Definiert Abhängigkeiten, die nicht in den Bundle aufgenommen werden sollen. Dies ist nützlich für Peer-Abhängigkeiten oder große Bibliotheken, die der Benutzer bereits installiert hat.

// React und ReactDOM ausschließen
external: ['react', 'react-dom']

// Alle Abhängigkeiten ausschließen
external: Object.keys(require('./package.json').dependencies)

5. Praktische Beispiele

5.1. React-Komponente bündeln

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.tsx'],
    format: ['cjs', 'esm'],
    dts: true,
    external: ['react', 'react-dom'],
    sourcemap: true,
    clean: true,
});

5.2. Node.js-Bibliothek mit mehreren Einstiegspunkten

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: {
        main: 'src/index.ts',
        cli: 'src/cli.ts',
    },
    format: ['cjs'],
    dts: true,
    clean: true,
});

5.3. Für die Browser-Nutzung (IIFE)

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],
    format: ['iife'],
    globalName: 'MyLibrary',
    minify: true,
    sourcemap: false,
});

6. Fazit

tsup ist ein leistungsstarkes und dennoch einfaches Werkzeug zum Bündeln von TypeScript-Bibliotheken. Mit seiner Zero-Config-Philosophie und der unglaublichen Geschwindigkeit von esbuild ist es die ideale Wahl für moderne JavaScript- und TypeScript-Entwickler. Egal, ob Sie eine kleine Utility-Bibliothek oder eine komplexe Komponentenbibliothek erstellen – tsup macht den Build-Prozess schnell, zuverlässig und wartbar.

Probieren Sie tsup in Ihrem nächsten Projekt aus und überzeugen Sie sich selbst von der Leistungsfähigkeit und Einfachheit dieses Tools!