Написание модулей NPM в Typescript

103

Я работаю над своим первым модулем NPM. Раньше я кратко работал с машинописным текстом, и большая проблема заключалась в том, что для многих модулей не было доступных файлов определений. Поэтому я подумал, что было бы неплохо написать свой модуль на машинописном тексте.

Однако я не могу найти никакой информации о том, как это лучше всего сделать. Я нашел связанный вопрос « Могу ли я написать пакет npm в coffeescript? », Где люди предлагают публиковать только файлы javascript. Но в отличие от файлов coffeescript, файлы машинописного текста могут быть полезны, если они используются в приложении машинописного текста.

Должен ли я включать файлы Typescript при публикации модуля NPM или я должен публиковать только файлы javascript и предоставлять сгенерированные файлы .d.ts в DefinentyTyped?

javascript  node.js  npm  typescript 
— Андреас Гассманн
источник
2
Полезные примечания: я написал проект copee вместе с сообщением в блоге, чтобы помочь вам настроить проект TS для выдачи определений типов вместе с целями CJS и ESM перед публикацией в npm. Это максимизирует использование node.js и браузеров в будущем.
— Styfle

Ответы:

84

Вот пример модуля Node, написанного на TypeScript: https://github.com/basarat/ts-npm-module

Вот образец проекта TypeScript, который использует этот образец модуля https://github.com/basarat/ts-npm-module-consume

В основном вам необходимо:

  • компилировать с commonjsиdeclaration:true
  • создать .d.tsфайл

А потом

  • Пусть ваш ide прочитает сгенерированный .d.ts.

Atom-TypeScript просто обеспечивает хороший рабочий процесс вокруг этого: https://github.com/TypeStrong/atom-typescript#packagejson-support

— басарат
источник
Ссылку привязки Atom-TypeScript необходимо обновить (привязка больше не действительна).
— Fidan Hakaj
@basarat, в ts-npm-module вы используете "версию": "1.5.0-alpha". Я предполагаю, что это версия Typescript, с которой вы транслируете. Имеет ли значение оставить это без внимания? (это не выполняется автоматически плагином Atom). Если используется версия, потребуется ли для этого другим пользователям использовать точную версию для транспиляции (или только более новую)? (или, может быть, это версия tsconfig.json?)
— Джастин
Есть ли у вас варианты использования модулей, зависящих от других библиотек? Чтобы избежать проблемы с дублированием определений, вам нужно настроить tsconfig.json, но, на мой взгляд, это слишком вручную.
— Серхио Михельс
1
Будете ли вы выступать за этот подход в четвертом квартале 2016 года?
— SuperUberDuper
7
Это был хороший практический совет
— tsmean.com/articles/how-to-write-a-typescript-library
78

В TypeScript 3.x или TypeScript 2.x следующие шаги описывают, что вам нужно сделать для создания библиотеки (пакета npm) с TypeScript:

  • Создайте свой проект, как обычно (с тестами и всем остальным)
  • Добавьте, declaration: trueчтобы tsconfig.jsonгенерировать набор текста.
  • Экспортируйте API через index.ts
  • В package.json, укажите на созданные вами типы. Например, если у вас outDirесть dist, добавьте "types": "dist/index.d.ts"в свой пакет json.
  • В package.jsonукажите на свой основной входной файл. Например, если у вас outDirесть, distа основной входной файл - это index.js, добавьте "main": "dist/index.js"в свой package.json.
  • Создайте, .npmignoreчтобы игнорировать ненужные файлы (например, источник).
  • Публикуйте в npm с помощью npm publish. Используйте спецификации semver для обновлений (исправление исправлений / ошибок npm version patch, неразрывные дополнения npm version minor, критические изменения api npm version major)

Так как у меня появилось время, чтобы просмотреть все устаревшие ресурсы по этой теме в Интернете (например, на этой странице ...), я решил обернуть это в библиотеке how-to-write-a-typescript с помощью актуальный рабочий минимальный пример.

— Берслинг
источник
Придется ли мне проверять js в системе управления версиями? Или у npm есть собственная версия кода?
— Olian04,
1
@ Olian04 Вы указываете создать .npmignoreфайл, чтобы указать npm, какие файлы игнорировать при публикации ( .tsфайлы), и a, .gitignoreчтобы указать git, какие файлы игнорировать ( dist/)
— Purag
@ Olian04 нет, вам не нужно (и IMO не следует) фиксировать сгенерированные файлы JS. Они не являются частью исходного кода проекта.
— Джош М.
59

Это более свежий ответ с использованием TypeScript 1.8.10:

Моя структура проекта:

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

Я добавил следующее, .npmignoreчтобы избежать включения посторонних файлов и сохранить минимум для импорта и работы пакета:

node_modules/
*.log
*.tgz

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

У меня .gitignoreесть:

typings

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

У меня package.jsonесть:

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

Сейчас бегу: npm pack

Результирующий файл (в распакованном виде) имеет следующую структуру:

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

Теперь я перехожу к проекту, где хочу использовать его как библиотеку, и набираю: npm install ./project-1.0.0.tgz

Устанавливается успешно.

Теперь я создаю файл index.tsв своем проекте, в котором только что установил npm import Project = require("project");

Печатание Project.дает мне возможности Intellisense, что и было целью всего этого упражнения.

Надеюсь, это поможет кому-то еще в использовании своих проектов TypeScript npm в качестве внутренних библиотек в своих более крупных проектах.

PS: Я считаю , что такой подход составления проектов по НПМ модулям , которые могут быть использованы в других проектах , напоминает .dllв .NETмире. Я вполне мог представить себе проекты, организованные в решение в VS Code, где каждый проект создает пакет npm, который затем может использоваться в другом проекте в решении в качестве зависимости.

Поскольку мне потребовалось изрядное количество времени, чтобы понять это, я опубликовал его на случай, если кто-то здесь застрянет.

Я также разместил его для закрытой ошибки по адресу: https://github.com/npm/npm/issues/11546

Этот пример загружен на Github: vchatterji / tsc-seed

— Варун Чаттерджи
источник
не могли бы вы выложить пример на github? Это очень поможет! :)
— Хан Че
3
Пример был загружен на Github: github.com/vchatterji/tsc-seed
— Варун Чаттерджи
Как его также можно использовать в проектах без машинописного текста?
— SuperUberDuper
5

Вам следует публиковать исходные тексты машинописных текстов вместо определения типа. В package.jsonПусть точка свойства «типов» в * .ts файл.

*.d.ts хороши для аннотирования существующих JS-библиотек, но как потребитель я бы предпочел читать машинописный код, чем переключаться между определениями типов и сгенерированным JS-кодом с пониженным уровнем.

— Свен Эффтинге
источник
1
Компилятор TypeScript, похоже, пока не подходит для этого. См. Этот выпуск github.com/Microsoft/TypeScript/issues/14479
— Sven Efftinge
2
в настоящее время включение *.d.tsявляется рекомендуемым способом сделать это, хотя я согласен с вами в преимуществах включения *.tsфайлов, typescriptlang.org/docs/handbook/declaration-files/…
— Тим
5

Я в основном следую предложению Варуна Чаттерджи

Но я хотел бы показать полный пример с модульным тестированием и покрытием кода, а также опубликовать его npmи импортировать с помощью javascriptилиtypescript

Этот модуль написан с использованием, typescript 2.2и важно настроить prepublishловушку для компиляции кода с использованием, tscпрежде чем публиковать его в npm.

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

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

— Тим
источник
1
Это очень полезный пример, спасибо, что поделились! В настоящее время я также пытаюсь научиться создавать пакеты таким образом.
— Джеффри Вестеркамп
1
По состоянию на июль 2017 года это лучшая структура проекта, которую я когда-либо встречал. Спасибо Тиму и
— Варуну
3

Вы можете использовать autodts для обработки распространения и использования .d.tsфайлов из npm также без поддержки со стороны Atom IDE.

autodts generate.d.tsобъединит все ваши собственные файлы вместе для публикации на npm и будет autodts linkобрабатывать ссылки на другие установленные пакеты, которые не всегда могут находиться непосредственно node_modulesв большом проекте, разделенном на несколько подпакетов.

Обе команды читают свои настройки из package.jsonи tsconfig.jsonв «конвент по конфигурации» стиль.

Есть еще один ответ на stackoverflow и сообщение в блоге с более подробной информацией.

— jjrv
источник
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.