Der einfachste Weg, Ihr erstes NPM-Paket zu erstellen

Dieser Leitfaden führt Sie von Anfang bis Ende durch den einfachsten Prozess zum Erstellen und Freigeben Ihres NPM-Pakets mithilfe eines Mikrobundles .

Lassen Sie uns ein wenig über das microbundle sprechen. Ich finde es besonders effektiv für einfache Bibliotheken, da Sie sich nicht um die Konfiguration kümmern müssen und sich auf die Entwicklung Ihres Pakets konzentrieren können.

Hier ist eine kurze Liste seiner Funktionen:

• Integrierte Konfigurationen; Sie müssen lediglich ein „Export“-Feld in package.json hinzufügen
• TypeScript-Unterstützung sofort einsatzbereit ohne tsconfig.json
• Mehrere Ausgabeformate (CJS, UMD und ESM)
• Integrierte Terser-Komprimierung

Grundsätzlich basiert microbundle auf rollup.js . Wenn Sie komplexere Bibliotheken erstellen müssen, als ich in diesem Artikel erwähne, könnten Sie die Verwendung einer reinen rollup.js Konfiguration in Betracht ziehen.

Initialisieren Sie Ihr Paket

Als Beispiel erstellen wir eine einfache Bibliothek zum Summieren zweier Zahlen, die nur eine Funktion sum exportiert.

1. Erstellen Sie einen Ordner für das Projekt und führen Sie npm init mit Standardwerten aus, um package.json zu generieren

   
   

2. Erstellen Sie index.ts im src Ordner

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. microbundle installieren

   npm i -D microbundle

   
   

4. Aktualisieren Sie package.json mit den folgenden Werten:

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Führen Sie das Build-Skript aus

   npm run build

   
   

   Die Ausgabe sollte genau die Dateien enthalten, die wir in package.json deklariert haben

   

Und voilà, wir haben unser erstes Paket gemacht. Werfen wir einen Blick auf komplexere Szenarien.

Hinzufügen von React zu Ihrer Bibliothek

Wenn Sie React in Ihre Bibliothek integrieren möchten, können Sie es weiterhin microbundle verwenden, aber jetzt sollte Ihr Build-Befehl so aussehen:

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Fügen Sie den Befehl zur späteren Vereinfachung zu package.json in build Skript ein:

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Verwenden von Storybook für UI-Komponenten

Beim Erstellen einer UI-Bibliothek benötigen Sie möglicherweise eine Sandbox, in der Sie Komponenten entwickeln, visualisieren und Demokomponenten für Ihre Dokumentation bereitstellen können.

Hier kommt das Bilderbuch . Es handelt sich um eine Sandbox mit eigener praktischer Schnittstelle und Bundler, in der Sie problemlos verschiedene Zustände Ihrer Komponenten beschreiben können. Jede Erfassung Ihres Komponentenstatus wird als „Story“ bezeichnet.

Dieses Bild aus ihrer Dokumentation zeigt, wie es aussieht:

Die Installation von Storybook ist recht einfach. Führen Sie einfach den Befehl in Ihrer Bibliothek aus:

 npx storybook@latest init

Dieser Befehl installiert alle erforderlichen Abhängigkeiten für Storybook, fügt auszuführende Skripte hinzu und baut Storybook in package.json ein, erstellt einen Ordner .storybook mit Standardkonfiguration und fügt dem Ordner src/stories einige Beispiele für Storys hinzu.

Integrieren Sie Styling in Ihre Bibliothek

Sie können Stile auf zwei Arten hinzufügen: CSS-Datei oder CSS-in-JS. Die CSS-Datei ermöglicht eine einfache Anpassung, erfordert jedoch eine separate Einbindung, während CSS-in-JS das Styling vereinfacht, aber die Bundle-Größe erhöht.

• CSS-Datei

  Erstellen Sie eine CSS-Datei im src-Verzeichnis und importieren Sie sie in die Root-React-Komponentendatei:

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Führen wir also den Build-Befehl erneut aus.

   npm run build

  
  

  Und Ihre importierte Datei styles.css wird im Ordner dist erstellt:

  

  Großartig! Wir haben eine CSS-Datei mit den notwendigen Stilen erhalten. Allerdings gibt es bei dieser Lösung eine kleine Unannehmlichkeit. Die CSS-Datei muss nach der Installation des Pakets separat hinzugefügt werden.

  
  

  Daher müssen Benutzer Ihrer Bibliothek einen CSS-Loader (z. B. einen CSS-Loader für das Webpack) verwenden, um Ihre CSS-Datei zu verarbeiten, und ihre Verwendung sieht folgendermaßen aus:

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS-in-JS

  Zu diesem Zweck können Sie Bibliotheken wie styled-components verwenden. Und es wird so aussehen:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Mit dieser Lösung müssen Benutzer keine CSS-Datei importieren und keinen speziellen Loader für ihr Projekt hinzufügen. Nach der Installation der Bibliothek verfügt die Komponente über ein eigenes Design. Allerdings erhöht sich dadurch die Bundle-Größe und es wird für Benutzer schwieriger, Elemente mithilfe von CSS-Selektoren anzupassen.

Wählen Sie die Option, die am besten zu Ihnen passt. Ich bevorzuge die Verwendung der CSS-Datei, da Benutzer damit jedes Element mit CSS-Selektoren anpassen können, die Bundle-Größe nicht beeinträchtigt wird und schneller funktioniert.

Entwickeln einer detaillierten README.md- Datei

Eine README.md- Datei enthält Informationen über Ihre Bibliothek, deren Installation, ihre grundlegende Verwendung und die darin enthaltenen Funktionen. Dies ist häufig die erste Datei, die Entwickler lesen, wenn sie auf Ihr Repository oder NPM-Paket stoßen. Daher sollte sie prägnant und informativ sein.

Ich erstelle gerne eine Struktur in der folgenden Reihenfolge:

1. Titel
2. Super kurze Paketbeschreibung
3. Ausgefallene Statistikabzeichen ( shields.io )
4. Wenn es sich bei Ihrer Bibliothek um eine UI-Komponente handelt, fügen Sie einen Screenshot hinzu oder stellen Sie einen Demo-Link auf CodeSandbox bereit
5. Funktionsliste
6. Installationsanleitung
7. Codefragmente mit Verwendung
8. Optionen und Requisiten, die Ihre Bibliothek zur Konfiguration akzeptiert

Als Inspiration können Sie sich Beispiele für README.md Dateien aus meinen Paketen ansehen, z. B. dot-path-value und React-nested-dropdown .

Navigieren im Abhängigkeitsmanagement

Dies ist ein wichtiger Teil, denn wenn Sie es falsch machen, können Benutzer mit Versionskonflikten oder anderen Problemen konfrontiert werden und müssen Ihre Bibliothek entfernen. Werfen wir also einen Blick auf die Hauptunterschiede zwischen den Abhängigkeitstypen.

• „devDependencies“ dienen nur der Entwicklung und sind nicht in Ihrem Paket enthalten. Wenn Sie beispielsweise das microbundle Paket installiert haben, das Benutzer nicht verwenden müssen, behalten Sie es in devDependencies und es wird nicht im Bundle angezeigt.

• „Abhängigkeiten“ werden zusammen mit dem Paket installiert. Fügen Sie Abhängigkeiten hinzu, die Ihr Paket benötigt, um in den Projekten der Benutzer zu funktionieren. Beachten Sie, dass einige Abhängigkeiten, wie z. B. „react“, möglicherweise bereits im Projekt des Benutzers installiert sind. Eine doppelte „Reagierung“ in Ihrem Paket könnte die Paketgröße erhöhen. Hier kommen „peerDependencies“ zum Einsatz.

• „peerDependencies“ sind Abhängigkeiten, die Ihr Paket verwendet, aber nicht in Ihr Bundle einschließt. Ihr Paket verwendet die Version der Abhängigkeit, die der Benutzer in seinem Projekt hat.

  
  

  Grundsätzlich sollten wir eine Peer-Abhängigkeit angeben, wenn wir eine Bibliothek für ihr Ökosystem erstellen. Wenn Sie beispielsweise eine React-Komponente erstellen, legen Sie React als Peer-Abhängigkeit fest. Wenn Sie eine React-Komponente mit einem Kalender entwickeln, fügen Sie React und eine Datumsberechnungsbibliothek (z. B. date-fns) als peerDependencies hinzu.

  
  

  Wenn der Benutzer nicht über die angegebene Peer-Abhängigkeit in seinem Projekt verfügt, zeigt der Befehl npm install eine Warnung an, installiert die Abhängigkeit jedoch nicht automatisch.

Nur ein kleines Beispiel, wie es aussieht:

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Verwenden Sie GitHub für Ihr Paket

Wenn Sie ein NPM-Paket veröffentlichen, bedeutet dies, dass es öffentlich zugänglich ist (sofern Sie über ein kostenloses Konto verfügen). Um Feedback von Benutzern zu sammeln, können Sie ein GitHub-Repository für Ihren Originalcode erstellen. Dort können die Leute Probleme erstellen und mit Ihnen über Ihr Paket kommunizieren. Sie können auch Ihre Veröffentlichungen beschreiben und einige Sterne erhalten!

Sie können diesen Schritt sicherlich überspringen, aber er ist ein integraler Bestandteil der Entwicklerkultur und kann einen wertvollen Beitrag zu Open Source leisten.

Veröffentlichen und Verwalten des Pakets

Bevor Sie Ihr Paket veröffentlichen können, müssen Sie unbedingt sicherstellen, dass Ihre package.json Datei ordnungsgemäß konfiguriert ist. Hier sind einige wichtige Schritte, die Sie befolgen sollten:

1. Benennen und versuchen Sie, die Kernfunktionalität Ihrer Bibliothek zu beschreiben. Zum Beispiel:

    "name": "react-color-picker"

   
   

2. Fügen Sie GitHub-Repository-Informationen hinzu (falls vorhanden):

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. Konfigurieren Sie die files :

    ... "files": [ "dist", ], ...

   Sie sollten die Dateien angeben, die bei der Installation Ihrer Bibliothek in node_modules enthalten sein werden. Normalerweise reicht es aus, den dist Ordner einzuschließen.

   
   

4. keywords hinzufügen:

   Schlüsselwörter sind eine Reihe von Zeichenfolgen, die Ihr Paket beschreiben und von NPM für Suchen und Empfehlungen verwendet werden. Wählen Sie Wörter aus, die für Ihr Paket relevant sind und von denen Sie erwarten, dass sie bei der Suche verwendet werden. Lassen Sie uns Schlüsselwörter für unsere sum erstellen:

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Es ist wichtig, Ihre Technologien anzugeben, da Benutzer häufig nach Begriffen wie „Typoskriptbibliothek für Mathematik“ oder „Kalenderauswahl reagieren“ suchen.

   
   

5. Erstellen Sie ein NPM- Konto, falls Sie dies noch nicht getan haben, und führen Sie npm login in Ihrem Terminal aus. Befolgen Sie die Anweisungen zur Authentifizierung Ihres Kontos. Standardmäßig ist die Version Ihres Pakets 1.0.0 ; Sie können es in der Datei package.json überprüfen. Ich empfehle, es auf 0.0.1 zu ändern.

   
   

6. Führen Sie npm publish aus, und schon sind Sie fertig! Um die Version in Zukunft zu aktualisieren, verwenden Sie den Befehl npm version patch um die Version zu erhöhen, und veröffentlichen Sie dann das aktualisierte Paket mit npm publish .

Abschluss

Wie Sie sehen, ist das Erstellen einer eigenen Bibliothek ganz einfach! Im Wesentlichen ist dies alles, was Sie zum Erstellen und Verwalten des Pakets benötigen. Wenn Sie Schwierigkeiten haben, Ihre Bibliothek mit microbundle einzuschränken, empfehle ich die Verwendung von rollup.js mit einer spezifischeren Konfiguration.

Das Erstellen von NPM-Paketen und das Mitwirken an Open Source ist eine lohnende und wertvolle Erfahrung für Entwickler aller Erfahrungsstufen. Es ermöglicht Ihnen, Ihren Code mit der Community zu teilen, viel Erfahrung zu sammeln und ein Portfolio Ihrer Arbeit aufzubauen.