native-dates

API / Setup

configure() function

Read or update process-wide defaults for time zone, locale, week start, and plugins.

import { configure } from 'native-dates'core 7.3 kB min+br

Global defaults

configure()

configure(settings?): ActiveSettings

Updates one or more process-wide defaults and returns a snapshot of the active configuration. Calling it with no arguments reads the current settings without changing them.

Omitted properties keep their current values. Pass null for the time zone or locale to restore the runtime’s local defaults.

setup.js
import { configure, date, datetime } from 'native-dates';

configure({
  zone: 'Europe/Berlin',
  locale: 'de-DE',
  weekStart: 'sunday',
});

datetime('2026-11-16T17:30:00Z').zone; // 'Europe/Berlin'
date('2026-11-18').startOf('week').toString(); // '2026-11-15'
configure().weekStart; // 7

// Reset back to the runtime time zone, runtime locale, and Monday
configure({ zone: null, locale: null, weekStart: 'monday' });

Parameters

settingsSettings

Process-wide defaults to update. Omitted keys stay unchanged.

5 options
zoneZone | null

Default time zone for factories and now(). Pass null to reset to the runtime's local zone.

localeLocale | null

Default BCP 47 locale tag for format() and text. Pass null to reset to the runtime's locale.

weekStartWeekdaydefault 1

First day of the week for week boundaries, from 1 for Monday through 7 for Sunday.

dayFirstbooleandefault false

Read ambiguous numeric dates such as '07.09.2026' day-first with @native-dates/plugins/loose.

zoneAliasesRecord<string, Zone>

Custom names mapped to valid zones, merged into active aliases with @native-dates/plugins/zones.

Returns

{ zone, locale, weekStart, dayFirst, zoneAliases }

A shallow copy of the active settings after applying any updates.

Plugins extend configure() with their own options once imported. Setting a plugin option before importing its plugin throws a RangeError:

import { configure, date, now } from 'native-dates';
import '@native-dates/plugins/loose';
import '@native-dates/plugins/zones';

configure({
  dayFirst: true,
  zoneAliases: { hq: 'Europe/Berlin' },
});

date('07.09.2026', { loose: true })?.toString(); // '2026-09-07'
now('hq').zone; // 'Europe/Berlin'

configure({ dayFirst: false });

Configure once at startup on servers

Global configuration updates shared state across the entire JavaScript process. Set defaults once when your server boots, and pass each user’s time zone or locale directly to factories and format() inside request handlers.

Weekday helper

Check or normalize weekday names and numbers using the same ISO convention used across the library.

weekday()

weekday(day): number

Converts a weekday name, three-letter prefix, or ISO number into an integer from 1 for Monday through 7 for Sunday. Unrecognized names or numbers outside that range throw a RangeError.

Parameters

dayWeekdayrequired

Weekday name such as 'monday', case-insensitive prefix such as 'Fri', or integer from 1 to 7.

Returns

number

ISO weekday number from 1 for Monday through 7 for Sunday.

import { weekday } from 'native-dates';

weekday('monday'); // 1
weekday('Fri'); // 5
weekday('sunday'); // 7
weekday(3); // 3
Edit this pageUpdated Nov 12, 2026