패키지 만들어서 NPM에 배포해보기

sham·2024년 10월 28일
Reactnpm
0

SkyScope 개발일지

목록 보기
11/12

다음 토이프로젝트의 개발 기록이다.

배포한 패키지는 ultra-exact-ncst라는 이름으로 npm에 배포되어 있다.

개요

기상청 API와 카카오 API를 서로 조합해서 파싱해야만 의도한 대로 작동하는 이 불편함을, 나말고 다른 사람도 겪지 않았을까 하는 생각이 들었다. 그래서 패키지를 만들어서 배포해보면 어떨까 하는 생각이 들었다.

과정

npm 설치 및 세팅

npm init
npm i axios
npm i typescript -D
npx tsc --init

tsconfig.json 세팅 - 컴파일 설정

tsconfig.json 파일에 어떤 방식으로, 어떤 경로로 컴파일 할지를 지정한다.

tsc 명령어를 실행하면 include의 경로의 파일의 ts 파일을 outDir 경로에 지정한 곳으로 컴파일해준다. (일반적으로 dist 디렉토리에 배치)

{
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig to read more about this file */
    /* Language and Environment */
    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
   
    /* Modules */
    "module": "commonjs",                                /* Specify what module code is generated. */
    "rootDir": "./src",                                  /* Specify the root folder within your source files. */

    /* Emit */
    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
     "resolveJsonModule": true,
    "declaration": true,                                 /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
    /* Interop Constraints */
   "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */

    /* Type Checking */
    "strict": true,                                      /* Enable all strict type-checking options. */
    
    /* Completeness */
    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
  },
  "include": ["src/**/*.ts"], // 포함할 파일 경로
  "exclude": ["node_modules"] // 제외할 파일 경로
}

package.json 세팅

package.json에 files가 있다면 해당 필드에 포함된 경로의 파일들만 배포하게 된다. files가 없다면 .npmignore에 있는 경로나 파일을 제외한 모든 파일이 배포된다.

node_modules가 배포될 수 있는 대참사를 방지하기 위해 files를 지정해서 dist 디렉토리의 파일들만 배포하게 해주자.

{
  "name": "ultra-exact-ncst",
  "version": "0.0.3",
  "description": "nowcast with coordinate",
  "main": "dist/index.js",
  "type": "commonjs",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "npx ts-node src/index.ts"
  },
  "author": "GulSam00",
  "license": "ISC",
  "dependencies": {
    "axios": "^1.7.7"
  },
  "devDependencies": {
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3"
  },
  "files": [
    "dist/**/*"
  ]
}

tsc로 build 해보기

tsc 명령어를 실행하면 tsconfig에서 세팅한 설정 값대로 dist 디렉토리 안에 ts 파일들이 js로 컴파일되어서 배포되는 것을 볼 수 있을 것이다. 배포한다면 package.json에서 files에 설정해둔 dist 디렉토리의 내용물만이 패키지로 배포되게 된다.

npm 회원 가입 후 세팅

패키지를 만들기에 앞서서 npm 상에 패키지를 올릴 수 있도록 터미널 상에서 로그인을 진행해주자.

npm | Home

위의 사이트에서 npm 계정을 생성한 후, 터미널로 npm에 로그인을 한다.

npm login

로그인을 마쳤으면 현재 디렉토리를 배포하는 것이 가능해진다. package.json에 작성한 정보를 기반으로 동일한 이름의 package가 올라간다.

npm publish

dist에 있는 파일만 잘 배포된 것을 확인할 수 있다!

이후 npm publish로 재배포를 할 때, 이전에 배포한 버전보다 높은 버전으로 설정해줘야 한다.

동작 테스트

다음과 같은 패키지 내용을 담는 index.ts 파일을 생성하고, 

import {hello} from './getExactNcst';
import sum from './sum';
import {hi, bye} from './twoFunc';

export {hello, sum, hi, bye};

새로운 폴더에서 배포한 패키지를 다운받아 준다.

npm i ultra-exact-ncst
import { hello, hi, bye, sum } from 'ultra-exact-ncst';

hello();
hi();
bye();
console.log(sum(2, 3));

이제 우리는 패키지를 배포하고, 배포한 패키지를 받아서 사용할 수 있게 되었다!

(선택) 버전 관리 툴

달라진 버전을 publish 하더라도 사용할 때 업데이트를 하지 않으면 반영되지 않는다.

ncu 툴을 사용하면 편리하게 최신 버전들로 버전을 바꿔준다.

npm install -g npm-check-updates
ncu -u
npm i

모듈 작성

기존 프로젝트에 작성한 API 요청 로직을 그대로 가져왔다.

import axios from 'axios';
import { format, getMinutes, subHours } from 'date-fns';
import _code_local from './short_api_code.json' assert { type: 'json' };

interface ICodeCoordJson {
  code: number;
  address_name: string;
  depth1: string;
  depth2: string;
  depth3: string;
  x: number;
  y: number;
}

export interface GetNcstRequestTypes {
  x: number;
  y: number;
  kakaoKey?: string;
  ncstKey?: string;
}

export interface WeatherData {
  baseDate: string; // 예: '20241023'
  baseTime: string; // 예: '2100'
  category: string; // 예: 'PTY', 'REH', 'RN1', 'T1H', 'UUU', 'VEC', 'VVV', 'WSD'
  nx: number; // 예: 56
  ny: number; // 예: 112
  obsrValue: string; // 예: '62', '-1.1', '2.6'
}

export type GetNcstResponseTypes = WeatherData[];

const code_local = _code_local as ICodeCoordJson[]; // 타입 정의는 유지

const kakaoURL = 'http://dapi.kakao.com/v2/local';
const ncstURL = 'https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0';

export const getNcst = async ({ x, y, ncstKey }: GetNcstRequestTypes): Promise<GetNcstResponseTypes | undefined> => {
  const url = ncstURL + '/getUltraSrtNcst';

  if (!x || !y) throw new Error('좌표값이 유효하지 않습니다.');
  if (!ncstKey) throw new Error('API 키가 필요합니다.');
  const params = {
    serviceKey: ncstKey,
    dataType: 'JSON',
    base_date: '',
    base_time: '',
    numOfRows: '1000',
    nx: 0,
    ny: 0,
  };

  let base_date = new Date();
  const date = format(base_date, 'yyyyMMdd');
  if (getMinutes(base_date) <= 10) base_date = subHours(base_date, 1);
  const hour = format(base_date, 'HH');
  params.base_date = date;
  params.base_time = hour + '00';
  params.nx = x;
  params.ny = y;

  try {
    const result = await axios.get(url, { params });
    const data: GetNcstResponseTypes = result.data.response.body.items.item;
    return data;
  } catch (e) {
    let message;
    if (e instanceof Error) message = e.message;
    else message = String(e);
    console.error(message);
    return undefined;
  }
};

export const getKakaoLocal = async ({ x, y, kakaoKey }: GetNcstRequestTypes): Promise<ICodeCoordJson | undefined> => {
  const url = kakaoURL + '/geo/coord2regioncode';

  if (!kakaoKey) throw new Error('API 키가 필요합니다.');

  try {
    const result = await axios.get(url, {
      params: {
        x,
        y,
      },
      headers: {
        Authorization: `KakaoAK ${kakaoKey}`,
      },
    });

    const document = result.data.documents[1];
    const { code, region_3depth_name } = document;
    const parsedLocal = code_local.find(item => item.code === Number(code));
    if (!parsedLocal) {
      const depth3Local = code_local.find(item => item.depth3 === region_3depth_name);
      return depth3Local;
    }
    return parsedLocal;
  } catch (e) {
    let message;
    if (e instanceof Error) message = e.message;
    else message = String(e);
    console.error(message);
    return undefined;
  }
};

export const getKakaoNcst = async ({
  x,
  y,
  kakaoKey,
  ncstKey,
}: GetNcstRequestTypes): Promise<GetNcstResponseTypes | undefined> => {
  const local = await getKakaoLocal({ x, y, kakaoKey });

  if (!local) throw new Error('지역 정보를 가져올 수 없습니다.');
  if (!ncstKey) throw new Error('API 키가 필요합니다.');

  try {
    return getNcst({ x: local.x, y: local.y, ncstKey });
  } catch (e) {
    let message;
    if (e instanceof Error) message = e.message;
    else message = String(e);
    console.error(message);
    return undefined;
  }
};

모듈 확인

import { getKakaoNcst, getKakaoLocal, getNcst } from 'ultra-exact-ncst';
import dotenv from 'dotenv';
dotenv.config();

const kakaoKey = process.env.KAKAO_KEY;
const ncstKey = process.env.NCST_KEY;

const kakaoLocalResult = await getKakaoLocal({ x: 126.65955373649118, y: 37.42760161347335, kakaoKey });
const kakaoNcstResult = await getKakaoNcst({ x: 126.65955373649118, y: 37.42760161347335, kakaoKey, ncstKey });

const ncstResult = await getNcst({x : 54, y : 124, ncstKey});

console.log("kakaoLocalResult", kakaoLocalResult);
console.log("kakaoNcstResult", kakaoNcstResult);
console.log("ncstResult", ncstResult);

d.ts 파일 생성

만들었던 패키지는 TS로 만들었지만, 배포하는 과정에서 JS로 컴파일되기 때문에 패키지를 사용하는 단이 TS 환경이라면 type이 지정되지 않다며 에러를 뱉게 된다.

해당 패키지의 타입을 담는 @types라는 패키지를 따로 만드는 방법도 있지만, d.ts 파일을 생성해서 타입을 추론하게끔 할 수도 있다.

tsconfig.json 파일의 compilerOptions에 다음 옵션을 추가하자.

declaration는 ts 파일의 d.ts 파일을 자동으로 생성하고, Map 관련 옵션은 소스맵으로 IDE 상에서 해당 모듈의 원본을 추적할 수 있게 해준다.

"declaration": true,                                 /* .d.ts 파일을 자동으로 생성한다. */
"declarationMap": true,                              /* d.ts 파일에 대한 소스맵을 생성한다. */
"sourceMap": true,                                   /* 소스맵을 생성한다. */

최종 세팅

package.json

{
  "name": "ultra-exact-ncst",
  "version": "1.1.2",
  "description": "nowcast with coordinate",
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "npx ts-node src/index.ts"
  },
  "author": "GulSam00",
  "license": "ISC",
  "Keywords"  : ["nowcast", "coordinate"],
  "dependencies": {
    "axios": "^1.7.7",
    "date-fns": "^4.1.0"
  },
  "devDependencies": {
    "dotenv": "^16.4.5",
    "prettier": "^3.3.3",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3"
  },
  "files": [
    "dist/**/*"
  ]
}

tsconfig.json

{
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig to read more about this file */
    /* Language and Environment */
    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
   
    /* Modules */
    "module": "ESNext",                                /* Specify what module code is generated. */
    "moduleResolution": "node",                          /* Specify how TypeScript looks up a file from a given module specifier. */
    "rootDir": "./src",                                  /* Specify the root folder within your source files. */
    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */

    /* Emit */
    "resolveJsonModule": true,                           /* Include modules imported with .json extension. */
    "declaration": true,                                 /* .d.ts 파일을 자동으로 생성한다. */
    "declarationMap": true,                              /* d.ts 파일에 대한 소스맵을 생성한다. */
    "sourceMap": true,                                   /* 소스맵을 생성한다. */
    
    /* Interop Constraints */
   "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */

    /* Type Checking */
    "strict": true,                                      /* Enable all strict type-checking options. */
    
    /* Completeness */
    "skipLibCheck": false                                 /* Skip type checking all .d.ts files. */
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

에러 핸들링

JSON import 관련 이슈

JSON 모듈을 가져오려면 tsconfig.json에서 "resolveJsonModule": true 를 추가해줘야 한다.

json 확장자 파일로 import 할 수 있게끔 해준다.

프로젝트에서 패키지 사용하고 build 시 - Matched by default include pattern '*/’

프로젝트의 tsconfig.json에 "include": ["src/*/"]를 추가해준다.

레퍼런스

npm 에 내가 만든 패키지 배포하기 (feat. github action 으로 배포 자동화)

npm 에 내가만든 패키지 배포하기 - (0) : 프로젝트 세팅 가이드

[tsconfig의 모든 것] Compiler options / Emit

npm에 라이브러리 배포하기!

힘들었던 점

  • 어떻게 패키지 배포해야 하지?
  • 직접 패키지 세팅하고, dist에 넣어주고, ts 쓸꺼면 config도 손 봐주고,
  • ESM(module), CommonJS 방식. 뭐가 다르고 어떻게 설정해야 하지?
  • d.ts 파일 세팅. 그냥 tsconfig에 "declaration": true 설정해주면 됐었다...
profile
sham
씨앗 개발자
이전 포스트

Firebase 적용해보기

다음 포스트

React useCallback 의존성 관리로 인해 벌어질 수 있는 상태 갱신 이슈

0개의 댓글

관련 채용 정보