TypeScript로 라이브러리 만들기

사이드 프로젝트를 하면서 외부 라이브러리 사용을 하지말고 우리만의 라이브러리를 만들자고 하여

내가 맡게되었는데 ..

초보 개발자 입장에서는 도통 아무것도 모르겠고 어디서 부터 어떻게 시작하는지도 감이 안와서

여기저기 검색해보고 끌어모은 정보로  작성하게 되었다. 

이게 정답이라고는 할수 없지만 비슷한 상황이신 분들에게 도움이 되었으면 좋겠땨 🐥

 

NPM Package 생성 부터 배포 _진짜진짜최종🚀

 

👩🏻‍💻 NPM Package를 생성하여 라이브러리를 만드는 건

동일하기에 관련 글 참고 바랍니다. 👩🏻‍💻

 

npm

• NPM 회원 가입해주기
• 회원가입 시 e-mail 인증 필수 (인증하지 않으면 배포가 불가능합니다.)

 

🔆 Package 설정

 

저는 React (create-react-app) + TypeScript을 사용하여 만들어보겠습니다.

 

요즘 프로젝트들은 대부분 TypeScript로 이루어져 있습니다.
라이브러리에서 TypeScript를 지원해주지 않는다면 다른 사용자들이 나의 라이브러리를 사용할 수 없습니다.

그래서 언어는 JavaScript가 아닌 TypeScript를 통해서 라이브러리를 만드는 게 좋습니다.

 

본인의 터미널에 아래 명령어를 입력해주세요.

[프로젝트 명] 에는 만들고자 하는 라이브러리의 폴더명을 작성해주시면 됩니다.

 

npx create-react-app [프로젝트 명] --template typescript

 

 

사진과 같이 폴더 내에 생성된 것을 보실 수 있을 겁니다.

 

tsconfig.json 에서 Npm을 타입 스크립트로 배포하기 위해서

몇 가지 설정을 해야 합니다.

 

 

"compilerOptions": {
    "target": "es5", // 'es3', 'es5', 'es2015', 'es2016', 'es2017','es2018', 'esnext' 가능
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true, // js 파일들 ts에서 import해서 쓸 수 있는지
    "checkJs": true, // 일반 js 파일에서도 에러체크 여부
    "skipLibCheck": true,
    "esModuleInterop": true,
    "removeComments": true, //컴파일시 주석제거
    "allowSyntheticDefaultImports": true,
    "strict": true, //strict 관련, noimplicit... 관련 모드 전부 켜기
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true, //switch문 이상하면 에러내기
    "module": "esnext", //무슨 import 문법 쓸건지 'commonjs', 'amd', 'es2015', 'esnext'
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "jsx": "react-jsx", // tsx 파일을 jsx로 어떻게 컴파일할 것인지 'preserve', 'react-native', 'react'
    "declaration": true, //컴파일시 .d.ts 파일도 자동으로 함께생성 (현재쓰는 모든 타입이 정의된 파일)
    "outDir": "./dist", //js파일 아웃풋 경로바꾸기
    "outFile": "./", //모든 ts파일을 js파일 하나로 컴파일해줌 (module이 none, amd, system일 때만 가능)
    "noImplicitAny": true, // any라는 타입이 의도치않게 발생할 경우 에러를 띄워주는 설정
    "strictNullChecks": true, // null, undefined 타입에 이상한 조작하면 에러를 띄우는 설정
    "strictFunctionTypes": true, //함수파라미터 타입체크 강하게
    "strictPropertyInitialization": true, //class constructor 작성시 타입체크 강하게
    "noImplicitThis": true, //this 키워드가 any 타입일 경우 에러내기
    "alwaysStrict": true, //자바스크립트 "use strict" 모드 켜기
    "noUnusedLocals": true, //쓰지않는 지역변수 있으면 에러내기
    "noUnusedParameters": true, //쓰지않는 파라미터 있으면 에러내기
    "noImplicitReturns": true //함수에서 return 빼먹으면 에러내기
    }

 

✅ 개발 시 많이 사용하는 것들과 설명 참고하세요.

본인이 필요한 것들만 사용하시면 됩니다.

 

저는 라이브러리를 배포하기 위한 최소한의 설정만 하겠습니다.

 

create-react-app typescript version 기준

 

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "jsx": "react-jsx",
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["./src/lib/**/*.tsx", "./src/lib/**/*.ts"]
}

 

1. "noEmit": false

noEmit 옵션은 출력을 내보내지 않는다는 설정입니다.
npm 배포를 하기 위해서는 내가 만든 컴포넌트 혹은 파일이 출력으로 나와야 합니다.

 

2. "declaration": true

. d.ts파일을 생성할 것인지에 대한 옵션입니다.
라이브러리가 타입 스크립트를 지원하기 위해서는 해당 옵션을 true로 주어야 합니다.

 

3. "outDir": "./dist"

tsc 명령어로 컴파일된 파일들이 어디에 위치할 것인지에 대한 옵션입니다.
dist 폴더에 두기 위해서 위와 같이 작성합니다.

 

4. "include" 속성

tsc 명령어로 컴파일할 파일이 어디에 위치하는지를 명시해주는 옵션입니다.
저는 라이브러리를 개발할 위치를 src 폴더에서 lib 폴더를 생성해서 그 안에서 개발을 할 겁니다. 그래서 아래와 같이 작성을 합니다.

"include": ["./src/lib/**/*.tsx", "./src/lib/**/*.ts"]

 

이 외의 옵션들에 대해서는 선택적입니다.

추가 적으로 필요한 옵션이 있으시다면 참고하세요.

 

tsconfig.json의 수정을 마쳤다면 package.json을 변경해야 합니다.
package.json에는 내가 배포할 라이브러리의 정보들을 적어주고,
배포할 파일들의 엔드포인트들을 적어줍니다.

꼭 변경해야 하는 부분은 다음과 같습니다.

 

1. "name"

 

제일 중요한 라이브러리의 이름을 적어주어야 합니다.
이미 존재하는 패키지 이름이라면 중복으로 사용할 수 없습니다.
이름은 내가 만들 라이브러리를 가장 잘 표현하고 찾기 쉬운 이름을 생각해보세요.

 

npm info <Package Name>

 

 위 명령어를 사용하여 중복 확인을 해봐야 합니다.

 

중복된 이름이라면 이미 배포된 패키지의 정보를 확인할 수 있고,

중복되지 않은 이름이라면 정보가 없기에 404 에러가 발생합니다. 

✅ 404 에러가 나오면 생성할 수 있는 패키지 이름입니다. ✅

 

2. "description"

 

프로젝트 설명으로, 문자열로 기술합니다.
npm search로 검색된 리스트에 표시되기 때문에 사람들이 패키지를 찾아내고 이해하는 데 도움이 됩니다.

// 예시입니다
"description": "Very Very Awesome Component"

 

3. "version"

 

"version": "0.0.1"

 

우리 라이브러리의 버전을 명시하는 곳입니다.
버전은 기본적으로 major.minor.patch (0.0.1)를 사용합니다.

이미 라이브러리 개발이 완료되었고, 배포만을 남겨둔 상황이라면 1.0.0을 사용합니다.

아직 개발 중이고, 완벽하지 않다면 0.0.1을 지정하여 안정적인 버전이 아님을 명시합니다.

 

⚠️주의⚠️ 패키지를 수정한 후 npm에 배포할 때는 버전을 무조건 올려서 배포해야 합니다.
안 그러면 버전이 겹쳐있다고 에러가 뜹니다.

package.json의 version 명시하는 법이 더 알고 싶으시다면 참고하세요.

 

4. "private"

 

"private": false

 

중앙 저장소인 npm에 오픈 라이브러리로 배포하기 위해 private 옵션을 false로 변경해주세요.

 

5. "main"

 

"main": "dist/index.js"

 

 

라이브러리의 진입점 파일을 명시해주는 곳입니다.
저는 dist 폴더로 생성해서 배포할 것이기 때문에
dist 폴더에 있는 index.js 파일로 명시해주세요.
(typescript 파일은 tsc 명령어를 통해서 js로 변환됩니다.)

 

6. "types"

 

"types": "dist/index.d.ts"

 

타입 스크립트를 지원하기 위해서 타입 추론을 도와주는 진입점 파일을 명시해줍니다.

 

⚠️주의⚠️ package.json이 "files" 프로퍼티를 포함하고 있으면 "types" 프로퍼티는 무시됩니다.

이 경우 메인 선언 파일을 "files" 프로퍼티에 전달해야 합니다.

 

7. "browser"

 

"browser": "./browser/specific/main.js"

 

우리는 브라우저에서 구동되는 라이브러리를 제공해야 하기 때문에 browser 필드도 설정해야 합니다.

클라이언트(client-side) 사용을 위하는 경우 자바스크립트 번들러 또는 구성 요소 도구에 대한 힌트로 제공하기 위해 main 옵션(field) 대신에 사용해야 합니다.

 

8. "keywords"

 

본인의 패키지를 다른 사용자들이 검색할 때 참조되는 키워드입니다.

(해시태그# 같은 개념이라고 보시면 될 것 같습니다.)
description과 마찬가지로 npm search로 검색된 리스트에 표시됩니다.

 

// 예시입니다
"keywords" : ["react", "component", "library", "scroll"]

 

9. "scripts"

 

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "prepare": "rm -rf dist && mkdir dist && tsc"
  },

 

prepare 스크립트를 추가해놓아야 합니다.

 

1. rm -rf dist 명령어로 dist폴더를 삭제하고

2. mkdir dist 명령어로 다시 dist 폴더를 만들고

3. 다시 만들어진 폴더에 tsc 명령어로 컴파일을 진행해서 나온 파일들을 dist에 넣는 과정입니다.

 

npm 배포를 하기 전에 실행하는 명령어입니다.

 

10. "author"

 

"author": "eun-ji <eun_ji_zz@naver.com>",

 

프로젝트 작성자 정보로, 한 사람만을 지정합니다. 보통 Name <Email Address> 형식으로 작성합니다.

 

11. "repository"

 

프로젝트의 소스 코드를 저장한 저장소의 정보입니다.
소스 코드에 참여하고자 하는 사람들에게 도움이 될 수 있습니다.

✅ 프로젝트의 홈페이지 url을 명시해서는 안 됩니다.

 

// 예시입니다.
"repository" : {
	"type": "git",
    "url" : "git://gitbub.com/documentcloud/test.git"
 },

 

12. "license"

 

"license": "MIT",

 

배포하려는 라이브러리의 라이선스입니다.

자신의 라이브러리의 라이선스에 맞게 작성합니다. ex) MIT, ISC 등

라이선스에 키워드에 관해서 추가적인 사항은 참고 바랍니다.

 

🔆 .npmignore

 

npm에 배포하지 않을 파일을 명시해줍니다.

 

우리는 dist 폴더를 제외하고 나머지 src 폴더, public 폴더, tsconfig과 같은 것들은

우리 라이브러리에 포함시켜 라이브러리 크기를 키울 필요가 없습니다.

라이브러리에서 사용되지 않는 폴더나 파일은 이곳에서 명시합시다.

 

 

✅ 본인이 설정하고 싶은 것들만 설정하시면 됩니다.

아래의 폴더나 파일이 정답은 아닙니다.

 

node_modules/
src/
public/
tsconfig.json

 

🔆 개발 진행

 

라이브러리 개발 폴더는 lib으로  tsconfig.json에서 설정해놓았기 때문에
lib 폴더를 생성하고, 거기에 index.tsx 파일에 우리가 최종적으로 보내고자 하는 컴포넌트를 내보내면 됩니다.

 

🛠️ 개발 과정에서 CSS-in-JS가 아닌 CSS, SASS, SCSS를 사용한다면 여러가지 전처리(webpack)를 해주어야 하고,

개발시 라이브러리 안에서 사용하는 다른 라이브러리들과의 의존성(Dependencies)도 생각해야 합니다.

그리고 컴포넌트 라이브러리가 아닌 다른 편의성을 위한 라이브러리라면 여러 설정(검색해보시길..🧚‍♀️)도 바꿔주어야 합니다. 🛠️

 

📦src
 ┣ 📂lib
   ┣ 📂[Component]
   ┃ ┗ 📜index.tsx
   ┗ 📜index.tsx

 

폴더의 구조는 대략 이렇게 생겼고,

[Component] 내에 index.tsx 파일은 작성한 라이브러리 코드가 내보내지는 파일입니다.

그리고 여러 컴포넌트를 내보낼 가능성을 생각해, src/lib/index.tsx 파일을 추가로 만들고 최종적으로 컴포넌트를 내보내게끔 하였습니다.

 

 

 

필자의 경우에는 프로젝트 팀 이름으로 컴포넌트를 만들고 index.tsx 파일과 svg 파일을 담을 assets를 설정해두었습니다.

 

src/lib/index.tsx

그리고 src/lib/index.tsx 에는 export default를 해주었습니다. 

개발을 진행하면서 더 많은 컴포넌트가 생긴다면 src/lib/index.tsx 에 export 해주시면 됩니다.

 

🔆 개발 진행 시 참고하기

 

💡 타입스크립트에서 styled-components 사용 시,

 

// styled-components 가 설치가 안되어 있다면
npm i styled-components

 

// 타입스크립트 - 타입정의 받기
npm i -D @types/styled-components

 

기존 JavaScript에서 styled-components 사용하셨어도 TypeScript로 진행 시에는

타입 정의를 해주어야 합니다.

 

💡 타입스크립트에서 svg파일 import 문제 발생 시,

 

 

// custom.d.ts
declare module '*.svg' {
    import React = require('react');
    export const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
    const src: string;
    export default src;
  }

 

custom.d.ts 파일을 만들고 파일 내에서 모든 svg파일에 대해 속성을 설정해 줍니다.

 

 

그리고 ts 컴파일러가 ts|tsx 확장을 처리하도록 tsconfig.json 내에 "include" 속성에 custom.d.ts를 호출하도록 설정해줍니다.

 

💡 전처리가 필요한 SCSS, SASS와 같은 파일들은 Webpack 설정이 필요합니다.

 

디자인이 많이 요구되는 라이브러리라면 CRA로 프로젝트를 생성하는 것은 비추합니다.
CRA는 sass-loader가 내장되어 있기 때문에 로컬에서 테스트를 할 때는 모릅니다.
하지만 배포를 하고 나서 테스트를 해보면 sass 파일을 찾지 못한다고 에러를 뱉습니다.
sass, scss loader 같은 설정들을 webpack에 해주어야 하지만, CRA는 webpack 설정하기가 너무 힘듭니다.

 

 

🌱

이렇게 하면 우리는 npm에 라이브러리를 내보낼 준비가 되었습니다.

 

🔆 Build 및 NPM 배포 하기

 

우리가 만든 라이브러리를 빌드 후, NPM에 배포하는 방법을 진행하겠습니다.

 

NPM에 자신의 라이브러리를 배포하기 위해서는, 아래에 명령어를 사용하면 로그인을 하기 위한 절차가 실행됩니다.

 

npm login

 

Password 에는 암호화가 걸려있는건지.. 입력이 안되는것 처럼 보이지만 비밀번호 입력후 엔터 하면 Email로 넘어간댜..😮‍💨

 

NPM 계정의 정보를 입력하여 로그인합니다.

유저네임, 패스워드, 이메일 주소까지 입력한 후 해당 메일에 발송된 일회성 OTP 번호를 입력하시면 됩니다.

 

로그인을 하였다면 아래에 명령어를 실행하여 제대로 로그인되었는지 확인합니다.

 

npm whoami

 

로그인까지 완료되었다면 아래에 명령어를 통해 자신의 라이브러리를 NPM에 배포합니다.

 

npm publish

package.json내에 설정해두었던

"scripts": {
"prepare": "rm -rf dist && mkdir dist && tsc"
}

이 실행되면서 dist 폴더가 생성되고 컴파일을 진행해서 나온 파일들을 /dist에 넣어주는 과정도 진행되는 것을 볼 수 있습니다.

 

 

🐥 이렇게 해서 TypeScript로 NPM Package를 만들어 

자신의 Library를 생성부터_배포까지 하는 법을 진행해보았습니다. 🐥

 

🙅🏻‍♀️ 당연하지만 위의 과정들이 모든 라이브러리를 만들때 정답은 아닙니다. 🙅🏻‍♀️

 

 

🔆 Open Source Library 진행 시 중요한 것

 

✅ 공식문서

라이브러리를 만들면서 제일 중요시해야 하는 요소 중에 하나입니다.
공식문서가 잘 되어있다면, 다른 요소들은 따라서 오는 것이라고 생각합니다.

컴포넌트 라이브러리를 만들었다면 컴포넌트의 속성을 변경시키며 사용해볼 수 있는 공식문서를 만들어두고,

사용방법과 종류에 대해서도 설명을 잘해놓는다면 사용자가 쉽게 접근할 수 있을 것입니다.

 

✅ README.md

README 파일은 라이브러리의 얼굴입니다.

깃허브에서 사용자들이 라이브러리를 찾고, 맨 처음 보게 되는 것이 README 파일이기 때문에 각별히 신경을 써야 합니다.

자신의 라이브러리의 정체성을 잘 표현하고, 사용법과 설명을 적어두시면 되는데, 

작성하기 어렵다면 유명 라이브러리들의 README를 참고해서 작성을 해보시면 좋을 것 같습니다.

 

✅ 라이선스

위 package.json 작성에서도 언급해놓았지만, 라이선스는 '해야 할 것'과 '하지 말아야 할 것'에 대한 약속입니다.
오픈소스는 모두에게 공개되어 있기 때문에 이런 약속은 더더욱 중요합니다.

Github 문서에 의하면, 라이선스가 없으면 기본 저작권법이 적용되지만, 라이선스를 선택하게 됨으로써 코드의 모든 권리는 내가 가지고 다른 사람이 내 코드를 복제, 배포, 재생산을 할 수 없으니 오픈소스 프로젝트는 오픈소스 라이선스를 선택하라고 권장하고 있습니다.

참고: Github license의 종류와 나에게 맞는 라이선스 선택하기

 

✅ Contribute

오픈소스는 혼자 만들 때 보다, 같이 만들 때 그 가치가 더욱 빛납니다.

라이브러리를 만들 때 어떻게 하면 사람들이 기여하기 쉽게 구조를 짤지,
설명은 어떻게 할지, 어떻게 커뮤니티를 활성화시킬지에 대한 고민을 해보는 것도 중요할 것 같습니다.

혼자 해서 키워나가는 것보다는, 구조를 만들어놓고 사람들이 자발적으로 도와주도록 만들어 놓으면 내가 들이는 시간은 줄이면서 더욱 라이브러리를 단단하게 만들 수 있습니다.

 

 

 

 

❤️ 도움 주신 분 :

https://velog.io/@junghyeonsu/NPM-%EB%B0%B0%ED%8F%AC-%EC%96%B4%EB%A0%B5%EC%A7%80-%EC%95%8A%EC%95%84%EC%9A%94-with-%ED%85%8C%EC%98%A4-%EA%B5%AC%EA%B8%80-%EC%8A%A4%ED%94%84%EB%A6%B0%ED%8A%B8-4%EA%B8%B0

https://choi95.tistory.com/206