모듈: TypeScript

[기록]

버전	변경 사항
v22.7.0	`--experimental-transform-types` 플래그가 추가되었습니다.

[안정성: 1 - 실험적]

안정성: 1 안정성: 1.1 - 활발한 개발 중

활성화

Node.js에서 런타임 TypeScript 지원을 활성화하는 방법에는 두 가지가 있습니다.

전체 TypeScript 지원

tsconfig.json을 포함한 모든 TypeScript 기능을 완전히 지원하는 TypeScript를 사용하려면 타사 패키지를 사용할 수 있습니다. 다음 지침에서는 tsx를 예로 사용하지만 유사한 라이브러리가 많이 있습니다.

타입 제거

추가됨: v22.6.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1.1 - 활발한 개발 중

--experimental-strip-types 플래그를 사용하면 Node.js에서 TypeScript 파일을 실행할 수 있습니다. 기본적으로 Node.js는 enum 또는 네임스페이스와 같이 변환이 필요한 TypeScript 기능이 없는 파일만 실행합니다. Node.js는 인라인 타입 주석을 공백으로 바꾸고 타입 검사는 수행하지 않습니다. 이러한 기능의 변환을 활성화하려면 --experimental-transform-types 플래그를 사용하십시오. 경로 또는 최신 JavaScript 구문을 이전 표준으로 변환하는 것과 같이 tsconfig.json 내 설정에 따라 달라지는 TypeScript 기능은 의도적으로 지원되지 않습니다. 전체 TypeScript 지원을 받으려면 전체 TypeScript 지원을 참조하십시오.

타입 제거 기능은 가볍게 설계되었습니다. JavaScript 코드 생성이 필요한 구문을 의도적으로 지원하지 않고 인라인 타입을 공백으로 대체함으로써 Node.js는 소스 맵 없이 TypeScript 코드를 실행할 수 있습니다.

타입 제거는 대부분의 TypeScript 버전에서 작동하지만 다음 tsconfig.json 설정과 함께 버전 5.7 이상을 사용하는 것이 좋습니다.

json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

모듈 시스템 결정

Node.js는 TypeScript 파일에서 CommonJS 및 ES 모듈 구문을 모두 지원합니다. Node.js는 한 모듈 시스템에서 다른 모듈 시스템으로 변환하지 않습니다. 코드를 ES 모듈로 실행하려면 import 및 export 구문을 사용해야 하며, 코드를 CommonJS로 실행하려면 require 및 module.exports를 사용해야 합니다.

.ts 파일은 .js 파일과 동일한 방식으로 모듈 시스템이 결정됩니다. import 및 export 구문을 사용하려면 가장 가까운 부모 package.json에 "type": "module"을 추가합니다.
.mts 파일은 .mjs 파일과 마찬가지로 항상 ES 모듈로 실행됩니다.
.cts 파일은 .cjs 파일과 마찬가지로 항상 CommonJS 모듈로 실행됩니다.
.tsx 파일은 지원되지 않습니다.

JavaScript 파일에서와 마찬가지로, import 문과 import() 표현식에서 파일 확장자는 필수입니다. 즉, import './file'이 아니라 import './file.ts'와 같이 작성해야 합니다. 이전 버전과의 호환성 때문에 require() 호출에서도 파일 확장자가 필수입니다. CommonJS 파일에서 require 호출에 .cjs 확장자가 필수인 것과 마찬가지로, require('./file')이 아니라 require('./file.ts')와 같이 작성해야 합니다.

tsconfig.json 옵션 allowImportingTsExtensions는 TypeScript 컴파일러 tsc가 .ts 확장자를 포함하는 import 지정자를 사용하여 파일을 타입 검사할 수 있도록 합니다.

TypeScript 기능

Node.js는 인라인 타입만 제거하므로, --experimental-transform-types 플래그를 전달하지 않는 한 TypeScript 구문을 새로운 JavaScript 구문으로 바꾸는 모든 TypeScript 기능에서 오류가 발생합니다.

변환이 필요한 가장 눈에 띄는 기능은 다음과 같습니다.

Enum
namespaces
legacy module
매개변수 속성

데코레이터는 현재 TC39 스테이지 3 제안이며 곧 JavaScript 엔진에서 지원될 예정이므로 변환되지 않으며 파서 오류가 발생합니다. 이는 일시적인 제한 사항이며 향후 해결될 예정입니다.

또한 Node.js는 tsconfig.json 파일을 읽지 않으며, 경로 또는 새로운 JavaScript 구문을 이전 표준으로 변환하는 것과 같이 tsconfig.json 내 설정에 의존하는 기능을 지원하지 않습니다.

`type` 키워드 없이 유형 가져오기

유형 제거 특성상, type 키워드는 유형 가져오기를 올바르게 제거하는 데 필요합니다. type 키워드가 없으면 Node.js는 가져오기를 값 가져오기로 처리하여 런타임 오류가 발생합니다. tsconfig 옵션인 verbatimModuleSyntax를 사용하여 이 동작을 일치시킬 수 있습니다.

다음 예제는 올바르게 작동합니다.

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

다음은 런타임 오류가 발생합니다.

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

파일 형식이 아닌 입력

--eval에 대해 유형 제거를 활성화할 수 있습니다. 모듈 시스템은 JavaScript와 마찬가지로 --input-type에 의해 결정됩니다.

TypeScript 구문은 REPL, STDIN 입력, --print, --check 및 inspect에서 지원되지 않습니다.

소스 맵

인라인 유형은 공백으로 대체되므로 스택 추적에서 올바른 줄 번호에 소스 맵이 불필요하며 Node.js는 이를 생성하지 않습니다. --experimental-transform-types가 활성화되면 소스 맵이 기본적으로 활성화됩니다.

종속성의 유형 제거

패키지 작성자가 TypeScript로 작성된 패키지를 게시하지 않도록 하기 위해 Node.js는 기본적으로 node_modules 경로 아래의 폴더 내에서 TypeScript 파일을 처리하는 것을 거부합니다.

경로 별칭

tsconfig "paths"는 변환되지 않으므로 오류가 발생합니다. 사용 가능한 가장 가까운 기능은 #로 시작해야 한다는 제한이 있는 하위 경로 가져오기입니다.

모듈: TypeScript ​

활성화 ​

전체 TypeScript 지원 ​

타입 제거 ​

모듈 시스템 결정 ​

TypeScript 기능 ​

type 키워드 없이 유형 가져오기 ​

파일 형식이 아닌 입력 ​

소스 맵 ​

종속성의 유형 제거 ​

경로 별칭 ​