React 프로젝트에 TSRX를 조용히 얹어보는 방법

React 환경이 지겨워서 TypeScript Render Extensions(TSRX)에 눈독을 들이는 개발자가 늘었습니다. 문법이 깔끔하고 제어 흐름이 직관적이라는 소문은 자자하지만, 막상 실무 프로덕션에 도입하려니 겁부터 납니다. 멀쩡히 돌아가는 Vite나 Webpack 빌드 시스템이 깨지면 복구하느라 밤을 새워야 하고, 팀원들에게 도입하자고 설득할 정량적인 근거도 부족하기 때문입니다.

동작하는 파일럿 환경을 구축하고 안전하게 마이그레이션하는 구체적인 실무 설정법을 정리했습니다.

---

기존 빌드 도구에 TSRX 컴파일러 통합하기

Vite 기반의 React 프로젝트에 @tsrx/vite-plugin을 붙여서 .tsrx 확장자를 컴파일러가 인식하도록 빌드 파이프라인을 수정해야 합니다.

Vite 환경 설정

먼저 프로젝트 루트 폴더에서 패키지를 설치합니다.

npm install --save-dev @tsrx/vite-plugin

vite.config.ts 파일을 열고 플러그인을 불러옵니다.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { tsrxPlugin } from '@tsrx/vite-plugin';

export default defineConfig({
  plugins: [
    tsrxPlugin(),
    react()
  ]
});

plugins 배열 안에서 기존 react() 플러그인보다 앞선 순서에 tsrxPlugin()을 넣는 것이 핵심입니다. TSRX 문법이 표준 JSX로 먼저 변환되어야 에러 없이 컴파일 단계를 통과합니다.

TypeScript 호환성 확보

TypeScript 컴파일러(tsc)가 파일 확장자와 신규 키워드를 이해하지 못하면 빨간 줄이 도배됩니다. 에디터 에러를 잡기 위해 src 폴더 안에 tsrx-env.d.ts 파일을 만들고 아래 코드를 채워 넣습니다.

declare module '@tsrx/core';

그다음 tsconfig.json 파일의 include 항목에 .tsrx 경로를 포함합니다.

{
  "compilerOptions": {
    "jsxImportSource": "@tsrx/runtime"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.tsrx"]
}

설정을 마치면 VS Code 에디터가 수정한 구문을 정상적으로 읽기 시작합니다.

Webpack 5 환경 패치

오래된 대형 프로젝트나 Webpack 환경을 고수하는 코드베이스라면 Babel 로더에 프리셋을 직접 주입합니다.

npm install --save-dev @tsrx/babel-preset

webpack.config.js 파일의 Babel 설정을 찾아 프리셋을 추가합니다.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx|tsrx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              '@babel/preset-typescript',
              '@tsrx/babel-preset'
            ]
          }
        }
      }
    ]
  }
};

모듈 페더레이션 아키텍처를 쓰는 구조에서도 이 패치를 적용하면 공통 React 의존성이 꼬이는 현상을 막을 수 있습니다.

---

점진적 마이그레이션을 위한 컴포넌트 선정 기준

프로덕션 전체를 한 번에 바꾸는 짓은 자살 행위입니다. 가독성은 엉망인데 의존성이 적어서 고장 나도 타격이 적은 구석진 컴포넌트부터 노려야 합니다.

평가 지표	고점 (전환 대상)	저점 (도입 보류)
조건부 렌더링	3단계 중첩 삼항 연산자 도배	단순 노출 여부 분기
반복 로직	복잡한 Key 연산과 중첩 map 함수	단순 리스트 렌더링
의존성 구조	순수 React UI 컴포넌트	외부 라이브러리와 차트 연동
장애 영향도	어드민 화면의 특정 통계 카드	결제 및 본인 인증 핵심 로직

선정한 컴포넌트는 다음 절차에 맞춰서 안전하게 변환합니다.

1단계: 병렬 파일 생성

기존 UserInfo.tsx 파일을 두고, 동일한 경로에 UserInfo.tsrx 파일을 만듭니다. 빌드 시스템이 꼬였을 때 확장자만 갈아끼워 롤백하기 위함입니다.

2단계: 선언문 수정

컴포넌트 선언부를 TSRX 지시어로 교체합니다.

// 기존
const UserInfo = () => { ... }

// 변경
component UserInfo() { ... }

3단계: 제어 구문 치환

중첩 삼항 연산자와 map 함수를 직관적인 if 조건문과 for...of 루프로 변경합니다. 가독성이 즉시 올라갑니다.

테스트 코드 보존

내부 코드를 바꿨다고 테스트가 터지면 마이그레이션을 진행할 수 없습니다. Jest 환경이라면 jest.config.js를 수정해 파일 확장자를 바르게 추적하도록 설정합니다.

module.exports = {
  transform: {
    "^.+\\.(ts|tsx|tsrx)$": "ts-jest",
  },
  moduleFileExtensions: ["js", "jsx", "ts", "tsx", "tsrx", "json"]
};

이 세팅이 끝나면 내부 구현을 완전하게 뜯어고쳐도 기존 테스트 코드가 정상 작동합니다.

---

실무 도입 타당성을 입증할 성능 벤치마크 설계

기술 도입의 키를 쥔 결정권자나 아키텍트를 설득하려면 정량적인 수치가 담긴 보고서가 필요합니다. 보기 예쁘다는 이유만으로는 설득할 수 없습니다.

Rollup 번들 크기 측정

추가되는 런타임 라이브러리가 전체 번들 용량을 얼마나 늘리는지 시각적으로 증명해야 합니다. rollup-plugin-visualizer를 연동합니다.

npm install --save-dev rollup-plugin-visualizer

Vite 설정 파일에 시각화 도구를 추가합니다.

import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    tsrxPlugin(),
    react(),
    visualizer({ filename: 'bundle-analysis.html' })
  ]
});

npm run build를 실행하면 루트 경로에 bundle-analysis.html이 떨어집니다. 브라우저로 파일을 열어 TSRX 헬퍼 함수가 차지하는 순수 바이트 크기를 확인합니다. 불필요한 의존성 없이 트리 쉐이킹이 잘 작동하는지 눈으로 확인할 수 있는 가장 확실한 지표가 됩니다.

브라우저 렌더링 성능 프로파일링

TSRX는 인라인 익명 콜백 함수 생성을 억제하도록 설계되었습니다. 대규모 목록 화면에서 이 특성이 메모리 절약에 얼마나 기여하는지 입증하면 도입 설득이 쉬워집니다.

Chrome 개발자 도구의 Performance 탭을 열고 Memory 옵션을 활성화합니다. 동일한 목록 화면에서 스크롤을 끝까지 내리며 데이터를 불러올 때 가비지 컬렉션(GC) 빈도와 힙 메모리 점유율을 추적합니다. 수집한 타임라인 데이터를 정리해 마이그레이션 전후의 가비지 컬렉션 발생 횟수 감소 폭을 비교 보고서에 수치로 기재합니다.