[SvelteKit] Markdown 체크리스트 적용기: markdown-it-task-lists

| 서론

안녕하세요! 팡일입니다.

프로젝트에서 마크다운을 렌더링하는 기능을 만들다 보면, 체크박스(To-do 리스트)가 필요해지는 순간이 한 번쯤은 찾아옵니다. 리로그(Re-Log)도 마찬가지였습니다. 사용자들이 회고를 작성할 때, 작업 목록을 체크할 수 있으면 더 편리하겠다는 생각이 들어 markdown-it-task-lists 플러그인을 도입해보았습니다.

| 패키지 설치

현재 프로젝트에서는 기본 마크다운 렌더러로 markdown-it를 사용하고 있었습니다. 여기에 체크박스 기능을 추가하기 위해 아래 패키지를 설치했습니다.

npm install markdown-it-task-lists

그리고 렌더러 설정에 플러그인을 적용했습니다.

import MarkdownIt from 'markdown-it';
import taskLists from 'markdown-it-task-lists';

const md = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true
}).use(taskLists);

export function renderMarkdown(markdown: string): string {
  return md.render(markdown);
}

여기까지는 순조로웠습니다. 브라우저에서 테스트했을 때도 체크박스가 잘 렌더링되었습니다.

| 갑자기 등장한 TypeScript 오류

하지만 npm run check를 실행하자마자 오류가 발생했습니다.

모듈 'markdown-it-task-lists'에 대한 선언 파일을 찾을 수 없습니다.
암시적으로 'any' 형식이 포함됩니다.
해당 항목이 있는 경우 '@types/markdown-it-task-lists' 설치를 시도하거나,
'declare module "markdown-it-task-lists";'을 포함하는 .d.ts 파일을 추가하세요.

요약하자면 이렇게 말하는 것이었습니다.

-> “이 모듈은 타입 정의가 없는데요? any로 처리해야 해요.”

| 문제 원인: JS-only 패키지

알고 보니 markdown-it-task-lists는 순수 자바스크립트로 작성된 플러그인이었습니다. 타입 선언 파일(.d.ts)을 제공하지도 않고, DefinitelyTyped(@types)에도 등록되어 있지 않더군요.

따라서 TypeScript 입장에서는 “이 모듈의 타입을 도저히 모르겠다…” 라고 판단해 오류를 띄운 것이었습니다.

| 해결 방법: 선언 파일 수동 추가

이런 경우에는 타입을 직접 알려주는 방식이 가장 깔끔합니다. 저는 프로젝트에 /src/types/ 폴더를 만들고 아래 파일을 추가했습니다.

1) src/types/markdown-it-task-lists.d.ts

declare module 'markdown-it-task-lists';

이 한 줄이면 충분합니다. TypeScript는 이 모듈을 any 기반으로 처리하고, 더 이상 타입 오류를 발생시키지 않습니다. npm run check도 정상적으로 통과했습니다.

| 느낀 점

SvelteKit + TypeScript 조합에서는 이처럼 타입 정의가 없는 외부 JS 패키지와 마주치는 일이 자주 생깁니다.

이번 경험을 통해 타입 선언이 없는 패키지에서 왜 오류가 발생하는지, 어떻게 선언 파일을 만들어 해결하는지, TypeScript의 타입 안전성 원리가 무엇인지 다시 한 번 익힐 수 있는 시간이었습니다. 체크리스트 기능 자체는 아주 간단했지만, 그 과정에서 만나는 트러블슈팅은 결국 프로젝트 전체의 품질을 높여주는 좋은 경험이라고 느꼈습니다.