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 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. microbundle Hier ist eine kurze Liste seiner Funktionen: Integrierte Konfigurationen; Sie müssen lediglich ein „Export“-Feld in hinzufügen package.json TypeScript-Unterstützung sofort einsatzbereit ohne tsconfig.json Mehrere Ausgabeformate (CJS, UMD und ESM) Integrierte Terser-Komprimierung Grundsätzlich basiert auf . Wenn Sie komplexere Bibliotheken erstellen müssen, als ich in diesem Artikel erwähne, könnten Sie die Verwendung einer reinen Konfiguration in Betracht ziehen. microbundle rollup.js rollup.js Initialisieren Sie Ihr Paket Als Beispiel erstellen wir eine einfache Bibliothek zum Summieren zweier Zahlen, die nur eine Funktion exportiert. sum Erstellen Sie einen Ordner für das Projekt und führen Sie mit Standardwerten aus, um zu generieren npm init package.json Erstellen Sie im Ordner index.ts src // src/index.ts export function sum(a: number, b: number) { return a + b; } installieren microbundle npm i -D microbundle Aktualisieren Sie mit den folgenden Werten: package.json // 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 } ... Führen Sie das Build-Skript aus npm run build Die Ausgabe sollte genau die Dateien enthalten, die wir in deklariert haben package.json 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 verwenden, aber jetzt sollte Ihr Build-Befehl so aussehen: microbundle microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx Fügen Sie den Befehl zur späteren Vereinfachung zu in Skript ein: package.json build // 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 . 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. Bilderbuch 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 ein, erstellt einen Ordner mit Standardkonfiguration und fügt dem Ordner einige Beispiele für Storys hinzu. package.json .storybook src/stories Styling Bibliothek Integrieren Sie in Ihre 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 wird im Ordner erstellt: styles.css dist 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 verwenden. Und es wird so aussehen: styled-components 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 Datei README.md- Eine 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. README.md- Ich erstelle gerne eine Struktur in der folgenden Reihenfolge: Titel Super kurze Paketbeschreibung Ausgefallene Statistikabzeichen ( ) shields.io 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 Funktionsliste Installationsanleitung Codefragmente mit Verwendung Optionen und Requisiten, die Ihre Bibliothek zur Konfiguration akzeptiert Als Inspiration können Sie sich Beispiele für Dateien aus meinen Paketen ansehen, z. B. und . README.md dot-path-value 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 Paket installiert haben, das Benutzer nicht verwenden müssen, behalten Sie es in devDependencies und es wird nicht im Bundle angezeigt. microbundle „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 eine Warnung an, installiert die Abhängigkeit jedoch nicht automatisch. npm install 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 Datei ordnungsgemäß konfiguriert ist. Hier sind einige wichtige Schritte, die Sie befolgen sollten: package.json Benennen und versuchen Sie, die Kernfunktionalität Ihrer Bibliothek zu beschreiben. Zum Beispiel: "name": "react-color-picker" 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" }, ... Konfigurieren Sie die : files ... "files": [ "dist", ], ... Sie sollten die Dateien angeben, die bei der Installation Ihrer Bibliothek in enthalten sein werden. Normalerweise reicht es aus, den Ordner einzuschließen. node_modules dist hinzufügen: keywords 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 erstellen: sum ... "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. Erstellen Sie ein Konto, falls Sie dies noch nicht getan haben, und führen Sie in Ihrem Terminal aus. Befolgen Sie die Anweisungen zur Authentifizierung Ihres Kontos. Standardmäßig ist die Version Ihres Pakets ; Sie können es in der Datei überprüfen. Ich empfehle, es auf zu ändern. NPM- npm login 1.0.0 package.json 0.0.1 Führen Sie aus, und schon sind Sie fertig! Um die Version in Zukunft zu aktualisieren, verwenden Sie den Befehl um die Version zu erhöhen, und veröffentlichen Sie dann das aktualisierte Paket mit . npm publish npm version patch 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 einzuschränken, empfehle ich die Verwendung mit einer spezifischeren Konfiguration. microbundle von rollup.js 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.
