Перейти к содержимому
MDX ↗

Установка

На этой странице — пошаговая инструкция по настройке окружения, установке зависимостей и подключению VKUI.

Если вы разрабатываете мини-приложение ВКонтакте, см. также Интеграции | VK Mini Apps ↗.

Базовая установка

Подготовьте SPA React приложение

О вариантах создания React-приложения — в документации React ↗. Подойдут любые шаблоны и сборщики, включая Vite ↗ и Next.js ↗. VKUI поддерживает TypeScript.

Установите зависимости

Установите библиотеку командой вашего пакетного менеджера:

npm i --save @vkontakte/vkui

Peer Dependencies

Если не используете стартовый пакет, установите обязательные зависимости:

"peerDependencies": {
  "react": "^18.2.0 || ^19.0.0",
  "react-dom": "^18.2.0 || ^19.0.0"
}

Настройте meta-тег

Для корректного отображения на безрамочных смартфонах (подробнее — “The Notch” and CSS ↗) добавьте meta-тег ↗ в корневой html:

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=no, viewport-fit=cover"
/>

Подключите VKUI

Оберните приложение в обязательные провайдеры и импортируйте CSS-бандл '@vkontakte/vkui/dist/vkui.css'. Лучше сделать это в корне приложения (обычно main.tsx или index.tsx).

Пример для шаблона React + TypeScript + Vite ↗.

src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { ConfigProvider, AppRoot } from '@vkontakte/vkui';
import '@vkontakte/vkui/dist/vkui.css';
import App from './App.tsx';
 
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfigProvider>
      <AppRoot>
        <App />
      </AppRoot>
    </ConfigProvider>
  </StrictMode>,
);
  • ConfigProvider – конфигурирует приложение под разные платформы и темы.
  • AppRoot – управляет режимами встраивания, полосой прокрутки, безопасными отступами и порталами.
  • см. Vite | CSS ↗
  • см. Next.js | External stylesheets ↗

Установка ESNext версии

VKUI позволяет подключить сборку с ESNext и CSS Modules ↗. Она уменьшает размер приложения — и JS, и CSS, — но требует дополнительной настройки сборщика.

Шаги те же, что в базовой установке, но отличается CSS-бандл.

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

Импортируйте CSS-бандл '@vkontakte/vkui/dist/cssm/styles/themes.css' вместо '@vkontakte/vkui/dist/vkui.css' в корень вашего приложения.

На примере файла src/main.tsx из базовой установки:

src/main.tsx
import { ConfigProvider, AppRoot } from '@vkontakte/vkui';
- import '@vkontakte/vkui/dist/vkui.css';
+ import '@vkontakte/vkui/dist/cssm/styles/themes.css';
import { App } from './App.tsx';

Настройте сборщик

Нужно трансформировать импорты, включить транспиляцию и подключить CSS Modules. Для каждого сборщика или фреймворка — свои инструкции.

Next.js
next.config.js
module.exports = {
  // ...
 
  // Включаем транспиляцию
  transpilePackages: ['@vkontakte/vkui'],
 
  // Трансформируем импорты
  modularizeImports: {
    '@vkontakte/vkui': {
      transform: '@vkontakte/vkui/dist/cssm',
      skipDefaultConversion: true,
    },
  },
};

Пример приложения ↗ на Next.js

Vite
vite.config.js
export default defineConfig({
  // ...
  resolve: {
    alias: [{ find: /^@vkontakte\/vkui$/, replacement: '@vkontakte/vkui/dist/cssm' }],
  },
});

Пример приложения ↗ на Vite

webpack
webpack.config.js
module.exports = {
  //...
 
  module: {
    rules: [
      // Включаем транспиляцию
      {
        test: /\.js$/,
        include: /node_modules\/@vkontakte\/vkui/,
        use: ['babel-loader'],
      },
 
      // Обрабатываем css modules
      {
        test: /\.css$/,
        include: /node_modules\/@vkontakte\/vkui/,
        use: [
          {
            loader: 'css-loader',
            /* Используем следующие опции в случае использования `css-loader >= 7.0.0` (см. https://github.com/webpack-contrib/css-loader/blob/v7.1.0/CHANGELOG.md) */
            // options: {
            //   namedExport: false,
            //   exportLocalsConvention: 'as-is',
            // }
          },
        ],
      },
    ],
  },
 
  // Трансформируем импорты
  resolve: {
    alias: {
      '@vkontakte/vkui$': '@vkontakte/vkui/dist/cssm',
    },
  },
};

Иконки

Некоторые компоненты VKUI используют иконки из @vkontakte/icons ↗ — набор готовых SVG-иконок в виде React-компонентов. Полный список — в отдельной документации иконок ↗.

Если вы тоже используете @vkontakte/icons и указываете пакет в package.json, возможна дубликация зависимостей.

Дедупликация @vkontakte/icons

Выполните команду вашего пакетного менеджера:

npm dedupe

CDN

Чтобы начать с минимальной настройкой, подключите VKUI через esm.sh ↗ или esm.run ↗.

Пример с esm.sh:

<link rel="stylesheet" href="https://esm.sh/@vkontakte/vkui@7/dist/vkui.css" />
<script type="importmap">
  {
    "imports": {
      "react": "https://esm.sh/react@19/",
      "react-dom/": "https://esm.sh/react-dom@19/",
      "@vkontakte/vkui": "https://esm.sh/@vkontakte/vkui@7/"
    }
  }
</script>
<script type="module">
  import React from 'react';
  import { createRoot } from 'react-dom/client';
  import { Button } from '@vkontakte/vkui';
 
  const root = createRoot(document.getElementById('root'));
  root.render(React.createElement(Button, null, 'Кнопка'));
</script>
Предыдущая
Обзор
Следующая
Использование