Установка

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

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

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

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

npm i --save @vkontakte/vkui

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

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

Для корректного отображения интерфейса на безрамочных смартфонах (подробнее см. в статье “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"
/>

Для этого нужно обернуть приложение в обязательные провайдеры и импортировать 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 ↗

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, то в таком случае вы можете столкнуться с дублированием зависимостей.

В зависимости от вашего пакетного менеджера вам необходимо будет выполнить следующую команду:

npm dedupe

Для того, чтобы начать использовать VKUI с минимальными затратами на настройку окружения, можно воспользоваться такими инструментами как esh.sh ↗ или esm.run ↗.

На примере esm.sh ваш index.html может выглядеть следующим образом:

<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>