Самый простой способ создать свой первый пакет NPM

Это руководство проведет вас через самый простой процесс создания и выпуска пакета NPM от начала до конца с использованием микропакета .

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

Вот краткий список его особенностей:

• Встроенные конфиги; все, что вам нужно сделать, это добавить поле «экспорт» в package.json
• Поддержка TypeScript «из коробки» без tsconfig.json
• Несколько форматов вывода (CJS, UMD и ESM)
• Встроенное сжатие Terser

По сути, microbundle построен на основеrollup.js . Если вам нужно создать более сложные библиотеки, чем я упомяну в этой статье, вы можете рассмотреть возможность использования чистой rollup.js .

Инициализация вашего пакета

В качестве примера создадим простую библиотеку для суммирования двух чисел, которая будет экспортировать только одну функцию sum .

1. Создайте папку для проекта и запустите npm init со значениями по умолчанию, чтобы сгенерировать package.json

   
   

2. Создайте index.ts в папке src

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. Установить microbundle

   npm i -D microbundle

   
   

4. Обновите package.json , указав следующие значения:

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Запустите скрипт сборки

   npm run build

   
   

   Вывод должен содержать именно те файлы, которые мы объявили в package.json .

   

И вуаля, мы сделали нашу первую посылку. Давайте рассмотрим более сложные сценарии.

Добавление React в вашу библиотеку

Если вы хотите добавить React в свою библиотеку, вы все равно можете использовать его microbundle , но теперь ваша команда сборки должна выглядеть так:

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Для удобства в будущем добавьте команду в package.json в скрипт build :

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Использование Storybook для компонентов пользовательского интерфейса

При создании библиотеки пользовательского интерфейса вам может понадобиться «песочница», где вы сможете разрабатывать, визуализировать компоненты и предоставлять демонстрационные компоненты для вашей документации.

Вот и сборник рассказов . Это песочница со своим удобным интерфейсом и сборщиком, в которой вы легко сможете описывать различные состояния ваших компонентов. Каждый захват состояния вашего компонента называется «историей».

На этом изображении, взятом из их документации, показано, как это выглядит:

Установить Storybook довольно просто; просто запустите команду внутри вашей библиотеки:

 npx storybook@latest init

Эта команда установит все необходимые зависимости для Storybook, добавит сценарии для запуска и встроит Storybook в package.json , создаст папку .storybook с конфигурацией по умолчанию и добавит несколько примеров историй в папку src/stories .

Интеграция стилей в вашу библиотеку

Вы можете добавить стиль одним из двух способов: файлом CSS или CSS-in-JS. Файл CSS позволяет легко настраивать, но требует отдельного включения, тогда как CSS-in-JS упрощает стилизацию, но увеличивает размер пакета.

• CSS-файл

  Создайте файл CSS в каталоге src и импортируйте его в корневой файл компонента реакции:

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Итак, давайте снова запустим команду сборки.

   npm run build

  
  

  И ваш импортированный файл styles.css будет создан в папке dist :

  

  Большой! Мы получили CSS-файл с необходимыми стилями. Однако у этого решения есть небольшое неудобство. Файл CSS необходимо добавить отдельно после установки пакета.

  
  

  Следовательно, пользователям вашей библиотеки потребуется использовать загрузчик CSS (например, загрузчик CSS для веб-пакета) для обработки вашего файла CSS, и их использование будет выглядеть следующим образом:

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS-в-JS

  Для этой цели вы можете использовать такие библиотеки, как стилизованные компоненты . И это будет выглядеть так:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Благодаря этому решению пользователям не нужно будет импортировать файл CSS и добавлять специальный загрузчик для своего проекта. После установки библиотеки компонент будет иметь собственный стиль. Однако это увеличит размер пакета и затруднит пользователям настройку элементов с помощью селекторов CSS.

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

Разработка подробного файла README.md

Файл README.md содержит информацию о вашей библиотеке, способах ее установки, ее базовом использовании и имеющихся у нее функциях. Часто это первый файл, который читают разработчики, когда они сталкиваются с вашим репозиторием или пакетом NPM, поэтому он должен быть кратким и информативным.

Мне нравится создавать структуру в следующем порядке:

1. Заголовок
2. Супер короткое описание пакета
3. Необычные статистические значки ( shields.io )
4. Если ваша библиотека является компонентом пользовательского интерфейса, добавьте снимок экрана или предоставьте демонстрационную ссылку на CodeSandbox.
5. Список функций
6. Инструкция по установке
7. Фрагменты кода с использованием
8. Параметры и реквизиты, которые ваша библиотека принимает для настройки.

Для вдохновения вы можете обратиться к примерам файлов README.md из моих пакетов, таких как dot-path-value и response-nested-dropdown .

Навигация по управлению зависимостями

Это важная часть, потому что если вы сделаете это неправильно, пользователи могут столкнуться с конфликтами версий или другими проблемами, и им придется удалить вашу библиотеку. Итак, давайте рассмотрим основные различия между типами зависимостей.

• «devDependities» предназначены только для разработки и не будут включены в ваш пакет. Например, если у вас установлен пакет microbundle , который пользователям не нужно использовать, сохраните его в devDependities, и он не появится в пакете.

• «зависимости» будут установлены вместе с пакетом. Включите зависимости, необходимые вашему пакету для работы в проектах пользователей. Обратите внимание, что некоторые зависимости, такие как «реакция», могут уже быть установлены в проекте пользователя. Наличие дубликата «реакции» в вашем пакете может увеличить размер пакета. Вот тут-то и пригодятся «peerDependities».

• «peerDependency» — это зависимости, которые ваш пакет использует, но не включает в себя. Ваш пакет будет использовать версию зависимости, которую пользователь имеет в своем проекте.

  
  

  По сути, нам следует указать зависимость от однорангового узла, если мы создаем библиотеку для ее экосистемы. Например, если вы создаете компонент React, установите React как одноранговую зависимость. При разработке компонента React с календарем добавьте React и библиотеку расчета дат (например, date-fns) в качестве одноранговых зависимостей.

  
  

  Если у пользователя нет указанной одноранговой зависимости в его проекте, команда npm install отобразит предупреждение, но не установит зависимость автоматически.

Просто небольшой пример того, как это выглядит:

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Использование GitHub для вашего пакета

Если вы публикуете пакет NPM, это означает, что он будет общедоступен (если у вас есть бесплатная учетная запись). Чтобы собрать отзывы пользователей, вы можете создать репозиторий GitHub для своего исходного кода. Здесь люди могут создавать проблемы и общаться с вами по поводу вашего пакета. Вы также можете описать свои релизы и получить несколько звезд!

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

Публикация и поддержка пакета

Прежде чем вы сможете опубликовать свой пакет, важно убедиться, что ваш файл package.json настроен правильно. Вот несколько важных шагов, которые необходимо выполнить:

1. Назовите и попытайтесь описать основные функции вашей библиотеки. Например:

    "name": "react-color-picker"

   
   

2. Добавьте информацию о репозитории GitHub (если она существует):

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. Настройте files :

    ... "files": [ "dist", ], ...

   Вы должны указать файлы, которые будут включены в node_modules при установке вашей библиотеки. Обычно достаточно включить папку dist .

   
   

4. Добавьте keywords :

   Ключевые слова — это массив строк, описывающих ваш пакет и используемых NPM для поиска и рекомендаций. Выберите слова, относящиеся к вашему пакету, которые, как вы ожидаете, люди будут использовать при поиске. Давайте создадим ключевые слова для нашей библиотеки sum :

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Важно указать ваши технологии, потому что пользователи часто ищут такие термины, как «библиотека машинописных текстов для математики» или «выбор календаря React».

   
   

5. Создайте учетную запись NPM, если вы еще этого не сделали, и запустите npm login в своем терминале; следуйте инструкциям для аутентификации вашей учетной записи. По умолчанию версия вашего пакета будет 1.0.0 ; вы можете проверить это в файле package.json . Я рекомендую изменить его на 0.0.1 .

   
   

6. Запустите npm publish и все готово! Чтобы обновить версию в будущем, используйте команду npm version patch для увеличения версии, а затем опубликуйте обновленный пакет с помощью npm publish .

Заключение

Как видите, создать свою собственную библиотеку очень просто! По сути, это все, что вам нужно для создания и поддержки пакета. Если вам сложно ограничить свою библиотеку с помощью microbundle , я рекомендую использоватьrollup.js с более конкретной конфигурацией.

Создание пакетов NPM и участие в разработке открытого исходного кода — это полезный и ценный опыт для разработчиков всех уровней квалификации. Это позволяет вам поделиться своим кодом с сообществом, получить большой опыт и создать портфолио своих работ.