Что включать в NPM-пакет, что оставлять в репозитории?

Question

[Александр Куракин]

Что включать в NPM-пакет, что оставлять в репозитории?
Допустим, библиотека написана на ES2015 + TypeScript и является изоморфной.
Единого подхода я не нашел за год наблюдения, поэтому предлагается дискуссия:

1. Включать ли в NPM-пакет исходные (ES2015 + TypeScript) файлы?
   
2. Включать ли в NPM-пакет откомпилированные файлы? Если да, то какие? Browserify-бандл, CommonJS (ES5.1)-файлы, ES2015-файлы?
   
3. Включать ли в NPM-пакет тесты?
   
4. Хранить ли в репозитории откомпилированные файлы?
   
5. Корнем NPM-пакета считать корень репозитория или создать директорию package?
   
6. Включать ли в NPM-пакет такие вещи, как примеры?
   

Спасибо!

Comments

[Дмитрий]

Просто по приколу пожаловался, что вопрос ведет к дискуссии :) вы даже написали это.

[Александр Куракин]

Ок, спасибо.

Answer 1

[Константин Китманов]

1. Включать. Если проект сразу на ES6, зачем мне импортить ES6 скомпиленный в ES5? И tree-shake не сработает...
2. CommonJS. Кому надо ES6-модули — см. пункт 1. bundle потребитель пакета сделает сам.
3. Тесты — неплохой источник информации на тему «а как оно должно работать-то, и как его вызывать вообще». Но можно не включать, но тогда лучше написать в readme.md, мол, «дополнительные примеры см. в test/ в репо».
4. Нет особого смысла. prepublish решает задачу «не забыть скомпилить перед публикацией».
5. Зачем? Придется вручную или в prepublish-скрипте в эту директорию все нужное копировать, лишняя работа.

Comments

[Александр Куракин]

Спасибо за подробный ответ!

2. А чем CommonJS принципиально отличается от остального?

Вообще, по этому пункту у меня логика такая - либо включать "всё", либо ничего. Другой вопрос, что есть "всё". Вот в Aurelia, например, под этим понимают ( https://github.com/aurelia/router/tree/master/dist ):
* CommonJS, SystemJS, AMD (код на ES5.1),
* ES2015 module system (код на ES2015),
* бандл (код на ES2015) с помощью https://github.com/aurelia/tools/blob/master/src/b... , а-ля Rollup, только без tree-shake.

P.S,. На этом примере возникает другой вопрос: а CommonJS, SystemJS, AMD с кодом на ES2015 вообще не начнут рассматривать? И чего, они отомрут? Но язык - одно, module system - другое, не?

[Константин Китманов]

Александр Куракин: Смысла публиковать ES5-код в ES6 модулях — никакого. Глобалы — зло. AMD не успело как следует получить популярность, как начало умирать. Остается только CommonJS (ну или UMD), особенно если пакет изоморфный, потому что все остальное под nodejs — только с плясками.

> И чего, они отомрут?
Трудно прогнозировать, но сообщество надеется, что да, это все отомрет.

> Но язык - одно, module system - другое, не?
На данный момент, слава богам, не. Если бы это было так, то выражение вида import $ from 'jquery' было бы синтаксической ошибкой, чего мы не наблюдаем.

[Александр Куракин]

Константин Китманов:
Я имел ввиду наоборот: станет ли популярным бандлинг CommonJS, но код ES2015.

let func = require('package');

Почему-то такого нигде не наблюдается. То есть если CommonJS, то и код на ES5.1. Хотя, казалось бы, выбор CommonJS vs AMD vs etc. - это одно, а выбор ES5.1 vs ES2015 - другое.

[Константин Китманов]

Александр Куракин: Я какое-то время назад писал так под node. Потому что let и const уже были, а модули все еще за флагом. Естественно, не в публикуемых либах. Возможно, сейчас уже нет в этом смысла, надо проверить.

[Александр Куракин]

Константин Китманов: И все-таки замечу, что CommonJS и ES2015 import-export не только не совместимы, но и принципиально различны: как минимум в первом случае это runtime, во втором - compile-time.

[Константин Китманов]

Александр Куракин: если юзать browserify, то cjs — такой же compile-time. Ну нельзя динамически модуль загрузить — это не конец света.

Answer 2

[Котик Антон]

Что мешает посмотреть, что прописывают в .npmignore создатели популярных NPM-пакетов?

Comments

[Александр Куракин]

Спасибо за ответ! То, что каждый решает по-своему. Поэтому и спрашиваю у сообщества. Уточню в вопросе.

Answer 3

[sim3x]

1 +
2 - (в зависимости пакета пропиши, что нужно установить, чтоб пакет работал)
3 +
4 -
5 корень репо

пример
https://github.com/sass/node-sass