Vue Academy · Урок

Публикация и типизация плагинов Vue

Структура пакета, расширение ComponentCustomProperties в TypeScript и распространение через npm

«Публикация и типизация плагинов Vue» — бесплатный урок Vue Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Vue Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Vue Academy содержит 4 уроков всего.

Упаковка плагина для npm

Чтобы поделиться плагином Vue, опубликуйте его как пакет npm. Пакет должен объявлять правильные зависимости, содержать корректную сборку и типы TypeScript, а также быть правильно опубликован. В этом уроке рассматривается каждый шаг.

peerDependencies для Vue

Укажите Vue как peerDependency, а не как обычную зависимость. Это гарантирует, что Vue предоставляется хост-приложением, и предотвращает появление двух копий Vue в одной сборке, из-за чего нарушается реактивность.

{
  "name": "vue-toast-kit",
  "peerDependencies": {
    "vue": "^3.4.0"
  },
  "devDependencies": {
    "vue": "^3.4.0"
  }
}

Режим библиотеки Vite

Соберите пакет в режиме библиотеки Vite. Настройте build.lib, указав точку входа, имя и форматы вывода (ES + UMD), а Vue объявите внешней зависимостью, чтобы она не включалась в сборку.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'VueToastKit',
      fileName: 'index',
      formats: ['es', 'umd']
    }
  }
})

Исключение Vue в rollupOptions

Пометьте vue как внешнюю зависимость и сопоставьте её с глобальным объектом для сборки UMD, чтобы использовалась Vue из приложения пользователя.

build: {
  lib: { /* ... */ },
  rollupOptions: {
    external: ['vue'],
    output: {
      globals: { vue: 'Vue' }
    }
  }
}

Генерация объявлений типов

Поставляйте файлы .d.ts, чтобы пользователи получали автодополнение и проверку типов. Используйте vite-plugin-dts для создания объявлений во время сборки библиотеки.

import dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    vue(),
    dts({ insertTypesEntry: true })
  ]
})

Карта exports в package.json

Укажите пользователям правильные файлы с помощью поля exports, открыв сборку ESM и объявления типов. Установите type: module для пакетов, в первую очередь ориентированных на ESM.

{
  "type": "module",
  "main": "./dist/index.umd.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.umd.cjs"
    }
  }
}

Поставка расширения типов

Если плагин добавляет глобальные свойства, например this.$toast, включите расширение ComponentCustomProperties в опубликованные типы, чтобы редакторы пользователей автоматически распознавали его.

// src/types.d.ts (included in the build)
import type { ToastService } from './toast'

declare module 'vue' {
  interface ComponentCustomProperties {
    $toast: ToastService
  }
}

export {}

Публичная точка входа

Точка входа src/index.ts должна экспортировать плагин по умолчанию, а также все нужные пользователям композаблы, ключи и типы.

import ToastPlugin from './plugin'
export default ToastPlugin

export { useToast } from './composable'
export { toastKey } from './toast'
export type { ToastService, Toast } from './toast'

Поле files

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

{
  "files": ["dist"],
  "sideEffects": false
}

Публикация с подтверждением происхождения

Публикуйте в npm с подтверждением происхождения, которое криптографически связывает пакет со сборкой CI и исходным коммитом. Выполняйте публикацию из доверенного CI, например GitHub Actions, с необходимыми разрешениями.

# in CI (GitHub Actions)
npm publish --provenance --access public

# package.json can also set:
# "publishConfig": { "provenance": true }

Проверка перед публикацией

Перед публикацией убедитесь, что Vue указана как peer-зависимость, dist содержит ESM и типы, exports разрешается правильно, версия обновлена, а пробный запуск выглядит корректно.

# inspect what will be published
npm publish --dry-run

# verify the tarball contents
npm pack

Быстрая проверка

Проверьте своё понимание публикации плагинов Vue.

Итоги

Вы изучили публикацию и типизацию плагинов:

Указывайте Vue как peerDependency, чтобы избежать дублирования копий Vue
Собирайте пакет в режиме библиотеки Vite, исключая Vue из сборки
Создавайте .d.ts с помощью vite-plugin-dts и поставляйте расширение типов
Настраивайте exports, files и type: module
Публикуйте с --provenance из доверенного CI

Часто задаваемые вопросы

Урок «Публикация и типизация плагинов Vue» бесплатный?

Да — полный текст урока «Публикация и типизация плагинов Vue» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Vue Academy, подпишись на CoddyKit PRO. Курс Vue Academy содержит 4 уроков всего.

Чему я научусь в уроке «Публикация и типизация плагинов Vue»?

Структура пакета, расширение ComponentCustomProperties в TypeScript и распространение через npm Ты практикуешь Vue Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Vue Academy?

Предыдущий опыт не требуется. Vue Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Публикация и типизация плагинов Vue»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Vue Academy?

Да. Каждый урок Vue Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Архитектура плагинов и app.use()
Глобальные свойства и provide/inject в плагинах
Пример плагина уведомлений и всплывающих сообщений
Публикация и типизация плагинов Vue

← Назад к Vue Academy