KickJS Asset Manager: Typisierte Dateipfade für Node.js-Anwendungen

Das klassische Dilemma bei Node.js-Anwendungen: Eine einfache Dateioperation wie das Einlesen einer E-Mail-Vorlage funktioniert lokal, scheitert aber in der Produktion. Der Grund? Unterschiedliche Pfadstrukturen zwischen Entwicklungs- und Produktionsumgebung. Der KickJS Asset Manager löst dieses Problem durch ein typsicheres System für statische Dateien – und eliminiert damit lästige Runtime-Fehler.

Warum herkömmliche Ansätze scheitern

Die Verwaltung von Assets außerhalb des Quellcodes ist ein oft unterschätzter Risikofaktor. Drei zentrale Probleme treten dabei regelmäßig auf:

• Pfadinkonsistenz zwischen Entwicklung und Produktion: Während im Entwicklungsmodus der Pfad ../templates/welcome.ejs korrekt auflöst, scheitert derselbe Code in der gebauten Anwendung, weil __dirname auf das dist/-Verzeichnis zeigt. Die Folge sind 500-Fehler im Live-Betrieb.

• Fehlende Typsicherheit: Asset-Pfade werden als reine Strings behandelt. Eine Umbenennung der Datei führt zu Runtime-Fehlern, die erst durch Tools wie Sentry oder Nutzerbeschwerden auffallen – ohne dass der Compiler warnt.

• Technische Schulden durch Workarounds: Viele Projekte kompensieren die Probleme mit komplexen Bedingungen wie process.env.NODE_ENV === 'production' ? '../../dist/templates' : '../templates'. Diese Codefragmente häufen sich im Projekt an und werden zu einer unwartbaren Ansammlung von Fallunterscheidungen.

Der KickJS Asset Manager ersetzt diese ad-hoc-Lösungen durch ein Build-zeit-orientiertes System, das Assets typsicher und konsistent verwaltet.

Die Architektur: Manifest und typsicherer Proxy

Zwei zentrale Komponenten bilden das Rückgrat des Systems:

1. `.kickjs-assets.json` – Das Manifest:

Während des Build-Prozesses wird eine JSON-Datei generiert, die alle Assets mit ihren endgültigen Pfaden verzeichnet. Das Manifest enthält eine flache Struktur mit Kategorien (z. B. mails, schemas) und den dazugehörigen Dateipfaden – entweder absolut oder relativ zum dist/-Verzeichnis.

1. `.kickjs/types/assets.d.ts` – Die typsichere Schnittstelle:

Basierend auf dem Manifest wird eine TypeScript-Deklarationsdatei erzeugt, die das KickAssets-Interface erweitert. Dieses Interface spiegelt die Struktur des Manifests exakt wider. Dadurch wird sichergestellt, dass Zugriffe wie assets.mails.welcome nur dann kompilieren, wenn die Datei tatsächlich im Manifest definiert ist.

Der typsichere Proxy löst die Asset-Pfade zur Laufzeit auf. Wird ein Asset wie assets.mails.welcome() aufgerufen, durchsucht der Proxy das Manifest und gibt den korrekten Pfad zurück – ohne manuelle Pfadberechnungen oder Umgebungsabfragen. Jeder Tippfehler oder fehlende Eintrag führt zu einem Compiler-Fehler und nicht zu einem Runtime-Crash.

Vier Möglichkeiten, Assets zu nutzen

Der KickJS Asset Manager bietet unterschiedliche Konsumptionsmuster, die alle auf demselben Manifest basieren – je nach Anwendungsfall mehr oder weniger ergonomisch.

1. Der eingebettete Proxy – Standardlösung für die meisten Fälle

Der einfachste Ansatz: Einmal importieren und überall nutzen. Der Proxy ist als Singleton verfügbar und bietet IDE-Unterstützung durch Autovervollständigung.

import { assets } from '@forinda/kickjs';

// Pfadauflösung – typsicher und plattformunabhängig
const path = assets.mails.welcome();
const html = await renderEjs(await readFile(path, 'utf8'), { user });

Die Struktur assets. zeigt alle verfügbaren Kategorien an, assets.mails. listet die definierten Assets auf – ideal für die Entwicklung mit moderner IDE-Unterstützung.

2. useAssets() – Factory-Muster für Dependency Injection

Manchmal soll der Resolver nicht als Singleton vorliegen, sondern als Factory oder für Tests austauschbar sein. Hier kommt die Funktion useAssets() ins Spiel.

import { useAssets } from '@forinda/kickjs';

class MailService {
  constructor(private readonly assets = useAssets()) {}

  async sendWelcome() {
    const path = this.assets.mails.welcome();
    const html = await renderTemplate(path);
    return html;
  }
}

Dieses Muster eignet sich besonders für Dependency Injection oder das Mocken in Tests, ohne die Importstruktur des Projekts zu verändern.

3. @Asset() – Dekorator für deklarative Resolution

Für klassische, objektorientierte Services bietet sich der Klassenfeld-Dekorator an. Die Asset-Resolution erfolgt erst bei erstem Zugriff – und bleibt typsicher.

import { Asset } from '@forinda/kickjs';

class MailService {
  @Asset('mails/welcome')
  private welcomeTemplate!: string;

  async send(user: User) {
    const html = await renderEjs(
      await readFile(this.welcomeTemplate, 'utf8'),
      { user }
    );
    return html;
  }
}

Der String-Parameter wird gegen das Manifest validiert. Falsche Pfade führen bereits zur Kompilierzeit zu Fehlern.

4. resolveAsset() – Dynamische Auflösung bei Bedarf

In Fällen, in denen die Asset-Kategorie erst zur Laufzeit bestimmt wird – etwa bei feature-flaggten Templates oder nutzerdefinierten Vorlagen – kommt die Funktion resolveAsset() zum Einsatz.

import { resolveAsset } from '@forinda/kickjs';

const category = 'mails';
const slug = 'welcome'; // Oder dynamisch aus einer Datenbank
const path = resolveAsset(category, slug);

Die Kategorie bleibt typsicher, während die konkrete Datei erst zur Laufzeit aufgelöst wird. Fehlende Einträge führen zu einem klaren Runtime-Fehler – nicht zu einem falschen Pfad.

Der Build-Prozess: Von der Konfiguration zum fertigen Asset

Der KickJS Asset Manager trennt die Verantwortlichkeiten strikt in Build- und Runtime-Phase. Der Prozess ist transparent und lässt sich individuell anpassen:

1. Konfiguration in `kick.config.ts`:

Im Projekt wird definiert, welche Assets kopiert werden sollen – inklusive optionaler Zielpfade oder Glob-Muster.

1. Asset-Kopie und Manifest-Generierung:

Der Befehl kick build:assets oder kick build (je nach Konfiguration) durchsucht die angegebenen Quellverzeichnisse, kopiert die Dateien in das dist/-Verzeichnis und generiert das Manifest sowie die Typsignaturen.

1. Typische Konfiguration:

   {
     assetMap: {
       mails: {
         src: 'src/assets/mails',
         dest: 'templates', // Optional: Zielverzeichnis in dist/
         glob: '**/*.ejs',  // Standard: **/*
       },
     },
   }

1. Integration in den Build-Workflow:

Der KickJS Asset Manager lässt sich nahtlos in bestehende Build-Prozesse integrieren. Nach der Generierung stehen die Assets im Zielverzeichnis bereit – und das Runtime-System löst sie zuverlässig auf.

Fazit: Weniger Runtime-Fehler, mehr Entwicklerproduktivität

Der KickJS Asset Manager adressiert ein fundamentales Problem der Node.js-Entwicklung: die Diskrepanz zwischen Entwicklungs- und Produktionsumgebungen bei der Asset-Verwaltung. Durch die Kombination aus Build-zeit-generierten Manifesten, typsicheren Proxies und klaren Konsumptionsmustern eliminiert er typische Fehlerquellen wie falsche Pfade oder fehlende Typsicherheit.

Die Lösung ist besonders für Projekte sinnvoll, die auf statische Dateien wie Templates, Schemata oder Konfigurationsdateien angewiesen sind. Statt manuelle Workarounds zu pflegen, setzt der Asset Manager auf Automatisierung und Typsicherheit – und das bereits zur Kompilierzeit. Für Teams, die ihre Asset-Verwaltung professionalisieren möchten, ist KickJS Asset Manager eine überzeugende Wahl.