Schreiben von NPM-Modulen in Typescript

Ich arbeite an meinem ersten NPM-Modul. Ich habe vorher kurz mit Typoskript gearbeitet und ein großes Problem war, dass für viele Module keine Definitionsdateien verfügbar waren. Daher hielt ich es für eine gute Idee, mein Modul in Typoskript zu schreiben.

Ich kann jedoch keine Informationen darüber finden, wie dies am besten funktioniert. Ich habe diese verwandte Frage " Kann ich ein npm-Paket in Coffeescript schreiben? " Gefunden, bei der vorgeschlagen wird, nur die Javascript-Dateien zu veröffentlichen. Im Gegensatz zu den Coffeescript-Dateien können die Typoskript-Dateien jedoch nützlich sein, wenn sie in einer Typoskript-Anwendung verwendet werden.

Sollte ich beim Veröffentlichen eines NPM-Moduls Typescript-Dateien einschließen oder sollte ich nur die Javascript-Dateien veröffentlichen und die generierten .d.ts-Dateien für DefinitelyTyped bereitstellen?

Hier ist ein Beispielknotenmodul, das in TypeScript geschrieben wurde: https://github.com/basarat/ts-npm-module

Hier ist ein Beispiel für ein TypeScript-Projekt, das dieses Beispielmodul verwendet: https://github.com/basarat/ts-npm-module-consume

Grundsätzlich müssen Sie:

• kompilieren mit commonjsunddeclaration:true
• Generieren Sie eine .d.tsDatei

Und dann

• Lassen Sie Ihre Idee das Generierte lesen .d.ts.

Atom-TypeScript bietet lediglich einen schönen Workflow: https://github.com/TypeStrong/atom-typescript#packagejson-support

In TypeScript 3.x oder TypeScript 2.x wird in den folgenden Schritten beschrieben, was Sie tun müssen, um eine Bibliothek (npm-Paket) mit TypeScript zu erstellen:

• Erstellen Sie Ihr Projekt wie gewohnt (mit Tests und allem)
• Hinzufügen declaration: truezu tsconfig.json, um Tippungen zu generieren.
• Exportieren Sie die API über eine index.ts
• In der package.json, weisen auf Ihre generierten Typisierungen. Wenn dies beispielsweise der Fall outDirist dist, fügen Sie "types": "dist/index.d.ts"Ihrem Paket json hinzu.
• Zeigen Sie in der package.jsonauf Ihre Haupteintragsdatei. Zum Beispiel , wenn Ihr outDirheißt distund die Haupteingangsdatei index.js, fügen Sie dann "main": "dist/index.js"zu Ihrem package.json.
• Erstellen Sie eine .npmignore, um unnötige Dateien (z. B. die Quelle) zu ignorieren.
• Veröffentlichen Sie auf npm mit npm publish. Verwenden Sie Semver-Spezifikationen für Updates (Patch- / Bugfix npm version patch, nicht brechende Ergänzungen npm version minor, brechende API-Änderungen npm version major).

Da ich eine Weile gebraucht habe, um alle veralteten Ressourcen zu diesem Thema im Internet zu durchsuchen (wie die auf dieser Seite ...), habe ich beschlossen, sie in eine Anleitung zum Schreiben einer Typoskript-Bibliothek mit einem zu packen aktuelles Arbeitsminimalbeispiel.

Dies ist eine neuere Antwort mit TypeScript 1.8.10:

Meine Projektstruktur ist:

|
|--- src
|--- test
|--- dist     <= My gulp file compiles and places the js, sourcemaps and .d.ts files here
|      |--- src
|      |--- test
|--- typings
.gitignore
.npmignore
gulpfile.js
package.json
README.md
tsconfig.json
tslint.json
typings.json

Ich habe Folgendes hinzugefügt .npmignore, um zu vermeiden, dass überflüssige Dateien eingeschlossen werden, und das Minimum zu halten, damit das Paket importiert wird und funktioniert:

node_modules/
*.log
*.tgz

src/
test/
gulpfile.js
tsconfig.json
tslint.json
typings.json
typings
dist/test

Mein .gitignorehat:

typings

# ignore .js.map files
*.js.map
*.js
dist

Mein package.jsonhat:

"main": "dist/src/index.js",
"typings":  "dist/src/index.d.ts",

Jetzt renne ich: npm pack

Die resultierende Datei (beim Entpacken) hat die folgende Struktur:

|
|--- dist
|       |--- src
|              |
|              index.js
|              index.js.map
|              index.d.ts
|
package.json
README.md

Jetzt gehe ich zu dem Projekt, in dem ich dies als Bibliothek verwenden möchte, und tippe: npm install ./project-1.0.0.tgz

Es wird erfolgreich installiert.

Jetzt erstelle ich eine Datei index.tsin meinem Projekt, in der ich gerade die npm installiert habe import Project = require("project");

Durch das Tippen habe Project.ich die Intellisense-Optionen, um die es in dieser ganzen Übung ging.

Ich hoffe, dies hilft jemand anderem dabei, seine TypeScript npm-Projekte als interne Bibliotheken in größeren Projekten zu verwenden.

PS: Ich glaube, dass dieser Ansatz, Projekte zu npm-Modulen zu kompilieren, die in anderen Projekten verwendet werden können, an den .dllin der .NETWelt erinnert. Ich könnte mir gut vorstellen, dass Projekte in einer Lösung in VS Code organisiert werden, in der jedes Projekt ein npm-Paket erstellt, das dann in einem anderen Projekt in der Lösung als Abhängigkeit verwendet werden kann.

Da ich ziemlich viel Zeit gebraucht habe, um das herauszufinden, habe ich es veröffentlicht, falls jemand hier festsitzt.

Ich habe es auch für einen geschlossenen Fehler gepostet: https://github.com/npm/npm/issues/11546

Dieses Beispiel wurde auf Github hochgeladen: vchatterji / tsc-seed

Sie sollten die ursprünglichen Typoskriptquellen anstelle der Typdefinition veröffentlichen. In package.jsonläßt die Eigenschaft Punkt ‚Typen‘ auf die * .ts - Datei.

*.d.ts Es ist gut, vorhandene JS-Bibliotheken mit Anmerkungen zu versehen, aber als Verbraucher würde ich lieber den Typoskript-Code lesen, als zwischen Typdefinitionen und heruntergestuftem, generiertem JS-Code zu wechseln.

Ich folge hauptsächlich dem Vorschlag von Varun Chatterji

Ich möchte jedoch ein vollständiges Beispiel mit Unit-Tests und Codeabdeckung zeigen und es npmmit javascriptoder veröffentlichen und importierentypescript

Dieses Modul wurde mit geschrieben typescript 2.2und es ist wichtig, den prepublishHook so zu konfigurieren , dass der Code mit kompiliert wird, tscbevor er in npm veröffentlicht wird

https://github.com/sweetim/haversine-position

https://www.npmjs.com/package/haversine-position

Sie können Autodts verwenden , um das Verteilen und Verwenden von .d.tsDateien von npm auch ohne Unterstützung durch die Atom-IDE zu handhaben .

autodts generatebündelt alle Ihre eigenen .d.tsDateien für die Veröffentlichung auf npm und autodts linkverarbeitet Verweise auf andere installierte Pakete, die node_modulesin einem größeren Projekt, das in mehrere Unterpakete aufgeteilt ist , möglicherweise nicht immer direkt darunter liegen.

Beide Befehle lesen ihre Einstellungen aus package.jsonund tsconfig.jsonim Stil "Konvention über Konfiguration".

Es gibt eine weitere Antwort zu Stackoverflow und einen Blog-Beitrag mit weiteren Details.

Bei Lossless haben wir ein One-Stop-TypeScript-Entwicklungstool für npm-Pakete erstellt: https://gitzone.gitlab.io/npmts/