Простой путь к публикации Vue3 модуля на NPM с помощью Vite

Для веб-разработчика (особенно начинающего) создание собственных модулей и публикация их в open source может казаться сложным процессом. В этой статье я покажу один из самых простых и быстрых способов публикации своего модуля на NPM при помощи бандлера Vite.

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

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

Этап 1. Регистрация на сайте NPM

В первую очередь необходимо зарегистрироваться на ресурсе со всеми пакетами и модулями, которые только существуют для JavaScript. Самое важное после регистрации – связать менеджер пакетов у себя на компьютере с только что созданным аккаунтом. Для этого в консоли необходимо прописать следующую команду:

npm adduser

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

Этап 2. Настройка сборщика Vite

Для полной настройки конечной сборки модуля необходимо импортировать в файл vite.config.js два сторонних модуля, которые помогут правильно собрать модуль.

"vite-plugin-css-injected-by-js": "^3.1.1",
"vite-plugin-dts": "^3.6.4",

vite-plugin-dts – этот плагин предназначен для генерации файлов .d.ts (TypeScript объявления типов) для вашего модуля. Это необходимо при использовании TypeScript, который часто используется в связке с Vue3. Файлы .d.ts используются для описания типов данных, интерфейсов и других типизированных элементов вашего кода, чтобы TypeScript мог обеспечить проверку типов и автодополнение кода.

vite-plugin-css-injected-by-js – плагин позволяет внедрять CSS стили непосредственно в JavaScript код. Это может быть полезно, если вы хотите создать компоненты или библиотеки, где стили должны быть динамически внедрены в зависимости от состояния компонента или других факторов. Он также может использоваться для обработки CSS в стиле CSS-in-JS. Самое главное то, что при помощи этого плагина пользователю не придется импортировать стили в проект отдельно из общей папки модуля.

Важно! Помимо настройки vite.config.js необходимо правильно настроить main.ts самого проекта. Файл должен выглядеть аналогично файлу, куда вы импортируете сторонние модули в проекте Vue, например:

import TooltipComponent from './components/TooltipComponent.vue';
import TooltipDirective from './directives/tooltip';
import './assets/index.css';

export const install = (app: any) => {
  app.component('tooltip', TooltipComponent);
  app.directive('tooltip', TooltipDirective);
};

export default {
  install,
};

export { TooltipComponent, TooltipDirective };

В результате файл vite.config.js будет выглядеть следующим образом:

import { resolve } from 'path';
import { defineConfig } from 'vite';
import vue from "@vitejs/plugin-vue";
import dts from 'vite-plugin-dts';
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';

export default defineConfig({
  plugins: [ 
    vue(),
    cssInjectedByJsPlugin({ useStrictCSP: true, relativeCSSInjection: false }), 
    dts({ rollupTypes: true }),
  ],
  build: {
    lib: {
      name: 'vue3-module',
      entry: resolve(__dirname, 'src/index.ts'),
      fileName: (format) => `vue3-module.${format}.js`,
    },
    emptyOutDir: true,
    rollupOptions: {
      external: ['vue'],
      output: {
        exports: 'named',
        globals: {
          vue: 'Vue',
        },
      },
    },
  },
})

В конфиге с 8-ой по 12-ю строчку происходит настройка плагинов для сборки модуля при помощи Vite.

В cssInjectedByJsPlugin имеются следующие атрибуты:

• useStrictCSP: true – указывает, следует ли использовать строгие правила Content Security Policy (CSP) при внедрении CSS. Content Security Policy – это механизм безопасности, который ограничивает, откуда могут быть загружены ресурсы на странице.

• relativeCSSInjection: false – указывает, следует ли использовать относительные пути при внедрении CSS. Если установлен в false, CSS будет внедряться с абсолютными путями (интегрироваться в JS файлы). Если установлен в true, CSS будет внедряться с относительными путями (необходим самостоятельный импорт со стороны пользователя).

С 13-ой по 29-ю строчку в конфиге происходит настройка сборщика для модуля.

Настройки путей и названия модуля, lib:

• name: 'vue3-tooltip' – название библиотеки.

• entry: resolve(__dirname, 'src/index.ts') – путь к точке входа в проекте

• fileName: (format) => `\vue3-tooltip.${format}.js` – функция, которая определяет форматы файлов, которые будут сгенерированы в результате сборки библиотеки.

• emptyOutDir: true – очистить выходную директорию перед сборкой.

Настройки инструмента сборки, rollupOptions:

• external: ['vue'] – указание, что библиотека vue должна быть внешней зависимостью и не должна включаться в сборку.

• output: { ... } – опции вывода, такие как экспорт и глобальные переменные.

• exports: 'named' – указание на то, что экспортируемые элементы должны быть именованными.

• globals: { vue: 'Vue' } – глобальные переменные, которые используются внутри библиотеки, например, в этом случае Vue должен быть доступен глобально.

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

vite build

или, при условии, что в package.json она уже добавлена:

yarn build

Этап 3. Настройка package.json

Файл package.json – это основной файл конфигурации для любого Node.js проекта, включая модули. Он содержит всю важную информацию о вашем модуле – имя, версию, описание, зависимости, скрипты для запуска и тестирования, лицензию, а также другие метаданные. При публикации вашего модуля эти данные используются другими разработчиками для того, чтобы понять, что делает ваш модуль, как его установить, какие зависимости он имеет и какие команды можно использовать для его работы. Также package.json необходим для управления зависимостями при установке модуля через npm или yarn.

Для рассмотрения готового файла package.json, он был взят из модуля vue3-tooltip. Эталонным этот файл назвать, конечно же, нельзя, но правильно составленным – можно!

{
  "name": "vue3-tooltip",
  "description": "Module for convenient work with tooltips in Vue3 (using a directive and a component)",
  "type": "module",
  "version": "2.2.4",
  "private": false,
  "author": {
    "name": "Dmitry Luckyanenko",
    "nickname": "neluckoff",
    "email": "[e-mail]",
    "github": "https://github.com/neluckoff"
  },
  "main": "./dist/vue3-tooltip.umd.js",
  "module": "./dist/vue3-tooltip.es.js",
  "typings": "./dist/index.d.ts",
  "styles": "./dist/style.css",
  "files": [
    "dist"
  ],
  "exports": {
    ".": {
      "import": "./dist/vue3-tooltip.es.js",
      "require": "./dist/vue3-tooltip.umd.js",
      "types": "./dist/index.d.ts"
    },
    "./tooltip.css": "./dist/style.css"
  },
  "peerDependencies": {
    "vue": "^3.2.47"
  },
  "keywords": [
    "vue3-tooltip",
    "tooltip",
    "vue3",
    "tooltip-component",
    "v-tooltip",
    "tooltip-directive"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/neluckoff/vue3-tooltip.git"
  },
  "bugs": {
    "url": "https://github.com/neluckoff/vue3-tooltip/issues"
  },
  "homepage": "https://goo.su/YfII",
  "scripts": {
    "build": "vite build"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.4",
    "typescript": "^5.2.2",
    "vite": "^5.1.4",
    "vite-plugin-css-injected-by-js": "^3.1.1",
    "vite-plugin-dts": "^3.6.4",
    "vue": "^3.4.21",
    "vue-tsc": "^1.8.27"
  }
}

В представленном package.json файле имеются следующие настройки:

• "name" – имя вашего модуля;

• "description" – описание модуля, обычно краткое описание его функций и назначения'

• "type" – тип модуля, в данном случае "module" указывает, что ваш модуль - это ES модуль'

• "version" – версия вашего модуля'

• "private" – определяет, является ли ваш проект приватным (true/false). Здесь установлено в false, что означает, что ваш модуль не является приватным'

• "author" – информация об авторе модуля'

• "main" – основной файл модуля, который будет загружен при использовании require ;

• "module" – файл ES модуля, который будет загружен при использовании import;

• "typings" – путь к файлу типов TypeScript (.d.ts), который определяет типы данных вашего модуля;

• "styles" – путь к файлу стилей вашего модуля;

• "files" – список файлов и директорий, которые будут включены в вашу опубликованную версию модуля;

• "exports" – определяет, какие файлы модуля доступны для импорта;

• "peerDependencies" – зависимости, которые ваш модуль ожидает, чтобы их предоставили при его использовании;

• "keywords" – ключевые слова, помогающие пользователям находить ваш модуль при поиске;

• "license" – лицензия, по которой распространяется ваш модуль.

• "repository" – информация о репозитории вашего модуля;

• "bugs" – URL для отчетов об ошибках;

• "homepage" – URL домашней страницы вашего модуля;

• "scripts" – скрипты, которые можно запускать с помощью npm или yarn ;

• "devDependencies" – зависимости, необходимые только для разработки и тестирования вашего модуля.

Особое внимание стоит уделить настройке “exports”, ведь именно она будет отвечать за импорт модуля в проект пользователя.

"exports": {
    ".": {
      "import": "./dist/vue3-tooltip.es.js",
      "require": "./dist/vue3-tooltip.umd.js",
      "types": "./dist/index.d.ts"
    },
    "./tooltip.css": "./dist/style.css"
},

Точка на 2-ой строке используется для того, чтобы из корня модуля можно было импортировать все необходимое (первая строчка в примере ниже), а путь на 7-ой строке необходим для импорта стилей, так как в этом модуле они не сливаются с JS (вторая строка в примере ниже):

import { TooltipDirective, TooltipComponent } from 'vue3-tooltip';
import 'vue3-tooltip/tooltip.css';

Этап 4. Публикация

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

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

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

npm publish

Готово! Модуль загружен для общего пользования!

Заключение

В этой статье мы рассмотрели простой и эффективный способ публикации модулей Vue3 на NPM с использованием Vite. Надеюсь, что эта информация поможет вам упростить ваш рабочий процесс и сделает публикацию модулей более доступной.

Небольшой бонус :)

Хочу поделиться с вами несколькими модулями, которыми я руководствовался при публикации своего модуля и подготовке этого поста. Эти модули значительно облегчили мою работу – возможно, окажутся полезными и для вас:

• vue3-notification – модуль для добавления уведомлений в Vue3 приложения, обеспечивающий простой способ показать информативные сообщения;

• vue3-tooltip – модуль для добавления всплывающих подсказок к элементам в Vue3 приложениях, позволяющий настроить стиль, позицию и поведение подсказок;

• vue3-draggable – модуль для реализации функциональности перетаскивания элементов в Vue 3 приложениях, особенно полезный для создания интерактивных пользовательских интерфейсов.