circular-progress-bar 라이브러리 간단 개조

react-circular-progress-bar

alptugidin • Updated Oct 6, 2025

문제상황.

프로젝트에서 해당 라이브러리를 사용하는 중에 있는데, 드랍 셰도우 제거 등

해당 라이브러리의 세세한 스타일 등을 변경해야하는 상황이 생겼습니다.

해당 라이브러리에서는 지원하지 않는 기능이기 때문에,

해당 프로젝트를 fork 후 npm에 수정버전을 업로드 하여 프로젝트에 적용했습니다. 문제를 해결하기는 한듯 싶었으나…

react-circular-progress-bar

Lamyzm • Updated May 27, 2024

해당라이브러리를 그대로 빌드해서 배포했는데

동작 자체는 정상적으로 작동하나 아래와 같이 vscode에서 내 라이브러리의 경로를 잡지 못하는 문제가 발생했습니다.

건든것은 스타일과 간단한 props 수정사항밖에없었는데 어째서…? 동작도 제대로하는데?

문제를 해결하기 위해 찬찬히 코드를 살펴보았습니다.

이 프로젝트는 vite를 사용해서 빌드하고 있었고 tsup이라는 라이브러리를 사용하고 있었습니다.

여기서 TSUP이란?

TSUP: TypeScript 를 위한 번들러

TSUP은 TypeScript 라이브러리의 번들링을 위한 도구로, 복잡한 설정 없이도 간편하게 사용할 수 있는 컨셉의 번들러 입니다. Go 언어로 개발되어 굉장히 빠른 속도를 자랑하는 esbuild에 의해 구동됩니다.

TSUP의 주요 특징 중 하나는 별도의 플러그인 설치 없이도 TypeScript를 CommonJS와 ESM 형식의 JavaScript로 컴파일 할 수 있고, 타입 정의 파일도 자동으로 생성됩니다. 이는 아직 다른 번들러 에서 제공하지 않는 기능이며, TSUP는 이러한 기능을 기본적으로 제공합니다.

더불어, esbuild의 기본적인 트리 쉐이킹(tree-shaking) 기능 덕분에 TSUP은 불필요한 코드 없이 최적화된 번들을 생성합니다. 또한, 코드의 Minify(최소화)도 지원하여 프로덕션 준비 과정을 간소화합니다.

‣

타입스크립트 컴파일러는 진짜 컴파일만 해주기 때문에 위와같은 번들러를 사용해서 트리셰이킹 등 여러 유틸성을 제공받는듯 하다.

여기서 dts 옵션은 tsconfig의 declaration 설정과 관계가 있는데

tsconfig의 declaration 설정

tsconfig.json 파일에서 declaration 옵션은 TypeScript 컴파일러가 .d.ts 타입 선언 파일을 생성할지 여부를 결정합니다. 다음과 같이 설정할 수 있습니다:



{
  "compilerOptions": {
    "declaration": true}
}

이 설정을 활성화하면 TypeScript는 컴파일 시 타입 선언 파일을 생성합니다. 외부에서 라이브러리를 사용할 때 타입 정보를 제공하기 위해 사용한다고 합니다.

tsup의 dts 옵션

tsup은 TypeScript 프로젝트를 빌드하는 데 사용되는 도구입니다. dts 옵션은 tsup이 타입 선언 파일을 생성하도록 지시합니다. 이 옵션을 사용하면 타입 선언 파일을 자동으로 생성할 수 있어 타입 정보를 제공할 수 있습니다.

원래 vite.config.ts 설정


import { defineConfig } from 'tsup';
export default defineConfig({
   entry: ['./lib/index.ts'],
   format: ['cjs', 'esm'],
   dts: { entry: { index: './lib/types.d.ts' } }, // 문제 발생 부분
   minify: true,
   clean: true,
   outExtension({ format }) {
      return format === 'esm' ? { js: `.${format}.js` } : { js: '.js' };
   },
})

dts: { entry: { index: './lib/types.d.ts' } } 특정 파일에서 타입 선언 파일을 생성하도록 지정합니다.

수정된 설정


import { defineConfig } from 'tsup';
export default defineConfig({
   entry: ['./lib/index.ts'],
   format: ['cjs', 'esm'],
   dts: true, // <= 수정된 부분!
   minify: true,
   clean: true,
   outExtension({ format }) {
      return format === 'esm' ? { js: `.${format}.js` } : { js: '.js' };
   },
});

여기서는 dts: true로 설정되어 있어, tsup이 자동으로 타입 선언 파일을 생성하도록 합니다.

타입 설정부분에서 문제가 발생하여 해당 부분을 번들러에게 맡겼더니 문제 자체는 해결되었다.

하지만 해당 문제가 왜 해결되었는지는 이해가 잘 되지 않아 조금더 찾아보았다.

빌드 후 type.d.ts를 확인하니

원래는 기존 빌드시 그냥 export로 내보내고 있었으나

변경후 빌드하니 아래처럼 declare 와 react.FC로 해당 컴포넌트의 타입을 정의해서 내보내고 있었다.

해당 부분에 대해서 멘토님께 문의해본 결과 라이브러리를 배포할때는 단순타입이 아니라 React 컴포넌트의 타입을 설정해주어야 한다는 답변을 받았습니다.

해당 추가된 부분의 의미는

declare Flat, Heat, Nested라는 컴포넌트가 있으며, 각각의 타입의 props를 받는 React 함수형 컴포넌트임을 TypeScript에게 알려줍니다.

해당 부분이 추가되면서 타입 자체를 내보내면서 경로충돌이 발생한 부분이 해결되었습니다.