Установка
На этой странице представлены пошаговые инструкции по настройке окружения, установке зависимостей и непосредственное подключение VKUI.
Если вы разработчик мини-приложений ВКонтакте, то рекомендуем также ознакомиться со страницей Интеграции | VK Mini Apps ↗.
быстрого старта SPA-приложений
приложений с поддержкой SSR
Базовая установка
Подготовьте 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 ↗.
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
из базовой установки:
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
module.exports = {
// ...
// Включаем транспиляцию
transpilePackages: ['@vkontakte/vkui'],
// Трансформируем импорты
modularizeImports: {
'@vkontakte/vkui': {
transform: '@vkontakte/vkui/dist/cssm',
skipDefaultConversion: true,
},
},
};
Пример приложения ↗ на Next.js
Vite
export default defineConfig({
// ...
resolve: {
alias: [{ find: /^@vkontakte\/vkui$/, replacement: '@vkontakte/vkui/dist/cssm' }],
},
});
Пример приложения ↗ на Vite
webpack
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 с минимальными затратами на настройку окружения, можно воспользоваться такими инструментами как 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>