npm에 배포된 Angular 라이브러리 사용하기

Angular 애플리케이션을 만들 때는 Angular에서 직접 제공하는 정교한 라이브러리와 풍부한 서드 파티 라이브러리 생태계를 활용하세요. Angular Material은 Angular에서 직접 제공하는 정교한 라이브러리의 예입니다.

라이브러리 설치하기

라이브러리는 npm 패키지로 배포되며, 보통 Angular CLI와 통합하는 스키매틱도 함께 제공됩니다. 재사용할 수 있는 라이브러리 코드를 애플리케이션에 통합하려면 패키지를 설치하고 기능을 사용하는 위치에서 해당 기능을 불러와야 합니다. 대부분의 배포된 Angular 라이브러리는 Angular CLI의 ng add <lib_name> 명령으로 추가할 수 있습니다.

Angular CLI의 ng add 명령은 패키지 관리자로 라이브러리 패키지를 설치하고, 패키지에 포함된 스키매틱을 실행해서 프로젝트 코드에 필요한 구성을 추가합니다. 패키지 관리자로는 npm이나 yarn 등이 있습니다. 프로젝트 코드에 추가되는 구성에는 import 구문, 폰트, 테마 등이 포함됩니다.

배포된 라이브러리에는 일반적으로 애플리케이션에 라이브러리를 추가하는 방법을 설명하는 README 파일이나 문서가 있습니다. 예를 들어 Angular Material 문서를 참고하세요.

라이브러리 타입 선언

라이브러리 패키지는 일반적으로 .d.ts 파일에 타입 선언을 포함합니다. node_modules/@angular/material에서 예제를 확인할 수 있습니다. 라이브러리 패키지에 타입 선언이 없어서 IDE가 오류를 표시한다면 라이브러리와 함께 @types/<lib_name> 패키지를 설치해야 할 수 있습니다.

예를 들어 d3라는 라이브러리가 있다고 해 봅시다:

npm install d3 --save
npm install @types/d3 --save-dev

워크스페이스에 설치한 라이브러리의 @types/ 패키지에 정의된 타입은 해당 라이브러리를 사용하는 프로젝트의 TypeScript 설정에 자동으로 추가됩니다. TypeScript는 기본적으로 node_modules/@types 디렉터리에서 타입을 찾으므로 각 타입 패키지를 개별적으로 추가할 필요가 없습니다.

라이브러리의 타입 선언이 @types/에 없다면 직접 타입 선언을 추가해서 사용할 수 있습니다. 다음과 같이 진행하세요:

src/ 디렉터리에 typings.d.ts 파일을 만드세요. 이 파일은 전역 타입 정의로 자동 포함됩니다.

src/typings.d.ts에 다음 코드를 추가하세요:

declare module 'host' {
  export interface Host {
    protocol?: string;
    hostname?: string;
    pathname?: string;
  }
  export function parse(url: string, queryString?: string): Host;
}

라이브러리를 사용하는 컴포넌트나 파일에 다음 코드를 추가하세요:

import * as host from 'host';
const parsedUrl = host.parse('https://angular.dev');
console.log(parsedUrl.hostname);

필요에 따라 타입 선언을 더 정의하세요.

라이브러리 업데이트하기

라이브러리는 배포자가 업데이트할 수 있으며, 라이브러리가 사용하는 개별 의존성도 최신 상태로 유지해야 합니다. 설치한 라이브러리의 업데이트를 확인하려면 Angular CLI의 ng update 명령을 사용하세요.

개별 라이브러리의 버전을 업데이트하려면 Angular CLI의 ng update <lib_name> 명령을 사용하세요. Angular CLI는 라이브러리의 최신 배포 버전을 확인하고 설치된 버전보다 새 버전이면 다운로드한 뒤 package.json도 최신 버전에 맞게 변경합니다.

Angular를 새 버전으로 업데이트할 때는 사용 중인 라이브러리도 최신 상태인지 확인해야 합니다. 라이브러리 사이에 의존 관계가 있다면 특정 순서로 업데이트해야 할 수 있습니다. 도움이 필요하면 Angular 업데이트 가이드를 참고하세요.

런타임 전역 스코프에 라이브러리 추가하기

레거시 JavaScript 라이브러리를 애플리케이션으로 직접 불러오지 않는 경우에는 런타임 전역 스코프에 추가해서 script 태그로 추가한 것처럼 로드할 수 있습니다. 워크스페이스 빌드 설정 파일인 angular.json에서 빌드 대상의 scripts와 styles 옵션을 사용하면 Angular CLI가 빌드할 때 이렇게 처리하도록 설정할 수 있습니다.

예를 들어 Bootstrap 4 라이브러리를 사용하려면 다음과 같이 진행하세요.

npm 패키지 관리자로 라이브러리와 관련 의존성을 설치하세요:

npm install jquery --save
npm install popper.js --save
npm install bootstrap --save

angular.json 설정 파일의 scripts 배열에 관련 스크립트 파일을 추가하세요:

"scripts": [
    "node_modules/jquery/dist/jquery.slim.js",
    "node_modules/popper.js/dist/umd/popper.js",
    "node_modules/bootstrap/dist/js/bootstrap.js"
  ],

styles 배열에 bootstrap.css CSS 파일을 추가하세요:

"styles": [
    "node_modules/bootstrap/dist/css/bootstrap.css",
    "src/styles.css"
],

Angular CLI의 ng serve 명령을 실행하거나 다시 시작해서 애플리케이션에서 Bootstrap 4가 동작하는지 확인하세요.

앱 안에서 런타임 전역 라이브러리 사용하기

"scripts" 배열로 라이브러리를 불러왔다면 TypeScript 코드의 import 구문으로 다시 불러오면 안 됩니다. 다음 코드는 import 구문의 예입니다.

import * as $ from 'jquery';

import 구문으로도 불러오면 전역 라이브러리로 불러온 사본과 모듈로 불러온 사본이 따로 존재하게 됩니다. jQuery처럼 플러그인을 사용하는 라이브러리는 사본마다 서로 다른 플러그인이 포함되므로 특히 문제가 됩니다.

대신 npm install @types/jquery로 라이브러리의 타입 선언을 다운로드하고, tsconfig.app.json의 types 배열에 "jquery"를 추가한 뒤 라이브러리 설치 단계를 따르세요. 그러면 라이브러리가 노출하는 전역 변수에 접근할 수 있습니다.

런타임 전역 라이브러리의 타입 선언 정의하기

사용하려는 전역 라이브러리에 전역 타입 선언이 없다면 src/typings.d.ts에서 직접 any로 선언할 수 있습니다.

예를 들면 다음과 같습니다:

declare var libraryName: any;

일부 스크립트는 다른 라이브러리를 확장합니다. 예를 들어 jQuery 플러그인은 다음과 같습니다:

$('.test').myPlugin();

이 경우 설치한 @types/jquery에는 myPlugin이 포함되지 않으므로 src/typings.d.ts에 인터페이스를 추가해야 합니다. 예를 들면 다음과 같습니다:

interface JQuery {
  myPlugin(options?: any): any;
}

스크립트에서 정의한 확장 기능의 인터페이스를 추가하지 않으면 IDE에 오류가 표시됩니다:

[TS][Error] Property 'myPlugin' does not exist on type 'JQuery'