날다람쥐

Posted on May 30

date-light: A 1.8KB Alternative to date-fns You Might Actually Like

#typescript #javascript #npm #opensource

If you've ever shipped a frontend app and watched your bundle bloat because of date utilities, you're not alone. date-fns is fantastic — but importing 20 functions costs you 18 KB. dayjs is lighter at 3 KB, but it wraps every Date in a mutable object.

I wanted something different: pure functions, zero dependencies, and a bundle so small you forget it's there.

That's date-light.

What is it?

date-light is a zero-dependency, fully typed date utility library for JavaScript and TypeScript. It covers the 20 most-used date-fns operations with 39 functions — and the entire thing weighs 1.79 KB minzipped.

npm install date-light

import { format, addDays, differenceInDays, isBefore, startOfDay } from "date-light";

const date = new Date(2026, 5, 30, 14, 30, 45);

format(date, "yyyy-MM-dd HH:mm:ss"); // "2026-06-30 14:30:45"
addDays(date, 7); // Tue Jul 07 2026
differenceInDays(date, new Date(2026, 0, 1)); // 180
isBefore(date, new Date()); // true
startOfDay(date); // Mon Jun 30 2026 00:00:00

Same pattern syntax as date-fns. Most projects can migrate with a single import change.

Why not just use date-fns?

You absolutely can, and if you need all 252 functions, you should. But for most projects, you use maybe 15-20. Here's what that costs:

Library	minzipped	What you get
date-light	1.79 KB	39 functions, fully tree-shakeable
dayjs	2.97 KB	Core only (plugins add more)
date-fns (20 functions)	18.34 KB	Just the 20 most-used functions
date-fns (full)	261.3 KB	All 252 functions

That's a 10x size difference for the same functionality most people actually use.

How fast is it?

Benchmarks on Node.js 24 — nanoseconds per operation (lower = better):

vs date-fns v4

Function	date-light	date-fns
`format`	668 ns	1,495 ns	2.2x faster
`parseISO`	138 ns	1,218 ns	8.8x faster
`differenceInDays`	117 ns	946 ns	8.1x faster
`isWeekend`	4 ns	39 ns	9.8x faster
`isLeapYear`	5 ns	41 ns	8.2x faster
`startOfDay`	47 ns	49 ns	~same

vs dayjs v1

Function	date-light	dayjs
`addDays`	80 ns	642 ns	8x faster
`addMonths`	133 ns	2,067 ns	15.5x faster
`isBefore`	56 ns	531 ns	9.5x faster

Why so fast? date-light calls native Date methods directly. No wrapper objects (dayjs), no shared internal modules (date-fns). Pure functions with zero overhead.

What's included?

Format & Parse: format, parseISO, parse

Add & Subtract: addDays, addMonths, addYears, addHours, addMinutes, addSeconds, subDays, subMonths, subYears, subHours, subMinutes, subSeconds

Difference: differenceInDays, differenceInHours, differenceInMinutes, differenceInSeconds, differenceInMonths, differenceInYears

Compare: isBefore, isAfter, isEqual, isSameDay, isSameMonth

Query: isWeekend, isLeapYear, isValid, getDaysInMonth, getWeekOfYear

Start & End: startOfDay, endOfDay, startOfWeek, endOfWeek, startOfMonth, endOfMonth, startOfYear, endOfYear

Design decisions

date-fns compatible pattern syntax. yyyy-MM-dd, not YYYY-MM-DD. If you're migrating from date-fns, most code works as-is.

Pure functions, immutable. Every function returns a new Date. No mutation, no surprises.

Named exports only. No default export, no class instances. Tree-shaking works perfectly out of the box.

Month clamping matches date-fns. addMonths(new Date(2026, 0, 31), 1) returns Feb 28, not Mar 3. Same behavior you'd expect.

Calendar days vs physical time. addDays uses calendar-day semantics (preserves time-of-day across DST). addHours uses physical time (exact N hours later). This is the correct behavior — and it's what date-fns does too.

Migration from date-fns

One import change:

- import { format, addDays, differenceInDays } from 'date-fns';
+ import { format, addDays, differenceInDays } from 'date-light';

That's it. Same function names, same arguments, same pattern tokens.

DEV Community