Day.js – Lightweight JavaScript Date Library

Overview

Day.js is a JavaScript library for working with dates and times in web applications. Its primary goal is to provide a lightweight, immutable alternative to larger date libraries like Moment.js, while maintaining a compatible API. This approach aims to reduce the overall bundle size of applications, which can improve load times and performance, particularly on mobile devices or in environments with limited bandwidth. The library is designed to be easy to learn for developers already familiar with similar date manipulation patterns.

The core Day.js library offers fundamental functionalities for parsing various date and time formats, validating dates to ensure they are legitimate, manipulating dates by adding or subtracting units of time (e.g., days, months, years), and formatting dates into human-readable strings or specific machine-readable formats. It supports both local time and UTC, allowing developers to handle time zones as needed within their applications. The API is designed to be intuitive, using method chaining to perform multiple operations sequentially on a Day.js object.

Day.js is particularly well-suited for modern web development frameworks and libraries such as React, Vue, and Angular, where minimizing the client-side bundle size is often a priority. Its immutable nature means that date manipulation methods return new Day.js instances rather than modifying the original, which can help prevent unintended side effects in complex applications and aligns with functional programming paradigms often favored in contemporary JavaScript development. The library also includes a plugin system, allowing developers to extend its core functionality with additional features like advanced parsing, time zone support, or internationalization, without increasing the size of the base library if those features are not required. This modularity contributes to its efficiency and flexibility.

For example, a developer building a single-page application that displays event schedules might use Day.js to parse event timestamps from an API, format them for display in a user's local time, and enable users to navigate between different days or weeks. In such a scenario, the small footprint of Day.js would contribute to a faster initial page load, enhancing the user experience. The library's focus on a minimal core and an extensible plugin system provides a balance between essential functionality and the ability to customize for specific project requirements, making it a pragmatic choice for many JavaScript projects.

Key features

• Parsing: Converts various input types (strings, numbers, Date objects) into Day.js objects for manipulation, supporting common date and time formats.
• Validation: Provides methods to check if a given input represents a valid date, returning a boolean value.
• Manipulation: Allows adding or subtracting units of time (years, months, days, hours, minutes, seconds, milliseconds) from a Day.js object.
• Formatting: Formats Day.js objects into custom string representations using a flexible token-based system, for example, YYYY-MM-DD or HH:mm:ss. More details are available in the Day.js display format documentation.
• Immutability: All manipulation methods return a new Day.js instance, ensuring that original date objects remain unchanged.
• Lightweight Core: The base library has a small footprint, contributing to reduced bundle sizes in web applications.
• Plugin System: Extends core functionality with optional plugins for features such as advanced parsing, time zones, and relative time.
• Internationalization (i18n): Supports multiple locales for date formatting and display through its plugin system, enabling applications to serve a global audience.

Pricing

Day.js is an open-source library distributed under the MIT License. It is freely available for use in both commercial and personal projects without any licensing fees.

Additional information regarding its open-source nature can be found on the Day.js GitHub repository license page.

Common integrations

Day.js is a standalone utility library and integrates primarily by being imported into JavaScript projects. It can be used with:

• Modern JavaScript Frameworks: Easily integrated into projects built with React (React documentation), Vue.js (Vue.js quick start), Angular (Angular tutorial), or Svelte (Svelte tutorial) for handling date and time logic within components.
• Node.js Applications: Used in backend services built with Node.js, often alongside frameworks like Express.js (Express.js installation guide) or Fastify (Fastify getting started) for server-side date processing.
• Bundlers and Build Tools: Compatible with module bundlers like Webpack, Rollup, and Vite, which optimize its inclusion in application bundles.
• Date Pickers and UI Libraries: Can be used as the underlying date utility for various UI components, including date pickers, calendars, and data grids that require date manipulation.

Alternatives

• Moment.js: A widely used JavaScript date library, known for its comprehensive feature set, though it has a larger bundle size and is no longer actively developed for new features.
• date-fns: A modular JavaScript date utility library that provides a collection of functions for date manipulation, aiming for immutability and tree-shakability.
• Luxon: A modern JavaScript library for dates and times, developed by the Moment.js team, offering immutable objects and improved internationalization and time zone support.

Getting started

To begin using Day.js in a JavaScript project, install it via npm or yarn. Once installed, import the library and start parsing, manipulating, or formatting dates. Here's a basic example:

// Install Day.js
// npm install dayjs
// or
// yarn add dayjs

// Import Day.js
import dayjs from 'dayjs';

// Get the current date and time
const now = dayjs();
console.log('Current date and time:', now.format('YYYY-MM-DD HH:mm:ss'));

// Parse a specific date string
const specificDate = dayjs('2024-03-15');
console.log('Parsed date:', specificDate.format('MMMM D, YYYY'));

// Add 7 days to the current date
const futureDate = now.add(7, 'day');
console.log('Date 7 days from now:', futureDate.format('dddd, MMMM D, YYYY'));

// Subtract 2 months from a specific date
const pastDate = specificDate.subtract(2, 'month');
console.log('Date 2 months before specific date:', pastDate.format('YYYY/MM/DD'));

// Check if a date is before another date
const isBefore = specificDate.isBefore(now);
console.log('Is 2024-03-15 before now?', isBefore);

// Use a plugin (e.g., for relative time)
import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(relativeTime);

const twoHoursAgo = dayjs().subtract(2, 'hour');
console.log('Two hours ago (relative):', twoHoursAgo.fromNow());

const inThreeDays = dayjs().add(3, 'day');
console.log('In three days (relative):', inThreeDays.fromNow());

This code snippet demonstrates common Day.js operations: getting the current time, parsing a string, adding and subtracting time units, comparing dates, and using a plugin for relative time formatting. For a complete guide, refer to the Day.js official documentation.