TypeScript Vue.js Vueuse 빌드 시 발생한 타입에러 "error TS2304: Cannot find name 'BluetoothLEScanFilter'."

Vite, TypeScript, Vue.js, Vueuse 를 사용하는 프로젝트에서 로컬 빌드 시 발생한 타입에러

transforming (704) node_modules/.pnpm/axios@1.8.4/node_modules/axios/lib/helpers/isAbsoluteURL.jsnode_modules/.pnpm/@vueuse+core@13.0.0_vue@3.5.13_typescript@5.8.3_/node_modules/@vueuse/core/index.d.mts:627:15 - error TS2304: Cannot find name 'BluetoothLEScanFilter'.

627     filters?: BluetoothLEScanFilter[] | undefined;
                  ~~~~~~~~~~~~~~~~~~~~~

node_modules/.pnpm/@vueuse+core@13.0.0_vue@3.5.13_typescript@5.8.3_/node_modules/@vueuse/core/index.d.mts:635:24 - error TS2304: Cannot find name 'BluetoothServiceUUID'.

635     optionalServices?: BluetoothServiceUUID[] | undefined;
                           ~~~~~~~~~~~~~~~~~~~~

node_modules/.pnpm/@vueuse+core@13.0.0_vue@3.5.13_typescript@5.8.3_/node_modules/@vueuse/core/index.d.mts:658:24 - error TS2304: Cannot find name 'BluetoothDevice'.

658     device: ShallowRef<BluetoothDevice | undefined>;
                           ~~~~~~~~~~~~~~~

node_modules/.pnpm/@vueuse+core@13.0.0_vue@3.5.13_typescript@5.8.3_/node_modules/@vueuse/core/index.d.mts:660:24 - error TS2304: Cannot find name 'BluetoothRemoteGATTServer'.

660     server: ShallowRef<BluetoothRemoteGATTServer | undefined>;
                           ~~~~~~~~~~~~~~~~~~~~~~~~~


Found 4 errors.

 ELIFECYCLE  Command failed with exit code 1.
 ELIFECYCLE  Command failed.
ERROR: "type-check" exited with 1.
 ELIFECYCLE  Command failed with exit code 1.

프로젝트 내에서 useBluetooth를 사용하진 않지만, 빌드 시 전체를 타입 체크하는 과정에서 발생한 에러이다.

vueuse의 useBluetooth에서 Web Bluetooth API를 사용하고 있는데, TypeScript에서 이 타입들을 인식하지 못하여 발생한 것

• BluetoothLEScanFilter
• BluetoothServiceUUID
• BluetoothDevice
• BluetoothRemoteGATTServer

왜냐하면 이 타입들은 현재 TypeScript의 lib.dom.d.ts(DOM 타입 선언 파일)에 포함되어 있지 않기 때문이다.

/node_modules/@vueuse/core/index.d.mts 참조:

interface UseBluetoothRequestDeviceOptions {
    /**
     *
     * An array of BluetoothScanFilters. This filter consists of an array
     * of BluetoothServiceUUIDs, a name parameter, and a namePrefix parameter.
     *
     */
    filters?: BluetoothLEScanFilter[] | undefined;
    /**
     *
     * An array of BluetoothServiceUUIDs.
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/API/BluetoothRemoteGATTService/uuid
     *
     */
    optionalServices?: BluetoothServiceUUID[] | undefined;
}
interface UseBluetoothOptions extends UseBluetoothRequestDeviceOptions, ConfigurableNavigator {
    /**
     *
     * A boolean value indicating that the requesting script can accept all Bluetooth
     * devices. The default is false.
     *
     * !! This may result in a bunch of unrelated devices being shown
     * in the chooser and energy being wasted as there are no filters.
     *
     *
     * Use it with caution.
     *
     * @default false
     *
     */
    acceptAllDevices?: boolean;
}
declare function useBluetooth(options?: UseBluetoothOptions): UseBluetoothReturn;
interface UseBluetoothReturn {
    isSupported: ComputedRef<boolean>;
    isConnected: Readonly<ShallowRef<boolean>>;
    device: ShallowRef<BluetoothDevice | undefined>;
    requestDevice: () => Promise<void>;
    server: ShallowRef<BluetoothRemoteGATTServer | undefined>;
    error: ShallowRef<unknown | null>;
}

 

vueuse에서는 이렇게 선언하였으나, TypeScript lib.dom.d.ts에는 위에서 사용 중인 타입들이 포함되어 있지 않음
(lib.dom.d.ts: TypeScript가 브라우저 환경에서 사용하는 모든 전역 API 타입을 정의해놓은 파일)

(tsconfig.json의 lib의 기본값 중에 "DOM"이 포함돼 있는데 이 설정의 의미가 바로 lib.dom.d.ts를 포함해서 읽는다는 의미라고 함)

 

구글링을 통해 여러 방법을 찾아보았지만, 결국 임시로 직접 타입선언 하는 방식으로 해소하였다.

/types/bluetooth-polyfill.d.ts

// 빌드 시 타입 에러 해소를 위해 Web Bluetooth API 타입 수동 선언
interface BluetoothLEScanFilter {
  name?: string;
  namePrefix?: string;
  services?: BluetoothServiceUUID[];
}

type BluetoothServiceUUID = number | string;

interface BluetoothDevice {
  id: string;
  name?: string;
  gatt?: BluetoothRemoteGATTServer;
}

interface BluetoothRemoteGATTServer {
  device: BluetoothDevice;
  connected: boolean;
  connect(): Promise<BluetoothRemoteGATTServer>;
  disconnect(): void;
}

이 타입들을 참조한 곳:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/web-bluetooth/index.d.ts

DefinitelyTyped/types/web-bluetooth/index.d.ts at master · DefinitelyTyped/DefinitelyTyped

이 중에서 현재 빌드 에러가 발생하는 부분만 일부 가져옴

 

이제 타입스크립트가 BlueTooth 관련 타입을 잘 인식하여 빌드가 성공한다.