TypeScript library starter

소개

TypeScript를 사용하여 라이브러리를 만들기 위한 보일러플레이트입니다.
Vite를 사용하여 빌드하며, Prettier, ESLint, Jest, Husky, GitHub Action 설정이 내장되어 있습니다.
Semantic Release와 Conventional Commits을 사용하여 버저닝, 릴리즈 노트, 체인지 로그를 생성하며 NPM 레지스트리에 배포합니다.

활용 방법

설치 방법

공개된 패키지인 경우 일반적인 방법으로 다운로드 받을 수 있습니다.

# 설명을 위한 예제 패키지입니다.
npm i @divlook/library-starter-example
yarn add @divlook/library-starter-example
pnpm add @divlook/library-starter-example

비공개 패키지이거나 레지스트리가 다른 경우 레지스트리 설정과 레지스트리의 엑세스토큰이 필요합니다. 예를들어 @divlook scope의 패키지를 GitHub에서 다운받고 싶다면 아래 명령어를 입력하면 됩니다.

npm login --scope=@divlook --registry=https://npm.pkg.github.com

사용 방법

모듈 방식

// ES 모듈
import { HelloWorld } from '@divlook/library-starter-example'

// CommonJs
const { HelloWorld } = require('@divlook/library-starter-example')

인라인 스크립트 방식

<!-- ES 모듈 -->
<script type="module">
    // 지원되지 않는 브라우저가 있을 수 있습니다.
    import { HelloWorld } from './dist/lib.mjs'

    // 이렇게 사용할 수도 있습니다.
    import './dist/lib.umd.js'
    LibraryStarterExample.HelloWorld()
</script>

<!-- UMD -->
<script src="./dist/lib.umd.js"></script>
<script>
    LibraryStarterExample.HelloWorld()
</script>

환경 설정

개발 환경

# https://github.com/nvm-sh/nvm
nvm use
npm i -g pnpm
pnpm i

husky 설정

husky에 등록된 git hook에서 NVM 인식이 안되는 문제가 있습니다. 아래와 같이 설정해주세요.

sudo vi ~/.huskyrc

#!/usr/bin/env bash

source ~/.bash_profile
# or `source ~/.zshrc`

if test -f ".nvmrc"; then
    nvm use
fi

만약 아래와 같은 메시지가 발생한다면 터미널에 chmod ug+x .husky/*를 입력해주세요.

hint: The '.husky/pre-push' hook was ignored because it's not set as executable.
hint: You can disable this warning with `git config advice.ignoredHook false`.

패키지 설정

scope 관련 설명은 여기를 참고해주세요.

// package.json
{
    "name": "@divlook/library-starter-example", // 패키지명을 설정합니다. script tag로 로드하는 경우 window.LibraryStarterExample으로 선언됩니다.
    "version": "0.0.0", // 시작 버전을 입력해주세요. Fork를 사용한 경우 git tag가 존재할 수 있습니다. git tag도 모두 삭제해주세요.
    "description": "이 라이브러리의 설명을 입력해주세요.",
    "repository": {
        "type": "git",
        "url": "https://github.com/divlook/ts-library-starter.git" // git 주소를 입력해주세요.
    },
    "license": "MIT", // 사용할 라이센스를 입력해주세요. 없으면 삭제해주세요.
}

브라우저 호환성

브라우저 호환성은 이 문서를 참고해주세요. 레거시 브라우저는 @vitejs/plugin-legacy 플러그인을 사용하여 설정할 수 있습니다.

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default {
    plugins: [
        legacy({
            targets: ['defaults', 'not IE 11'],
        }),
    ],
}

개발 및 배포

빌드

dist 디렉토리에 컴파일된 파일이 생성됩니다.

pnpm build

로컬 개발 모드

로컬 개발 모드는 로컬에서 개발할 때 사용하는 방법입니다. 자세한 사용 방법은 npm link를 참고해주세요. 빌드할 때 소스맵이 생성되며, 파일을 수정할 때마다 빌드가 재실행됩니다.

아래 예제에서 패키지명과 프로젝트명은 설명을 위한 예시입니다.

# 패키지 설정
cd /workspace/ts-library-starter
pnpm link --global
pnpm local

# 실제 프로젝트에 패키지 설치
cd /workspace/another-project
pnpm link --global @divlook/library-starter-example

# 개발 완료 후 정리 방법
cd /workspace/another-project
pnpm rm @divlook/library-starter-example
cd /workspace/ts-library-starter
pnpm unlink

코드품질

유닛 테스트

**/*.test.ts 패턴의 파일을 찾아 테스트를 실행합니다.
```
pnpm test
pnpm test -- --watch
```
ESLint
```
pnpm eslint
pnpm eslint:fix
```
Prettier
```
pnpm prettier
pnpm prettier:fix
```

릴리즈 생성

develop branch에 Pull Request가 정상적으로 병합되면 릴리즈, 체인지로그, 버전태그가 생성되고 package.json의 version이 업데이트됩니다. 이 설정을 변경하고 싶은 경우 아래 파일을 수정해주세요.

.github/workflows/release.yml
conventionalcommits.config.js

배포

릴리즈가 생성되면 배포가 자동으로 실행됩니다. 패키지를 비공개로 관리하고 싶은 경우 아래와 같이 수정해주세요.

# .github/workflows/npm-publish.yml
- npm publish --access public
+ npm publish --access restricted