Vue Design System

Универсальная библиотека компонентов Vue, совместимая с Vue 2 и Vue 3.

Быстрый старт

Требования

• Node.js 16.x или выше
• npm или yarn

Шаг 1. Клонирование и установка

git clone <repository-url>
cd vue-design-system-fs
npm install

Шаг 2. Запуск для разработки

npm run dev

Откройте http://localhost:5173 в браузере для просмотра компонентов.

Шаг 3. Сборка библиотеки

npm run build:lib

Собранные файлы будут находиться в папке dist.

Рекомендуемая настройка IDE

VSCode + Volar (отключить Vetur) + TypeScript Vue Plugin (Volar).

Настройка TypeScript в IDE

1. Отключить встроенное расширение TypeScript
   • Выполнить Extensions: Show Built-in Extensions из палитры команд VSCode
   • Найти TypeScript and JavaScript Language Features, нажать правой кнопкой мыши и выбрать Disable (Workspace)
2. Перезагрузить окно VSCode, выполнив Developer: Reload Window из палитры команд.

Структура проекта

vue-design-system-fs/
├── src/
│   ├── components/     # Vue компоненты
│   ├── index.ts        # Точка входа библиотеки
│   └── main.ts         # Точка входа для разработки
├── dist/               # Собранные файлы библиотеки
├── rollup.config.js    # Конфигурация сборки библиотеки
└── package.json        # Зависимости и скрипты

Доступные команды

Разработка

npm run dev              # Запуск dev сервера с горячей перезагрузкой
npm run lint             # Проверка кода ESLint

Сборка

npm run build            # Сборка приложения для продакшена
npm run build:lib        # Сборка библиотеки для публикации

Публикация

npm publish              # Публикация в npm (требуется аккаунт)

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

Конфигурация package.json

Добавьте следующие поля в package.json:

{
  "name": "vue-design-system-fs",
  "main": "dist/vue-design-system-fs.cjs.min.js",
  "browser": "dist/vue-design-system-fs.esm.min.js",
  "unpkg": "dist/vue-design-system-fs.global.min.js",
  "scripts": {
    "build:lib": "rimraf dist && rollup -c rollup.config.js --bundleConfigAsCjs"
  }
}

Конфигурация rollup.config.js

const pkg = require('./package.json')

export default {
  plugins: [...],
  external: ['vue-demi'],
  input: ['src/index.ts'],
  output: [
    {
      format: 'umd',
      file: pkg.unpkg,
      sourcemap: true,
      name: 'VueUniversalLibrary',
      globals: {
        'vue-demi': 'VueDemi'
      }
    }
  ]
}

Использование библиотеки в проекте

Установка

# используя yarn
yarn add vue-design-system-fs

# используя npm
npm install vue-design-system-fs

Подключение стилей

// main.js или main.ts (в зависимости от вашего проекта)
import 'vue-design-system-fs/dist/vue-design-system-fs.min.css'

Использование компонентов

import { Button } from 'vue-design-system-fs'

export default {
  components: {
    Button
  }
}

Локальное тестирование библиотеки

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

Шаг 1. Сборка библиотеки

npm run build:lib

Шаг 2. Создание тестового проекта

Для Vue 2

mkdir test-project-vue2
cd test-project-vue2
npm init vue@2
npm install

Для Vue 3

mkdir test-project-vue3
cd test-project-vue3
npm init vue@latest
npm install

Шаг 3. Локальная установка библиотеки через npm link

В директории библиотеки

npm run build:lib
npm link

В директории тестового проекта

npm link vue-design-system-fs

Примечание: npm link не добавляет зависимость в package.json и используется только для локальной разработки.

Шаг 4. Подключение в тестовом проекте

В Vue 2 проекте (Options API)

// src/main.js
import Vue from 'vue'
import App from './App.vue'
import 'vue-design-system-fs/dist/vue-design-system-fs.min.css'
import { Button } from 'vue-design-system-fs'

Vue.component('Button', Button)
new Vue({
  render: (h) => h(App)
}).$mount('#app')

В Vue 2 проекте (Composition API)

// src/main.js
import Vue from 'vue'
import App from './App.vue'
import VueCompositionAPI from '@vue/composition-api'
import 'vue-design-system-fs/dist/vue-design-system-fs.min.css'
import { Button } from 'vue-design-system-fs'

Vue.use(VueCompositionAPI)
Vue.component('Button', Button)
new Vue({
  render: (h) => h(App)
}).$mount('#app')

В Vue 3 проекте

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import 'vue-design-system-fs/dist/vue-design-system-fs.min.css'
import { Button } from 'vue-design-system-fs'

const app = createApp(App)
app.component('Button', Button)
app.mount('#app')

Шаг 5. Использование в компонентах

В Vue 2 компоненте (Options API)

<!-- src/components/TestComponent.vue -->
<template>
  <div>
    <Button variant="primary">Тестовая кнопка Vue 2</Button>
  </div>
</template>

<script>
export default {
  name: 'TestComponent'
}
</script>

В Vue 2 компоненте (Composition API)

<!-- src/components/TestComponent.vue -->
<template>
  <div>
    <Button variant="primary">Тестовая кнопка Vue 2</Button>
  </div>
</template>

<script>
import { defineComponent } from '@vue/composition-api'

export default defineComponent({
  name: 'TestComponent'
})
</script>

В Vue 3 компоненте

<!-- src/components/TestComponent.vue -->
<template>
  <div>
    <Button variant="primary">Тестовая кнопка Vue 3</Button>
  </div>
</template>

<script setup>
// Vue 3 Composition API
</script>

Шаг 6. Запуск тестового проекта

npm run dev

Особенности тестирования в Vue 2

• Composition API: Требуется установка @vue/composition-api для использования Composition API в Vue 2
• Импорты: В Vue 2 используйте .js расширения вместо .ts если проект не настроен для TypeScript
• Глобальная регистрация: Компоненты регистрируются через Vue.component() вместо app.component()
• Экземпляр Vue: Создается через new Vue() вместо createApp()
• Vite конфигурация: Добавьте в vite.config.js для корректной работы с npm link:

// vite.config.js
export default defineConfig({
  // ... другие настройки
  resolve: {
    dedupe: ['vue', 'vue-demi']
  }
})

Устранение распространенных ошибок

Ошибка: "Could not read from file: vue/dist/vue.runtime.esm.js"

Эта ошибка возникает когда vue-demi пытается импортировать Vue 3 в проекте Vue 2. Решение:

# Эта ошибка не должна возникать при правильной настройке библиотеки
# vue-demi автоматически определяется версию Vue в проекте

Ошибка: "vue-demi is not installed"

Эта ошибка не должна возникать так как vue-demi устанавливается автоматически вместе с библиотекой.

После успешного локального тестирования в обеих версиях Vue библиотека готова к публикации в npm.

Дополнительная информация

• Vite Configuration Reference
• Vue Demi Documentation