SEO npm-пакета: почему важно правильно настраивать конфиг и писать тесты

Не так давно я опубликовал статью ^[1] о своем CLI для React-компонент, который для меня стал первым публичным npm-пакетом. И так как мне хотелось поделиться своими наработками с как можно большим кругом разработчиков я начал изучать разные способы улучшения своей позиции в поисковой выдаче на разных специализированных сайтах. В попытках улучшить свое положение я опирался на поиск в npm ^[2], yarn ^[3] и npms ^[4]. И если вы сейчас откроете страничку моего пакета ^[5] в любом из этих трех сайтов, то результаты там будут, к сожалению, достаточно скромными и я попробую объяснить почему и порассуждаю на эту тему.

Popularity, quality, maintainance

Если мы сделаем поиск в npm по любому запросу, то напротив каждого из пакетов будет указан набор из трех характеристик: popularity, quality и maintainance. Они в каком-то роде напоминают значения по пирам и сидам на каком-нибудь торрент-трекере и в достаточной мере влияют на выдачу и на последующий выбор людей.

Popularity рейтинг достаточно очевидный и связан напрямую со скачиванием пакета, со звездочками на гитхабе, с количеством форков и подписчиков у автора. Все подробности можно почитать на сайте npms ^[6].

Так как у нас пакет новый то popularity у нас само собой будет на нуле, поэтому будем смотреть на остальные два рейтинга. Quality мы оставим на десерт, а сначала поговорим о maintainance. И тут все достаточно просто, он отображает состояние пакета с точки зрения разработки. Либо его активно разрабатывают и поддерживают, либо на него забили и не занимаются. Тут учитывается то, как часто происходят коммиты, релизы, насколько много issue и как быстро они закрываются. В целом вроде все просто, но если в npms у меня этот показатель заполнен на 100%, потому что я активно дорабатываю пакет и прикручиваю новые фишки почти каждую неделю, то в npm у меня этот рейтинг только 33%. И как бы я не старался, выше он не поднимается. Более того, если взять любой другой популярный генератор кода, то окажется что все эти пакеты имеют данный рейтинг тоже равный 33%, что выглядит немного подозрительным. Даже у самого React этот рейтинг такой же.

Popularity у нас на нуле, maintainance на максимум, а что с quality? А тут все гораздо интереснее. Изначально я писал свою CLI на чистом js и без тестов. Но к тому моменту, когда я решил вытащить её в публичное поле я уже переписал её на Typescript и более или менее причесал, но все еще тестов не было. И я точно не помню сколько у меня был этот показатель качества, но думаю был примерно в районе 20%. Сейчас же я его разогнал до 61% и могу немного рассказать, как этого можно добиться. Причем я пытался применять сразу несколько практик одновременно, поэтому я до конца не уверен все ли они влияют, но даже если нет, то в целом это стоит того чтобы добавить в свой проект, если вы тоже решитесь опубликовать пакет.

У меня получился следующий список настроек:

1. В проекте должен быть настроен линтер. Я лично использую ESLint, возможно с TSLint пакетные менеджеры тоже нормально работают.

2. Стоит написать хороший readme.mdи changelog.md и поддерживать их в актуальном состоянии

3. Стоит добавить файл лицензии

4. Не лишним будет добавить файл .editorconfig Не факт что оно влияет на рейтинг, но пригодиться если кто-то решит вам помочь с вашим пакетом. Хотя и линтер тоже с этим поможет.

5. Также я подключил свой проект на github к Travis ^[7] и создал для него конфиг с помощью файла .travis.yml. Когда я его подключал я преследовал исключительно цель попробовать подняться в рейтинге, однако это оказалось достаточно неплохим инструментом тестирования. Более того, в моем CLI очень важно чтобы все корректно работало как на Linux так и на Windows и для меня оказалось приятной неожиданностью, когда Travis прогнал мои тесты у себя на Linux и я поймал баг, о котором совсем не знал, потому что разрабатываю под виндой.

6. Не уверен что это влияет на рейтинг, но достаточно важно корректно заполнить файл package.json. Указать в нем все скрипты, главный файл, описание и теги.

Ну и конечно помимо банальных настроек проекта нужно писать тесты. И чтобы рейтинг поднялся высоко, покрытие должно быть очень высоким. Как я уже сказал выше, итоговый рейтинг в npm у меня вышел равным 61%, при этом покрытие тестами у меня всего лишь 49%, ну и есть все эти настройки, указанные выше. На nmps все получше, там у меня 96%. Само собой, в первую очередь, я покрыл критическую функциональность пакета, поскольку с каждой новой фичей тестировать все кейсы становится все сложнее и сложнее, хотя в некоторых случаях я откровенно читерил и покрывал тестами файлы, в которых максимально сложно совершить ошибку, но зато тесты пишутся легко и покрытие растет очень дешево.

Цифры или PR

Ну хорошо, настроили мы проект, пушим в него часто и фиксим оперативно все баги, покрываем тестами, но что-то никто не приходит скачивать наш пакет. Открываем поиск того же npm, вбиваем релевантный запрос для нашего пакета и начинаем листать страницы: 1, 2, 3,... 21. Находим наш пакет на какой-нибудь очень далекой странице и как нам понять что пошло не так?

Начну, пожалуй, с одной забавной истории про одно поле. Когда я всеми силами пытался вытащить свой пакет в первые строчки yarn, я настраивал проект, писал тесты, выбирал теги получше и улучшал readme. Писал посты на reddit и пиарил пакет среди коллег. Из кожи вон лез, но пакет качали очень слабо, где-то скачиваний 20-30 в день было. И хоть даже это меня радовало, хотелось узнать, как на это повлиять и я начал смотреть что есть в пакетах «конкурентов». Многие пакеты в поиске по релевантному для меня запросу были вообще не подходящими по сути и делали совершенно не то, что я как бы пытаюсь искать, но тем не менее были выше и я пытался выяснить почему. Первое что достаточно сомнительно выстреливает, когда мы говорим о поиске - это то что мелкие, крайне бесполезные пакеты, в которых 150 строк кода, покрытых тестами, вылезают в топ за счет невероятно высокого покрытия. Часто бывало так что у меня только index файл был длиннее чем пакеты, которые обходили меня в рейтинге, хотя при этом и популярными они тоже не были, потому что такой пакет может написать каждый за парочку часов. И вот я натыкаюсь на очередной пакет, который крайне маленький, бесполезный, но почему-то находящийся выше в yarn. Стало очень любопытно и я начал проглядывать каждый файл репозитория и сравнивать настройки со своими. И тут я вижу что единственное отличие моей репки, от репки конкурента - это поле description в package.json. Ну, я подумал, что вряд ли это мне как-то поможет, но почему бы его не добавить, а то я как-то про него забыл. В общем добавляю поле и на следующий день бац и +200 скачиваний, потом еще больше и еще. Более того, по одному из запросов в yarn я находился на 23 станице до которой вряд ли бы кто-то дошел, пытаясь найти нужный пакет, но, указав это поле, пакет оказался буквально на первой строчке поисковика.

После такого успеха и роста до двух тысяч скачиваний в месяц и почти тысячи скачиваний за неделю, в одном из моментов, я подумал, что, кажется, я поддал нужного количества углей в эту PR печку и оно дальше как-то само пойдет. Тем более я заходил в соседние пакеты, поглядывал на их issue и с довольным видом продолжал работать над своим продуктом, потому что у меня эти фичи были реализованы из коробки. Но шло время, и весь этот мощный буст превратился в невероятный спад. С каждым днем кривая скачиваний спускалась все ниже, и ниже и я пытался разобраться в том что сделал не так, но точного понимания этого у меня до сих пор нет.

В каком-то смысле все эти настройки пакета реально работают и улучшают позицию в разного рода выдачах, с другой стороны в чистом виде оно тоже работает плохо и даже с учетом того что спустя время у меня появились и звезды на github ^[8] и целая гора новых фич, оно все еще где-то висит далеко не на первых строчках в поиске, все еще очень слабо скачивается. И кажется, что все-таки сам по себе поиск плохо работает и чтобы пакет стал реально популярным, нужно хорошо так его прорекламировать. Так что если вдруг соберетесь что-то подобное разрабатывать, то готовьтесь к чему-то такому.

Возможно, мне стоило разместить пакет в домене моей компании, поскольку я его делал в первую очередь для работы и вполне возможно это дало бы больший буст. Возможно, есть какие-то скрытые механизмы регуляции о которых я не знаю, поскольку подобная динамика видна во многих пакетах. Сначала резкий всплеск популярности, а потом спад до какого-то плато, которое очень неспешно ползет вверх. Может быть там есть какая-то акселерация на ранних этапах.

Кто-то может сказать, что это из-за того что эта функциональность никому не нужна. И этот кто-то тоже окажется не прав, поскольку есть другие пакеты, которые решают схожую задачу, далеко не всегда лучше, но при этом имеют 15 тысяч скачиваний в месяц и более. Хотя, конечно там более старые, известные проекты, которые имеют не одну публикацию в интернете и много коллабораторов на github.

В целом я не удивлен что все работает именно так, поскольку если бы я зашел на страничку пакета у которого 150 скачиваний в неделю, я бы скорее всего тоже даже описание не начал бы читать, поскольку все мы привыкли доверять чему-то очень популярному и проверенному, даже если у этого чего-то 200 issue.

Надеюсь эта статья поможет кому-то улучшить свой публичный npm-пакет или изменит ваш взгляд на то, что значат все эти цифры, когда вы в очередной раз решите поискать решения своей задачи на просторах интернета. Но несмотря на это все, не стоит забывать о том, что, в любом случае, продать что-то никому ненужное и некачественное все равно не получится и стоит сфокусироваться в первую очередь на продукте, а там уже спустя какое-то время, если пакет действительно чего-то стоит, его аудитория найдется, пусть и не сразу.

Автор: m1ndKiller

Источник ^[9]