10. Режим библиотеки

Vite поддерживает специальный режим сборки для создания npm библиотек — library mode. В этом режиме Vite собирает ваш код в различные форматы: ESM, CommonJS, UMD — с правильной обработкой внешних зависимостей.

Настройка Library Mode

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'
import dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    react(),
    dts({ include: ['lib'] }), // Генерация .d.ts файлов
  ],
  build: {
    // Включаем library mode
    lib: {
      entry: resolve(__dirname, 'lib/main.ts'), // Точка входа
      name: 'MyLib',          // Имя глобальной переменной для UMD/IIFE
      formats: ['es', 'cjs'], // Форматы вывода
      fileName: (format) => 'my-lib.' + format + '.js',
    },

    // Внешние зависимости — НЕ включаем в бандл
    rollupOptions: {
      external: ['react', 'react-dom', 'react/jsx-runtime'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
  },
})

Структура библиотеки

my-lib/
├── lib/                    ← Исходники библиотеки
│   ├── main.ts             ← Точка входа (всё экспортируется здесь)
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Modal.tsx
│   └── hooks/
│       └── useTheme.ts
├── src/                    ← Demo/playground приложение
│   └── App.tsx
├── dist/                   ← После сборки
│   ├── my-lib.es.js
│   ├── my-lib.cjs.js
│   └── index.d.ts
└── vite.config.ts

Форматы вывода

formats: ['es', 'cjs', 'umd', 'iife']

// es — ES Modules (для современных бандлеров, tree-shakeable)
// import { Button } from 'my-lib'

// cjs — CommonJS (для Node.js, старый Webpack)
// const { Button } = require('my-lib')

// umd — Universal Module Definition (браузер + Node.js)
// Для подключения через <script> тегом

// iife — Immediately Invoked Function Expression
// Самодостаточный файл для <script> подключения

package.json для библиотеки

{
  "name": "my-vite-lib",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],

  // Современный exports field
  "exports": {
    ".": {
      "import": "./dist/my-lib.es.js",
      "require": "./dist/my-lib.cjs.js",
      "types": "./dist/index.d.ts"
    }
  },

  // Для обратной совместимости
  "main": "./dist/my-lib.cjs.js",
  "module": "./dist/my-lib.es.js",
  "types": "./dist/index.d.ts",

  // Peer dependencies — НЕ включать в бандл
  "peerDependencies": {
    "react": ">=17",
    "react-dom": ">=17"
  },

  "devDependencies": {
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.0.0"
  }
}

TypeScript декларации (vite-plugin-dts)

npm i -D vite-plugin-dts

vite.config.ts

import dts from 'vite-plugin-dts'

plugins: [
  react(),
  dts({
    include: ['lib'],          // Только из директории lib/
    exclude: ['src'],          // Исключить demo app
    rollupTypes: true,         // Объединить в один .d.ts файл
    insertTypesEntry: true,    // Добавить types в package.json
  }),
],

externals — Что НЕ включать в бандл

rollupOptions: {
  // Всё, что будет установлено как peerDependency
  external: [
    'react',
    'react-dom',
    'react/jsx-runtime',

    // Regex — все пакеты @mui
    /^@mui\/.+/,

    // Функция
    (id) => id.includes('node_modules'),
  ],
}

Ниже — сравнение размеров бандлов для разных форматов и стратегий externals: