Quick Start

Source Files

This page is generated from the following source files:

• README.md
• package.json
• docs/usage.md
• docs/intro.md
• benchmarks/performance/padStart.bench.ts
• benchmarks/performance/startCase.bench.ts
• benchmarks/performance/trimStart.bench.ts
• benchmarks/performance/startsWith.bench.ts
• benchmarks/performance/eq.bench.ts
• benchmarks/performance/gt.bench.ts

es-toolkit is a state-of-the-art, high-performance JavaScript utility library designed for modern development workflows. It provides a comprehensive collection of everyday utility functions with a focus on performance, small bundle size, and excellent TypeScript support.

What is es-toolkit

es-toolkit serves as a modern alternative to traditional utility libraries like lodash, offering significantly improved performance and reduced bundle size. The library achieves 2-3× better performance in modern JavaScript environments compared to alternatives, while reducing JavaScript code by up to 97% through effective tree shaking support (README.md:7-16).

The library is built with TypeScript from the ground up, providing straightforward yet robust type definitions. It includes useful type guards such as isNotNil and maintains 100% test coverage, ensuring reliability and robustness for production applications. es-toolkit is trusted by popular open-source projects including Storybook, Recharts, ink, and CKEditor (README.md:7-16).

Key advantages include modern implementations leveraging the latest JavaScript features, built-in TypeScript support, and a complete compatibility layer (es-toolkit/compat) for seamless migration from lodash. The library offers utilities across multiple categories including array manipulation, function control, math operations, object manipulation, predicates, promises, and string utilities (docs/intro.md:1-8).

Installation

es-toolkit supports multiple runtime environments and package managers, making it accessible for various project configurations.

Node.js Environment

For Node.js projects, es-toolkit requires Node.js 18 or later. The package is available through npm and can be installed using any major package manager (docs/usage.md:17-44):

bash
1# Using npm
2npm install es-toolkit
3
4# Using pnpm
5pnpm add es-toolkit
6
7# Using yarn
8yarn add es-toolkit

After installation, functions can be imported directly from the main package:

typescript
1import { sum } from 'es-toolkit';
2
3sum([1, 2, 3]);

Deno Runtime

For Deno projects, es-toolkit is distributed via JSR (JavaScript Registry). Note that the package name includes an additional scope (@es-toolkit) as required by JSR conventions (docs/usage.md:45-68):

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

Import syntax for Deno:

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

Bun Runtime

Bun users can install es-toolkit directly through the Bun package manager (docs/usage.md:45-68):

bash
1bun add es-toolkit

Browser Usage

For browser-based projects, es-toolkit is available through multiple CDN providers. The library exposes a global _ variable containing all functions, similar to Lodash's convention (docs/usage.md:69-110).

Using jsdelivr CDN:

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>

Using unpkg CDN:

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>

Using esm.sh for modern ES modules:

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>

Basic Usage

es-toolkit provides a clean, intuitive API for importing and using utility functions. The library supports tree shaking out of the box, ensuring only imported functions are included in the final bundle.

Simple Import Pattern

Functions are imported directly from the main es-toolkit package, with TypeScript types automatically included (docs/usage.md:37-44):

typescript
1import { sum } from 'es-toolkit';
2
3sum([1, 2, 3]);

Practical Examples

The library offers a variety of everyday utility functions with modern implementations. Here's an example demonstrating the debounce and chunk functions (README.md:19-35):

typescript
1import { chunk, debounce } from 'es-toolkit';
2
3// Debounce example - delays function execution
4const debouncedLog = debounce(message => {
5  console.log(message);
6}, 300);
7
8// This call will be debounced
9debouncedLog('Hello, world!');
10
11// Chunk example - splits array into smaller arrays
12const array = [1, 2, 3, 4, 5, 6];
13const chunkedArray = chunk(array, 2);
14
15console.log(chunkedArray);
16// Output: [[1, 2], [3, 4], [5, 6]]

Module-Specific Imports

For optimal tree shaking, functions can also be imported from specific category modules (package.json:14-28):

typescript
1// Import from specific modules
2import { debounce } from 'es-toolkit/function';
3import { chunk } from 'es-toolkit/array';
4import { sum } from 'es-toolkit/math';
5import { pick } from 'es-toolkit/object';

Available Modules

es-toolkit organizes its utilities into logical modules, allowing developers to import only what they need. The package structure supports both main entry point imports and module-specific imports for optimal bundle size (package.json:14-28).

Module Categories

(docs/intro.md:9-20)

Compatibility Layer

For projects migrating from lodash, es-toolkit provides a complete compatibility layer accessible via es-toolkit/compat. This layer allows seamless replacement of lodash functions while benefiting from es-toolkit's performance improvements (package.json:14-28):

typescript
1// Using the compatibility layer
2import { padStart } from 'es-toolkit/compat';
3import { startCase } from 'es-toolkit/compat';

The compatibility layer is particularly useful during incremental migrations, allowing teams to adopt es-toolkit without rewriting existing code that depends on lodash-specific behavior.

Verification and Testing

After installation, verify that es-toolkit is working correctly by running a simple test.

Basic Verification

Create a test file to verify the installation:

typescript
1// test-es-toolkit.ts
2import { sum, chunk, debounce } from 'es-toolkit';
3
4// Test sum function
5console.log('Sum:', sum([1, 2, 3, 4, 5])); // Expected: 15
6
7// Test chunk function
8console.log('Chunk:', chunk([1, 2, 3, 4, 5, 6], 2)); 
9// Expected: [[1, 2], [3, 4], [5, 6]]
10
11// Test debounce function
12const debouncedLog = debounce((msg: string) => console.log('Debounced:', msg), 100);
13debouncedLog('test');

TypeScript Verification

For TypeScript projects, verify that type definitions are properly resolved:

typescript
1import { isNotNil } from 'es-toolkit';
2
3const values: (string | null | undefined)[] = ['a', null, 'b', undefined, 'c'];
4const filtered = values.filter(isNotNil);
5// TypeScript correctly infers filtered as string[]
6console.log(filtered); // ['a', 'b', 'c']

Running Tests

If contributing to the project or running the test suite locally, use the following command (package.json:51-62):

bash
1# Run tests with coverage and type checking
2yarn test
3
4# Or using npm
5npm test

The test command executes vitest with coverage and typecheck enabled, ensuring both runtime correctness and type safety.

Common Issues and Troubleshooting

Issue 1: Import Resolution Errors

Problem: TypeScript or bundler cannot resolve es-toolkit imports.

Solution: Ensure the package is properly installed and check tsconfig.json module resolution settings:

json
1{
2  "compilerOptions": {
3    "moduleResolution": "bundler",
4    "esModuleInterop": true
5  }
6}

For Node.js projects using CommonJS, ensure the appropriate module format is selected. es-toolkit provides both ESM (index.mjs) and CommonJS (index.js) outputs (package.json:103-118).

Issue 2: Tree Shaking Not Working

Problem: Bundle size is larger than expected, indicating tree shaking is not functioning correctly.

Solution: Verify that the bundler is configured to support tree shaking:

1. Ensure sideEffects: false is recognized by the bundler (package.json:1-13)
2. Use ES module imports (not CommonJS require)
3. For webpack, ensure mode: 'production' is set
4. For Rollup, verify that treeshake option is enabled

javascript
1// Correct - supports tree shaking
2import { debounce } from 'es-toolkit';
3
4// Avoid - may prevent tree shaking
5const { debounce } = require('es-toolkit');

Issue 3: Node.js Version Incompatibility

Problem: Installation or runtime errors related to Node.js version.

Solution: es-toolkit requires Node.js 18 or later (docs/usage.md:17-44). Check the current Node.js version:

bash
1node --version

If using an older version, upgrade Node.js or use a version manager like nvm:

bash
1# Using nvm
2nvm install 18
3nvm use 18

Issue 4: Lodash Compatibility Issues

Problem: Functions from es-toolkit/compat behave differently than lodash equivalents.

Solution: The compatibility layer covers most lodash use cases but may have subtle differences. Check the compatibility documentation for known differences. For critical production code:

1. Review the specific function documentation
2. Run comparative tests during migration
3. Report any discrepancies as GitHub issues

Issue 5: CDN Loading in Browsers

Problem: CDN scripts fail to load or _ global is undefined.

Solution: Ensure the correct CDN URL format is used. The @%5E1 in the URL represents @^1 (version range) (docs/usage.md:69-110):

html
1<!-- Correct -->
2<script src="https://cdn.jsdelivr.net/npm/es-toolkit@%5E1"></script>
3
4<!-- Alternative with specific version -->
5<script src="https://cdn.jsdelivr.net/npm/es-toolkit@1.45.1"></script>

For modern ES module usage, prefer the esm.sh approach with import maps for better tree shaking and module resolution.

Next Steps

After successfully installing and verifying es-toolkit, explore the following resources to maximize the library's potential:

Explore Function Reference

Browse the complete function reference documentation to discover all available utilities organized by category. Each function includes detailed usage examples, TypeScript signatures, and performance comparisons.

Performance Benchmarks

Review the performance benchmarks to understand the performance gains compared to lodash and other utility libraries. The benchmark suite covers functions like padStart, startCase, trimStart, startsWith, eq, and gt (benchmarks/performance/padStart.bench.ts:1-18, benchmarks/performance/startCase.bench.ts:1-34).

Bundle Size Analysis

Visit the bundle size comparison to see how es-toolkit reduces JavaScript bundle size by up to 97% compared to alternatives through effective tree shaking and modern implementation strategies.

Migration Guide

For projects currently using lodash, refer to the compatibility layer documentation for step-by-step migration instructions. The es-toolkit/compat package provides a seamless transition path while leveraging es-toolkit's performance benefits.

Community and Support

• GitHub Repository: https://github.com/toss/es-toolkit
• Discord Community: Join the discussion
• NPM Package: https://www.npmjs.com/package/es-toolkit
• JSR Package: https://jsr.io/@es-toolkit/es-toolkit