개발을 시작한 지 얼마 안 된 분들이나 프로젝트를 새로 셋업하다 보면 .ts와 .tsx 확장자가 헷갈리는 순간이 옵니다. 결론부터 말하면, .ts는 JSX 문법 없이 TypeScript만 사용하는 파일이고, .tsx는 React 컴포넌트처럼 JSX 문법을 사용할 때 쓰는 확장자입니다. 단순해 보이지만 이 차이를 모르고 파일을 만들면 컴파일 에러를 마주하게 됩니다. 이 글에서는 두 확장자의 용도와 실전에서 헷갈리지 않게 구분하는 팁을 정리해 봤습니다.
.ts와 .tsx, 도대체 뭐가 다른 걸까
TypeScript는 JavaScript에 정적 타입을 추가한 언어입니다. 여기서 .ts는 TypeScript 코드만 포함하는 기본 확장자입니다. 서버 코드(Node.js + Express), 유틸리티 함수, 타입 정의 파일, API 클라이언트 등 React와 무관한 모든 TypeScript 파일이 여기에 해당합니다.
반면 .tsx는 TypeScript 파일 안에 JSX(JavaScript XML) 문법이 포함될 수 있다는 뜻입니다. JSX는 React에서 UI를 선언적으로 작성하기 위해 사용하는 문법으로, JavaScript 안에 HTML 태그를 섞어 쓰는 방식입니다. React 컴포넌트를 만들 때 return <div>...</div> 같은 코드가 필요한데, 이 코드가 들어간 파일은 반드시 .tsx 확장자를 써야 합니다.
가장 큰 차이는 JSX 문법 허용 여부입니다. .ts 파일에 JSX를 쓰면 TypeScript 컴파일러가 바로 에러를 뱉습니다. 반대로 .tsx 파일에는 순수 TypeScript 로직만 작성해도 문제없습니다. 다만 타입 정의 파일(.d.ts)은 예외적으로 JSX를 사용할 수 없는 특수한 경우입니다.
실제 프로젝트에서 확장자 선택이 헷갈리는 순간
Next.js나 Vite로 프로젝트를 구성하다 보면 확장자 선택이 고민될 때가 있습니다. 예를 들어 API 라우트 핸들러를 만들 때는 route.ts로 작성하고, 페이지 컴포넌트는 page.tsx로 작성합니다. 이 기준은 명확합니다. 화면에 렌더링되는 요소(컴포넌트, 레이아웃, 페이지)가 있으면 .tsx, 그 외 로직 파일이면 .ts 입니다.
실무에서 자주 하는 실수 중 하나는 커스텀 훅을 만들 때입니다. useAuth.ts처럼 훅 로직 자체에는 JSX가 없으니 .ts가 맞습니다. 하지만 어떤 훅은 JSX를 반환하거나 렌더링 관련 코드를 포함하기도 하는데, 이 경우에는 .tsx를 써야 합니다. 혼란을 줄이는 가장 간단한 기준은 이렇습니다.
- 파일 안에
<div>,<Component />같은 JSX 태그가 한 번이라도 등장하면.tsx - 타입, 함수, 클래스, API 호출만 있다면
.ts
또 하나 알아두면 좋은 점은, .tsx 파일에서 제네릭 화살표 함수를 사용할 때입니다. <T> 같은泛型 문법이 JSX 태그로 해석될 수 있어서 <T,>처럼 쉼표를 붙여야 하는 불편함이 있습니다. 이런 경우가 아니라면 .ts 파일이 더 깔끔하게 작성할 수 있습니다.
파일 확장자 규칙, 이렇게만 기억하면 됩니다
프로젝트를 처음 셋업할 때 확장자 규칙을 팀 차원에서 정해 두면 나중에 혼선이 줄어듭니다. 일반적으로 많이 쓰는 컨벤션은 다음과 같습니다.
- React 컴포넌트, 페이지, 레이아웃:
.tsx - API 클라이언트, 유틸리티 함수, 상수, 타입 정의:
.ts - Next.js API 라우트:
.ts(네이밍은route.ts) - 테스트 파일: 테스트 대상이 컴포넌트면
.tsx, 로직이면.ts
이 규칙은 팀마다 조금씩 다를 수 있지만, 공통된 핵심은 "JSX가 들어가는 파일은 전부 .tsx"라는 점입니다. TypeScript 컴파일러 옵션에서 jsx 설정이 활성화되어 있더라도, .ts 파일에 JSX를 쓰는 것은 허용되지 않으니 확장자 규칙을 지키는 것이 중요합니다.
Q. .tsx 파일에서도 타입만 정의해도 되나요?
네, 가능합니다. .tsx 파일에 타입 인터페이스만 작성해도 정상 동작합니다. 다만 관례적으로 타입 정의만 있는 파일은 .ts로 분리하는 게 코드 구조상 더 명확합니다. 특히 전역에서 쓰는 타입은 types.ts 같은 별도 파일로 관리하는 게 유지보수에 유리합니다.
Q. React 안 쓰는데 .tsx가 필요한 경우가 있나요?
React 외에 Preact, SolidJS 등 JSX 문법을 지원하는 라이브러리를 쓸 때도 .tsx를 사용합니다. JSX 자체가 React 전용이 아니라 범용적인 문법이기 때문입니다. 반면 Vue나 Angular를 쓸 때는 .tsx를 쓸 일이 거의 없습니다.
Q. 확장자를 잘못 쓰면 어떤 에러가 나나요?
.ts 파일에 JSX를 작성하면 "JSX expressions cannot be used in .ts files"라는 에러가 발생합니다. 반대로 .tsx 파일에 JSX 없이 TypeScript만 작성해도 에러는 나지 않지만, 팀 컨벤션에 어긋날 수 있습니다. 실행 자체는 문제없지만 파일 구조가 지저분해질 수 있습니다.
결국 두 확장자의 차이는 단순합니다. JSX 사용 여부 하나만 기억하면 됩니다. 컴포넌트 관련 파일을 만들 때는 .tsx, 그 외 로직과 타입 파일은 .ts로 작성하는 습관을 들이면 코드베이스가 훨씬 깔끔해집니다. 프로젝트 초기 셋업할 때 이 규칙을 설정 파일에 명시해 두면 팀원 모두가 헷갈리지 않고 작업할 수 있습니다.