Vue и TypeScript: как регистрировать глобальные компоненты

Короткий ответ: глобальные компоненты во Vue 3 регистрируют через app.component() до вызова app.mount(). В TypeScript важно дополнительно настроить типы .vue файлов и, если нужно, объявить глобальные компоненты для подсказок редактора. Но для индексации поисковиками сама глобальная регистрация почти ничего не решает: индексация зависит от того, появляется ли контент в HTML, SSR/SSG, роутинга и доступности страницы

Минимальный пример:

import { createApp } from "vue";
import App from "./App.vue";
import BaseButton from "./components/BaseButton.vue";

const app = createApp(App);

app.component("BaseButton", BaseButton);

app.mount("#app");

Теперь <BaseButton /> можно использовать в шаблонах компонентов внутри этого Vue-приложения

Где регистрировать компоненты

Регистрируйте глобальные компоненты в main.ts, до mount:

const app = createApp(App);

app.component("BaseIcon", BaseIcon);
app.component("BaseModal", BaseModal);
app.component("BaseButton", BaseButton);

app.mount("#app");

Если вызвать app.component() после mount, проект может вести себя непредсказуемо: компонент уже нужен шаблону, а регистрация произошла слишком поздно

Когда глобальная регистрация уместна

Глобально удобно регистрировать базовые UI-компоненты:

• BaseButton;
• BaseIcon;
• BaseInput;
• BaseModal;
• AppLink.

Но не стоит регистрировать глобально весь проект. Vue-документация прямо предупреждает о минусах: глобальная регистрация ухудшает tree-shaking и делает зависимости менее явными. Иначе говоря, сборщику сложнее выкинуть неиспользуемое, а разработчику сложнее понять, откуда компонент взялся

Типы для .vue файлов

Если TypeScript не понимает импорт .vue, добавьте декларацию, например src/env.d.ts:

declare module "*.vue" {
  import type { DefineComponent } from "vue";

  const component: DefineComponent<object, object, unknown>;
  export default component;
}

В проектах Vite + Vue этот файл часто создается шаблоном автоматически. Но если проект собран вручную, без декларации TypeScript может показать ошибку:

Cannot find module './App.vue'

Глобальные компоненты и автоподсказки

Если компонент зарегистрирован глобально, приложение может работать, но редактор не всегда хорошо подсказывает его в шаблонах. Для ручной декларации можно расширить GlobalComponents:

import BaseButton from "./components/BaseButton.vue";

declare module "vue" {
  export interface GlobalComponents {
    BaseButton: typeof BaseButton;
  }
}

Так TypeScript и tooling лучше понимают, что <BaseButton /> существует

Что здесь с индексацией

Фраза “для индексации” в этом запросе может означать две разные вещи

Первое — индексация поисковиками. Тогда глобальная регистрация компонентов сама по себе не помогает. Поисковику важнее, чтобы страница отдавала доступный контент, имела нормальные адрес, заголовки, текст, canonical и не прятала важное за поздней клиентской загрузкой. Для SEO во Vue часто смотрят в сторону SSR или SSG

Второе — “индексация” внутри редактора или проекта: чтобы компоненты находились, подсказывались и корректно типизировались. Тогда помогают .d.ts, GlobalComponents, понятные имена и единое место регистрации

Частые ошибки

Первая ошибка — регистрировать компоненты после app.mount(). Делайте это до монтирования

Вторая ошибка — глобально регистрировать все подряд. Для страниц и крупных блоков чаще лучше локальный импорт

Третья ошибка — путать имя файла и имя компонента. Если зарегистрировали app.component("BaseButton", BaseButton), в шаблоне используйте <BaseButton />

Четвертая ошибка — считать, что глобальная регистрация решит SEO. Она решает доступность компонента в Vue-приложении, а не то, как поисковик видит страницу

Самопроверка

Создайте BaseButton.vue, зарегистрируйте его в main.ts, вставьте <BaseButton /> в App.vue и запустите проект. Затем временно удалите регистрацию. Если Vue сообщает, что компонент не найден, значит вы проверили именно глобальную регистрацию

После этого добавьте декларацию GlobalComponents и проверьте, появились ли подсказки редактора

Что почитать дальше по TypeScript

Если нужен общий маршрут по теме, откройте рубрику TypeScript. Для соседних задач пригодятся эти разборы:

• 10 вопросов по TypeScript и ответы на них
• Any, unknown, never и strict
• App.tsx: что это за файл и как добавить TypeScript в React
• Conditional types в TypeScript: как работает extends