Yarn-2-Plugins – eine Einführung

Artikel von

13. April 2020

0 Min. Lesezeit

Wenn Sie mehr über Yarn 2 und seine Plugin-Architektur erfahren möchten, empfehlen wir als Einstieg die Dokumentation zur Plugin-Architektur auf yarnpkg.com sowie das Yarn-2-Plugin-Tutorial auf der Website.

Wenn Sie neu bei Yarn 2 sind, empfehle ich Ihnen dringend, meinen Blogbeitrag zur Einführung in Yarn 2 zu lesen.

Ein Plugin für Yarn 2 entwickeln

Zunächst richten wir eine Umgebung zum Entwickeln des Plugins ein. Legen wir dafür ein neues Projekt an, das mit Yarn 2 verwaltet wird:

mkdir my-app
cd my-app
yarn policies set-version berry
yarn init

Damit erhalten wir ein unverändertes npm-Paketprojekt, das mit Yarn 2 verwaltet wird.

Damit Yarn während des Ablaufs ein Plugin aufruft, legen wir eine neue Datei namens .yarnrc.yml an und fügen dort die Plugin-Definition mit dem Pfad zu dem Plugin hinzu, das wir entwickeln:

plugins:
 - ./plugin-hook-install-hello-world.js

Weiter geht es mit dem Code des Plugins. Entwickeln wir etwas, das sich in eine Phase des Yarn-Ablaufs einklinkt, die afterAllInstalled heißt und nach der wir eine Meldung in der Konsole ausgeben. Der Plugin-Code sieht dann so aus:

const afterAllInstalled = project => {
 console.log("Everything is installed 🎉");
};

module.exports = {
 name: `plugin-hello-world`,
 factory: require => {
   return {
     default: {
       hooks: {
         afterAllInstalled
       }
     }
   };
 }
};

Um unser Plugin zu testen, führen Sie einfach den Befehl yarn über die CLI aus. Daraufhin sollte Folgendes ausgegeben werden:

➜ yarn
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed in 0s
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed in 0s
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed in 0.01s
Everything is installed 🎉
➤ YN0000: Done in 0.04s

Sehr cool, wir haben jetzt unser eigenes Yarn-2-Plugin!

Yarn-2-Plugins können viele verschiedene Aufgaben übernehmen: Sie können beispielsweise einen Befehl zur ausführbaren Datei von yarn hinzufügen, neue Resolver oder Fetcher bereitstellen, wie Yarn sie nennt, und sogar Yarn-Plugins miteinander verknüpfen!

Wenn Sie erfahren möchten, wie Sie ein Yarn-2-Plugin entwickeln, das Befehle zu Yarn hinzufügt, besuchen Sie die offizielle Dokumentation zu Yarn-Plugins. Sie führt Sie Schritt für Schritt durch den Prozess.

Mit einem Yarn-2-Plugin detaillierte Informationen zu Abhängigkeiten abrufen

Wie wir im vorherigen Beispiel gesehen haben, ermöglichen uns einige Hooks von Yarn eine engere Integration, indem sie ein globales öffentliches Objekt mit detaillierten Metadaten zum Projekt bereitstellen, die Yarn erfasst.

Im folgenden Beispiel integrieren wir uns erneut in den afterAllInstalled-Hook, der

mit einem zusätzlichen Parameter aufgerufen wird – dem öffentlichen Project-Objekt. Dank dieses zusätzlichen Parameters können wir auf alle Informationen zugreifen, die Yarn über das Projekt erfasst hat: Abhängigkeiten, Paketmanifest, Informationen zu Arbeitsbereichen und mehr.

Im folgenden Plugin-Beispiel plugin-hook-install-hello-brave-world.js speichern wir die Informationen dieses Objekts in der Variablen _ und schreiben deren Inhalt in eine JSON-Datei, um ihn genauer untersuchen zu können:

const fs = require("fs");
const util = require("util");

module.exports = {
 name: `plugin-hello-brave-world`,
 factory: require => {
   return {
     default: {
       hooks: {
         afterAllInstalled(_) {
           console.log("🎉 afterAllInstalled hook invoked");
           fs.writeFileSync("afterAll.json", util.inspect(_, false, 10));
         }
       }
     }
   };
 }
};

Die Objektstruktur von Project ist in packages/berry-core/sources/Project.ts definiert. Eine unvollständige Liste der Schlüssel auf der obersten Ebene des Objekts sieht wie folgt aus:

Project {
 configuration: {},
 cwd: {},
 workspaces: Map {},
 storedResolutions: Map {},
 storedDescriptors: Map {},
 storedPackages: Map {},
 storedChecksums: Map {},
 ...
}

Diese stored*-Schlüssel helfen uns dabei, die Abhängigkeiten zu verstehen und den Abhängigkeitsbaum für dieses Projekt zu erstellen.

Um die Sache einfach zu halten, führen wir dieses Plugin für ein npm-Projekt aus, das nur eine Abhängigkeit hat: debug. debug hat wiederum ms als Abhängigkeit.

Das Objekt storedPackages dient als Einstiegspunkt, um die Liste der Abhängigkeiten für dieses Projekt abzurufen. Beachten Sie, dass dieses Objekt auch einen Eintrag für den Namen des eigentlichen Projekts enthält, der durch die Referenz workspace: key gekennzeichnet ist.

Sehen wir uns an, wie der Eintrag für die Abhängigkeit debug in der storedPackages-Map aussieht:

'a1f870a4a95fff67eeac2388e06345982ebf1149c710f8efe18fe5d1967fec40db60987022a5c6fe55708167d1add4b63bc8ad6f755e20c6fba140d721180595' => { identHash:
       'd027b0b474dd440d333c0ae6200111acff30aa5931aeacf1841b1eb9212edea377606a118ff0f8675b69eabe9ff00db4f2f16659519c82810c6b534f9b8ad82d',
      scope: undefined,
      name: 'debug',
      locatorHash:
       'a1f870a4a95fff67eeac2388e06345982ebf1149c710f8efe18fe5d1967fec40db60987022a5c6fe55708167d1add4b63bc8ad6f755e20c6fba140d721180595',
      reference: 'npm:4.1.1',
      version: '4.1.1',
      languageName: 'node',
      linkType: 'hard',
      dependencies:
       Map {
         '299701b4a21f15498c990a6ec8bf49b0331f01e1d610cefaa6f7040bab1be634be89d1462245207c21d1334b31690861f303a0a71aa94f80445d80b9ee37eaf6' => { identHash:
            '299701b4a21f15498c990a6ec8bf49b0331f01e1d610cefaa6f7040bab1be634be89d1462245207c21d1334b31690861f303a0a71aa94f80445d80b9ee37eaf6',
           scope: undefined,
           name: 'ms',
           descriptorHash:
            '0742408cf974a8f1cd5081a9aec19656dc8016eec3c6e2358f302902e6f1f87241f601911cb45e855f3b0d26160c1520715ae79904c5ed1d29f5383ab906440e',
           range: 'npm:^2.1.1' } },
      peerDependencies: Map {},
      dependenciesMeta: Map {},
      peerDependenciesMeta: Map {},
      bin: Map {} },
    '9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33' => { identHash:
       '299701b4a21f15498c990a6ec8bf49b0331f01e1d610cefaa6f7040bab1be634be89d1462245207c21d1334b31690861f303a0a71aa94f80445d80b9ee37eaf6',
      scope: undefined,
      name: 'ms',
      locatorHash:
       '9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33',
      reference: 'npm:2.1.2',
      version: '2.1.2',
      languageName: 'node',
      linkType: 'hard',
      dependencies: Map {},
      peerDependencies: Map {},
      dependenciesMeta: Map {},
      peerDependenciesMeta: Map {},
      bin: Map {} },

Der Eintrag für debug enthält einen eindeutigen Hash zur Identifizierung, einige Metadaten wie die aufgelöste Version und ein weiteres verschachteltes dependencies-Objekt, das die Abhängigkeiten von debug auflistet. Allerdings werden Sie feststellen, dass ms im verschachtelten dependencies-Objekt nicht aufgelöst ist, sondern nur durch einen Versionsbereich angegeben wird.

Um die verschachtelten Abhängigkeiten aufzulösen, müssen wir den descriptorHash verwenden und in der Map storedResolutions nachschlagen. Sie sieht folgendermaßen aus:

storedResolutions:
  Map {
    '35f50d92512bedba8fbf78bdeae4f2bce60934a798f5e0a0ab58b087fb7dc73880c7ffee2e135c15e48ca70687336bbdf4163e75da3f90b55da5ba5e41d36051' => '35f50d92512bedba8fbf78bdeae4f2bce60934a798f5e0a0ab58b087fb7dc73880c7ffee2e135c15e48ca70687336bbdf4163e75da3f90b55da5ba5e41d36051',
    'ee78c55248c8a07a4079ce749bc462124c923d7b990785b50150c417b2821ca3363767b8dc304d80d4feae3faf9f95e1c2c46cebc582b81fe70a8f45a69b6377' => 'a1f870a4a95fff67eeac2388e06345982ebf1149c710f8efe18fe5d1967fec40db60987022a5c6fe55708167d1add4b63bc8ad6f755e20c6fba140d721180595',
    '0742408cf974a8f1cd5081a9aec19656dc8016eec3c6e2358f302902e6f1f87241f601911cb45e855f3b0d26160c1520715ae79904c5ed1d29f5383ab906440e' => '9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33' },

Der descriptorHash von ms lautet 0742408cf974a8f1cd5081a9aec19656dc8016eec3c6e2358f302902e6f1f87241f601911cb45e855f3b0d26160c1520715ae79904c5ed1d29f5383ab906440e. Wir finden ihn als drittes Element in storedResolutions. Er verweist auf den Hash 9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33, der wiederum einem Abhängigkeitseintrag in der Map storedPackages zugeordnet ist. Diesmal handelt es sich jedoch um die vollständig aufgelösten Abhängigkeitsmetadaten von ms:

'9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33' => { identHash:
       '299701b4a21f15498c990a6ec8bf49b0331f01e1d610cefaa6f7040bab1be634be89d1462245207c21d1334b31690861f303a0a71aa94f80445d80b9ee37eaf6',
      scope: undefined,
      name: 'ms',
      locatorHash:
       '9455a02525b0e2c50eca4e204d71900a775107249d4245c1ea1f95e3f124c8a1d27484b29ccea934895da4d0273b22dc95cefd0561c39490cd7c86ab4404ca33',
      reference: 'npm:2.1.2',
      version: '2.1.2',
      languageName: 'node',
      linkType: 'hard',
      dependencies: Map {},
      peerDependencies: Map {},
      dependenciesMeta: Map {},
      peerDependenciesMeta: Map {},
      bin: Map {} },

Yarn-2-Plugins im Überblick

Yarn 2 ist noch neu und gewinnt gerade Nutzerinnen und Nutzer hinzu, während die Community Feedback gibt. Das macht jetzt zu einem idealen Zeitpunkt, um an Plugins zu arbeiten.

Starten Sie mit Capture-the-Flag

Erfahren Sie in unserem virtuellen On-Demand-Workshop für Einsteiger, wie Sie Capture-the-Flag-Challenges lösen.

Jetzt ansehen

Ein Plugin für Yarn 2 entwickeln

Mit einem Yarn-2-Plugin detaillierte Informationen zu Abhängigkeiten abrufen

Yarn-2-Plugins im Überblick

Starten Sie mit Capture-the-Flag

Weiterlesen