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

<Overview type="doc">
# Установка

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

Если вы разработчик мини-приложений ВКонтакте, то рекомендуем также ознакомиться со
страницей [Интеграции | VK Mini Apps](https://www.npmjs.com/package/@vkontakte/create-vk-mini-app).

</Overview>

<InstallTemplates />

## Базовая установка [#base-install]

<Steps>

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

Подробнее узнать о возможных вариантах создания React-приложения можно в [документации React](https://ru.react.dev/learn/start-a-new-react-project).
Вы можете использовать любые шаблоны и сборщики, в том числе [Vite](https://vite.dev/) или [Next.js](https://nextjs.org/).
Обратите внимание, что VKUI поддерживает Typescript.

### Установите зависимости [#step2]

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

<PackageManagers
  npm="npm i --save @vkontakte/vkui"
  yarn="yarn add @vkontakte/vkui"
  pnpm="pnpm add @vkontakte/vkui"
/>

#### Peer Dependencies

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

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

### Настройте `meta`-тег [#step3]

Для корректного отображения интерфейса на безрамочных смартфонах (подробнее см. в статье ["The Notch" and CSS](https://css-tricks.com/the-notch-and-css/)),
необходимо добавить [meta-тег](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag) в корневой `html`:

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

- см. [Vite | `index.html` and Project Root](https://vite.dev/guide/#index-html-and-project-root)
- см. [Next.js | How to add metadata and create OG images](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)

### Подключите VKUI [#step4]

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

Пример для проекта с шаблоном [React + TypeScript + Vite](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts).

```tsx showLineNumbers filename="src/main.tsx" {4,9-10,12-13}
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`](/components/config-provider) – конфигурирует приложение под разные платформы и темы.
- [`AppRoot`](/components/app-root) – управляет режимами встраивания, полосой прокрутки, безопасными отступами и порталами.
- см. [Vite | CSS](https://vite.dev/guide/features#css)
- см. [Next.js | External stylesheets](https://nextjs.org/docs/app/getting-started/css#external-stylesheets)

</Steps>

## Установка ESNext версии [#esnext-install]

VKUI позволяет подключить специальную сборку с ESNext и [CSS Modules](https://github.com/css-modules/css-modules).
Такая сборка позволяет уменьшить размер приложения как JS кода, так и CSS, однако для её использования необходимо дополнительно
настроить сборщики.

Шаги идентичны [базовой установке](#basic-install), но отличается CSS-бандл, который нужно подключить.

<Steps>

### Подключите стили [#esnext-step1]

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

На примере файла `src/main.tsx` из [базовой установки](#basic-install):

```diff filename="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';
```

### Настройте сборщик [#esnext-step2]

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

<details>
<summary>Next.js</summary>

```js filename="next.config.js"
module.exports = {
  // ...

  // Включаем транспиляцию
  transpilePackages: ['@vkontakte/vkui'],

  // Трансформируем импорты
  modularizeImports: {
    '@vkontakte/vkui': {
      transform: '@vkontakte/vkui/dist/cssm',
      skipDefaultConversion: true,
    },
  },
};
```

[Пример приложения](https://codesandbox.io/p/sandbox/vkui-next-js-cssm-el0g7c) на Next.js

</details>

<details>
<summary>Vite</summary>

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

[Пример приложения](https://codesandbox.io/p/sandbox/vkui-vite-cssm-4iikku) на Vite

</details>

<details>
<summary>webpack</summary>

```js filename="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',
    },
  },
};
```

</details>

</Steps>

## Иконки [#icons]

Некоторые компоненты VKUI используют иконки из пакета [@vkontakte/icons](https://www.npmjs.com/package/@vkontakte/icons) для
добавления элементов графического интерфейса. Пакет содержит набор готовых SVG-иконок, представленных в виде React-компонентов.
Увидеть полный список иконок можно в отдельной [документации иконок](https://vkcom.github.io/icons).

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

### Дедупликация @vkontakte/icons [#dedupe-icons]

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

<PackageManagers npm="npm dedupe" yarn="yarn dedupe @vkontakte/icons" pnpm="pnpm dedupe" />

## CDN

Для того, чтобы начать использовать VKUI с минимальными затратами на настройку окружения, можно
воспользоваться такими инструментами как [esh.sh](https://esm.sh/) или [esm.run](https://www.jsdelivr.com/esm).

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

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

<Callout>
  Мы рекомендуем выбирать данный метод только для быстрого прототипирования. Для того, чтобы
  использовать VKUI с оптимальными настройками, отдавайте предпочтение [установке с использованием
  сборщиков](#base-install).
</Callout>