Escribir módulos de NPM en TypeScript

Estoy trabajando en mi primer módulo de NPM. Trabajé brevemente con mecanografiado antes y un gran problema fue que para muchos módulos no había archivos de definición disponibles. Así que pensé que sería una buena idea escribir mi módulo a máquina.

Sin embargo, no puedo encontrar ninguna información sobre la mejor manera de hacerlo. Encontré esta pregunta relacionada " ¿Puedo escribir el paquete npm en coffeescript? " Donde la gente sugiere publicar solo los archivos javascript. Pero a diferencia de los archivos coffeescript, los archivos mecanografiados pueden ser útiles si se utilizan dentro de una aplicación mecanografiada.

¿Debo incluir archivos de Typecript al publicar un módulo NPM, o debo publicar solo los archivos javascript y proporcionar los archivos .d.ts generados a DefinitelyTyped?

Aquí hay un módulo de nodo de muestra escrito en TypeScript: https://github.com/basarat/ts-npm-module

Aquí hay un proyecto de TypeScript de muestra que usa este módulo de muestra https://github.com/basarat/ts-npm-module-consume

Básicamente necesitas:

• compilar con commonjsydeclaration:true
• generar un .d.tsarchivo

Y entonces

• Haga que su ide lea el archivo .d.ts.

Atom-TypeScript solo proporciona un buen flujo de trabajo en torno a esto: https://github.com/TypeStrong/atom-typescript#packagejson-support

Con TypeScript 3.xo TypeScript 2.x, los siguientes pasos describen lo que debe hacer para crear una biblioteca (paquete npm) con TypeScript:

• Crea tu proyecto como lo harías normalmente (con pruebas y todo)
• Agregue declaration: truea tsconfig.jsonpara generar mecanografía.
• Exportar la API a través de un index.ts
• En package.json, apunte a sus mecanografiados generados. Por ejemplo, si lo outDires dist, agréguelo "types": "dist/index.d.ts"a su paquete json.
• En package.json, apunte a su archivo de entrada principal. Por ejemplo, si tu outDires disty el archivo de entrada principal es index.js, agrégalo "main": "dist/index.js"a tu package.json.
• Cree un .npmignorepara ignorar archivos innecesarios (por ejemplo, la fuente).
• Publicar en npm con npm publish. Utilice las especificaciones de semver para las actualizaciones (parche / corrección de errores npm version patch, adiciones npm version minorpermanentes, cambios de API importantes npm version major)

Como me tomó un tiempo examinar todos los recursos desactualizados sobre este tema en Internet (como el de esta página ...), decidí resumirlo en cómo-escribir-una-biblioteca-mecanografiada con un ejemplo mínimo de trabajo actualizado.

Esta es una respuesta más reciente usando TypeScript 1.8.10:

La estructura de mi proyecto es:

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

Agregué lo siguiente .npmignorepara evitar incluir archivos extraños y mantener lo mínimo para que el paquete se importe y funcione:

node_modules/
*.log
*.tgz

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

Mi .gitignoretiene:

typings

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

Mi package.jsontiene:

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

Ahora corro: npm pack

El archivo resultante (cuando se descomprime) tiene la siguiente estructura:

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

Ahora voy al proyecto donde quiero usar esto como biblioteca y escribo: npm install ./project-1.0.0.tgz

Se instala con éxito.

Ahora creo un archivo index.tsen mi proyecto donde acabo de instalar el npm import Project = require("project");

Escribir Project.me da las opciones de Intellisense, que fue el objetivo de todo este ejercicio.

Espero que esto ayude a alguien más a usar sus proyectos npm de TypeScript como bibliotecas internas en sus proyectos más grandes.

PD: Creo que este enfoque de compilar proyectos en módulos npm que se pueden usar en otros proyectos recuerda al .dlldel .NETmundo. Bien podría imaginar que los proyectos se organizan en una solución en VS Code donde cada proyecto produce un paquete npm que luego se puede usar en otro proyecto en la solución como una dependencia.

Como me tomó bastante tiempo resolver esto, lo publiqué en caso de que alguien se quede atascado aquí.

También lo publiqué por un error cerrado en: https://github.com/npm/npm/issues/11546

Este ejemplo se ha subido a Github: vchatterji / tsc-seed

Debería publicar las fuentes originales mecanografiadas en lugar de la definición de tipo. En package.jsondejar que la perspectiva de la propiedad 'tipos' en el fichero * Ts.

*.d.ts son buenos para anotar las librerías JS existentes, pero como consumidor prefiero leer el código mecanografiado que cambiar entre definiciones de tipo y código JS generado de nivel inferior.

Sigo principalmente la sugerencia de Varun Chatterji

Pero, me gustaría mostrar un ejemplo completo con pruebas unitarias y cobertura de código y publicarlo npme importarlos usando javascriptotypescript

Este módulo está escrito usando typescript 2.2y es importante configurar el prepublishgancho para compilar el código usando tscantes de publicarlo en npm

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

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

Puede usar autodts para manejar la distribución y el uso de .d.tsarchivos de npm también sin el soporte del IDE de Atom.

autodts generate empaquetará todo el tuyo .d.tsagrupará archivos para publicarlos en npm, y manejará autodts linklas referencias a otros paquetes instalados, que no siempre pueden estar directamente debajo node_modulesen un proyecto más grande dividido en varios subpaquetes.

Ambos comandos leen sus configuraciones desde package.json y tsconfig.jsonen estilo "convención sobre configuración".

Hay otra respuesta en stackoverflow y una publicación de blog con más detalles.

En Lossless creamos una herramienta de desarrollo de TypeScript integral para paquetes npm: https://gitzone.gitlab.io/npmts/