React에서 Swiper Element 사용 시 TypeScript 에러 해결하기

스와이퍼 리액트 페이지에 들어가보면 가장 먼저 눈에 띄는 문구가 있다.

Swiper React components will likely to be removed in future versions. It is recommended to migrate to Swiper Element instead.
If you are upgrading from Swiper 8 to Swiper 9, check out Migration Guide to Swiper 9
If you are looking for v8 docs, they are here v8.swiperjs.com

스와이퍼 리액트 컴포넌트는 향후 버전에서 제거될 가능성이 있으니, 웹 컴포넌트로 만든 스와이퍼 엘리먼트로 마이그레이션하라는 것이다. 빨간색 배경에다가 강조하는 듯한 느낌까지 들어서 리액트 컴포넌트로 구현했다가는 괜히 문제가 생길 것 같고..찝찝해서 나중을 위해 권고 사항을 따르기로 했다.

 

전에 한번 써보기도 했고, Usage with React 섹션도 있어서 천천히 보다보면 금방 사용을 할 수 있었다. 문제는 타입스크립트도 같이 사용할 때 곳곳에서 에러가 난다는 것이다. 이와 관련된 예시는 공식 문서에서 찾을 수 없었다. 일단 useRef에서 나타나는 에러는 SwiperContainer 인터페이스를 불러와서 해결할 수 있다.

const swiperElRef = useRef<SwiperContainer>(null);

가장 헤맸던 부분이 웹 컴포넌트에 대한 타입 정의였다. 에러 내용을 보면 "'JSX.IntrinsicElements' 형식에 'swiper-container' 속성이 없습니다."라는 것을 확인할 수 있는데, 이것은 swiper-container와 같은 사용자 정의 태그가 해당 형식에 포함되어 있지 않다는 것을 뜻한다. 확인해 보니 아직은 라이브러리에서 직접 제공하진 않고, 그때까지는 타입을 직접 정의해 주어야 한다.

 

이를 위해, 프로젝트의 루트 디렉토리에 전역 타입 선언 파일을 만들고 스와이퍼 관련 태그들을 정의해 준다.(파일 이름은 .d.ts 확장자로 끝나야 한다.)

// 📂 swiper.d.ts

import React from 'react';

import type { SwiperSlideProps, SwiperProps } from 'swiper/react';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'swiper-container': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & SwiperProps,
        HTMLElement
      >;
      'swiper-slide': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & SwiperSlideProps,
        HTMLElement
      >;
    }
  }
}

이제 tsconfig.json에서 해당 정의에 대한 경로를 포함하도록 include를 추가해 준다.

// 📂 tsconfig.json

{
  "compilerOptions": {
   ...
  },
  "include": ["src", "swiper.d.ts"]
}

이렇게 하면 JSX 관련 에러 문구가 사라지고, 코드 자동 완성(intellisense) 기능이 제공된다.

참고

Swiper Element (WebComponent) - swiper
Provide Typescript definition for Element - GitHub swiper issues
Consuming a Web Component in React in Typescript - goulet.dev
How to use Web Components with TypeScript and React - coryrylan