Most frontend and Node.js apps need date utilities.
But in many projects, the actual needs are pretty small:
- format a date
- parse an ISO string
- add a few days or months
- compare two dates
- get the start or end of a day/week/month
- check weekends or leap years
For those common cases, pulling in a larger date library can feel heavier than necessary.
So I built date-light.
What is date-light?
date-light is a small, zero-dependency date utility library for TypeScript and JavaScript.
It provides 39 common date helpers in about 2.18KB minzipped.
npm install date-light
ts
import { addDays, differenceInDays, format, startOfWeek } from "date-light";
const launch = new Date(2026, 5, 30, 14, 30);
const reminder = addDays(launch, -7);
format(launch, "yyyy-MM-dd HH:mm");
// "2026-06-30 14:30"
format(startOfWeek(launch), "yyyy-MM-dd");
// "2026-06-29"
differenceInDays(launch, reminder);
// 7
You can also try it in the docs/playground site:
https://date-light.flyingsquirrel.me
Why I made it
I like date-fns. It has a great API and covers a huge range of date operations.
But most apps I work on only use a small subset of that surface area.
Common examples:
format(date, "yyyy-MM-dd");
parseISO("2026-01-15");
addDays(date, 7);
addMonths(date, 1);
differenceInDays(a, b);
startOfMonth(date);
endOfMonth(date);
isSameDay(a, b);
I wanted a tiny library that focused on those common operations and avoided everything else:
- no locale system
- no timezone database
- no plugins
- no chainable wrapper
- no runtime dependencies
Just the date helpers most apps actually ship.
What it includes
date-light currently includes helpers for:
| Area | Examples |
|---|---|
| Format & parse |
format, parseISO, parse
|
| Add & subtract |
addDays, addMonths, addYears, subDays
|
| Difference |
differenceInDays, differenceInMonths, differenceInYears
|
| Compare |
isBefore, isAfter, isEqual, isSameDay
|
| Query |
isWeekend, isLeapYear, isValid, getDaysInMonth
|
| Start & end |
startOfDay, startOfWeek, endOfMonth, endOfYear
|
All functions are typed and return new Date instances instead of mutating the input.
import { addMonths } from "date-light";
const original = new Date(2026, 0, 31);
const next = addMonths(original, 1);
console.log(original);
// Jan 31, 2026
console.log(next);
// Feb 28, 2026
Handling date edge cases
Dates have a lot of sharp edges, so I added tests for the cases that usually cause problems.
For example, month-end clamping:
addMonths(new Date(2026, 0, 31), 1);
// Feb 28, 2026
addMonths(new Date(2024, 0, 31), 1);
// Feb 29, 2024
Leap years:
isLeapYear(new Date(2024, 0, 1));
// true
isLeapYear(new Date(1900, 0, 1));
// false
isLeapYear(new Date(2000, 0, 1));
// true
And date-only ISO parsing:
parseISO("2026-01-15");
// local midnight, matching date-fns behavior
Package support
The package ships with:
- ESM
- CommonJS
- TypeScript declarations
- zero runtime dependencies
- tree-shakeable exports
The package entrypoints are tested before release.
Size
The current library build is about 2.18KB minzipped.
That is the main goal of the project: keep the useful common date helpers small enough that you do not have to think much about adding them.
What date-light is not
date-light is intentionally not a complete date platform.
It does not try to replace:
- full
date-fns - Luxon
- Temporal
- timezone-aware libraries
- advanced locale formatting
If you need full i18n, timezone conversions, duration objects, or complex calendar logic, you should use a more complete library.
date-light is for the smaller common case:
“I just need the date helpers I use all the time.”
Try it
Docs and playground:
https://date-light.flyingsquirrel.me
GitHub:
https://github.com/flyingsquirrel0419/date-light
npm:
npm install date-light
Example:
import {
format,
parseISO,
addDays,
differenceInDays,
startOfMonth,
endOfMonth,
} from "date-light";
const date = parseISO("2026-06-30");
console.log(format(date, "yyyy-MM-dd"));
console.log(format(startOfMonth(date), "yyyy-MM-dd"));
console.log(format(endOfMonth(date), "yyyy-MM-dd"));
console.log(differenceInDays(addDays(date, 7), date));
If you try it, feedback is welcome.
And if you find the project useful, a GitHub star would help a lot:
Top comments (0)