javascript - Scrierea modulelor npm în TypeScript

Lucrez la primul meu modul npm. Am lucrat puțin cu TypeScript înainte și o mare problemă era că pentru multe module nu existau fișiere de definire disponibile. Așa că m-am gândit că ar fi o idee bună să scriu modulul meu în TypeScript.

Totuși, nu pot găsi nicio informație despre cea mai bună modalitate de a face asta. Am găsit această întrebare legată „Pot să scriu un pachet npm în CoffeeScript?” unde oamenii sugerează să publici doar fișierele JavaScript. Dar, spre deosebire de fișierele CoffeeScript, fișierele TypeScript ar putea fi de fapt utile dacă sunt folosite într-o aplicație TypeScript.

Ar trebui să includ fișierele TypeScript atunci când public un modul npm, sau ar trebui să public doar fișierele JavaScript și să furnizez fișierele generate .d.ts către DefinitelyTyped?

Răspuns #1

Faceți următoarele pentru a crea un pachet npm folosind orice versiune de TypeScript de la 2.x -> 5.x:

  • Creează-ți proiectul așa cum ai face de obicei (cu teste și tot)
  • Adaugă declaration: true în tsconfig.json pentru a genera tipuri.
  • Exportă API-ul printr-un index.ts
  • În package.json, indică tipurile tale generate. De exemplu, dacă outDir este dist, atunci adaugă "types": "dist/index.d.ts" în package.json-ul tău.
  • În package.json, indică fișierul tău principal de intrare. De exemplu, dacă outDir este dist și fișierul principal de intrare este index.js, atunci adaugă "main": "dist/index.js" în package.json.
  • În package.json, includeți pe lista albă fișierele pe care doriți să le trimiteți către npm: files: ["/dist"]. O abordare alternativă este blocarea pe listă neagră folosind .npmignore, dar este mai greu de menținut actualizat.
  • Publică pe npm cu npm publish. Folosește specificațiile semver pentru actualizări (patch/corecție de bug npm version patch, adăugiri care nu rup compatibilitatea npm version minor, modificări majore de API npm version major)

Deoarece mi-a luat ceva timp să trec prin toate resursele învechite despre acest subiect de pe internet (cum este cea de pe această pagină...) am decis să rezum totul într-un ghid despre cum să scrii o bibliotecă TypeScript cu un exemplu minimal funcțional și actualizat.

Răspunsul #2

Iată un modul Node scris în TypeScript: https://github.com/basarat/ts-npm-module

Iată un proiect TypeScript de exemplu care folosește acest modul de exemplu https://github.com/basarat/ts-npm-module-consume

Practic, trebuie să:

  • compilați cu commonjs și declaration:true
  • generează un fișier .d.ts

Și atunci

  • Fă ca IDE-ul tău să citească fișierul generat .d.ts.

Atom-TypeScript oferă doar un flux de lucru plăcut în jurul acestuia: https://github.com/TypeStrong/atom-typescript#packagejson-support

Răspunsul #3

Aceasta este o răspuns mai recent folosind TypeScript 1.8.10:

Structura proiectului meu este:

|
|--- 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

Am adăugat următoarele în .npmignore pentru a evita includerea fișierelor inutile și pentru a păstra strictul necesar pentru ca pachetul să fie importat și să funcționeze:

node_modules/
*.log
*.tgz

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

Fișierul meu .gitignore conține:

typings

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

Fișierul meu package.json conține:

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

Acum rulez: npm pack

Fișierul rezultat (când este dezarhivat) are următoarea structură:

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

Acum merg la proiectul unde vreau să folosesc asta ca bibliotecă și scriu: npm install ./project-1.0.0.tgz

Se instalează cu succes.

Acum creez un fișier index.ts în proiectul meu unde tocmai am instalat npm import Project=require("project");

Tastând Project. îmi oferă opțiunile Intellisense, care a fost scopul întregului acestui exercițiu.

Sper că acest lucru îi ajută pe altcineva să folosească proiectele lor TypeScript npm ca biblioteci interne în proiectele lor mai mari.

PS: Cred că această abordare de a compila proiecte în module npm care pot fi utilizate în alte proiecte amintește de .dll în lumea .NET. Îmi pot imagina cu ușurință ca proiectele să fie organizate într-o Soluție în VS Code unde fiecare proiect produce un pachet npm care poate fi apoi utilizat într-un alt proiect din soluție ca o dependență.

Deoarece mi-a luat destul de mult timp să îmi dau seama de asta, am postat acest lucru în caz că cineva se blochează aici.

De asemenea, l-am postat pentru un bug închis la: https://github.com/npm/npm/issues/11546

Acest exemplu a fost încărcat pe Github: vchatterji/tsc-seed