Date And Time Handling With Luxon
Published: 2024-01-13 12:55:32

by [David Mukundi](https://blog.openreplay.com/authors/david-mukundi)


<blockquote><em>
Luxon.js is a fully open-source JavaScript library designed for time and date manipulation. In this ever-evolving web development landscape, accurate date and time representation remains crucial for various applications, from scheduling events to handling data analysis spanning various time zones. Luxon.js steps in as a comprehensive solution, offering an intuitive API that not only simplifies the process but also ensures precise and reliable results, and this article will show you how to use it.
</em></blockquote>


<div style="background-color:#efefef; border-radius:8px; padding:10px; display:block;">
<hr/>
<h3><em>Session Replay for Developers</em></h3> 
<p><em>Uncover frustrations, understand bugs and fix slowdowns like never before with <strong><a href="https://github.com/openreplay/openreplay" target="_blank">OpenReplay</a></strong> — an open-source session replay suite for developers. It can be <strong>self-hosted</strong> in minutes, giving you complete control over your customer data.</em></p>
<img alt="OpenReplay" style="margin-top:5px; margin-bottom:5px;" width="768" height="400" src="https://raw.githubusercontent.com/openreplay/openreplay/main/static/openreplay-git-hero.svg" class="astro-UXNKDZ4E" loading="lazy" decoding="async">
<p><em>Happy debugging! <a href="https://openreplay.com" target="_blank">Try using OpenReplay today.</a></em><p>
<hr/>
</div>


Hello folks! In this blog post, I will walk you through using Luxon.js to manipulate dates and times in your JavaScript application.

Luxon is a result of continuous improvement in date-time libraries. It was created by the same team responsible for Moment.js, a widely popular JavaScript library for manipulating dates. However, as the JavaScript ecosystem advanced, Moment.js became a huge library with a big bundle size for just date and time manipulation. Additionally, it was lagging in terms of performance and features. This led to the emergence of Day.js, which had a smaller bundle size and more features than moment.js, and as a result, it addressed Moment's shortcomings. The JavaScript developer community shifted from using the moment to day.js; however, even Day.js had its limitations, especially in timezoning, prompting some engineers in the Moment team to start fresh and develop Luxon. As a result, Luxon combines the knowledge gained from Moment.js and Day.js, offering a modern, robust, and feature-packed solution for manipulating dates and times.

## Installation through a CDN
To get started, we need to install the Luxon library in our working environment. Two major ways of installing Luxon in an application are via a CDN or npm install. The installation type entirely depends on your application's tech stack and the Luxon library's purpose. Now, when running an HTML vanilla JavaScript application, you will install Luxon via a Content Delivery Network (CDN). For that, in your HTML `<head>`, include the link to the Luxon library below.
```html
<script src="https://cdn.jsdelivr.net/npm/luxon@3.4.3/build/global/luxon.min.js"></script>
```
Having done that, you can now access the various Luxon classes to confirm everything is good; in your Javascript file, you can have the line of code below just to print out the date, the time, and the zone.
```javascript
//test
const DateTime = luxon.DateTime;
const now = DateTime.local();
console.log(`the time is ${now.toISO()}`);

```

## Installation via NPM
If you run a Javascript front-end library or a build tool such as Webpack, npm install would be a more precise way to install Luxon. To install, open your terminal on your working directory and run the below command.
```bash
npm install --save luxon
```
The --save option instructed NPM to include the package inside of the dependencies section of your package.json.To utilize the Luxon classes, we bring it in via the line below.
```javascript
const { DateTime } = require("luxon");
```
The ES6 syntax is written below.

```javascriptx
import { DateTime } from "luxon";
```

## Passing and formatting dates
Luxon provides a robust API for working with dates and times in JavaScript.
Now, to pass the date, let's first create a date instance.
```javascript
const date = luxon.DateTime.local();
```
We have used the `Datetime` luxon class, which will give us the date and time based on your device's current date and time. You can also define a specific date via a parameter to the `Datetime` class.
```javascript
const birthDay = luxon.DateTime.local(2023,9,7,11,0);
```
The above code stores a date variable for September, date 7, and the time, which is 11:00 p.m.
Now, to format the date, we will use the `format` luxon method. The function allows us to format dates according to specific patterns.
```javascript
const date = luxon.DateTime.local(2023, 9, 7, 12, 0);
const formattedDate = date.toFormat('MMMM dd, yyyy hh:mm a'); 
```
The above function will output "September 07, 2023, 12:00 PM". You can adjust the format by rearranging the year, month, day, hours, and minutes dummy variables. Luxon also provides some predefined formats.
```javascript
const date = luxon.DateTime.local(2023, 9, 7, 12, 0);
const formattedDate = date.toLocaleString(luxon.DateTime.DATETIME_FULL); // Output: "Wednesday, September 7, 2023, 12:00 PM"
```
The `DATETIME_FULL` function will restructure the given date and time and output "Wednesday, September 7, 2023, at 12:00 PM". Additionally, you can internationalization your date and time, allowing you to format dates based on different locales:
```javascript
const date = luxon.DateTime.local(2023, 9, 7, 12, 0);
const formattedDate = date.setLocale('fr').toFormat('MMMM dd, yyyy hh:mm a'); // Output (in French locale): "septembre 07, 2023 12:00 PM"
```
The formatted date will be based in the French locale for the time of September 07, 2023, 12:00 PM.

## Time intervals
You can use the' Duration' class to handle time intervals using Luxon. This class represents a specific duration of time and allows you to specify it in different units, such as milliseconds, seconds, minutes, hours, days, and more.

Here is an illustration of how you can create and manipulate time intervals using Luxon.
```javascript
// Import Luxon
const { Duration } = require('luxon');

// Create a duration of 1 day and 3 hours
const interval = Duration.fromObject({ days: 1, hours: 3 });

// Add 30 minutes to the interval
const updatedInterval = interval.plus({ minutes: 30 });

// Get the total number of minutes in the interval
const totalMinutes = interval.as('minutes');

console.log(`Original Interval: ${interval.toISO()}`);
console.log(`Updated Interval: ${updatedInterval.toISO()}`);
console.log(`Total Minutes: ${totalMinutes}`);

```
In this example, we begin by importing the `Duration` class from Luxon. After that, we create a duration that represents a time interval of 1 day and 3 hours. We then use the `plus()` method to add 30 minutes to this interval. Lastly, we utilize the `as()` method to obtain the total number of minutes in the interval.

<CTA_Middle_Programming />



## Using the Intl API
To incorporate the Luxon library with the Intl API, you can combine them to format and display dates based on the user's locale. Here is an illustration of how you can achieve this:
```javascript
const { DateTime } = require('luxon');

const date = DateTime.fromISO('2023-09-09T12:34:56');

const formattedDate = date.toLocaleString(DateTime.DATETIME_FULL);

console.log(formattedDate);
```
In this example, we create a `DateTime` object using Luxon's `fromISO` method, which parses the given ISO date string. Following that, we utilize `the toLocaleString` method provided by Luxon, which internally utilizes the `Intl` API.

We specify the `DateTime.DATETIME_FULL` argument to determine the desired format. In this case, the date will be formatted as "weekday, month day, year - hour: minute: second AM/PM" (for example, "Saturday, September 9, 2023 - 12: 34: 56 PM").
The `toLocaleString` method utilizes the system's default locale by default, but if you wish to override it, you can provide a specific locale as the second argument.

```javascript
const formattedDate = date.toLocaleString(DateTime.DATETIME_FULL, { locale: 'en-US' });
```
This will format the date in the US.

## Luxon calendar
Luxon offers the `Calendar` class to support various calendar systems. By default, Luxon uses the Gregorian calendar. However, Luxon also provides support for alternative calendar systems like the Islamic, Hebrew, and Chinese calendars. Here is an example that demonstrates how to work with different calendar systems in Luxon.
```javascript
const { DateTime, Settings } = require('luxon');

// Set the default calendar to Islamic
Settings.defaultZone = 'Africa/Cairo';
Settings.defaultLocale = 'ar'; // Set locale to Arabic for proper month names

// Create a DateTime using the Islamic calendar
const islamicDate = DateTime.fromObject({ year: 1445, month: 3, day: 25, calendar: 'islamic' });

// Format the date
const formattedIslamicDate = islamicDate.toLocaleString(DateTime.DATE_FULL);

console.log(formattedIslamicDate);
```
In this example, we begin by importing the required modules from Luxon. Following that, we establish the default zone as 'Africa/Cairo', which is frequently used in regions that follow the Islamic calendar. Additionally, we set the default locale to 'ar' for Arabic.

Subsequently, we generate a `DateTime` object using the Islamic calendar system by specifying the `islamic` option for the calendar.

Lastly, we utilize the `toLocaleString` function with the `DATE_FULL` option to format the date and obtain a comprehensive representation.

## Time zones in Luxon
Luxon shines when it comes to time zones, it offers support for working with time zones through the `luxon.Settings` object. This allows you to set the default time zone and customize how Luxon handles time zones in your application.

Here is an example that demonstrates how to work with time zones in Luxon:
```javascript
const { DateTime, Settings } = require('luxon');

// Set the default time zone to 'America/New_York'
Settings.defaultZone = 'America/New_York';

// Create a DateTime in the specified time zone
const dateTime = DateTime.local(); // This creates a DateTime in the 'America/New_York' time zone

// Convert to a different time zone
const dateTimeInTokyo = dateTime.setZone('Asia/Tokyo');

// Format the dates
const formattedDateTime = dateTime.toISO(); // Outputs in 'America/New_York' time zone
const formattedDateTimeInTokyo = dateTimeInTokyo.toISO(); // Outputs in 'Asia/Tokyo' time zone

console.log(formattedDateTime);
console.log(formattedDateTimeInTokyo);
```
In this example, the process begins by importing the required modules from Luxon. Following that, the default time zone is set to 'America/New_York' using the `Settings.defaultZone` property.

Next, a `DateTime` object is created using `DateTime.local()`. This generates a `DateTime` object in the previously specified default time zone ('America/New_York').

Afterward, the `setZone` method is utilized to convert the `DateTime` object to a different time zone (in this case, 'Asia/Tokyo').

Finally, the dates are formatted using `toISO`. The resulting output will include the date and time in their respective time zones.

## Conclusion
In conclusion, Luxon is a comprehensive JavaScript library designed for efficient handling and manipulation of dates and times. With its user-friendly interface, compatibility with multiple calendars, and seamless integration with the `Intl` API, Luxon proves to be an invaluable resource for precise date and time operations. Whether utilized in web applications or server-side programming, Luxon streamlines intricate tasks, making it an essential component in the toolkit of every JavaScript developer.