빠른 시작

관련 소스 파일

이 페이지의 내용은 다음 소스 파일을 기반으로 생성되었습니다:

• README.md
• package.json
• .npmignore
• docs/usage.md
• docs/ko/usage.md
• src/index.ts
• src/map/index.ts
• src/set/index.ts
• src/math/index.ts
• src/util/index.ts

es-toolkit은 현대적인 JavaScript 환경에서 최적의 성능을 발휘하도록 설계된 고성능 유틸리티 라이브러리입니다. 작은 번들 사이즈와 강력한 TypeScript 타입 지원을 제공하며, Lodash와 같은 기존 라이브러리를 대체할 수 있는 호환성 계층도 포함하고 있습니다 (README.md:7-16).

es-toolkit 소개

es-toolkit은 다양한 일상 유틸리티 함수를 현대적인 구현으로 제공합니다. debounce, delay, chunk, sum, pick과 같은 함수들을 포함하고 있으며, 현대 JavaScript 환경에서 2-3배 더 나은 성능을 달성했습니다 (src/index.ts:1-14).

이 라이브러리의 핵심 장점은 다음과 같습니다:

• 성능: 현대 JavaScript 환경에서 2-3배 향상된 성능 제공
• 번들 사이즈: 다른 라이브러리 대비 최대 97%까지 JavaScript 코드 감소
• Tree Shaking: 기본적으로 tree shaking 지원
• TypeScript: 강력하고 직관적인 타입 지원
• 테스트 커버리지: 100% 테스트 커버리지로 검증된 신뢰성

설치 방법

Node.js 환경

es-toolkit은 Node.js 18 이상 버전을 지원합니다. npm, pnpm, yarn을 통해 설치할 수 있습니다 (docs/ko/usage.md:17-35).

npm 사용 시:

bash
1npm install es-toolkit

pnpm 사용 시:

bash
1pnpm add es-toolkit

yarn 사용 시:

bash
1yarn add es-toolkit

Deno 환경

Deno에서는 JSR(JavaScript Registry)을 통해 es-toolkit을 설치할 수 있습니다. JSR의 제한으로 인해 npm과 달리 추가적인 scope가 필요합니다 (docs/ko/usage.md:45-67).

bash
1deno add @es-toolkit/es-toolkit

Bun 환경

Bun에서도 es-toolkit을 사용할 수 있습니다:

bash
1bun add es-toolkit

기본 사용법

es-toolkit의 함수를 사용하려면 필요한 함수를 import하여 사용하면 됩니다. 예를 들어, 배열의 합계를 구하는 sum 함수는 다음과 같이 사용합니다 (docs/ko/usage.md:37-43).

typescript
1import { sum } from 'es-toolkit';
2
3sum([1, 2, 3]); // 결과: 6

더 복잡한 예제로, debounce와 chunk 함수를 조합하여 사용할 수 있습니다 (README.md:19-35).

typescript
1import { chunk, debounce } from 'es-toolkit';
2
3const debouncedLog = debounce(message => {
4  console.log(message);
5}, 300);
6
7// 이 호출은 debounce됩니다
8debouncedLog('Hello, world!');
9
10const array = [1, 2, 3, 4, 5, 6];
11const chunkedArray = chunk(array, 2);
12
13console.log(chunkedArray);
14// 출력: [[1, 2], [3, 4], [5, 6]]

브라우저에서 사용하기

CDN 사용

브라우저 환경에서는 CDN을 통해 es-toolkit을 직접 사용할 수 있습니다. jsdelivr와 unpkg 같은 CDN에서 제공되며, Lodash와 마찬가지로 _ 변수에 모든 함수가 포함됩니다 (docs/ko/usage.md:69-89).

jsdelivr 사용 시:

html
1<script src="https://cdn.jsdelivr.net/npm/es-toolkit@%5E1"></script>
2<script>
3  var arr = _.chunk([1, 2, 3, 4, 5, 6], 3);
4</script>

unpkg 사용 시:

html
1<script src="https://unpkg.com/es-toolkit@%5E1"></script>
2<script>
3  var arr = _.chunk([1, 2, 3, 4, 5, 6], 3);
4</script>

ESM 사용

현대적인 브라우저에서는 esm.sh를 통해 ES 모듈 방식으로 사용할 수 있습니다 (docs/ko/usage.md:91-110).

html
1<script type="importmap">
2  {
3    "imports": {
4      "es-toolkit": "https://esm.sh/es-toolkit@%5E1"
5    }
6  }
7</script>
8<script type="module">
9  import { chunk } from 'es-toolkit';
10
11  chunk([1, 2, 3, 4, 5, 6], 3);
12</script>

제공 모듈 구성

es-toolkit은 기능별로 모듈화되어 있어 필요한 기능만 선택적으로 import할 수 있습니다. 주요 모듈 카테고리는 다음과 같습니다 (src/index.ts:15-26).

패키지 구조상 각 모듈은 별도의 진입점을 통해 import할 수 있습니다 (package.json:14-28).

typescript
1// 전체 import
2import { sum } from 'es-toolkit';
3
4// 특정 모듈만 import (tree shaking 최적화)
5import { sum } from 'es-toolkit/math';
6import { debounce } from 'es-toolkit/function';
7import { chunk } from 'es-toolkit/array';

실행 검증

설치가 올바르게 완료되었는지 확인하려면 간단한 스크립트를 실행해 볼 수 있습니다.

검증 스크립트 (verify.ts):

typescript
1import { sum, chunk, debounce } from 'es-toolkit';
2
3// sum 함수 테스트
4const sumResult = sum([1, 2, 3, 4, 5]);
5console.log('sum 결과:', sumResult); // 예상 출력: 15
6
7// chunk 함수 테스트
8const chunkResult = chunk([1, 2, 3, 4, 5, 6], 2);
9console.log('chunk 결과:', chunkResult); // 예상 출력: [[1, 2], [3, 4], [5, 6]]
10
11console.log('es-toolkit이 정상적으로 설치되었습니다!');

실행 방법:

bash
1# Node.js 환경
2npx tsx verify.ts
3
4# 또는 ts-node 사용 시
5npx ts-node verify.ts

환경 요구사항

es-toolkit을 사용하기 위한 환경 요구사항은 다음과 같습니다:

패키지는 sideEffects: false로 설정되어 있어 webpack과 같은 번들러에서 tree shaking이 완벽하게 작동합니다 (package.json:12).

Lodash 호환성 계층

es-toolkit은 Lodash에서 완전히 마이그레이션할 수 있도록 호환성 계층인 es-toolkit/compat을 제공합니다. 이를 통해 기존 Lodash 코드를 큰 변경 없이 es-toolkit으로 교체할 수 있습니다 (README.md:12).

typescript
1// Lodash 호환 모드 사용
2import { map, filter, find } from 'es-toolkit/compat';
3
4// 또는 특정 함수만
5import get from 'es-toolkit/compat/get';

일반적인 문제와 해결 방법

문제 1: Tree Shaking이 작동하지 않음

증상: 번들 사이즈가 예상보다 큼

해결 방법:

• 패키지 이름이 정확한지 확인 (es-toolkit vs @es-toolkit/es-toolkit)
• 특정 모듈 경로를 사용하여 import (예: es-toolkit/math)
• 번들러 설정에서 ES 모듈 형식을 사용 중인지 확인

문제 2: TypeScript 타입 오류

증상: import 시 타입을 찾을 수 없음

해결 방법:

• TypeScript 버전이 5.0 이상인지 확인
• tsconfig.json에서 moduleResolution이 node16 또는 bundler로 설정되어 있는지 확인
• node_modules 삭제 후 재설치

bash
1rm -rf node_modules
2npm install

문제 3: Deno에서 import 오류

증상: 패키지를 찾을 수 없음

해결 방법: Deno에서는 JSR scope가 필요합니다. npm 패키지 이름이 아닌 JSR 패키지 이름을 사용해야 합니다.

typescript
1// 잘못됨
2import { sum } from 'es-toolkit';
3
4// 올바름
5import { sum } from '@es-toolkit/es-toolkit';

다음 단계

es-toolkit의 기본 설치와 사용법을 익혔으므로, 이제 다음 단계로 나아갈 수 있습니다:

1. API 레퍼런스 탐색: 각 함수의 상세 사용법과 매개변수는 API 문서에서 확인할 수 있습니다.
2. 성능 비교: 다른 라이브러리와의 성능 비교 결과를 통해 es-toolkit의 장점을 확인할 수 있습니다.
3. 번들 사이즈 분석: 프로젝트에서 실제로 얼마나 번들 사이즈를 절약할 수 있는지 분석해 보세요.
4. Lodash 마이그레이션: 기존 Lodash 프로젝트를 es-toolkit으로 마이그레이션하는 방법을 알아보세요.

공식 문서(https://es-toolkit.dev)에서 더 자세한 정보와 예제를 확인할 수 있습니다 (package.json:5).