Интеграция Яндекс Карт 3.0 в React + Vite: решение ошибки TS2688

Разработчики, использующие стек React, Vite и TypeScript, нередко сталкиваются с проблемой при сборке продакшн-версии проекта с Яндекс Картами 3.0. Ошибка TS2688: Cannot find type definition file for 'modules' и аналогичная для 'packages' возникает из-за несоответствия в структуре типов библиотеки @yandex/ymaps3-types. В этой статье мы подробно разберём причины и дадим рабочие решения.

Почему возникает ошибка TS2688?

Проблема кроется в том, что в файле node_modules/@yandex/ymaps3-types/index.d.ts есть строки:

import "./modules/types";
import "./packages/types";

Однако в реальной файловой системе пакета эти пути ведут к несуществующим каталогам (обычно там находятся файлы modules.d.ts и packages.d.ts, а не подпапки). TypeScript пытается найти файлы по этим путям, но находит только корневые точки входа, что и вызывает ошибку при компиляции.

Как исправить: 3 проверенных способа

Способ 1: Перенос файлов вручную (временный)

Этот метод упоминается в исходном вопросе и действительно работает, но неудобен при обновлении пакета. Необходимо создать каталоги modules и packages внутри @yandex/ymaps3-types и переместить туда соответствующие .d.ts файлы. После этого ошибка исчезает, но при каждом обновлении пакета операцию придётся повторять.

Способ 2: Использование paths в tsconfig.json

Более правильный подход - перенаправить пути импорта, не изменяя node_modules. Добавьте в tsconfig.json следующий блок:

"compilerOptions": {
  "paths": {
    "@yandex/ymaps3-types/modules/*": ["./node_modules/@yandex/ymaps3-types/types/*"],
    "@yandex/ymaps3-types/packages/*": ["./node_modules/@yandex/ymaps3-types/types/*"]
  }
}

Но этот способ не всегда срабатывает из-за особенностей разрешения типов в Vite.

Способ 3: Обновление typeRoots (рекомендуется)

Самый надёжный вариант - настроить typeRoots так, чтобы TypeScript искал типы в правильном порядке. Вместо того чтобы указывать конкретный путь к @yandex/ymaps3-types, оставьте только стандартные пути, но добавьте исключение для дублирующих типов. Пример конфигурации:

"typeRoots": [
  "./node_modules/@types",
  "./node_modules/@yandex/ymaps3-types"
]

Если это не помогает, попробуйте временно отключить typeRoots и использовать types: [], а типизацию для Яндекс Карт подключать через отдельный файл env.d.ts:

/// <reference types="@yandex/ymaps3-types" />

Это позволит избежать конфликта путей, сохранив автодополнение.

Дополнительные советы по настройке

• Очистка кэша: После изменений в tsconfig.json обязательно удалите node_modules/.vite и перезапустите сервер.
• Версия пакета: Убедитесь, что вы используете актуальную версию @yandex/ymaps3-types (проверьте на npm).
• Альтернатива: Рассмотрите использование Яндекс Карт 2.1, если версия 3.0 не критична - она имеет более стабильную поддержку TypeScript.

Заключение

Ошибка TS2688 при сборке Яндекс Карт 3.0 в проектах на React + Vite вызвана несоответствием путей в декларациях типов. Наиболее практичное решение - обойти проблему через typeRoots или ручное реферирование типов в env.d.ts. Если баг сохраняется, сообщите о нём в репозиторий Яндекс Карт - это поможет ускорить исправление.