Scrittura di moduli NPM in Typescript

Sto lavorando al mio primo modulo NPM. Ho lavorato brevemente con il dattiloscritto prima e un grosso problema era che per molti moduli non c'erano file di definizione disponibili. Quindi ho pensato che sarebbe stata una buona idea scrivere il mio modulo in dattiloscritto.

Tuttavia, non riesco a trovare alcuna informazione sul modo migliore per farlo. Ho trovato questa domanda correlata " Posso scrivere il pacchetto npm in coffeescript? " In cui le persone suggeriscono di pubblicare solo i file javascript. Ma a differenza dei file coffeescript, i file dattiloscritti potrebbero effettivamente essere utili se vengono utilizzati all'interno di un'applicazione dattiloscritta.

Devo includere file Typescript quando pubblico un modulo NPM, o devo pubblicare solo i file javascript e fornire i file .d.ts generati a DefinitelyTyped?

Ecco un modulo Node di esempio scritto in TypeScript: https://github.com/basarat/ts-npm-module

Ecco un progetto TypeScript di esempio che utilizza questo modulo di esempio https://github.com/basarat/ts-npm-module-consume

Fondamentalmente devi:

• compilare con commonjsedeclaration:true
• generare un .d.tsfile

E poi

• Chiedi al tuo ide di leggere il file generato .d.ts.

Atom-TypeScript fornisce solo un bel flusso di lavoro attorno a questo: https://github.com/TypeStrong/atom-typescript#packagejson-support

Con TypeScript 3.x o TypeScript 2.x, i seguenti passaggi descrivono cosa è necessario fare per creare una libreria (pacchetto npm) con TypeScript:

• Crea il tuo progetto come faresti normalmente (con test e tutto)
• Inserisci declaration: true a tsconfig.jsonper generare digitazioni.
• Esporta l'API tramite un file index.ts
• Nella package.json, punta alle tue digitazioni generate. Ad esempio, se lo outDirè dist, aggiungi"types": "dist/index.d.ts" al tuo pacchetto json.
• In package.json, punta al tuo file di ingresso principale. Ad esempio, se il tuo outDirè diste il file della voce principale è index.js, aggiungi "main": "dist/index.js"al tuo package.json.
• Crea un .npmignoreper ignorare i file non necessari (es. L'origine).
• Pubblica su npm con npm publish. Usa le specifiche semver per gli aggiornamenti (patch / correzione di bug npm version patch, aggiunte senza interruzioni npm version minor, modifiche alle API interrotte npm version major)

Dato che mi è servito un po 'di tempo per vagliare tutte le risorse obsolete su questo argomento su Internet (come quella in questa pagina ...), ho deciso di racchiuderlo nella libreria di come scrivere un dattiloscritto con una esempio minimo di lavoro aggiornato.

Questa è una risposta più recente utilizzando TypeScript 1.8.10:

La struttura del mio progetto è:

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

Ho aggiunto quanto segue .npmignoreper evitare di includere file estranei e mantenere il minimo indispensabile per importare e funzionare il pacchetto:

node_modules/
*.log
*.tgz

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

Il mio .gitignoreha:

typings

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

Il mio package.jsonha:

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

Adesso corro: npm pack

Il file risultante (quando decompresso) ha la seguente struttura:

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

Ora vado al progetto in cui voglio usarlo come libreria e digito: npm install ./project-1.0.0.tgz

Si installa con successo.

Adesso creo un file index.ts nel mio progetto in cui ho appena installato npm import Project = require("project");

Digitando Project. mi offre le opzioni Intellisense che erano il punto di tutto questo esercizio.

Spero che questo aiuti qualcun altro a utilizzare i loro progetti npm TypeScript come librerie interne nei loro progetti più grandi.

PS: credo che questo approccio alla compilazione di progetti in moduli npm che possono essere utilizzati in altri progetti ricordi il.dll il .NETmondo. Potrei ben immaginare progetti organizzati in una soluzione in VS Code in cui ogni progetto produce un pacchetto npm che può quindi essere utilizzato in un altro progetto nella soluzione come dipendenza.

Dato che ci è voluto un bel po 'di tempo per capirlo, l'ho pubblicato nel caso qualcuno fosse bloccato qui.

L'ho anche pubblicato per un bug chiuso su: https://github.com/npm/npm/issues/11546

Questo esempio è stato caricato su Github: vchatterji / tsc-seed

Dovresti pubblicare le fonti originali del dattiloscritto invece della definizione del tipo. In package.jsonlet la proprietà 'types' punta al file * .ts.

*.d.ts sono utili per annotare le librerie JS esistenti, ma come consumatore preferisco leggere il codice dattiloscritto piuttosto che passare da una definizione di tipo a un codice JS di livello inferiore e generato.

Seguo principalmente il suggerimento di Varun Chatterji

Tuttavia, vorrei mostrare un esempio completo con test di unità e copertura del codice e pubblicarlo in npme importarli utilizzandojavascript otypescript

Questo modulo è scritto usando typescript 2.2ed è importante configurare l' prepublishhook per compilare il codice usandotsc prima di pubblicarlo su npm

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

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

È possibile utilizzare autodts per gestire la distribuzione e l'utilizzo di .d.tsfile da npm anche senza il supporto dell'IDE Atom.

autodts generateraggrupperà tutti i tuoi .d.tsfile insieme per la pubblicazione su npm e gestirà autodts linki riferimenti ad altri pacchetti installati, che potrebbero non essere sempre direttamente sotto node_modulesin un progetto più grande diviso in diversi sottopacchetti.

Entrambi i comandi leggono le loro impostazioni da package.jsone tsconfig.jsonnello stile "convenzione sulla configurazione".

C'è un'altra risposta su stackoverflow e un post sul blog con maggiori dettagli.

In Lossless abbiamo creato uno strumento di sviluppo TypeScript completo per i pacchetti npm: https://gitzone.gitlab.io/npmts/