@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

npm install @hajtech/esbuild-config

Anforderungen

• Node.js >= 20.x

Verwendung

Grundlegende Verwendung

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

npx hajtech-esbuild

Watch-Modus

Für die Entwicklung mit automatischem Rebuild:

npx hajtech-esbuild --watch

In package.json Scripts

{
  "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:

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:

// src/javascript/app.ts
interface User {
  name: string;
  age: number;
}

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

export { greetUser };

React/JSX-Datei:

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

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

2. Importieren Sie TailwindCSS in Ihrer SCSS-Datei:

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

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:

<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