타입스크립트 입문 가이드 (설치·기본 문법·type vs interface 입문)

타입스크립트는 자바스크립트 코드에 타입 정보를 붙여, 코드를 실행하기 전에 오류를 미리 잡아 주는 언어입니다. 예를 들어 숫자가 들어와야 할 자리에 글자가 들어오면, 브라우저에서 화면이 깨진 다음에야 발견하는 게 아니라 코드를 작성하는 그 순간 편집기에 빨간 줄로 알려 줍니다. 작성한 코드는 결국 일반 자바스크립트로 변환(컴파일)되어 똑같이 동작하므로, 실행 환경은 그대로 두고 작성 단계의 안전망만 추가한다고 보면 됩니다.

제가 12개 사이트를 1인으로 운영하면서 가장 크게 체감한 차이는, 함수 하나를 고쳤을 때 그 함수를 쓰는 다른 30곳이 한 번에 빨간 줄로 떠오른다는 점이었습니다. JS만 쓸 때는 어디가 깨졌는지 몰라 사이트를 직접 눌러 보며 찾았는데, TS로 옮긴 뒤로는 편집기가 깨진 자리를 먼저 알려 줍니다. 다만 공짜는 아닙니다. 타입을 적는 손품이 늘고, 초반에는 빨간 줄을 없애느라 시간이 더 들어갑니다.

설치 자체는 정말 간단합니다. 전역으로 깔 수도 있지만, 저는 프로젝트마다 버전이 엇갈리는 사고를 피하려고 항상 프로젝트 안에 개발 의존성으로만 설치합니다. 새 폴더를 만들고 아래 순서대로 진행하면 됩니다.

설치가 끝나면 설정 파일인 tsconfig.json을 만듭니다. 이 파일이 어떤 규칙으로 검사하고 어떤 자바스크립트로 변환할지를 정하는 핵심입니다. 아래 명령으로 기본 골격을 자동 생성한 뒤, 필요한 항목만 손보는 흐름을 추천합니다.

이제 .ts 확장자로 파일을 하나 만들어 보겠습니다. 타입스크립트 파일은 변수 옆에 콜론과 타입을 적는 점만 빼면 자바스크립트와 거의 똑같이 생겼습니다. 아래는 가장 단순한 예시입니다.

이 파일을 자바스크립트로 변환하려면 npx tsc hello.ts 를 실행하면 같은 폴더에 hello.js 가 생깁니다. 실제로 한 번 돌려 보려면 변환 없이 바로 실행해 주는 도구를 쓰는 게 편한데, 저는 빠른 확인용으로 tsx 를 자주 씁니다. 아래처럼 설치 없이 한 번에 돌려 볼 수 있습니다.

타입스크립트 문법은 방대해 보이지만, 처음에는 다섯 가지만 손에 익혀도 일상 코드의 대부분을 처리할 수 있습니다. 저도 입문할 때 모든 문법을 외우려다 지쳐서 나가떨어졌는데, 자주 쓰는 것부터 익히니 훨씬 수월했습니다. 핵심만 추리면 다음과 같습니다.

• 기본 타입: string, number, boolean, null 처럼 자바스크립트의 자료형과 거의 그대로 대응됩니다.
• 배열과 객체: number 배열은 number와 대괄호로, 객체는 키마다 타입을 적어 모양을 정합니다.
• 유니온 타입: 세로 막대 기호로 여러 타입 중 하나를 허용합니다. 값이 둘 중 하나일 때 유용합니다.
• 옵셔널(선택) 속성: 키 뒤에 물음표를 붙이면 있어도 되고 없어도 되는 속성이 됩니다.
• 함수 타입: 매개변수와 반환값에 각각 타입을 적어, 잘못된 인자가 들어오는 걸 막습니다.

아래 예시 하나로 위 다섯 가지가 어떻게 쓰이는지 한눈에 볼 수 있습니다.

위 코드에서 views 키에 붙은 물음표가 옵셔널 속성입니다. 글에 조회수가 아직 없을 수도 있으니 있어도 되고 없어도 되도록 풀어 둔 것입니다. status 처럼 정해진 문자열 몇 개만 허용하는 유니온 타입은, 오타로 publised 같은 잘못된 값을 넣으면 즉시 빨간 줄로 잡아 줘서 실수가 크게 줄었습니다. 제가 게시글 상태를 다룰 때 가장 먼저 도입한 패턴이기도 합니다.

입문자가 가장 많이 검색하는 질문이 바로 이것입니다. 저도 처음엔 두 키워드가 똑같이 객체 모양을 정의하는 데 쓰여서 무엇이 다른지 한참 헷갈렸습니다. 결론부터 말하면, 객체나 클래스의 모양을 정의할 때는 어느 쪽을 써도 대부분 똑같이 동작합니다. 차이가 드러나는 건 특수한 경우입니다. 아래 표가 둘의 핵심 차이입니다.

같은 객체를 두 방식으로 적으면 이렇게 생겼습니다. 모양만 보면 거의 차이가 없습니다.

제가 실제로 적용하는 기준은 단순합니다. 객체나 클래스의 모양을 정의할 때는 interface 를 우선 쓰고, 유니온 타입이나 원시값 별칭처럼 interface 로 못 하는 경우에만 type 을 씁니다. 이렇게 한 줄 기준만 정해 두니 매번 고민하던 시간이 사라졌습니다. interface 를 기본으로 두는 이유는, 나중에 다른 사람이 같은 이름으로 속성을 덧붙이는 선언 병합이 가능해서 라이브러리 타입을 확장하기 편하기 때문입니다. 다만 이건 어디까지나 팀 컨벤션 문제이므로, 프로젝트에서 type 으로 통일했다면 그 규칙을 따르는 게 더 중요합니다.

tsconfig.json 을 자동 생성하면 strict 항목이 기본으로 true 인데, JS 프로젝트를 처음 옮길 때 이걸 켜 두면 빨간 줄이 수백 개씩 뜨는 경험을 하게 됩니다. 저도 첫 마이그레이션에서 이 광경을 보고 겁을 먹어 strict 를 꺼 버렸는데, 결과적으로는 그게 더 안 좋은 선택이었습니다. strict 가 잡아 주는 오류 상당수가 실제 버그였기 때문입니다. strict 는 여러 세부 옵션을 한 번에 켜는 묶음인데, 그중 입문자가 가장 자주 부딪히는 두 가지가 다음입니다.

• noImplicitAny: 타입을 안 적은 매개변수를 암묵적으로 any(아무 타입) 로 두지 않고 오류로 처리합니다. 타입을 빼먹지 못하게 강제합니다.
• strictNullChecks: null 이나 undefined 가 될 수 있는 값을 그냥 쓰지 못하게 막습니다. 화면이 가끔 깨지는 사고의 상당수가 여기서 걸러집니다.

제가 권하는 현실적인 절충안은 이렇습니다. 새 프로젝트라면 처음부터 strict 를 켜고 시작하세요. 코드가 적을 때 규칙을 들이는 게 가장 쉽습니다. 반대로 이미 큰 JS 프로젝트를 옮기는 중이라면, strict 를 한 번에 켜는 대신 아래처럼 세부 옵션을 하나씩 켜며 빨간 줄을 단계적으로 줄여 가는 방식이 덜 고통스럽습니다.

위 설정은 strict 전체를 끄되, 효과가 가장 큰 두 옵션만 먼저 켠 형태입니다. 이 상태로 빨간 줄을 모두 정리한 다음, 어느 정도 익숙해지면 strict 를 true 로 올리고 나머지 세부 검사를 마저 켜는 순서로 가면 됩니다. skipLibCheck 는 외부 라이브러리 타입 정의의 검사를 건너뛰어 초기 오류를 줄여 주는데, 입문 단계에서는 켜 두는 편이 정신 건강에 좋았습니다. 저는 이 순서로 옮긴 뒤로는 마이그레이션이 더는 무섭지 않게 됐습니다.

JS만 쓰던 사람이 가장 흔히 저지르는 실수가, 의욕에 넘쳐 전체 파일을 하루 만에 .ts 로 바꾸려는 것입니다. 저도 그랬다가 빨간 줄에 파묻혀 작업을 멈춘 경험이 있습니다. 타입스크립트는 .js 파일과 .ts 파일을 한 프로젝트에서 섞어 쓸 수 있으므로, 점진적으로 옮기는 게 정석입니다. 제가 실제로 따른 순서는 다음과 같습니다.

1. allowJs 켜기: tsconfig 에 allowJs 를 켜서 기존 .js 파일이 그대로 섞여 동작하게 합니다.
2. 새 파일부터 .ts 로: 새로 만드는 파일만 .ts 로 작성합니다. 기존 코드는 건드리지 않습니다.
3. 자주 고치는 파일부터 전환: 손이 자주 가는 핵심 파일을 우선 .ts 로 옮겨 효과를 빨리 봅니다.
4. any 임시 허용: 당장 타입을 못 정하겠으면 any 로 일단 막아 두고, 나중에 정교하게 좁힙니다.
5. strict 단계적 강화: 위에서 정리한 대로 세부 옵션을 하나씩 켜며 마무리합니다.

이 순서로 가면 작업이 멈추지 않습니다. 하루에 한두 파일씩만 옮겨도, 손이 자주 가는 파일부터 타입이 붙으니 체감 안정감이 빠르게 올라갔습니다. 한국 1인 개발자라면 시간이 늘 부족하니, 전부 멈추고 마이그레이션에 매달리기보다 평소 작업하면서 건드리는 김에 하나씩 .ts 로 바꾸는 방식이 현실적입니다. 저는 이 방법으로 큰 멈춤 없이 사이트 코드를 옮겼습니다.

다행히 타입스크립트 자체는 오픈소스라 설치·사용에 돈이 한 푼도 들지 않습니다. 깃허브(GitHub)에서 누구나 받아 쓸 수 있고, 위에서 정리한 설치·실행 방식 전부 무료입니다. 한국 카드로 따로 결제할 일도, 원화 환산이나 부가세(VAT 10%)를 신경 쓸 일도 없습니다. 편집기로 가장 많이 쓰는 VS Code 역시 무료이고, 타입스크립트 지원이 기본 내장돼 있어 별도 설정이 거의 필요 없습니다.

비용이 생긴다면 그건 타입스크립트가 아니라 곁들여 쓰는 AI 코딩 도구 쪽입니다. 저는 타입 정의를 빠르게 짜거나 빨간 줄 원인을 물어볼 때 클로드 코드(Claude Code)나 커서(Cursor) 같은 도구를 쓰는데, 이쪽은 구독료가 붙습니다. 해외 서비스라 한국 카드로 결제하면 환율과 부가세가 청구서에 반영되니, 결제 직전 공식 페이지에서 최종 금액을 확인하는 편이 좋습니다. 2026년 6월 기준 가격은 자주 바뀌므로 단정하지 않겠습니다. 정리하면, 타입스크립트 본체는 무료이고 비용은 선택적으로 쓰는 AI 도구에서만 발생한다고 보면 됩니다.

참고 자료

• 타입스크립트 공식 핸드북 (typescriptlang.org/docs/handbook) — 기본 문법과 타입 시스템 전반
• tsconfig 공식 레퍼런스 (typescriptlang.org/tsconfig) — strict 등 모든 컴파일러 옵션 설명