@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 mit esbuild
• 📘 Native TypeScript & TSX-Unterstützung
• 🎨 SCSS/SASS-Unterstützung mit PostCSS-Pipeline
• 🎯 TailwindCSS-Integration (optional)
• 👀 Watch-Modus für Entwicklung
• 📦 Automatische Asset-Verarbeitung (Bilder, Fonts, etc.)
• 🔧 Flexibles Konfigurationssystem
• 📁 Multi-Theme/Multi-Directory Support

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

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
└── dist/                   # Build-Ausgabe (wird automatisch erstellt)

Beispiel für Multi-Theme Setup

htdocs/themes/
├── theme1/
│   ├── src/
│   │   ├── css/
│   │   │   └── main.scss
│   │   └── javascript/
│   │       ├── app.js
│   │       └── components.tsx  # TypeScript React
│   ├── dist/           # Build-Ausgabe
│   └── tailwind.config.js  # Optional
└── theme2/
    ├── src/
    │   ├── css/
    │   │   └── style.scss
    │   └── javascript/
    │       ├── main.js
    │       └── utils.ts        # TypeScript
    └── dist/

TypeScript-Unterstützung

Das Tool unterstützt TypeScript nativ über esbuild. Sie können .ts und .tsx Dateien direkt verwenden, ohne zusätzliche Konfiguration.

TypeScript verwenden

1. Erstellen Sie TypeScript-Dateien in Ihrem src/javascript/ Verzeichnis:

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

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

export { greetUser };

2. Für React/JSX verwenden Sie .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>;
}

TypeScript-Konfiguration (Optional)

Sie können eine tsconfig.json in Ihrem Projekt anlegen für bessere IDE-Unterstützung:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "jsx": "react",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Hinweis: esbuild führt keine Type-Checking durch. Für Type-Checking verwenden Sie tsc --noEmit in einem separaten Schritt.

TailwindCSS-Integration

Das Tool erkennt automatisch, ob eine tailwind.config.js im Theme-Verzeichnis existiert und aktiviert TailwindCSS entsprechend.

TailwindCSS einrichten

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

Unterstützte Dateitypen

Verarbeitet und gebündelt

• .scss, .sass - SCSS/SASS mit PostCSS-Transformation
• .js - JavaScript mit ESM-Support
• .ts - TypeScript
• .tsx - TypeScript React (JSX)

Als Assets kopiert

• .woff, .woff2, .ttf, .eot, .otf - Font-Dateien
• .svg, .png, .jpg, .jpeg, .gif, .webp - Bild-Dateien

Build-Ausgabe

• Development-Modus (--watch):

  • Source Maps werden generiert
  • Keine Minifizierung
  • Automatischer Rebuild bei Änderungen

• Production-Modus (Standard):

  • Minifizierte Ausgabe
  • Keine Source Maps
  • Optimierte Asset-Namen mit Hashes

Inkludierte Plugins

• TailwindCSS mit offiziellen Plugins:
  • @tailwindcss/aspect-ratio
  • @tailwindcss/forms
  • @tailwindcss/typography
• Autoprefixer für Browser-Kompatibilität
• PostCSS Import für @import-Statements
• esbuild-sass-plugin für SCSS-Verarbeitung

Lizenz

BSD-3-Clause

Author

Haj.tech GmbH