Быстрый старт: подключение UI Kit к проекту

Битрикс24 UI Kit подключается к фронтенду приложения как npm-пакет @bitrix24/b24ui-nuxt. После подключения в проекте доступны Vue-компоненты, дизайн-токены и утилиты Tailwind CSS в стиле Битрикс24.

Подключение отличается в проекте на Nuxt и в проекте на Vue с Vite: различаются состав пакетов и файлы конфигурации. Параметры отдельных компонентов и интерактивные примеры остаются в документации библиотеки.

Что нужно перед началомЧто нужно перед началом

Требования пакета @bitrix24/b24ui-nuxt:

• Node.js версии 20.19 и выше в ветке 20 или 22.12 и выше
• Vue версии 3.5 и выше, а для пакета иконок — 3.5.24 и выше
• Tailwind CSS версии 4 — стили библиотеки подключаются в CSS-файл проекта и используют директивы четвертой версии
• Nuxt версии 4.1 и выше, если проект собирается на Nuxt
• менеджер пакетов npm, pnpm, yarn или bun

Команды на странице приведены для npm. Для другого менеджера пакетов замените их равнозначными: pnpm add, yarn add или bun add вместо npm install.

Ключ авторизации и scope для подключения библиотеки не нужны. UI Kit отвечает только за интерфейс и не обращается к Битрикс24. Данные и права приложение получает отдельно — это описано в статье Интеграция UI Kit с REST API и бизнес-логикой.

Как выбрать вариант подключенияКак выбрать вариант подключения

Nuxt и Vite поддерживаются одинаково — выбор зависит от задачи:

• Nuxt подходит для приложения с несколькими страницами, навигацией и локализацией. Он сразу дает серверный рендеринг, middleware, layout и composables.
• Vite подходит для одностраничного приложения и виджета, который открывается в слайдере Битрикс24. У него короче конфигурация и быстрее запускается dev-сервер.

Заготовка проектаЗаготовка проекта

Заготовка — это готовый проект с UI Kit: в нем уже прописаны зависимости, настроен сборщик и подключены стили библиотеки. Заготовок две, они отличаются только сборщиком — выбирайте по тем же критериям, что и вариант подключения.

Заготовка для проекта на Nuxt:

git clone https://github.com/bitrix24/starter-b24ui.git my-app
cd my-app
npm install
npm run dev

Заготовка для проекта на Vue и Vite:

git clone https://github.com/bitrix24/starter-b24ui-vue.git my-app
cd my-app
npm install
npm run dev

После запуска откройте адрес dev-сервера. Как убедиться, что стили библиотеки применились, описано в разделе Как проверить подключение.

Кроме минимальных заготовок есть заготовки Dashboard — проекты с боковым меню, панелью и рабочей областью: по одной заготовке для Nuxt и для Vue. Их состав описан в статье Компоненты и шаблоны.

Подключение к проекту на NuxtПодключение к проекту на Nuxt

1. Установите пакеты:

   npm install @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss
   

   @bitrix24/b24ui-nuxt — сама библиотека, @bitrix24/b24icons-vue — отдельный пакет с иконками. Если иконки в проекте не нужны, этот пакет можно не устанавливать. Обработку Tailwind CSS берет на себя модуль библиотеки, отдельный плагин Tailwind CSS подключать не нужно. Те же шаги с примерами есть в инструкции по установке для Nuxt.

2. Подключите модуль и CSS-файл проекта в nuxt.config.ts:

   export default defineNuxtConfig({
     modules: ['@bitrix24/b24ui-nuxt'],
     css: ['~/assets/css/main.css']
   })
   

3. Создайте файл app/assets/css/main.css и импортируйте в него Tailwind CSS и стили библиотеки:

   @import "tailwindcss";
   @import "@bitrix24/b24ui-nuxt";
   

   Пути в шагах 2 и 3 указывают на один файл: в Nuxt 4 алиас ~ ведет в каталог app.

4. Оберните приложение в компонент B24App в файле app.vue:

   <template>
     <B24App>
       <NuxtPage />
     </B24App>
   </template>
   

   B24App — корневой компонент библиотеки. Он задает общие настройки приложения и контейнеры, в которых выводятся уведомления, подсказки и окна поверх страницы. Без этой обертки не работают уведомления B24Toast, подсказки B24Tooltip и модальные окна, которые открываются из кода через useOverlay. Локализация при этом работает со значениями по умолчанию, переключить язык нельзя.

Модуль регистрирует компоненты автоматически — импортировать их на страницах не нужно.

Подключение к проекту на Vue и ViteПодключение к проекту на Vue и Vite

1. Установите пакеты:

   npm install @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss vue-router
   

   Пакет @bitrix24/b24ui-nuxt один для обоих вариантов запуска. В проекте на Vite из него берутся плагин сборки @bitrix24/b24ui-nuxt/vite и плагин Vue @bitrix24/b24ui-nuxt/vue-plugin, модуль Nuxt при этом не используется. Плагин сборки готовит компоненты и стили библиотеки, плагин Vue регистрирует их в приложении.

   vue-router в Vite устанавливается отдельно: в зависимостях библиотеки он необязателен, но по умолчанию плагин рендерит ссылки компонентов через RouterLink. Отключить это поведение можно опцией router: false в vite.config.ts — тогда ссылки станут обычными тегами a, а маршрутизатор не понадобится. Для проекта на Laravel или AdonisJS с Inertia укажите значение router: 'inertia'. Порядок настройки описан в инструкции по установке.

2. Добавьте плагин сборки в vite.config.ts:

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'
   
   export default defineConfig({
     plugins: [
       vue(),
       bitrix24UIPluginVite()
     ]
   })
   

   Отдельный плагин Tailwind CSS в конфигурацию добавлять не нужно: обработку Tailwind CSS берет на себя bitrix24UIPluginVite.

3. Создайте файл src/assets/css/main.css и импортируйте в него Tailwind CSS и стили библиотеки:

   @import "tailwindcss";
   @import "@bitrix24/b24ui-nuxt";
   

4. Подключите CSS-файл проекта и плагин Vue в src/main.ts:

   import './assets/css/main.css'
   import { createApp } from 'vue'
   import { createRouter, createWebHistory } from 'vue-router'
   import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
   import App from './App.vue'
   
   const app = createApp(App)
   const router = createRouter({
     routes: [],
     history: createWebHistory()
   })
   
   app.use(router)
   app.use(b24UiPlugin)
   app.mount('#app')
   

5. Оберните приложение в компонент B24App в файле src/App.vue:

   <template>
     <B24App>
       <RouterView />
     </B24App>
   </template>
   

6. Добавьте класс isolate корневому контейнеру в index.html. Класс создает отдельный контекст наложения, чтобы z-index модальных окон и всплывающих меню из библиотеки не конфликтовал с остальной разметкой страницы:

   <div id="app" class="isolate"></div>
   

7. Добавьте файлы типов components.d.ts и auto-imports.d.ts в include файла tsconfig.app.json и в .gitignore. Плагин сборки регистрирует компоненты и composables автоматически, как модуль в Nuxt, и создает эти файлы сам:

   {
     "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
   }
   

8. В paths файлов tsconfig.app.json и tsconfig.node.json пропишите алиас каталога, который создает плагин. Без алиаса не работает автодополнение темы:

   {
     "compilerOptions": {
       "paths": {
         "#build/b24ui": ["./node_modules/.b24ui-nuxt/b24ui"]
       }
     }
   }
   

Файлы типов появляются только после запуска Vite. Если проверка типов запускается в скрипте сборки раньше самой сборки, на чистом клоне она завершится ошибкой: сначала запустите dev-сервер или сборку, потом проверку типов.

Как проверить подключениеКак проверить подключение

Добавьте на страницу приложения кнопку:

<template>
  <B24Button>Кнопка</B24Button>
</template>

Запустите проект командой npm run dev и откройте страницу. Если библиотека подключена, кнопка отрисуется в оформлении Битрикс24.

Если кнопка выглядит как обычная кнопка браузера, стили не подключились. Проверьте импорт @bitrix24/b24ui-nuxt в CSS-файле проекта и путь к этому файлу: в проекте на Nuxt — в nuxt.config.ts, в проекте на Vite — в src/main.ts.

Дизайн-токены и иконкиДизайн-токены и иконки

Дизайн-токеныДизайн-токены

Токены входят в библиотеку: их подключает строка @import "@bitrix24/b24ui-nuxt" в CSS-файле проекта. Токены задают палитру Битрикс24 со светлой и темной темой, типографику, отступы, размеры и границы. В разметке они доступны как классы Tailwind CSS, писать CSS вручную не нужно. Переопределить значения можно директивой @theme в том же CSS-файле:

@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

@theme {
  --breakpoint-3xl: 1920px;
}

Токены не подключаются отдельно от сборки проекта: стили библиотеки собирают модуль Nuxt или плагин Vite. Документация библиотеки не описывает способ подключить только токены без Vue — установка описана для Nuxt и для Vue с Vite.

ИконкиИконки

Иконки поставляются отдельным пакетом @bitrix24/b24icons-vue. Это Vue-компоненты. Каждая иконка импортируется из отдельного файла:

<script setup>
import RocketIcon from '@bitrix24/b24icons-vue/main/RocketIcon'
</script>

<template>
  <B24Button :icon="RocketIcon">Кнопка</B24Button>
</template>

Все иконки и пути импорта опубликованы в каталоге иконок Битрикс24.

Продолжите изучениеПродолжите изучение

• Битрикс24 UI Kit: обзор
• Компоненты и шаблоны
• Принципы дизайна UI Kit Битрикс24
• Интеграция UI Kit с REST API и бизнес-логикой
• Каталог точек встраивания