npm package: @hajtech/esbuild-config
Description: Webpack SilverStripe preset
Author: Haj.tech
Latest version: 1.0.7

# @hajtech/esbuild-config

Eine vorkonfigurierte esbuild-basierte Build-Lösung für moderne Frontend-Projekte, optimiert für SilverStripe und Multi-Theme-Strukturen.

## Features

- 🚀 Schnelles Building für moderne Frontend-Projekte
- 📘 TypeScript & React/TSX Support
- 🎨 SCSS/SASS mit TailwindCSS-Integration
- 👀 Watch-Modus mit automatischem Rebuild
- 📦 Automatische Asset-Verarbeitung
- 📁 Multi-Theme Support für SilverStripe-Projekte

## Installation

```bash
npm install @hajtech/esbuild-config
```

## Anforderungen

- Node.js >= 20.x

## Verwendung

### Grundlegende Verwendung

Führen Sie den Build-Befehl in Ihrem Projektverzeichnis aus:

```bash
npx hajtech-esbuild
```

### Watch-Modus

Für die Entwicklung mit automatischem Rebuild:

```bash
npx hajtech-esbuild --watch
```

### In package.json Scripts

```json
{
  "scripts": {
    "build": "hajtech-esbuild",
    "watch": "hajtech-esbuild --watch"
  }
}
```

## Konfiguration

Erstellen Sie eine `esbuild.config.mjs` im Root Ihres Projekts, um die Standard-Konfiguration zu überschreiben:

```javascript
const esbuildConfig = {
    themes: {
        directory: 'htdocs/themes',
        resolveFolder: true,
        tailwindConfigMapping: {
            'colorset.scss': 'tailwind-colorset.config.js',
        }
    },
    admin: {
        directory: 'htdocs/app/client',
        resolveFolder: false
    },
    module: {
        directory: 'client',
        resolveFolder: false
    }
}

export default esbuildConfig;
```

### Konfigurations-Optionen

Jeder Eintrag in der Konfiguration unterstützt folgende Eigenschaften:

- **`directory`**: Pfad zum Verzeichnis (relativ zum Projekt-Root)
- **`resolveFolder`**: 
  - `true`: Behandelt jedes Unterverzeichnis als separates Projekt/Theme
  - `false`: Behandelt das Verzeichnis selbst als Projekt
- **`tailwindConfigMapping`** (optional): Ein Objekt, das SCSS-Dateien spezifischen Tailwind-Konfigurationsdateien zuordnet
  - Key: Name der SCSS-Datei (z.B. `'colorset.scss'`)
  - Value: Name der zugehörigen Tailwind-Konfigurationsdatei (z.B. `'tailwind-colorset.config.js'`)
  - Wenn keine Zuordnung definiert ist, wird standardmäßig `tailwind.config.js` verwendet

## Projektstruktur

Für jeden konfigurierten Pfad erwartet das Tool folgende Struktur:

```
your-project/
├── src/
│   ├── css/
│   │   └── *.scss          # SCSS Entry-Points
│   └── javascript/
│       ├── *.js            # JavaScript Entry-Points
│       ├── *.ts            # TypeScript Entry-Points
│       └── *.tsx           # TypeScript React Entry-Points
├── assets/
│   └── static/             # Statische Assets (werden 1:1 kopiert)
│       ├── images/
│       ├── fonts/
│       └── ...
└── dist/                   # Build-Ausgabe (wird automatisch erstellt)
```

### Entry Points

Das Build-Tool erkennt automatisch alle Dateien in den `src/css/` und `src/javascript/` Verzeichnissen als Entry Points:

- **CSS Entry Points**: Alle `.scss` Dateien in `src/css/`
- **JavaScript Entry Points**: Alle `.js`, `.ts` und `.tsx` Dateien in `src/javascript/`

Jeder Entry Point wird zu einer separaten Ausgabedatei kompiliert. Der Dateiname (ohne Erweiterung) wird beibehalten.

### Beispiel für Multi-Theme Setup

```
htdocs/themes/
├── theme1/
│   ├── src/
│   │   ├── css/
│   │   │   ├── main.scss
│   │   │   └── colorset.scss
│   │   └── javascript/
│   │       ├── app.js
│   │       ├── utils.ts            # TypeScript
│   │       └── components.tsx      # TypeScript React
│   ├── assets/
│   │   └── static/                 # Statische Assets für theme1
│   │       ├── images/
│   │       └── fonts/
│   ├── dist/                       # Build-Ausgabe
│   ├── tailwind.config.js          # Standard Tailwind-Config
│   └── tailwind-colorset.config.js # Spezielle Config für colorset.scss
└── theme2/
    ├── src/
    │   ├── css/
    │   │   └── style.scss
    │   └── javascript/
    │       ├── main.js
    │       └── utils.ts            # TypeScript
    ├── assets/
    │   └── static/                 # Statische Assets für theme2
    ├── dist/
    └── tailwind.config.js
```

## TypeScript-Unterstützung

Das Tool unterstützt TypeScript und React/JSX nativ. Erstellen Sie einfach `.ts` oder `.tsx` Dateien in Ihrem `src/javascript/` Verzeichnis:

**TypeScript-Datei:**
```typescript
// src/javascript/app.ts
interface User {
  name: string;
  age: number;
}

const greetUser = (user: User): string => {
  return `Hello, ${user.name}!`;
}

export { greetUser };
```

**React/JSX-Datei:**
```tsx
// src/javascript/Button.tsx
import React from 'react';

interface ButtonProps {
  label: string;
  onClick: () => void;
}

export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
}
```

**Hinweis:** Für Type-Checking in Ihrer IDE können Sie optional eine `tsconfig.json` anlegen. Das Build-Tool selbst benötigt keine TypeScript-Konfiguration.

## TailwindCSS-Integration

### Einfache TailwindCSS-Integration

1. Erstellen Sie eine `tailwind.config.js` in Ihrem Theme-Verzeichnis:

```javascript
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './templates/**/*.ss',
    './src/**/*.{js,ts,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

2. Importieren Sie TailwindCSS in Ihrer SCSS-Datei:

```scss
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";
```

Das Tool erkennt die `tailwind.config.js` automatisch und aktiviert TailwindCSS.

### Mehrere Tailwind-Konfigurationen

Für verschiedene SCSS-Dateien können Sie unterschiedliche Tailwind-Konfigurationen verwenden:

1. Erstellen Sie mehrere Konfigurationsdateien im Theme-Verzeichnis:
   - `tailwind.config.js` (Standard für alle SCSS-Dateien)
   - `tailwind-colorset.config.js` (spezielle Konfiguration)

2. Verknüpfen Sie SCSS-Dateien mit den Konfigurationen in `esbuild.config.mjs`:

```javascript
const esbuildConfig = {
    themes: {
        directory: 'htdocs/themes',
        resolveFolder: true,
        tailwindConfigMapping: {
            'colorset.scss': 'tailwind-colorset.config.js',
            'admin.scss': 'tailwind-admin.config.js',
            // Alle anderen SCSS-Dateien nutzen tailwind.config.js
        }
    }
}

export default esbuildConfig;
```


## Unterstützte Dateitypen

### Quellcode-Dateien
- `.scss`, `.sass` - SCSS/SASS-Dateien (werden zu CSS kompiliert)
- `.js` - JavaScript-Dateien
- `.ts` - TypeScript-Dateien
- `.tsx` - TypeScript React-Dateien (JSX)

### Asset-Dateien
- `.woff`, `.woff2`, `.ttf`, `.eot`, `.otf` - Schriftarten
- `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` - Bilder

**Hinweis:** Asset-Dateien müssen in JavaScript/TypeScript importiert werden. Für direkte Kopie ohne Import verwenden Sie den `assets/static/` Ordner.

## Statische Assets

Das Build-Tool kopiert automatisch alle statischen Assets aus dem `assets/static/` Verzeichnis in das Build-Ausgabeverzeichnis.

### Verzeichnisstruktur

```
your-project/
├── assets/
│   └── static/
│       ├── images/
│       │   ├── logo.png
│       │   └── background.jpg
│       ├── fonts/
│       │   └── custom-font.woff2
│       ├── icons/
│       │   └── favicon.ico
│       └── documents/
│           └── manual.pdf
└── dist/
    └── assets/
        └── static/         # Kopierte Assets
            ├── images/
            ├── fonts/
            ├── icons/
            └── documents/
```

### Verwendung

1. Legen Sie Ihre statischen Assets im `assets/static/` Verzeichnis ab
2. Die Dateien werden beim Build automatisch nach `dist/assets/static/` kopiert
3. Im Watch-Modus werden Änderungen automatisch synchronisiert

### Beispiel

Wenn Sie eine Datei unter `assets/static/images/logo.png` ablegen, ist diese nach dem Build unter `dist/assets/static/images/logo.png` verfügbar.

In Ihrem HTML/Template können Sie dann darauf verweisen:

```html
<img src="/dist/assets/static/images/logo.png" alt="Logo">
```

**Hinweis:** Im Gegensatz zu Assets, die über JavaScript/TypeScript importiert werden, erhalten statische Assets keine Hash-Namen und werden 1:1 kopiert.

## Build-Ausgabe

### Development-Modus (`--watch`)
- Source Maps für einfaches Debugging
- Keine Minifizierung (bessere Lesbarkeit)
- Automatischer Rebuild bei Änderungen
- Watch-Modus für statische Assets

### Production-Modus (Standard)
- Minifizierte und optimierte Ausgabe
- Keine Source Maps
- Asset-Namen mit Hashes für Cache-Busting

**Hinweis:** Der `dist/` Ordner wird vor jedem Build automatisch geleert.

## Lizenz

BSD-3-Clause

## Author

Haj.tech GmbH