web-dev-qa-db-fra.com

Ecriture de modules NPM en dactylographie

Je travaille sur mon premier module NPM. J'ai brièvement travaillé avec TypeScript auparavant et un gros problème était que pour de nombreux modules, aucun fichier de définition n'était disponible. J'ai donc pensé que ce serait une bonne idée d'écrire mon module en TypeScript.

Cependant, je ne trouve aucune information sur la meilleure façon de le faire. J'ai trouvé cette question connexe " Puis-je écrire le paquet npm dans coffeescript? " où les gens suggèrent de ne publier que les fichiers javascript. Mais contrairement aux fichiers coffeescript, les fichiers TypeScript peuvent être utiles s’ils sont utilisés dans une application TypeScript.

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

javascriptnode.jsnpmtypescript
89
Andreas Gassmann

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

Voici un exemple de projet TypeScript utilisant ce module exemple https://github.com/basarat/ts-npm-module-consume

Fondamentalement, vous devez:

  • compiler avec commonjs et declaration:true
  • générer un fichier .d.ts

Puis

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

Atom-TypeScript fournit juste un workflow Nice autour de ceci: https://github.com/TypeStrong/atom-TypeScript#packagejson-support

78
basarat

Méthode recommandée en 2018 avec TypeScript 2.x:

  • Créez votre projet comme vous le feriez normalement (avec des tests et tout le reste)
  • Ajouter declaration: true à tsconfig.json pour générer des typages.
  • Exporter l'API via un index.ts
  • Dans le package.json, pointez sur vos saisies générées. Par exemple, si votre outDir est dist, ajoutez "types": "dist/index.d.ts" à votre paquet json.
  • Dans le package.json, pointez sur votre fichier d’entrée principal. Par exemple, si votre outDir est dist et que le fichier d’entrée principal est index.js, puis ajouter "main": "dist/index.js" à votre package.json.
  • Créé un .npmignore pour ignorer les fichiers inutiles (par exemple la source).
  • Publier sur npm avec npm publish. Utiliser les spécifications semver pour les mises à jour (correctif/bogue corrigé npm version patch, ajouts intemporels npm version minor, briser les modifications d'api npm version major)

Comme il m’a fallu un certain temps pour passer en revue toutes les ressources obsolètes sur ce sujet sur Internet (comme celle de cette page ...), j’ai décidé de le résumer en comment écrire un TypeScript -library avec un exemple de travail à jour minimal .

65
bersling

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

Ma structure de 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 dans .npmignore Pour éviter d'inclure des fichiers superflus et de garder le strict minimum pour que le paquet soit importé et fonctionne correctement:

node_modules/
*.log
*.tgz

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

Mon .gitignore A:

typings

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

Mon package.json A:

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

Maintenant, je lance: npm pack

Le fichier résultant (lorsqu'il est 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 l'utiliser comme bibliothèque et je tape: npm install ./project-1.0.0.tgz

Il 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");

Taper Project. Me donne les options d’Intellisense qui étaient le but de tout cet exercice.

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

PS: Je pense que cette approche de compilation de projets en modules npm pouvant être utilisés dans d'autres projets rappelle le .dll Du .NET Monde. J'imaginais bien que les projets soient organisés dans une solution dans VS Code, chaque projet produisant un package npm pouvant ensuite être utilisé comme dépendance dans un autre projet de la solution.

Puisqu'il m'a fallu beaucoup de temps pour résoudre ce problème, je l'ai posté au cas où quelqu'un serait coincé ici.

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

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

57
Varun Chatterji

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

*.d.ts sont utiles pour annoter les bibliothèques JS existantes, mais en tant que consommateur, je préfère lire le code TypeScript que de basculer entre les définitions de type et le code JS généré, dégradé.

5
Sven Efftinge

Je suis principalement la suggestion de Varun Chatterji

Mais je voudrais montrer un exemple complet avec des tests unitaires et une couverture de code, le publier dans npm et les importer à l'aide de javascript ou TypeScript.

Ce module est écrit en utilisant TypeScript 2.2 et il est important de configurer le hook prepublish pour compiler le code avec tsc avant de le publier dans npm

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

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

5
Tim

Vous pouvez utiliser autodts pour gérer la distribution et l’utilisation de .d.ts fichiers de npm également sans support de Atom IDE.

autodts generate _ regroupera tous vos propres .d.ts fichiers ensemble pour publication sur npm, et autodts link gère les références à d’autres packages installés, qui ne sont pas toujours directement sous node_modules dans un projet plus grand divisé en plusieurs sous-packages.

Les deux commandes lisent leurs réglages de package.json et tsconfig.json dans le style "convention over configuration".

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

4
jjrv

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

1
philkunz