Working with dates in a Node app can be tricky as there are so many ways to format and display them.

The APIs available in native JavaScript are way too tedious to use directly, so your best option is to use a date/time library. The best known and most flexible option is 

For this article, I'll presume you understand the basics of JavaScript and Node.js.

To install Moment you should have Node and NPM installed on your machine. Any current version will do, but if you're installing from scratch, I'd recommend using the 

Other than for simple use cases and one-offs, the JavaScript 

 API will be too low-level and will require you to write many lines of code for what seems like a simple operation.

Moment is an incredibly flexible JavaScript library that wraps the 

 API giving you very convenient helper methods allowing you to easily perform tasks like:

Moment can be used in either the browser or on a Node.js server.

Let's begin by going to the terminal and installing Moment:

With that done, we can now require the Moment library in a Node.js project:

The first thing we'll do to use Moment is to create a new instance by calling the 

So what is a Moment instance, and what exactly has been assigned to the variable 

Think of the Moment instance as a wrapper object around a single, specific date. The wrapper provides a host of API methods that will allow you to manipulate or display the date. 

 method which, as you'd expect, allows you to add a time period to a date:

, similar to jQuery. It's  called "fluent" because the code will often read like a sentence. For example, read this line aloud and it should be immediately obvious what it does:

 Another aspect of fluent API methods is that they return the same object allowing you to chain additional methods for succinct and easy to read code.

moment()
  	.add(2, 'days')
	.subtract(3, 'week');

 one counter-intuitive aspect of Moment objects is that they are 

. Calling any of the "manipulation" methods e.g. 

, etc, will change the object they're applied to.

We said above that Moment wraps a single, specific date. So how do we specify the date we want to work with?

 object, if we don't pass anything to the 

 method when we first call it, the date associated with the instance will be the current date i.e. "now".

const now = moment();
now.add(2, 'days'); // 2 days from now

What if we want to create a Moment instance based on some fixed date in the past or future? Then we can pass the date as a parameter to 

. There are several ways to do this depending on your requirements.

You may be aware of some of the standards for formatting date strings (with unfortunate names like "ISO 8601" and "RFC 2822"). For example, my birthday formatted as an ISO 8601 string would look like this: 

 is a standard designed to provide an unambiguous and well-defined method of representing dates and times. 

 is designed for similar purposes but is more specifically designed for use on the internet and in email.

Since these standards are designed for accurately communicating dates, you'll probably find that your database and other software will provide dates in one of these formats.

If your date is formatted as either ISO 8601 or RFC 2822, Moment is able to automatically parse it.

const ISODateString = "1982-10-25T08:00:15+10:00";
const m = moment(ISODateString);
// 👍

 formatted using one of these standards, you'll need to tell Moment the format you're using. To do this, you supply a second argument to the 

Most date string formats are specified using format token templates. It's easiest to explain these using an example. Say we created a date in the format "1982-10-25". The format token template representing this would be "YYYY-MM-DD". If we wanted the same date it in the format "10/25/82" the template would be "MM/DD/YY". 

Hopefully, that example makes it clear that the format tokens are used for a unique date property e.g. "YYYY" corresponds to "1982", while "YY" is just "82".

Format tokens are quite flexible and even allow us to create non-numeric values in dates like "25th October, 1982" - the format token string for this one would be "Do MMMM, YYYY" (note that including punctuation and other non-token values in the template is perfectly okay).

For a complete list of date format tokens, see 

So, if you want to use non-standard formatting for a date, supply the format token template as the second argument and Moment will use this to parse your date string.

For example, shorthand dates in Britain are normally formatted as "DD-MM-YYYY", while in America they're normally formatted as "MM-DD-YYYY".  This means a date like the 10th of October, 2000 will be ambiguous (10-10-2000) and so Moment cannot parse it accurately without knowing the format you're using.

const m = moment("10-10-2000");
// "Invalid date"

If we provide the format token template, however, Moment knows what you're looking for:

const m = moment("10-10-2000", "DD-MM-YYYY");
// 👍

A Unix timestamp is a way to track time as a running total of seconds starting from the "epoch" time: January 1st, 1970 at UTC. For example, the 10th of October, 2000 is 971139600 seconds after the epoch time, therefore that value is the Unix timestamp representing that date.

You'll often see timestamps used by operating systems as they're very easy to store and operate on.

 method it will be parsed as a Unix timestamp:

Fun fact: Unix timestamps will reach the 32-bit limit on January 19, 2038, after which time they'll cease to work! Luckily, there's a 64-bit replacement being introduced.

Now we've learned how to parse dates with Moment. How can we display a date in a format we like?

The API method for displaying a date in Moment is 

 and it can be called on a moment instance:

const m = moment();
console.log(m.format());
// 2020-09-10T02:25:14+10:00"

As you can see in the console output, Moment will, by default, format a date using the ISO 8601 format. If we want to use a different format, we can simply provide a formatted token string to the method. For example, say we wanted to display the current date in the British shorthand "DD-MM-YYYY":

const now = moment();
console.log(now.format("DD-MM-YYYY")); 
// 10-09-2020

Here's another example showing a more reader-friendly date:

const now = moment();
now.format("dddd, Do of MMMM");
// Thursday, 10th of September

While it's the most popular date library, Moment is certainly not the only option. You can always consider an alternative library if Moment doesn't quite fit your needs.

One complaint developers have about Moment is that the library is quite large (20kB+). As an alternative, you might try 

 which is a 2kB minimalist replacement for Moment.js, using an almost identical API. 

Another complaint is that the Moment object is mutable, which can lead to confusing code. One of the maintainers of Moment has released 

,  a Moment-inspired library that provides an immutable and unambiguous API.

So now you know how to format dates using Moment and Node. You understand how to work with the current date, as well as how to use standard and non-standard date strings. You also know how to display a date in whatever format you like by supplying a format token template.

Here's a snippet summarizing the main use case:

const moment = require('moment');
const m = moment("10-10-2000", "DD-MM-YYYY");
console.log(m.format("YYYY-MM-DD")); // 2020-10-10

Parsing and displaying dates just scratches the surface of Moment's features. You can also use it to manipulate dates, calculate durations, convert between timezones, and more.

If you'd like to learn more about these features I'd recommend you start with the Moment docs:

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Formatting Dates in Node with Moment.js</h1><p>Working with dates in a Node app can be tricky as there are so many ways to format and display them.</p><p>The APIs available in native JavaScript are way too tedious to use directly, so your best option is to use a date/time library. The best known and most flexible option is <em>Moment.js</em>.</p><h1><a name="what-youll-learn">What you'll learn</a></h1><ul><li><p>Why you should use a date/time library in Node.js</p></li><li><p>How to install Moment</p></li><li><p>How to parse standard and non-standard date strings and timestamps with Moment</p></li><li><p>How to display a date with Moment in your desired format</p></li><li><p>Alternatives to Moment if it doesn't quite fit your needs</p></li></ul><h1><a name="prerequisites">PrerequisiteS</a></h1><p>For this article, I'll presume you understand the basics of JavaScript and Node.js.</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>For more on JavaScript, check out <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript" rel="noopener noreferrer nofollow">these interesting articles</a> to enhance your grasp on the subject.</p></div></div><p>To install Moment you should have Node and NPM installed on your machine. Any current version will do, but if you're installing from scratch, I'd recommend using the <a href="https://nodejs.org/en/download/" rel="noopener noreferrer nofollow">Node v12 LTS</a> which includes NPM 6.</p><h1><a name="why-use-moment?">Why use Moment?</a></h1><p>Other than for simple use cases and one-offs, the JavaScript <code>Date</code> API will be too low-level and will require you to write many lines of code for what seems like a simple operation.</p><p>Moment is an incredibly flexible JavaScript library that wraps the <code>Date</code> API giving you very convenient helper methods allowing you to easily perform tasks like:</p><ul><li><p>Parsing dates</p></li><li><p>Manipulating dates</p></li><li><p>Displaying dates</p></li><li><p>Converting between locales and timezones</p></li></ul><p>Moment can be used in either the browser or on a Node.js server.</p><h1><a name="installing-moment-in-nodejs">Installing Moment in Node.js</a></h1><p>Let's begin by going to the terminal and installing Moment:</p><textarea data-iscodemirror="true" data-mode="text/x-sh" data-uniqueid="cm-fBy6I" id="cm-fBy6I">npm install moment -S</textarea><p>With that done, we can now require the Moment library in a Node.js project:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-dL7ul" id="cm-dL7ul">const moment = require('moment');</textarea><p>The first thing we'll do to use Moment is to create a new instance by calling the <code>moment</code> method.</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-NWScz" id="cm-NWScz">const m = moment();</textarea><h1><a name="the-moment-instance">The moment instance</a></h1><p>So what is a Moment instance, and what exactly has been assigned to the variable <code>m</code> in the snippet above? </p><p>Think of the Moment instance as a wrapper object around a single, specific date. The wrapper provides a host of API methods that will allow you to manipulate or display the date. </p><p>For example, we can use the <code>add</code> method which, as you'd expect, allows you to add a time period to a date:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-ZvCCl" id="cm-ZvCCl">const m = moment();
m.add(2, 'days');</textarea><p>Note that Moment provides a <a href="https://www.linkedin.com/pulse/chain-your-javascript-methods-like-boss-fluent-apis-anthony-gore/" rel="noopener noreferrer nofollow">fluent API</a>, similar to jQuery. It's  called "fluent" because the code will often read like a sentence. For example, read this line aloud and it should be immediately obvious what it does:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-oIYSq" id="cm-oIYSq">moment().add(2, 'days');</textarea><p> Another aspect of fluent API methods is that they return the same object allowing you to chain additional methods for succinct and easy to read code.</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-X7f80" id="cm-X7f80">moment()
  	.add(2, 'days')
	.subtract(3, 'week');</textarea><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p><strong>Note:</strong>&nbsp;one counter-intuitive aspect of Moment objects is that they are <em>mutable</em>. Calling any of the "manipulation" methods e.g. <code>add</code>, <code>subtract</code>, etc, will change the object they're applied to.</p></div></div><h1><a name="parsing-dates">Parsing dates</a></h1><p>We said above that Moment wraps a single, specific date. So how do we specify the date we want to work with?</p><h2><a name="current-date">Current date</a></h2><p>Just like with the native JavaScript <code>Date</code> object, if we don't pass anything to the <code>moment</code> method when we first call it, the date associated with the instance will be the current date i.e. "now".</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-5RrNl" id="cm-5RrNl">const now = moment();
now.add(2, 'days'); // 2 days from now</textarea><h2><a name="fixed-date">Fixed date</a></h2><p>What if we want to create a Moment instance based on some fixed date in the past or future? Then we can pass the date as a parameter to <code>moment</code>. There are several ways to do this depending on your requirements.</p><h3><a name="formatted-strings">Formatted strings</a></h3><p>You may be aware of some of the standards for formatting date strings (with unfortunate names like "ISO 8601" and "RFC 2822"). For example, my birthday formatted as an ISO 8601 string would look like this: <code>"1982-10-25T08:00:15+10:00";</code>.</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p><a href="https://en.wikipedia.org/wiki/ISO_8601" rel="noopener noreferrer nofollow">ISO 8601</a> is a standard designed to provide an unambiguous and well-defined method of representing dates and times. <a href="https://tools.ietf.org/html/rfc2822" rel="noopener noreferrer nofollow">RFC 2822</a> is designed for similar purposes but is more specifically designed for use on the internet and in email.</p></div></div><p>Since these standards are designed for accurately communicating dates, you'll probably find that your database and other software will provide dates in one of these formats.</p><p>If your date is formatted as either ISO 8601 or RFC 2822, Moment is able to automatically parse it.</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-IWsZr" id="cm-IWsZr">const ISODateString = "1982-10-25T08:00:15+10:00";
const m = moment(ISODateString);
// 👍</textarea><p>If your date string is <em>not</em> formatted using one of these standards, you'll need to tell Moment the format you're using. To do this, you supply a second argument to the <code>moment</code>method - a string of <em>format tokens</em>.</p><h3><a name="format-token-templates">Format token Templates</a></h3><p>Most date string formats are specified using format token templates. It's easiest to explain these using an example. Say we created a date in the format "1982-10-25". The format token template representing this would be "YYYY-MM-DD". If we wanted the same date it in the format "10/25/82" the template would be "MM/DD/YY". </p><p>Hopefully, that example makes it clear that the format tokens are used for a unique date property e.g. "YYYY" corresponds to "1982", while "YY" is just "82".</p><p>Format tokens are quite flexible and even allow us to create non-numeric values in dates like "25th October, 1982" - the format token string for this one would be "Do MMMM, YYYY" (note that including punctuation and other non-token values in the template is perfectly okay).</p><p>For a complete list of date format tokens, see <a href="https://momentjs.com/docs/#/displaying/format/" rel="noopener noreferrer nofollow">this section of the Moment docs</a>.</p><h3><a name="specifying-date-format">Specifying date format</a></h3><p>So, if you want to use non-standard formatting for a date, supply the format token template as the second argument and Moment will use this to parse your date string.</p><p>For example, shorthand dates in Britain are normally formatted as "DD-MM-YYYY", while in America they're normally formatted as "MM-DD-YYYY".  This means a date like the 10th of October, 2000 will be ambiguous (10-10-2000) and so Moment cannot parse it accurately without knowing the format you're using.</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-0qkFR" id="cm-0qkFR">const m = moment("10-10-2000");
// "Invalid date"</textarea><p>If we provide the format token template, however, Moment knows what you're looking for:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-gwerx" id="cm-gwerx">const m = moment("10-10-2000", "DD-MM-YYYY");
// 👍</textarea><h3><a name="timestamps">Timestamps</a></h3><p>A Unix timestamp is a way to track time as a running total of seconds starting from the "epoch" time: January 1st, 1970 at UTC. For example, the 10th of October, 2000 is 971139600 seconds after the epoch time, therefore that value is the Unix timestamp representing that date.</p><p>You'll often see timestamps used by operating systems as they're very easy to store and operate on.</p><p>If you pass a number to the <code>moment</code> method it will be parsed as a Unix timestamp:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-dUW4z" id="cm-dUW4z">const m = moment(1599809043);
// 👍</textarea><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Fun fact: Unix timestamps will reach the 32-bit limit on January 19, 2038, after which time they'll cease to work! Luckily, there's a 64-bit replacement being introduced.</p></div></div><h1><a name="formatting-dates">Formatting dates</a></h1><p>Now we've learned how to parse dates with Moment. How can we display a date in a format we like?</p><p>The API method for displaying a date in Moment is <code>format</code> and it can be called on a moment instance:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-E17RE" id="cm-E17RE">const m = moment();
console.log(m.format());
// 2020-09-10T02:25:14+10:00"</textarea><p>As you can see in the console output, Moment will, by default, format a date using the ISO 8601 format. If we want to use a different format, we can simply provide a formatted token string to the method. For example, say we wanted to display the current date in the British shorthand "DD-MM-YYYY":</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-XN9xO" id="cm-XN9xO">const now = moment();
console.log(now.format("DD-MM-YYYY")); 
// 10-09-2020</textarea><p>Here's another example showing a more reader-friendly date:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-e9PlT" id="cm-e9PlT">const now = moment();
now.format("dddd, Do of MMMM");
// Thursday, 10th of September</textarea><h1><a name="alternatives-to-moment">Alternatives to Moment</a></h1><p>While it's the most popular date library, Moment is certainly not the only option. You can always consider an alternative library if Moment doesn't quite fit your needs.</p><p>One complaint developers have about Moment is that the library is quite large (20kB+). As an alternative, you might try <a href="https://day.js.org/" rel="noopener noreferrer nofollow">Day.js</a> which is a 2kB minimalist replacement for Moment.js, using an almost identical API. </p><p>Another complaint is that the Moment object is mutable, which can lead to confusing code. One of the maintainers of Moment has released <a href="https://moment.github.io/luxon/index.html" rel="noopener noreferrer nofollow">Luxon</a>,  a Moment-inspired library that provides an immutable and unambiguous API.</p><h1><a name="conclusion">Conclusion</a></h1><p>So now you know how to format dates using Moment and Node. You understand how to work with the current date, as well as how to use standard and non-standard date strings. You also know how to display a date in whatever format you like by supplying a format token template.</p><p>Here's a snippet summarizing the main use case:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-Yo8Yv" id="cm-Yo8Yv">const moment = require('moment');
const m = moment("10-10-2000", "DD-MM-YYYY");
console.log(m.format("YYYY-MM-DD")); // 2020-10-10</textarea><h1><a name="more-resources">More resources</a></h1><p>Parsing and displaying dates just scratches the surface of Moment's features. You can also use it to manipulate dates, calculate durations, convert between timezones, and more.</p><p>If you'd like to learn more about these features I'd recommend you start with the Moment docs:</p><ul><li><p><a href="https://momentjs.com/docs/" rel="noopener noreferrer nofollow">Moment docs</a></p></li></ul><p></p>

AUTHOR

Anthony Gore

Working with dates in a Node app can be tricky as there are so many ways to format and display them. The APIs available in native JavaScript are way too tedious to use directly, so your best option is to use a date/time library. The best known and most flexible option is Moment.js. For this…

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Free Tools

Formatting Dates in Node with Moment.js

Tags

Responses (0)

Free AI Career Tools

AI Job Listings

ATS Resume Checker

Startup Perks

Masterclasses

Tutorials

Fullstack React with TypeScript