Полное руководство по

Как создать пакет NPM с нуля

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

Вы готовы?!

Поскольку мы говорим о NPM, нам нужно сначала понять, что такое NPM и почему нам может потребоваться создать и опубликовать на нем пакет!

NPM означает Диспетчер пакетов узлов, который представляет собой проект с открытым исходным кодом, который помогает разработчикам делиться своими модулями конфиденциально (только в своей команде) или публично. Он также известен как клиент командной строки, который позволяет разработчикам устанавливать и публиковать эти пакеты.

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

Что нам нужно для сборки пакета?

Babel: это компилятор JavaScript, который преобразует код ECMAScript 2015+ в совместимую версию в текущих и старых браузерах. Он поддерживает последнюю версию Javascript-ES6 (также известную как ES2015), которая имеет множество замечательных функций, но большую проблему - большинство браузеров не поддерживают их полностью. Он использует функцию Polyfill (@ babel / polyfill), которая отсутствует во многих средах браузеров.

Вкратце можно сказать, что это JS-транспилятор, который преобразует новый JS-код в старый с помощью синтаксических преобразователей. Он позволяет преобразовать фрагмент кода, написанный на ECMAScript 2015+, в JavaScript, понятный любому браузеру.

Webpack - это сборщик модулей для современных приложений JavaScript.

Но что это значит?

Он компилирует ваш модуль и проверяет, что в нем есть все необходимое для нормальной работы в браузере. Когда webpack обрабатывает приложение, он строит так называемый граф зависимостей, который отображает все необходимые модули в вашем приложении в небольшое количество пакетов - или, только один - для загрузки браузером.

Во-первых, давайте создадим модуль (компонент React) с локальной демонстрацией:

Шаг 1:

Создайте учетную запись NPM, зарегистрировавшись здесь

Шаг 2:

Создайте новый каталог и инициализируйте пакет NPM.

Обязательно выберите имя для вашего модуля, которое еще не используется в NPM (мы можем выбрать лучшее имя для каждого модуля на основе требований модуля). Я назову свое: hala-test.

mkdir hala-test
cd hala-test

Создайте файл package.json с помощью команды npm init. Для модулей с ограниченной областью (частных) запустите:

npm init — scope=@scope-name

Для модулей без области действия выполните:

npm init

Запустив указанную выше команду, вы найдете файл package.json в каталоге вашего модуля. Каждый файл package.json имеет имя в соответствии с инструкциями NPM по именованию пакетов и версию, которая будет в виде xxx следует semver spec.

Шаг 3:

Добавьте зависимости в файл package.json.

На этом этапе я буду использовать только 2 типа зависимостей:

1. Зависимости разработки: это тип зависимости, который вам нужен на определенном этапе процесса разработки, но не во время выполнения вашего кода (например, зависимости Babel или WebPack).

используйте - save-dev как показано ниже, чтобы установить их автоматически:

npm install — save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin style-loader css-loader babel-core babel-loader babel-preset-env babel-preset-react file-loader

2. Зависимости: обычные зависимости, необходимые при запуске кода.

Используйте - сохранить как показано ниже, чтобы установить их автоматически:

npm install — save react react-dom @babel/polyfill

Как мы уже говорили ранее, мы установим функцию polyfill для поддержки всех браузеров и решения проблемы кроссбраузерности с помощью React. Мы установим его как обычную зависимость, а не как devDependency, потому что это полифилл, который запускается перед исходным кодом.

Шаг 4:

Обновите сценарии NPM в файле package.json

Откройте «package.json» в каталоге hala-test и добавьте следующий сценарий NPM:

{
  "name": "hala-test",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack-dev-server --mode development"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "babel-core": "^6.26.3",
    "babel-loader": "^7.1.5",
    "babel-preset-env": "^1.7.0",
    "babel-preset-react": "^6.24.1",
    "css-loader": "^2.1.1",
    "file-loader": "^3.0.1",
    "html-webpack-plugin": "^3.2.0",
    "style-loader": "^0.23.1",
    "webpack": "^4.31.0",
    "webpack-cli": "^3.3.2",
    "webpack-dev-server": "^3.3.1"
  },
  "dependencies": {
    "@babel/polyfill": "^7.4.4",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }
}

Сценарий start будет использоваться для запуска модуля в нашей среде разработки.

Шаг 5:

Добавьте следующую структуру в корень вашего модуля вручную или с помощью terminal / cmd.

hala-test/
|
├── src
│   ├── elements
│        └── MyComponent.js
|   ├── assets
|        └── styles.css
|   └── index.js
|
├── demo
│   ├── index.html
│   ├── index.js
│   └── App.js 
|
├── webpack.config.js
├── .babelrc
└── README.md

Шаг 6:

Напишите конфигурации Babel и Webpack.

В этом простом примере у нас будет только 2 файла конфигурации: webpack.config.js и .babelrc.

  • webpack.config.js

Файл конфигурации работает как модуль common.js. Файл конфигурации - это место для размещения всей конфигурации веб-пакета, загрузчиков (новые функции для CSS, стиля, файлов и т. Д.) И другой конкретной информации, относящейся к сборке.

const path = require('path');
const HtmlWebpackPlugin = require("html-webpack-plugin");
const htmlWebpackPlugin = new HtmlWebpackPlugin({
   template: path.join(__dirname, "demo/index.html"),
   filename: "./index.html"
});
module.exports = {
   entry: ["@babel/polyfill", path.join(__dirname, "demo/index.js")],
   output: {
        path: path.join(__dirname, "demo/dist"),
        filename: "bundle.js"
    },
   module: {
       rules: [
           {
               test: /\.(js|jsx)$/,
               use: "babel-loader",
               exclude: /node_modules/
           },
           {
               test: /\.css$/,
               use: ["style-loader", "css-loader"]
           },
           {
                test: /\.(png|jpg|gif|svg|ttf)$/,
                use: [
                  {
                    loader: 'file-loader',
                    options: {}
                  }
                ]
            }
       ]
   },
   plugins: [htmlWebpackPlugin],
   resolve: {
       extensions: [".js", ".jsx"]
   },
   devServer: {
       port: 3001,
       open: true
   }
};
  • .babelrc

Поскольку мы работаем с babel, нам нужно дать четкие инструкции, чтобы он что-то делал. Это делается с помощью файла babelrc, который представляет собой файл конфигурации, который включает в себя список необходимых пресетов и плагинов для нашего модуля.

Есть разные способы добавить конфигурации babel в ваш модуль, о которых вы можете прочитать здесь, если интересно.

Для нашего простого модуля нам просто нужно определить пресеты, которые могут действовать как массив плагинов Babel или даже конфигурация общих опций.

{
  "presets": ["env", "react"]
}

Шаг 7:

Напишите свой собственный модуль.

Мы создадим модуль, который будет печатать «Hello from My Component» в браузере. Все, что вам нужно, это добавить следующий код:

  • src / elements / MyComponent.js:
import React from 'react';
import '../assets/styles.css';
class MyComponent extends React.Component{
  render(){
    return(<h1>Hello from My Component</h1>);
  }
}
export default MyComponent;
  • src / assets / styles.css:
h1 {
   color: red;
}
  • src / index.js:
import "@babel/polyfill";
import MyComponent from './elements/MyComponent';
module.exports = {
  MyComponent: MyComponent,
};
  • демо / SRC / index.html:
<html>
<head>
   <title>My Component Demo</title>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
</head>
<body>
   <noscript>
       You need to enable JavaScript to run this app.
   </noscript>
   <div id="root"></div>
</body>
</html>
  • демо / SRC / index.js:
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(<App />, document.getElementById('root'));
  • демо / src / App.js:
import React, { Component }  from 'react'; 
import ReactDOM from 'react-dom';
import React, { Component }  from 'react';
import { MyComponent } from '../src';
class App extends Component {
render() {
return (
      <div className="App">
        <MyComponent />
      </div>
    );
  }
}
export default App;

Теперь, когда все готово, выполните следующую команду, чтобы запустить режим разработки:

npm start

Откройте localhost: 3001 в своем браузере, и вы должны увидеть демонстрационную страницу модуля. Внесите некоторые изменения, нажмите «Сохранить», и страница автоматически обновится.

Теперь мы можем опубликовать готовую версию модуля в виде пакета NPM.

Мы хотим опубликовать модуль с минимальным количеством файлов, необходимых для установки. Верно?

Шаг 1:

Установите Babel CLI

npm install — save-dev babel-cli

Шаг 2:

Обновите файл package.json, добавив скрипт транспиляции, который позволит Babel транспилировать исходные файлы нашего модуля, а также копировать любые ресурсы, не являющиеся исходными (например, файлы .css), в целевую папку. с именем dist и измените основную точку входа нашего модуля на транспилированную версию (папку dist).

{
  "name": "hala-test",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack-dev-server --mode development",
    "transpile": "babel src -d dist --copy-files"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "babel-cli": "^6.26.0",
    "babel-core": "^6.26.3",
    "babel-loader": "^7.1.5",
    "babel-preset-env": "^1.7.0",
    "babel-preset-react": "^6.24.1",
    "css-loader": "^2.1.1",
    "file-loader": "^3.0.1",
    "html-webpack-plugin": "^3.2.0",
    "style-loader": "^0.23.1",
    "webpack": "^4.31.0",
    "webpack-cli": "^3.3.2",
    "webpack-dev-server": "^3.3.1"
  },
  "dependencies": {
    "@babel/polyfill": "^7.4.4",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }
}

Шаг 3:

Выполните следующую команду:

npm run transpile

Шаг 4:

Измените файл package.json, чтобы улучшить модуль:

  • Добавление скрипта PreublishOnly, который будет автоматически запускать скрипт transpile NPM каждый раз, когда мы публикуем модуль. Это гарантирует, что мы всегда публикуем самую последнюю версию.
  • Добавление peerDependencies, который представляет собой особый тип зависимости, который уменьшит размер пакета и предотвратит катастрофу, связанную с наличием нескольких версий React в целевом проекте пользователя.

Установка пакетов как peerDependency заставляет NPM не включать React в опубликованный пакет.

{
  "name": "hala-test",
  "version": "1.0.0",
  "description": "",
  "main": "dist/index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack-dev-server --mode development",
    "transpile": "babel src -d dist --copy-files",
    "prepublishOnly":"npm run transpile"
  },
  "author": "",
  "license": "ISC",
  "peerDependencies": {
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  },
  "devDependencies": {
    "babel-cli": "^6.26.0",
    "babel-core": "^6.26.3",
    "babel-loader": "^7.1.5",
    "babel-preset-env": "^1.7.0",
    "babel-preset-react": "^6.24.1",
    "css-loader": "^1.0.1",
    "file-loader": "^1.1.11",
    "html-webpack-plugin": "^3.2.0",
    "style-loader": "^0.21.0",
    "webpack": "^4.30.0",
    "webpack-cli": "^3.3.0",
    "webpack-dev-server": "^3.3.1"
  },
  "dependencies": {
    "@babel/polyfill": "^7.4.3"
  }
}

Шаг 5: Сообщаем NPM, что в нашем модуле есть файлы и папки, которые можно не включать в опубликованный пакет. Добавьте .npmignore в корень модуля.

  • .npmignore:
src
demo
.babelrc
.gitignore
webpack.config.js

Шаг 6:

Добавьте четкую документацию для своего пакета, обновив файл README.md в каталоге модуля со следующей информацией:

  • Оглавление: включает основные заголовки с прямой ссылкой на каждый раздел.
  • Краткое описание: включает описание работы модуля, основных функций и ссылку на онлайн-демонстрацию или исходный код GitHub.
  • Установка: включает инструкции по установке пакета.
  • Использование: объясняет, как использовать пакет.
  • Свойства: включает в себя таблицу всех свойств в загруженном пакете.
  • Пример: фрагмент кода (вы можете использовать файл App.js в своем демонстрационном коде), который может помочь другим разработчикам, использующим ваш пакет, взять и обновить в соответствии с требованиями их проекта.

Наконец, войдите в свою учетную запись NPM с помощью терминала / cmd:

npm login

Теперь мы, наконец, готовы опубликовать наш модуль как пакет NPM! Для начала выполните следующую команду:

npm publish

Когда вы просматриваете свой профиль на NPM, вы должны увидеть, что новый пакет был добавлен. Поздравляю, все готово!

Исходный код на Github

Также опубликовано в блоге