Ecrire des modules NPM dans Typescript

Je travaille sur mon premier module NPM. J'ai brièvement travaillé avec dactylographié auparavant et un gros problème était que pour de nombreux modules, il n'y avait pas de fichiers de définition disponibles. J'ai donc pensé que ce serait une bonne idée d'écrire mon module en tapuscrit.

Cependant, je ne trouve aucune information sur la meilleure façon de procéder. J'ai trouvé cette question connexe " Puis-je écrire le package npm dans coffeescript? " Où les gens suggèrent de publier uniquement les fichiers javascript. Mais contrairement aux fichiers coffeescript, les fichiers dactylographiés peuvent en fait être utiles s'ils sont utilisés dans une application dactylographiée.

Dois-je inclure des fichiers Typescript lors de la publication d'un module NPM, ou dois-je publier uniquement les fichiers javascript et fournir les fichiers .d.ts générés à DefinitelyTyped?

Voici un exemple de module Node écrit en TypeScript: https://github.com/basarat/ts-npm-module

Voici un exemple de projet TypeScript qui utilise cet exemple de module https://github.com/basarat/ts-npm-module-consume

Fondamentalement, vous devez:

• compiler avec commonjsetdeclaration:true
• générer un .d.tsfichier

Puis

• Demandez à votre idée de lire le fichier généré .d.ts.

Atom-TypeScript fournit juste un bon flux de travail autour de ceci: https://github.com/TypeStrong/atom-typescript#packagejson-support

Avec TypeScript 3.x ou TypeScript 2.x, les étapes suivantes décrivent ce que vous devez faire pour créer une bibliothèque (package npm) avec TypeScript:

• Créez votre projet comme vous le feriez normalement (avec des tests et tout)
• Ajoutez declaration: trueà tsconfig.jsonpour générer des typages.
• Exportez l'API via un index.ts
• dans le package.json , pointez sur vos typages générés. Par exemple, si outDirc'est le cas dist, ajoutez "types": "dist/index.d.ts"à votre package json.
• dans le package.json , pointez sur votre fichier d'entrée principal. Par exemple, si votre outDirest distet le fichier d'entrée principal est index.js, ajoutez "main": "dist/index.js"à votre package.json.
• Créez un .npmignorepour ignorer les fichiers inutiles (par exemple la source).
• Publiez sur npm avec npm publish. Utiliser les spécifications semver pour les mises à jour (correctif / correction de boguenpm version patch , ajouts sans rupture npm version minor, changements de rupture d'API npm version major)

Puisqu'il m'a fallu un certain temps pour passer au crible toutes les ressources obsolètes sur ce sujet sur Internet (comme celle de cette page ...), j'ai décidé de conclure dans comment-écrire-une-bibliothèque-typographique avec un exemple minimal de travail à jour.

Voici une réponse plus récente utilisant TypeScript 1.8.10:

La structure de mon projet est:

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

J'ai ajouté ce qui suit .npmignorepour éviter d'inclure des fichiers superflus et garder le strict minimum pour que le package soit importé et fonctionne:

node_modules/
*.log
*.tgz

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

Mon .gitignorea:

typings

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

Mon package.jsona:

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

Maintenant je cours: npm pack

Le fichier résultant (une fois décompressé) a la structure suivante:

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

Maintenant, je vais au projet où je veux utiliser ceci comme bibliothèque et tapez: npm install ./project-1.0.0.tgz

Il s'installe avec succès.

Maintenant je crée un fichier index.ts dans mon projet où je viens d'installer le npm import Project = require("project");

Dactylographie Project. me donne les options Intellisense qui étaient le point de tout cet exercice.

J'espère que cela aidera quelqu'un d'autre à utiliser leurs projets TypeScript npm comme bibliothèques internes dans leurs projets plus importants.

PS: Je crois que cette approche de compilation de projets en modules npm qui peuvent être utilisés dans d'autres projets rappelle le .dlldans le.NET monde. Je pourrais bien imaginer des projets organisés dans une solution dans VS Code où chaque projet produit un package npm qui peut ensuite être utilisé dans un autre projet de la solution en tant que dépendance.

Puisqu'il m'a fallu beaucoup de temps pour comprendre cela, je l'ai publié au cas où quelqu'un serait coincé ici.

Je l'ai également posté pour un bug fermé à: https://github.com/npm/npm/issues/11546

Cet exemple a été téléchargé sur Github: vchatterji / tsc-seed

Vous devez publier les sources dactylographiées d'origine au lieu de la définition de type. Dans package.jsonlaissez la propriété 'types' pointer vers le fichier * .ts.

*.d.ts sont bons pour annoter les bibliothèques JS existantes, mais en tant que consommateur, je préfère lire le code dactylographié plutôt que de basculer entre les définitions de type et le code JS généré de bas niveau.

Je suis principalement la suggestion de Varun Chatterji

Mais, je voudrais montrer un exemple complet avec des tests unitaires et une couverture de code et le publier npmet les importer en utilisant javascriptoutypescript

Ce module est écrit en utilisant typescript 2.2et il est important de configurer le prepublishhook pour compiler le code en utilisanttsc avant de le publier sur npm

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

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

Vous pouvez utiliser autodts pour gérer la distribution et l'utilisation de .d.tsfichiers de npm également sans prise en charge de l'IDE Atom.

autodts generateregroupera tous vos propres .d.tsfichiers pour les publier sur npm, et autodts linkgère les références à d'autres packages installés, qui peuvent ne pas toujours être directement sous node_modulesdans un projet plus vaste divisé en plusieurs sous-packages.

Les deux commandes lisent leurs paramètres depuis package.jsonet tsconfig.jsondans le style «convention sur la configuration».

Il y a une autre réponse sur stackoverflow et un article de blog avec plus de détails.

Chez Lossless, nous avons créé un outil de développement TypeScript unique pour les packages npm: https://gitzone.gitlab.io/npmts/