TypeScript 프로젝트

TypeScript 프로젝트 생성기는 모던 TypeScript 라이브러리나 애플리케이션을 생성하는 데 사용할 수 있으며, ECMAScript Modules (ESM), TypeScript 프로젝트 참조, 테스트 실행을 위한 Vitest, 정적 분석을 위한 ESLint 등 모범 사례가 구성된 상태로 설정됩니다.

사용 방법

TypeScript 프로젝트 생성

새 TypeScript 프로젝트를 두 가지 방법으로 생성할 수 있습니다:

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#project
5. 필수 매개변수 입력
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#project

yarn

yarn nx g @aws/nx-plugin:ts#project

npm

npx nx g @aws/nx-plugin:ts#project

bun

bunx nx g @aws/nx-plugin:ts#project

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#project --dry-run

npm

npx nx g @aws/nx-plugin:ts#project --dry-run

bun

bunx nx g @aws/nx-plugin:ts#project --dry-run

옵션

매개변수	타입	기본값	설명
name 필수	string	-	TypeScript project name
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.

생성기 출력 결과

생성기는 <directory>/<name> 디렉토리에 다음 프로젝트 구조를 생성합니다:

• 디렉터리src TypeScript 소스 코드

  • index.ts
• project.json 프로젝트 구성 및 빌드 타겟
• tsconfig.json 이 프로젝트의 기본 TypeScript 구성 (워크스페이스 루트 tsconfig.base.json 상속)
• tsconfig.lib.json 라이브러리용 TypeScript 구성 (런타임 또는 패키지된 소스)
• tsconfig.spec.json 테스트용 TypeScript 구성
• vite.config.ts Vitest 구성
• eslint.config.mjs ESLint 구성

팁

package.json 파일이 생성되지 않는다는 점에 주목하세요! 이유는 아래에서 확인할 수 있습니다.

워크스페이스 루트의 다음 파일들에도 일부 변경 사항이 적용됩니다:

• nx.json Nx 구성이 업데이트되어 프로젝트에 @nx/js/typescript 플러그인이 구성됨
• tsconfig.base.json 워크스페이스 내 다른 프로젝트에서 이 프로젝트를 임포트할 수 있도록 TypeScript 별칭이 설정됨
• tsconfig.json 프로젝트에 대한 TypeScript 프로젝트 참조가 추가됨

TypeScript 소스 코드 작성

TypeScript 코드는 src 디렉토리에 추가하세요.

ESM 임포트 문법

TypeScript 프로젝트가 ES 모듈이므로, 파일 확장자를 명시적으로 참조하는 ESM 문법으로 임포트 문을 작성해야 합니다:

index.ts

import { sayHello } from './hello.js';

참고

TypeScript를 사용하고 sayHello가 hello.ts에 정의되어 있더라도, 임포트 시 .js 파일 확장자를 사용합니다. 자세한 내용은 여기에서 확인할 수 있습니다.

다른 TypeScript 프로젝트를 위한 내보내기

TypeScript 프로젝트의 진입점은 src/index.ts입니다. 다른 프로젝트에서 임포트할 수 있도록 여기에 내보내기를 추가할 수 있습니다:

src/index.ts

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

다른 프로젝트에서 라이브러리 코드 임포트

워크스페이스 tsconfig.base.json에 구성된 TypeScript 별칭을 통해 다른 TypeScript 프로젝트에서 이 프로젝트를 참조할 수 있습니다:

packages/my-other-project/src/index.ts

import { sayHello } from ':my-scope/my-library';

참고

TypeScript 프로젝트의 별칭은 전통적인 @ 대신 :로 시작합니다. 이는 워크스페이스의 로컬 패키지와 NPM의 원격 패키지 간 이름 충돌 가능성을 방지하기 위함입니다.

워크스페이스에서 새 프로젝트에 대한 임포트 문을 처음 추가할 때 다음과 유사한 IDE 오류가 발생할 수 있습니다:

임포트 오류

File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

이는 프로젝트 참조가 아직 설정되지 않았기 때문입니다.

TypeScript 프로젝트는 Nx TypeSync 생성기를 통해 기본적으로 구성되어 수동으로 프로젝트 참조를 구성할 필요가 없습니다. 다음 명령을 실행하면 Nx가 필요한 구성을 추가합니다:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

이후 IDE의 오류가 사라지고 라이브러리를 사용할 준비가 완료됩니다.

팁

프로젝트를 빌드하면 다음과 같은 메시지가 표시될 수도 있습니다:

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

프로젝트 참조를 업데이트하려면 Yes를 선택하세요.

의존성 관리

TypeScript 프로젝트에 package.json 파일이 없다는 점이 전통적인 TypeScript 모노레포에 익숙한 경우 예상과 다를 수 있습니다.

모노레포 내 TypeScript 패키지에 대한 의존성을 추가하려면 워크스페이스 루트의 package.json에 의존성을 추가하면 됩니다. 패키지 관리자 명령줄을 통해 이를 수행할 수 있습니다:

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install some-npm-package

이렇게 추가된 의존성은 워크스페이스 내 모든 TypeScript 프로젝트에서 사용 가능합니다.

런타임 코드

TypeScript 프로젝트를 런타임 코드(예: AWS Lambda 함수 핸들러)로 사용할 때는 esbuild와 같은 도구를 사용하여 프로젝트를 번들링하는 것이 좋습니다. 이는 트리 셰이킹을 통해 실제로 참조되는 의존성만 포함되도록 보장합니다.

project.json 파일에 다음과 같은 타겟을 추가하여 이를 구현할 수 있습니다:

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
      }
    },
  },
}

참고

위 타겟에서 src/index.ts를 번들 진입점으로 선택했으므로, 이 파일에서 내보낸 코드와 모든 의존성이 번들에 포함됩니다.

NPM에 배포

TypeScript 프로젝트를 NPM에 배포할 경우 반드시 package.json 파일을 생성해야 합니다.

이 파일은 프로젝트가 참조하는 모든 의존성을 선언해야 합니다. 빌드 시 프로젝트가 워크스페이스 루트 package.json을 통해 설치된 의존성을 확인하므로, Nx Dependency Checks ESLint Plugin을 구성하여 배포용 프로젝트의 package.json이 프로젝트에서 사용하는 모든 의존성을 포함하도록 권장합니다.

빌드

TypeScript 프로젝트는 build 타겟(project.json에 정의됨)으로 구성되며 다음 명령으로 실행할 수 있습니다:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

<project-name>은 프로젝트의 전체 이름입니다.

build 타겟은 프로젝트를 컴파일, 린트, 테스트합니다.

빌드 출력은 워크스페이스 루트 dist 폴더 내 패키지 및 타겟별 디렉토리(예: dist/packages/<my-library>/tsc)에서 확인할 수 있습니다.

테스트

Vitest가 프로젝트 테스트를 위해 구성됩니다.

테스트 작성

테스트는 프로젝트의 src 폴더 내 .spec.ts 또는 .test.ts 파일에 함께 위치시켜 작성해야 합니다.

예시:

• 디렉터리src

  • hello.ts 라이브러리 소스 코드
  • hello.spec.ts hello.ts 테스트

Vitest는 describe, it, test, expect와 같은 Jest 스타일 문법을 제공합니다.

hello.spec.ts

import { sayHello } from './hello.js';

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

테스트 작성 방법 및 의존성 모킹과 같은 기능에 대한 자세한 내용은 Vitest 문서를 참조하세요.

테스트 실행

테스트는 프로젝트의 build 타겟 실행 시 함께 실행되지만, test 타겟을 통해 별도로 실행할 수도 있습니다:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

-t 플래그를 사용하여 개별 테스트 또는 테스트 스위트를 실행할 수 있습니다:

pnpm

pnpm nx run <project-name>:test -t 'sayHello'

yarn

yarn nx run <project-name>:test -t 'sayHello'

npm

npx nx run <project-name>:test -t 'sayHello'

bun

bunx nx run <project-name>:test -t 'sayHello'

팁

VSCode 사용자는 실제로 동작하는 Vitest Runner for VSCode 확장을 설치하여 IDE에서 테스트를 실행, 감시, 디버그할 수 있습니다.

린팅

TypeScript 프로젝트는 린팅을 위해 ESLint, 포맷팅을 위해 Prettier를 사용합니다.

워크스페이스 루트 eslint.config.mjs 파일에서 ESLint를 구성하는 것을 권장합니다. 이 파일의 변경 사항은 워크스페이스 내 모든 TypeScript 프로젝트에 적용되어 일관성을 유지합니다.

마찬가지로 Prettier는 루트 .prettierrc 파일에서 구성할 수 있습니다.

린터 실행

프로젝트 린트 검사를 실행하려면 lint 타겟을 실행하세요:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

린트 문제 수정

대부분의 린트 또는 포맷팅 문제는 자동으로 수정할 수 있습니다. --configuration=fix 인자를 사용하여 ESLint가 린트 문제를 수정하도록 할 수 있습니다:

pnpm

pnpm nx run <project-name>:lint --configuration=fix

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

워크스페이스 내 모든 패키지의 린트 문제를 수정하려면 다음을 실행하세요:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix