XDate - Modern JavaScript Date Library (Circa 2013)

0.8.3 · deprecated · verified Sun Apr 19

XDate is a lightweight JavaScript date library released circa 2013, designed as a thin wrapper around the native `Date` object to provide enhanced functionality for parsing, formatting, and manipulating dates. It aims for familiarity by implementing many of the same methods as the native `Date` object and is non-destructive to the DOM, making it safe for inclusion in third-party libraries. The current stable version is 0.8.3, but the package is explicitly no longer actively maintained. The original author recommends migrating to `temporal-polyfill`, which implements the modern JavaScript Temporal API standard, as a direct replacement. Given its deprecated status, XDate does not have an active release cadence and lacks modern JavaScript features like native ESM support.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import XDate from 'xdate'` in a file or environment configured for CommonJS, or in a pure ES Module environment where XDate does not provide native ESM exports.

fix Ensure you are using the CommonJS `require` syntax: `const XDate = require('xdate');`. If your project is an ES Module, you will need to re-evaluate if XDate is appropriate or migrate to an ESM-compatible date library.
```
TypeError: XDate is not a constructor
```
cause This error can occur if XDate is incorrectly imported (e.g., trying `import { XDate } from 'xdate'` instead of `import XDate from 'xdate'` after some transpilation) or if CommonJS interop fails.

fix Verify that XDate is imported as a default CommonJS export: `const XDate = require('xdate');`. Ensure no named imports are being attempted.
```
Date calculations (e.g., adding days, diffing months) produce incorrect results, especially around timezone changes or DST.
```
cause The library is unmaintained and its internal logic for handling complex date arithmetic may be outdated or contain known bugs related to timezones and DST that have not been fixed.

fix This issue is inherent to the library's deprecated status. The most robust fix is to migrate to a modern, actively maintained date/time library that correctly implements current specifications for date arithmetic and timezone handling, such as `temporal-polyfill`.

Warnings

breaking The XDate package is officially deprecated and no longer actively maintained by its author. This means no new features, bug fixes, or security patches will be released. Using an unmaintained library introduces significant risks, including potential security vulnerabilities and compatibility issues with newer JavaScript runtimes or environments.
Fix: Migrate to `temporal-polyfill` or another actively maintained modern date library. The original author explicitly recommends `temporal-polyfill`.
gotcha XDate does not natively support ES Modules (ESM). It was developed before wide adoption of ESM and primarily exposes its functionality via CommonJS `require()`. Attempting to `import XDate from 'xdate'` in a pure ESM environment will result in a runtime `SyntaxError`.
Fix: Always use `const XDate = require('xdate');` for importing XDate. If your project is pure ESM, consider moving to a modern, ESM-compatible date library like `temporal-polyfill`.
gotcha Being a library from 2013, XDate may not correctly handle all modern timezone rules, Daylight Saving Time (DST) changes, or locale-specific date formatting nuances that have evolved since its last update. This can lead to subtle bugs in applications requiring precise date and time calculations.
Fix: For applications requiring accurate and robust date/time handling, especially across timezones and DST, migrate to `temporal-polyfill` or other battle-tested, actively maintained date libraries that adhere to current standards.

Install

npm install xdate npm
yarn add xdate yarn
pnpm add xdate pnpm

Imports

XDate
wrong:
```
import XDate from 'xdate'
```
correct:
```
const XDate = require('xdate')
```
XDate is primarily a CommonJS module. Direct ES Module imports will lead to runtime errors (e.g., 'SyntaxError: Cannot use import statement outside a module') without specific transpilation or Node.js configuration (e.g., 'type: module' with `import XDate from 'xdate'` might resolve to the default export if 'esModuleInterop' is enabled in TypeScript, but this is not guaranteed nor recommended).

Quickstart

Demonstrates basic usage of XDate, including creating, manipulating, formatting, and differencing dates using its CommonJS interface. Also highlights the deprecated status.

const XDate = require('xdate'); // Use CommonJS require

// Create a new XDate object for the current date and time
const now = new XDate();
console.log('Current XDate:', now.toString());

// Manipulate the date: add 7 days (returns a new XDate instance)
const futureDate = now.clone().addDays(7);
console.log('Date 7 days from now:', futureDate.toDateString());

// Format the date using a custom string
const formattedDate = futureDate.toString('yyyy-MM-dd HH:mm:ss');
console.log('Formatted future date (YYYY-MM-DD HH:MM:SS):', formattedDate);

// Calculate the difference between two dates in days
const today = new XDate();
const tomorrow = today.clone().addDays(1);
const diffInDays = tomorrow.diffDays(today);
console.log(`Difference between tomorrow and today in days: ${diffInDays}`);

// Create a date from an ISO string
const specificDate = new XDate('2025-12-25T12:00:00Z');
console.log('Specific XDate (Christmas 2025 UTC):', specificDate.toUTCString());

/*
NOTE: This library is deprecated and no longer actively maintained.
For new projects, it is strongly recommended to use a modern alternative
such as 'temporal-polyfill' which implements the ECMAScript Temporal API.
*/

view raw JSON →