node-red-contrib-datetime-format 1.1.2

A Node-RED node that formats datetime values (epoch, ISO 8601 or Date) into human-readable strings with configurable timezone, locale and format.

npm install node-red-contrib-datetime-format

node-red-contrib-datetime-format

A Node-RED node that formats datetime values — the epoch timestamps, ISO strings and Date objects that flow through Node-RED — into human-readable strings, with a configurable timezone, locale and output format.

Powered by Luxon.

Features

• Flexible input — reads from any msg/flow/global property (default msg.payload) and auto-detects the value type:
  • epoch milliseconds or seconds (auto-detected, or forced),
  • ISO 8601 strings (e.g. 2026-06-22T14:30:00Z),
  • JavaScript Date objects.
• Configurable timezone — any IANA name (e.g. Europe/Zurich, Asia/Tokyo). Blank uses the server's local timezone.
• Configurable locale — any BCP 47 locale (e.g. de-CH) for localised month/day names and ordering.
• Two formatting modes:
  • Presets — named formats such as DATETIME_MED (e.g. Jun 22, 2026, 2:30 PM),
  • Custom tokens — Luxon format strings such as yyyy-LL-dd HH:mm:ss.
• Configurable output — writes to any msg/flow/global property (default msg.payload), leaving everything else untouched.
• Optional JSON output — write a structured object (formatted, iso, epoch, seconds, zone, locale) instead of a plain string.
• Robust errors — unparseable input or an invalid timezone raises a catchable error (use a Catch node) and shows a red status; the flow keeps running.

Installation

From your Node-RED user directory (typically ~/.node-red):

npm install node-red-contrib-datetime-format

Or, to install this checkout locally for development:

cd ~/.node-red
npm install /path/to/this/repo

Then restart Node-RED. The datetime format node appears in the function category of the palette.

Usage

Wire it after any node that emits a datetime. For example:

[ inject (timestamp) ] → [ datetime format ] → [ debug ]

Configuration

Locale note. A blank Locale uses Node.js's default, which is derived from the LANG / LC_ALL / LC_TIME environment variables — not your OS regional settings. When those aren't set to a real locale (common for services, e.g. LANG=C.UTF-8), Node falls back to en-US, so output is US-formatted. For predictable results set Locale explicitly (e.g. de-CH), or start Node-RED with LANG/LC_ALL set to your locale.

Input

The input value (default msg.payload) may be:

Output

The formatted string is written to the configured Output property. With the defaults, msg.payload is replaced by the formatted string.

Enable Output as JSON to write a structured object instead — handy when a downstream node needs more than the display string:

{
  "formatted": "Nov 14, 2023, 10:13 PM",
  "iso": "2023-11-14T22:13:20.000Z",
  "epoch": 1700000000000,
  "seconds": 1700000000,
  "zone": "UTC",
  "locale": "en-US"
}

Presets

The examples above are en-US. In the editor, the Preset dropdown shows each example in your own locale (the browser reads your OS regional settings), so a de-CH user sees 22.06.2026, 14:30, etc. Note this is an editor preview only — the node's actual output follows the Locale field (see the note under Settings).

Custom tokens

Select Custom tokens and supply a Luxon format string. A few common tokens:

See the full Luxon token table.

Examples

Development

npm install      # install luxon + dev dependencies
npm test         # run the mocha test suite

The runtime is split into:

• lib/format.js — pure parse/format helpers (no Node-RED dependency, directly unit-tested),
• datetime-format.js — the thin Node-RED runtime wrapper,
• datetime-format.html — the editor UI and help.

Tests live in test/ and use node-red-node-test-helper.

License

MIT