컨텐츠로 건너뛰기
@aws/nx-plugin
Blog

TypeScript 프로젝트

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

사용 방법

TypeScript 프로젝트 생성하기

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

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

    옵션

    매개변수 타입 기본값 설명
    name 필수 string - Library 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 구성 파일

    작업 공간 루트의 다음 파일들에도 변경 사항이 적용됩니다:

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

    TypeScript 소스 코드 작성

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

    ESM 임포트 구문

    TypeScript 프로젝트가 ES 모듈이므로 파일 확장자를 명시적으로 포함한 ESM 구문으로 임포트문을 작성해야 합니다:

    index.ts
    import { sayHello } from './hello.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';

    작업 공간에서 새 프로젝트에 대한 임포트문을 처음 추가할 경우 다음과 유사한 IDE 오류가 발생할 수 있습니다:

    임포트 오류
    Terminal window
    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)

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

    Nx TypeScript Sync 생성기가 기본적으로 구성되어 있어 수동 구성 없이 다음 명령어 실행으로 필요한 구성을 추가할 수 있습니다:

    Terminal window
    pnpm nx sync

    이후 IDE 오류가 사라지고 라이브러리를 사용할 수 있게 됩니다.

    의존성 관리

    전통적인 TypeScript 모노레포와 달리 TypeScript 프로젝트에 package.json 파일이 없을 수 있습니다.

    모노레포 내 TypeScript 패키지에 의존성을 추가하려면 작업 공간 루트의 package.json에 의존성을 추가하면 됩니다. 패키지 매니저 명령어를 통해 추가할 수 있습니다:

    Terminal window
    pnpm add -w some-npm-package

    이렇게 추가된 의존성은 작업 공간 내 모든 TypeScript 프로젝트에서 사용 가능합니다.

    런타임 코드 사용 시

    AWS Lambda 함수 핸들러와 같이 런타임 코드로 TypeScript 프로젝트를 사용할 경우, 트리 셰이킹을 통해 실제 사용되는 의존성만 포함되도록 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"
          }
        },
      },
    }

    NPM 배포 시

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

    이 파일은 프로젝트가 참조하는 모든 의존성을 선언해야 합니다. 빌드 시 작업 공간 루트 package.json의 의존성을 사용하므로, Nx Dependency Checks ESLint 플러그인을 구성하여 배포용 package.json에 모든 사용 의존성이 포함되도록 하는 것이 좋습니다.

    빌드

    프로젝트 project.json에 정의된 build 대상으로 빌드를 실행할 수 있습니다:

    Terminal window
    pnpm nx run <project-name>:build

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

    build 대상은 컴파일, 린트, 테스트를 수행합니다.

    빌드 결과물은 작업 공간 루트 dist 폴더 내 dist/packages/<my-library>/tsc와 같은 경로에서 확인할 수 있습니다.

    테스트

    Vitest가 테스트 실행을 위해 구성되어 있습니다.

    테스트 작성하기

    .spec.ts 또는 .test.ts 파일에 테스트를 작성하고 프로젝트 src 폴더에 함께 배치하세요.

    예시:

    • 디렉터리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 대상으로 개별 실행도 가능합니다:

    Terminal window
    pnpm nx run <project-name>:test

    -t 플래그로 특정 테스트를 실행할 수 있습니다:

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

    린팅

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

    작업 공간 루트 eslint.config.mjs 파일에서 ESLint를 구성하여 모든 TypeScript 프로젝트에 일관된 설정이 적용되도록 하는 것이 좋습니다.

    Prettier는 루트 .prettierrc 파일에서 구성할 수 있습니다.

    린터 실행하기

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

    Terminal window
    pnpm nx run <project-name>:lint

    린트 문제 수정하기

    대부분의 린트/포맷팅 문제는 자동으로 수정 가능합니다. --configuration=fix 인자로 ESLint를 실행하여 수정할 수 있습니다:

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

    작업 공간 전체 패키지의 린트 문제를 수정하려면 다음 명령어를 사용하세요:

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