docs: plugin authors guide for rolldown-vite (#706) (#1044)

Co-authored-by: Rush Ali <s0aPii.ra@googlemail.com>

closes #706 #1044

Author: mstelbrink

docs/guide/rolldown.md

@@ -90,4 +90,107 @@ Für Echtzeit-Diskussionen und Fehlerbehebung treten Sie bitte dem [Rolldown Dis
 
 Das Paket `rolldown-vite` ist eine vorübergehende Lösung, um Feedback zu sammeln und die Rolldown-Integration zu stabilisieren. In Zukunft wird diese Funktionalität wieder in das Haupt-Repository von Vite integriert werden.
 
-Wir ermutigen Sie, `rolldown-vite` auszuprobieren und durch Feedback und Fehlerberichte zur Entwicklung beizutragen.
+Wir ermutigen Sie, `rolldown-vite` auszuprobieren und durch Feedback und Fehlerberichte zur Entwicklung beizutragen.
+
+## Plugin- / Framework-Authoren Leitfaden
+
+### Liste von großen Änderungen
+
+- Rolldown wird für den Build genutzt (Rollup wurde zuvor verwendet)
+- Rolldown wird für den Optimierer genutzt (esbuild wurde zuvor verwendet)
+- CommonJS Unterstützung wird von Rollup bereitgestellt (@rollup/plugin-commonjs zuvor verwendet)
+- Oxc wird zur Syntax-Reduktion genutzt (esbuild wurde zuvor verwendet)
+- Lightning CSS wird standardmäßig zur Minifizierung von CSS genutzt (esbuild wurde zuvor verwendet)
+- Oxc-Minifier wird standardmäßig zur Minifizierung von JS genutzt (esbuild wurde zuvor verwendet)
+- Rolldown wird zum Bündeln der Konfiguration genutzt (esbuild wurde zuvor verwendet)
+
+
+### Rolldown-Vite erkennen
+
+Sie können es entweder erkennen durch
+
+- Prüfen der Existenz von `this.meta.rolldownVersion`
+
+```js
+const plugin = {
+  resolveId() {
+    if (this.meta.rolldownVersion) {
+      // Logik für rolldown-vite
+    } else {
+      // Logik für rollup-vite
+    }
+  },
+}
+```
+
+- Prüfen der Existenz des `rolldownVersion` Exports
+
+```js
+import * as vite from 'vite'
+
+if (vite.rolldownVersion) {
+  // Logik für rolldown-vite
+} else {
+  // Logik für rollup-vite
+}
+```
+
+Wenn sie `vite` als Abhängigkeit (nicht als Peer-Abhängigkeit) haben, bietet sich der `rolldownVersion`-Export an, da er überall in Ihrem Code verwendet werden kann.
+
+### Ignorieren von Optionsvalidierung in Rolldown
+
+Rolldown wirft einen Fehler, wenn unbekannte oder ungültige Optionen angegeben werden. Da manche Optionen, die in Rollup verfügbar sind, in Rolldown nicht zur Verfügung stehen, kann es zu Fehlern kommen. Im Folgenden sehen Sie ein Beispiel für solch eine Fehlermeldung:
+
+> Error: Failed validate input options.
+>
+> - For the "preserveEntrySignatures". Invalid key: Expected never but received "preserveEntrySignatures".
+
+Dieser Fehler kann behoben werden, in dem die Option nur unter bestimmten Bedingungen angegeben wird. Wie oben gezeigt, muss dann in der Bedingung geprüft werden, ob das Programm mit `rolldown-vite` ausgeführt wird.
+
+Wenn Sie den Fehler vorerst unterdrücken möchten, können Sie die Umgebungsvariable `ROLLDOWN_OPTIONS_VALIDATION=loose` setzen. Beachten Sie allerdings, dass Sie irgendwann aufhören müssen, Optionen anzugeben, die nicht von Rolldown unterstützt werden.
+
+### `transformWithEsbuild` benötigt eine seperate `esbuild` Installation
+
+Eine ähnliche Funktion namens `transformWithOxc`, die Oxc anstelle von `esbuild` verwendet, wird von `rolldown-vite` exportiert.
+
+### Kompatibilitätsschicht für `esbuild`-Optionen
+
+Rolldown-Vite hat eine Kompatibilitätsschicht, um Optionen von `esbuild` für Oxc oder `rolldown` zu konvertieren. Getestet wurde in der [ecosystem-ci](https://github.com/vitejs/vite-ecosystem-ci/blob/rolldown-vite/README-temp.md) und funktioniert für viele Fälle, inklusive einfacher `esbuild`-Plugins.
+In Zukunft **werden wir die Unterstützung für `esbuild`-Optionen entfernen** und Sie ermutigen, die entsprechenden Optionen von Oxc oder `rolldown` zu verwenden.
+Sie können das Set an Optionen von der Kompatibilitätsschicht mit Hilfe der `configResolved`-Hook erhalten.
+
+```js
+const plugin = {
+  name: 'log-config',
+  configResolved(config) {
+    console.log('options', config.optimizeDeps, config.oxc)
+  },
+},
+```
+
+### Hook-Filter Funktion
+
+Rolldown hat eine [Hook-Filter](https://rolldown.rs/guide/plugin-development#plugin-hook-filters) Funktion eingeführt, um den Kommunikationsaufwand zwischen Rust und JavaScript Laufzeiten zu verringern. Durch die Verwendung dieser Funktion, können Sie Ihre Plugins performanter gestalten.
+
+Dies wird auch von Rollup 4.38.0+ und Vite 6.3.0+ unterstützt. Um eine Rückwärtskompatibilität für ältere Versionen für Ihr Plugin zu gewährleisten, sollten Sie die Filter auch im Hook-Behandler ausführen.
+
+### Inhalt zu JavaScript konvertieren in `load`- oder `transform`-Hooks
+
+Wenn Sie den Inhalt von anderen Typen zu JavaScript konvertieren in `load`- oder `transform`-Hooks, müssen Sie möglicherweise `moduleType: 'js'` zur zurückgegebenen Variable hinzufügen.
+
+```js
+const plugin = {
+  name: 'txt-loader',
+  load(id) {
+    if (id.endsWith('.txt')) {
+      const content = fs.readFile(id, 'utf-8')
+      return {
+        code: `export default ${JSON.stringify(content)}`,
+        moduleType: 'js', // [!code ++]
+      }
+    }
+  },
+}
+```
+
+Das liegt daran, dass [Rolldown unterstützt JavaScript-fremde Module](https://rolldown.rs/guide/in-depth/module-types) und leitet sich den Modultyp aus der Erweiterung ab, außer es wird spezifiziert. Beachten Sie, dass `rolldown-vite` keine ModuleTypes in dev unterstützt.