TypeScript와 Rollup으로 해결하는 패키지 빌드 문제

들어가며

안녕하세요. 노머스에서 백엔드 개발을 하고 있는 지승보입니다.

저희 팀은 TypeScript를 주 언어로 사용하고 있으며, 프로젝트의 구조를 효율적으로 관리하기 위해 모노레포를 활용하고 있습니다. 또한, 백엔드와 프론트엔드 간 데이터 구조를 공유하기 위해 API DTO(Data Transfer Object) 를 NPM 패키지 형태로 관리하고 있습니다. 이 과정에서 발생한 문제점을 해결하기 위해 Rollup을 도입하게 되었고, 이번 글에서는 저희가 어떤 과정을 거쳐 문제를 해결했는지 공유하고자 합니다.

문제 상황과 해결 방안

문제상황 발생

저희는 packages 워크스페이스에서 백엔드와 프론트엔드가 공유하는 타입과 유틸리티 함수들을 관리하고 있었습니다. 백엔드에서는 이러한 타입들을 유틸리티를 통해 유연하게 조작하여 사용하고 있었고, 이는 자연스럽게 DTO에도 적용되었습니다.

하지만 실제 프로젝트를 운영하면서 예상치 못한 문제가 발생했습니다. 백엔드에서 packages 워크스페이스의 타입을 활용해 다음과 같이 DTO를 작성했을 때였습니다:

// 백엔드의 DTO 코드
import { PostType } from '@packages/types';

// @packages/types 에 정의된 enum
enum PostType {
  LiveRecord = 'live_record',
  Video = 'video',
  ...
}

export class SomeDto {
  ...
  type: Exclude<PostType, PostType.LiveRecord>;  // PostType에서 LiveRecord를 제외
}

이 DTO를 npm 패키지로 빌드하여 프론트엔드에 제공했을 때, 겉으로 보기에는 동일한 코드가 생성되었습니다:

// 프론트엔드에 설치된 패키지의 코드
import { PostType } from '@packages/types';

export class SomeDto {
  ...
  type: Exclude<PostType, PostType.LiveRecord>;
}

하지만 프론트엔드에서는 이 패키지를 사용할 때마다 타입 에러가 발생했습니다. 당시 빌드 프로세스는 다음과 같았습니다:

nest build && tsc-alias

이 빌드 과정을 거치면 다음과 같은 결과물이 생성되었습니다:

import { PostType } from '@packages/types';

export class SomeDto {
  id: string;
  age: number;
  name: string;
  type: PostType;
}

문제를 자세히 분석해보니, 두 가지 핵심적인 이슈가 있었습니다. 첫째로, 빌드된 패키지에 백엔드의 공용 타입 정의가 함께 포함되지 않았습니다. 이로 인해 프론트엔드에서는 @packages/types의 PostType enum을 찾을 수 없었고, type 필드는 실질적으로 any 타입처럼 동작했습니다.

둘째로, 더 심각한 문제는 타입 조작과 관련이 있었습니다. 프론트엔드에 존재하지 않는 PostType enum을 Exclude로 조작하려 시도하다 보니, TypeScript는 이를 never 타입으로 추론했습니다. 결과적으로 프론트엔드에서는 type 필드에 어떤 값도 할당할 수 없는 상황이 발생했습니다.

문제 제보 슬랙

이러한 타입 불일치 문제는 그동안 단순한 타입만 사용할 때는 발견되지 않다가, 타입 유틸리티를 활용하면서 비로소 드러나게 되었습니다.

해결방안 모색

1. packages 워크스페이스도 Publish 하여 프론트엔드에서 사용
2. Swagger 사용
3. DTO에서 사용하는 백엔드 공용 타입을 빌드 결과물에 포함 (선택)

1. packages 워크스페이스도 Publish 하여 프론트엔드에서 사용

이 방법에는 다음과 같은 문제점이 있었습니다. packages는 백엔드 팀원 모두가 사용하고 수시로 수정될 수 있기 때문에, 다음과 같은 상황에서 변경사항 간 충돌이 발생할 수 있습니다:

1. 팀원 A가 패키지를 수정하고 빌드 후 Publish
2. 팀원 B가 패키지를 수정하고 빌드 후 Publish

이 경우, 팀원 A의 변경사항을 사용하는 프론트엔드는 팀원 B의 Publish로 인해 예기치 않게 빌드 결과물이 변경될 수 있습니다. 또한 packages 워크스페이스에는 백엔드에서만 사용하는 유틸리티 함수들도 포함되어 있어, 이를 프론트엔드에 노출시키는 것은 바람직하지 않았습니다.

2. Swagger 사용

Swagger는 API 문서화와 타입 정의를 자동으로 생성해주는 유용한 도구입니다. 하지만 다음과 같은 이유로 Swagger로의 전환을 보류했습니다:

1. 기존 코드베이스의 변경이 필요

• 기존 코드베이스에 Swagger 데코레이터가 정확하게 적용되어 있지 않았습니다.

2. 프론트엔드에서도 Swagger 스펙을 API로 전환하는 작업이 필요했습니다.

3. DTO에서 사용하는 백엔드 공용 타입을 빌드 결과물에 포함

이 방법이 저희 팀의 상황에 가장 적합한 해결책으로 판단되었습니다. 주요 장점은 다음과 같습니다:

1. 최소한의 코드 변경

• 기존 코드베이스를 크게 수정할 필요가 없습니다.
• 빌드 설정만 변경하면 되므로 리스크가 적습니다.

2. 타입 안정성 보장

• 백엔드의 실제 타입이 그대로 프론트엔드에 전달됩니다.
• 타입 불일치로 인한 런타임 에러를 방지할 수 있습니다.

3. 필요한 타입만 선택적 포함

• DTO에서 실제로 사용되는 타입만 빌드 결과물에 포함됩니다.
• 불필요한 코드 노출을 방지할 수 있습니다.

Rollup과 rollup-plugin-dts 도입

저희는 다음과 같은 이유로 Rollup과 rollup-plugin-dts 플러그인을 도입했습니다:

1. 효율적인 Tree-shaking

• Rollup은 ES 모듈을 기반으로 정적 분석을 수행하여 사용되지 않는 코드를 제거합니다.
• 특히 타입 정의에서 실제 사용되는 타입만 포함하므로, 불필요한 타입이 번들에 포함되는 것을 방지할 수 있습니다.

2. 타입 정의 파일 최적화

• rollup-plugin-dts를 사용하면 여러 타입 정의 파일들을 하나의 index.d.ts 파일로 번들링할 수 있습니다.
• 다른 파일에서 참조하는 타입들을 모두 인라인으로 포함시켜 하나의 파일에서 모든 타입 정보를 확인할 수 있습니다.

예시:

// 기존: 여러 파일에 분산된 타입들
// types/user.d.ts
declare interface User { ... }
// types/post.d.ts  
declare interface Post { ... }

// 번들링 후: index.d.ts
declare interface User { ... }
declare interface Post { ... }

Rollup 적용 과정

1. 패키지 설치

yarn workspace add [workspace_name] rollup rollup-plugin-dts rollup-plugin-typescript-paths

각 패키지의 역할:

• rollup: JavaScript 모듈 번들러
• rollup-plugin-dts: 타입 정의 파일(.d.ts)을 하나로 번들링
• rollup-plugin-typescript-paths: TypeScript 경로 별칭(path alias) 처리

2. Rollup 설정 파일 생성

워크스페이스 루트에 rollup.config.js 파일을 생성합니다:

const path = require('path');
const { dts } = require('rollup-plugin-dts');
const { typescriptPaths } = require('rollup-plugin-typescript-paths');

module.exports = {
    input: 'index.ts',                        // TypeScript로 컴파일된 d.ts 파일들의 진입점
    output: {
        file: 'publish/dist/index.d.ts',      // 최종 번들링된 타입 선언 파일 경로
        format: 'es'                          // ES Module 형식으로 번들링
    },
    plugins: [
        typescriptPaths({ preserveExtensions: true }),  // TypeScript paths 별칭 해석
        dts({
            respectExternal: true,            // 외부 패키지의 타입 선언을 유지
            compilerOptions: {
                baseUrl: path.resolve(__dirname)  // TypeScript 설정의 baseUrl과 동일하게 설정
            }
        })
    ]
};

3. 빌드 명령어

"scripts": {
  "build": "rollup -c rollup.config.js"
}

4. 빌드 결과물 확인

publish/dist/index.d.ts 파일을 확인해보면 모든 타입이 하나의 파일로 번들링되어 있음을 확인할 수 있습니다.

// 번들링 결과물
declare enum PostType { 
  LiveRecord = 'live_record',
  Video = 'video',
  ...
}

declare class SomeDto {
  ...
  type: Exclude<PostType, PostType.LiveRecord>;
}

이처럼 Rollup을 통해 빌드된 결과물에는 PostType enum이 함께 포함되어, 프론트엔드에서도 타입 유틸리티를 활용한 타입 조작이 가능해졌습니다.

문제 해결 슬랙

결론

Rollup과 rollup-plugin-dts를 도입하면서 우리가 겪었던 타입 관련 문제들을 해결할 수 있었습니다. 구체적으로 다음과 같은 부분들이 개선되었습니다:

1. 타입 정의 문제 해결

• 백엔드의 타입이 프론트엔드 패키지에 올바르게 포함됨
• 타입 유틸리티(Exclude, Pick 등)를 사용해도 예상한 대로 동작
• 프론트엔드에서 타입 에러가 정확하게 표시됨

2. 개발 생산성 향상

• IDE에서 타입 기반 자동완성 지원
• 컴파일 타임에 타입 오류 감지
• 명확한 타입 정보로 인한 디버깅 용이성 증가

이러한 개선을 통해 백엔드와 프론트엔드 사이의 타입 공유가 더욱 안정적으로 이루어지게 되었습니다. 특히 타입스크립트의 타입 조작 기능들을 의도한 대로 사용할 수 있게 된 점이 가장 큰 이점이었습니다.

읽어주셔서 감사합니다.