javascript - Menulis modul npm dalam TypeScript

Saya sedang mengerjakan modul npm pertama saya. Saya pernah bekerja sebentar dengan TypeScript sebelumnya dan masalah besar adalah untuk banyak modul tidak ada berkas definisi yang tersedia. Jadi saya pikir akan menjadi ide yang bagus untuk menulis modul saya dalam TypeScript.

Namun, saya tidak dapat menemukan informasi tentang cara terbaik untuk melakukannya. Saya menemukan pertanyaan terkait ini "Bisakah saya menulis paket npm dalam CoffeeScript?" di mana orang-orang menyarankan hanya menerbitkan file JavaScript. Tetapi berbeda dengan file CoffeeScript, file TypeScript mungkin sebenarnya berguna jika digunakan dalam aplikasi TypeScript.

Haruskah saya menyertakan file TypeScript saat menerbitkan modul npm, atau haruskah saya hanya menerbitkan file JavaScript dan menyediakan file .d.ts yang dihasilkan ke DefinitelyTyped?

Jawaban #1

Lakukan hal berikut untuk membuat paket npm menggunakan versi TypeScript apa pun dari 2.x -> 5.x:

  • Buat proyek Anda seperti biasa (dengan tes dan semuanya)
  • Tambahkan declaration: true ke tsconfig.json untuk menghasilkan tipe.
  • Ekspor API melalui index.ts
  • Di package.json, arahkan ke typings yang telah Anda buat. Misalnya jika outDir Anda adalah dist, maka tambahkan "types": "dist/index.d.ts" ke package json Anda.
  • Di package.json, tunjukkan file masuk utama Anda. Misalnya jika outDir Anda adalah dist dan file masuk utama adalah index.js, maka tambahkan "main": "dist/index.js" ke package.json Anda.
  • Di package.json, daftar putih file yang ingin Anda kirim ke npm: files: ["/dist"]. Pendekatan alternatif adalah daftar hitam dengan .npmignore, tetapi lebih sulit untuk diperbarui secara terus-menerus.
  • Terbitkan ke npm dengan npm publish. Gunakan spesifikasi semver untuk pembaruan (patch/perbaikan bug npm version patch, penambahan yang tidak mengganggu npm version minor, perubahan API yang mengganggu npm version major)

Karena butuh waktu bagi saya untuk menyaring semua sumber daya yang sudah usang tentang topik ini di internet (seperti yang ada di halaman ini...) saya memutuskan untuk merangkum semuanya dalam cara-menulis-perpustakaan-typescript dengan contoh minimal yang bekerja dan terbaru.

Jawaban #2

Berikut adalah contoh modul Node yang ditulis dalam TypeScript: https://github.com/basarat/ts-npm-module

Berikut adalah contoh proyek TypeScript yang menggunakan modul contoh ini https://github.com/basarat/ts-npm-module-consume

Pada dasarnya Anda perlu:

  • kompilasi dengan commonjs dan declaration:true
  • menghasilkan file .d.ts

Dan kemudian

  • Biarkan IDE Anda membaca .d.ts yang dihasilkan.

Atom-TypeScript hanya menyediakan alur kerja yang bagus seputar ini: https://github.com/TypeStrong/atom-typescript#packagejson-support

Jawaban #3

Ini adalah jawaban yang lebih baru menggunakan TypeScript 1.8.10:

Struktur proyek saya adalah:

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

Saya menambahkan hal berikut di .npmignore untuk menghindari menyertakan file yang tidak perlu dan menjaga agar hanya ada hal minimum agar paket dapat diimpor dan berfungsi:

node_modules/
*.log
*.tgz

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

File .gitignore saya memiliki:

typings

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

File package.json saya memiliki:

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

Sekarang saya menjalankan: npm pack

File yang dihasilkan (saat diekstrak) memiliki struktur berikut:

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

Sekarang saya pergi ke proyek di mana saya ingin menggunakan ini sebagai pustaka dan mengetik: npm install ./project-1.0.0.tgz

Ini berhasil diinstal.

Sekarang saya membuat sebuah file index.ts di proyek saya di mana saya baru saja menginstal npm import Project=require("project");

Mengetik Project. memberi saya opsi Intellisense yang merupakan tujuan dari seluruh latihan ini.

Semoga ini membantu orang lain dalam menggunakan proyek npm TypeScript mereka sebagai pustaka internal di proyek yang lebih besar.

PS: Saya percaya bahwa pendekatan ini untuk mengompilasi proyek menjadi modul npm yang dapat digunakan di proyek lain mengingatkan pada .dll di dunia .NET. Saya bisa membayangkan proyek-proyek diatur dalam sebuah Solution di VS Code di mana setiap proyek menghasilkan paket npm yang kemudian dapat digunakan di proyek lain dalam solusi sebagai dependensi.

Karena butuh cukup banyak waktu bagi saya untuk memahami ini, saya mempostingnya jika ada seseorang yang terjebak di sini.

Saya juga mempostingnya untuk bug yang ditutup di: https://github.com/npm/npm/issues/11546

Contoh ini telah diunggah ke Github: vchatterji/tsc-seed

Artikel terkait