12 타입스크립트 프로젝트 관리

12.1 앰비언트 타입 활용하기

1. 앰비언트 타입 선언

타입스크립트 타입 선언은 .ts 또는 .tsx 확장자를 가진 파일에서 할 수 있지만 .d.ts 확장자를 가진 파일에서도 선언할 수 있다.

앰비언트 타입 선언

.d.ts 확장자를 가진 파일에서는 타입 선언만 할 수 있으며 값을 표현할 수는 없다.

값을 포함하는 일반적인 선언과 구별하기 위해 .d.ts 확장자를 가진 파일에서 하는 타입 선언을 앰비언트 타입 선언이라고 부른다.

앰비언트(ambient)는 사전적으로 ‘주변의’란 의미를 가진다.

앰비언트 타입 선언으로 값을 정의할 수는 없지만 declare라는 키워드를 사용하여 어딘가에 자바스크립트 값이 존재한다는 사실을 선언할 수 있다.

declare는 타입스크립트 컴파일러에 어떤 것의 존재 여부를 명시해주는 역할을 한다.

단순히 존재 여부만 알려주기 때문에 컴파일 대상이 아니다.

대표적인 앰비언트 타입 선언 활용 사례

타입스크립트를 사용하다 보면 *.js 또는 *.ts 형식이 아닌 파일을 임포트할 때 종종 에러가 발생하는 것을 보게 된다.

예를 들어 자바스크립트로 png 등 이미지 파일을 모듈로 임포트할 때, 자바스크립트 환경에서는 멀쩡히 동작하던 게 타입스크립트 환경에서는 에러가 발생하는 상황이 연출되곤 한다.

타입스크립트는 기본적으로 .ts와 .js 파일만 이해하며 그 외의 다른 파일 형식은 인식하지 못한다.

따라서 알지 못하는 파일 형식을 모듈로 가져오려 하면 에러가 발생한다.

이런 상황에서 타입스크립트의 declare 키워드를 사용하여 아래와 같이 특정 형식을 모듈로 선언하면 타입스크립트 컴파일러에 미리 정보를 제공함으로써 에러를 수정할 수 있게 된다.

declare module '*.png' {
  const src: string;
  export default src;
}

보다시피 declare 키워드는 이미 존재하지만 타입스크립트가 알지 못하는 부분을 컴파일러에 ‘이러한 것이 존재해’라고 알려주는 역할을 한다.

자바스크립트로 작성된 라이브러리

자바스크립트로 작성된 npm 라이브러리가 있다고 가정해보자.

이 라이브러리는 자바스크립트로 구현되었기에 타입 선언이 존재하지 않는다.

따라서 타입스크립트에서 이 라이브러리를 사용할 수는 있지만 타입 선언이 없으므로 임포트한 모듈은 모두 any로 추론될 것이다.

만약 tsconfig.json 파일에서 any를 사용하지 못하게 설정했다면 프로젝트가 빌드되지 않을 것이다.

이때 앰비언트 타입 선언을 사용할 수 있다.

자바스크립트 라이브러리 내부 함수와 변수의 타입을 앰비언트 타입으로 선언하면 타입스크립트는 자동으로 .d.ts 확장자를 가진 파일을 검색하여 타입 검사를 진행하게 되므로 문제없이 컴파일된다.

또한 VSCode와 같은 코드 편집기도 .d.ts 확장자를 가진 파일을 해석하여 코드를 작성할 때 유용한 타입 힌트를 제공한다.

예를 들어 @types/react를 npm install -D 명령을 통해 설치하면 node_modules/@types/react에 index.d.ts와 global.d.ts가 설치된다.

이러한 파일에는 리액트의 컴포넌트와 훅에 대한 타입이 정의되어 있다.

더욱 흥미로운 점은 tsc는 별도의 설정 없이도 node_modules/@types 디렉터리에 있는 타입 선언을 타입 검사에 활용한다는 것이다.

앞서 언급한대로 VSCode는 index.d.ts와 global.d.ts 파일을 활용하여 코드 작성 시 유용한 타입 힌트를 제공한다.

즉, 앰비언트 타입 선언은 타입스크립트에게 ‘자바스크립트 코드 안에는 이러한 정보들이 있어’라고 알려주는 도구라고 이해하면 된다.

타입스크립트로 작성된 라이브러리

타입스크립트로 작성된 라이브러리일지라도 자바스크립트 파일과 .d.ts 파일로 배포되는 것이 일반적이다.

타입스크립트 파일을 직접 배포하여 라이브러리 사용자가 타입스크립트를 컴파일할 때 라이브러리 코드도 함께 컴파일하게 할 수도 있다.

그러나 자바스크립트 파일과 .d.ts 파일로 배포하면 라이브러리 코드를 따로 컴파일하지 않아도 되기 때문에 컴파일 시간이 크게 줄어든다.

또한 .d.ts 파일이 있기 때문에 사용자는 .d.ts 파일에 정의된 타입 정보를 활용하여 라이브러리를 사용할 수 있다.

또한 tsconfig.json 파일의 declaration을 true로 설정하면 타입스크립트 컴파일러는 자동으로 .d.ts 파일을 생성한다.

자바스크립트 어딘가에 전역 변수가 정의되어 있음을 타입스크립트에 알릴 때

타입스크립트로 직접 구현하지 않았지만 실제 자바스크립트 어딘가에 전역 변수가 정의되어 있는 상황을 타입스크립트에 알릴 때 앰비언트 타입 선언을 사용한다.

예를 들어 웹뷰를 개발할 때 네이티브 앱과의 통신을 위한 인터페이스를 네이티브 앱이 Window 객체에 추가하는 경우가 많다.

이렇게 전역 객체인 Window에 변수나 함수를 추가하면 타입스크립트에서 직접 구현하지 않았더라도 실제 런타임 환경에서 해당 변수를 사용할 수 있다.

네이티브 앱에서 Window 전역 객체에 deviceId나 appVersion 같은 값을 할당해주는 시나리오를 떠올려보자.

Window 객체의 속성은 타입스크립트로 직접 정의한 값이 아니기 때문에 타입스크립트는 해당 속성이 Window 객체의 타입에 존재하지 않는다고 판단한다.

따라서 해당 속성에 접근하려고 하면 Window 객체에 존재하지 않는 속성이라는 에러가 발생한다.

이때 global namespace에 있는 Window 객체에 해당 속성이 정의되어 있다는 것을 나타내기 위해 앰비언트 타입 선언을 사용할 수 있다.

declare global {
  interface Window {
    deviceId: string | undefined;
    appVersion: string;
  }
}

2. 앰비언트 타입 선언 시 주의점

타입스크립트로 만드는 라이브러리에는 불필요

tsconfig.json의 declaration을 true로 설정하면 타입스크립트 컴파일러가 .d.ts 파일을 자동으로 생성해주기 때문에 수동으로 .d.ts 파일을 작성할 필요가 없다.

따라서 타입스크립트로 라이브러리를 개발할 때는 앰비언트 타입 선언을 사용할 필요가 없다.

전역으로 타입을 정의하여 사용할 때 주의해야 할 점

서로 다른 라이브러리에서 동일한 이름의 앰비언트 타입 선언을 한다면 충돌이 발생하여 어떤 타입 선언이 적용될지 알기 어려우며, 의도한 대로 동작하지 않을 수 있다.

또한 앰비언트 타입 선언은 명시적인 임포트나 익스포트가 없기 때문에 코드의 의존성 관계가 명확하지 않아 나중에 변경할 때 어려움을 겪을 수 있다.

3. 앰비언트 타입 선언을 잘못 사용했을 때의 문제점

.ts 파일 내의 앰비언트 변수 선언은 개발자에게 혼란을 야기할 수 있다.

대표적으로 .ts 파일 내부에 앰비언트 변수를 선언할 때 앰비언트 타입의 의존성 관계가 보이지 않기 때문에 변경에 의한 영향 범위를 파악하기 어렵다.

왜냐하면 앰비언트 타입은 명시적인 임포트나 익스포트 없이 코드 전역에서 사용할 수 있기 때문이다.

특히 소스코드 규모가 크다면 추후 변경이 어려워질 수 있다.

다음과 같이 declare 키워드를 사용한 앰비언트 타입 선언은 .d.ts 파일이 아닌 .ts, .tsx 파일 내에서도 할 수 있다.

// src/index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import App from 'App'

declare global {
  interface Window {
    Example: string;
  }
}

const SomeComponent = () => {
  return <div>앰비언트 타입 선언은 .tsx 파일에서도 가능</div>
}

이렇게 선언된 앰비언트 타입은 아래와 같은 src/test.tsx 파일에서도 임포트 없이 사용할 수 있다.

// src/test.tsx
window.Example // 앰비언트 타입 선언으로 인해 타입스크립트 에러가 발생하지 않음

이렇듯 앰비언트 변수 선언은 어느 곳에나 영향을 줄 수 있기 때문에 일반 타입 선언과 섞이게 되면 앰비언트 선언이 어떤 파일에 포함되어 있는지 파악하기 어려워진다.

앞의 예시는 Window 전역 객체의 확장을 나타내고 있는데 src/index.tsx라는 최상위 파일에서 앰비언트 변수 선언을 했기 때문에 그나마 파악하기 쉽다.

하지만 작은 컴포넌트에 앰비언트 변수 선언이 포함되어 있다면 모든 파일의 타입에 영향을 주기 때문에 어떤 파일에서 앰비언트 타입이 선언되었는지 찾기 어려워진다.

.d.ts 확장자 파일 내에서 앰비언트 타입 선언을 하는 것은 일종의 개발자 간의 약속이다.

타입 선언 위치가 명확해야 가독성이 높아지고 유지보수도 편하게 할 수 있기 때문이다.

4. 앰비언트 타입 활용하기

타입을 정의하여 임포트 없이 전역으로 공유

.d.ts 파일에서의 앰비언트 타입 선언은 전역 변수와 같은 역할을 한다.

따라서 앰비언트 타입을 선언하면 모든 코드 내에서 임포트하지 않고 사용할 수 있다.

가령 유용한 유틸리티 타입을 작성했다고 가정해보자.

이렇게 앰비언트 타입으로 유틸리티 타입을 선언하면 모든 코드에서 임포트하지 않아도 해당 타입을 사용할 수 있다.

마치 내장 타입 유틸리티 함수를 사용하는 것처럼 말이다.

// src/index.d.ts
type Optional<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Partial<Pick<T, K>>

// src/components.ts
type Props = { name: string; age: number; visible: boolean; }
type OptionalProps = Optional<Props> // Expect: { name?: string; age?: number; visible?: boolean; }

declare type 활용하기

보편적으로 많이 사용하는 커스텀 유틸리티 타입을 declare type으로 선언하여 전역에서 사용할 수 있다.

아래 예시처럼 Nullable 타입을 선언해서 어디에서든 쉽게 사용할 수 있다.

declare type Nullable<T> = T | null

const name: Nullable<string> = 'woowa'

declare module 활용하기

CSS-in-JS 라이브러리의 사례를 살펴보자.

theme의 인터페이스 타입을 확장하여 theme 타입이 자동으로 완성되도록 하는 기능이 추가되었다.

CSS-in-JS 라이브러리는 기존의 폰트 크기, 색상 등을 객체로 관리한다.

이렇게 정의된 theme에서 스타일 값을 가져와 기존 인터페이스 타입과 통합하여 theme 타입이 자동으로 완성되는 기능을 지원하고 있다.

const fontSizes = {
  xl: '30px',
  // ...
}

const colors = {
  gray_100: '#222222',
  gray_200: '#444444',
  // ...
}

const depths = {
  origin: 0,
  foreground: 10,
  dialog: 100,
  // ...
}

const theme = {
  fontSizes,
  colors,
  depths,
}

declare module 'styled-components' {
  type Theme = typeof theme

  export interface DefaultTheme extends Theme {}
}

이외에도 로컬 이미지나 SVG같이 외부로 노출되어 있지 않은 파일을 모듈로 인식하여 사용할 수 있게끔 만들 수 있다.

declare module '*.gif' {
  const src: string

  export default src
}

declare namespace 활용하기

Node.js 환경에서 .env 파일을 사용할 때, declare namespace를 활용하여 process.env로 설정값을 손쉽게 불러오고 환경변수의 자동 완성 기능을 쓸 수 있다.

declare namespace NodeJS {
  interface ProcessEnv {
    readonly API_URL: string;
    readonly API_INTERNAL_URL: string;
    // ...
  }
}

앞과 같이 process.env를 통해 접근하는 변수 또한 타입을 지정할 수 있기 때문에 as 단언을 사용하지 않아도 된다.

아래와 같은 함수 예시를 통해 타입을 보강한 경우와 그렇지 않은 경우를 비교하여 개념을 이해할 수 있다.

function log(str: string) {
  console.log(str)
}
  1. namespace를 활용하여 process.env 타입을 보강해주지 않은 경우
// .env
API_URL = 'localhost:8080'

log(process.env.API_URL as string)
  1. namespace를 활용하여 process.env 타입을 보강한 경우
// .env
API_URL = 'localhost:8080'

declare namespace NodeJS {
  interface ProcessEnv {
    readonly API_URL: string;
  }
}

log(process.env.API_URL)

declare global 활용하기

declare global 키워드는 전역 변수를 선언할 때 사용한다.

예를 들어 전역 변수인 Window 객체의 스코프에서 사용되는 모듈이나 변수를 추가할 수 있다.

declare global {
  interface Window {
    newProperty: string;
  }
}

앞의 코드처럼 전역 변수인 Window 객체에 newProperty 속성을 추가한 것과 같은 동작을 구현할 수 있다.

대표적으로 네이티브 앱과의 통신을 위한 인터페이스를 Window 객체에 추가할 때 앰비언트 타입 선언을 활용할 수 있다.

다음 코드는 iOS 웹뷰에서 자바스크립트로 네이티브 함수를 호출하기 위한 함수를 정의한 것이다.

이를 통해 네이티브 앱과의 통신을 위한 함수를 호출할 때, 자동 완성 기능을 활용하여 실수를 줄일 수 있다.

declare global {
  interface Window {
    webkit?: {
      messageHandlers?: Record<
        string,
        {
          postMessage?: (parameter: string) => void;
        }
      >
    };
  }
}

5. declare와 번들러의 시너지

declare global로 전역 변수를 선언하는 과정과 번들러를 통해 데이터를 주입하는 절차를 함께 활용하면 시너지를 낼 수 있다.

const color = {
  white: '#ffffff',
  black: '#000000',
} as const

type ColorSet = typeof color

declare global {
  const _color: ColorSet
}

앞과 같이 전역에 _color라는 변수가 존재함을 타입스크립트 컴파일러에 알리면 해당 객체를 활용할 수 있다.

const white = _color['white']

하지만 아직 ColorSet 타입을 가지고 있는 _color 객체의 실제 데이터가 존재하지 않는다.

다시 말해 앞의 코드는 타입스크립트 에러를 발생시키지 않지만, 코드가 실행될 경우에는 실제 데이터가 없기 때문에 기대하는 동작과 다를 수 있다.

이러한 문제를 해결하기 위한 방법 중 하나가 번들 시점에 번들러를 통해서 해당 데이터를 주입하는 것이다.

다음은 롤업(rollup) 번들러의 inject 모듈로 데이터를 주입하는 예시를 나타낸 것이다.

// data.ts
export const color = {
  white: '#ffffff',
  black: '#000000',
} as const

// type.ts
import { color } from './data'
type ColorSet = typeof color

declare global {
  const _color: ColorSet
}

// index.ts
console.log(_color['white'])

// rollup.config.js
import inject from '@rollup/plugin-inject'
import typescript from '@rollup/plugin-typescript'

export default [
  {
    input: 'index.ts',
    output: [
      {
        dir: 'lib',
        format: 'esm',
      },
    ],
    plugins: [typescript(), inject({ _color: ['./data', 'color'] })]
  },
]

전체적인 흐름을 살펴보면 data.ts에서 색상을 정의하고 있으며 type.ts에서는 해당 데이터로부터 타입을 정의하여 전역적으로 선언하고 있다.

index.ts 파일에서는 전역 타입으로 선언된 변수인 _color[‘white’]를 콘솔로 출력하고 있다.

그리고 가장 중요한 롤업 번들러 설정에서 inject 모듈을 사용하여 _color에 해당하는 데이터를 삽입하고 있다.

inject 모듈

inject는 임포트문의 경로를 분석하여 데이터를 가져온다.

import { color } from './data'

./data 경로에서 color를 가져오는 경우, [’./data’, ‘color’]로 지정하여 어떤 데이터 값을 가져올지 명시할 수 있다.

해당 번들 결과물을 실행하면 #ffffff가 정상적으로 출력되는 것을 확인할 수 있다.