react-native-date

The fastest date library for React Native. Powered by C++ and Nitro Modules with zero-config localization.

Is this library for you?

Perfect for

• Apps that render many dates (calendars, timelines, feeds, chat apps)
• Apps targeting low-end devices where JS performance matters
• Apps requiring multiple locales without bundle size bloat
• Apps that need timezone conversions at scale

Maybe not needed

If your app only formats a few dates occasionally, date-fns or Day.js work fine. This library shines when performance and localization are critical - rendering hundreds of dates, supporting many languages, or running smoothly on budget devices.

Why react-native-date?

Zero-Config Localization

No locale plugins. No imports. No bundles. The library reads locales directly from the operating system.

Library	Locale Support
date-fns	Import each locale separately (~3KB per locale)
Day.js	Install locale plugin + import each locale
Moment.js	Import locales or full bundle (~300KB)
react-native-date	Built-in. Reads from device OS. Zero config.

import { format, setLocale } from '@bernagl/react-native-date';

// Works immediately - uses device's language
format(Date.now(), 'MMMM'); // "November" (or user's language)

// Or set explicitly - no imports needed
setLocale('ja');
format(Date.now(), 'MMMM'); // "11月"

setLocale('ar');
format(Date.now(), 'MMMM'); // "نوفمبر"

All 150+ locales supported by iOS/Android work out of the box.

Native Performance

Built with C++ and Nitro Modules for synchronous, near-native speed.

iPhone 14 Pro (ops/sec - higher is better)

Operation	NativeDate	date-fns	Day.js	Luxon
now()	445K 3.2x	278K	214K	139K
parse()	2.0M 71x	94K	329K	28K
format()	771K 25x	31K	103K	34K
addDays()	1.7M 65x	612K	68K	26K
addMonths()	279K	400K 1.4x	32K	26K
diffInDays()	1.6M 200x	74K	104K	8K
startOfDay()	1.8M 31x	727K	136K	58K
endOfDay()	1.8M 164x	727K	136K	11K
isWeekend()	2.1M 16x	711K	383K	134K
isLeapYear()	1.8M 8.9x	693K	400K	202K
getComponents()	673K 4.6x	147K	296K	180K
addHours()	1.7M 65x	414K	158K	26K
addMinutes()	1.7M 65x	642K	158K	26K
addSeconds()	1.7M 65x	456K	159K	26K
formatUTC()	805K 45x	18K	80K	29K
formatInTZ()	400K 27x	19K	15K	23K

Low-End Android Device (ops/sec - higher is better)

Operation	NativeDate	date-fns	Day.js	Luxon
now()	530K 17x	162K	76K	32K
parse()	465K 116x	13K	46K	4K
format()	270K 54x	5K	16K	5K
addDays()	378K 95x	107K	10K	4K
addMonths()	80K 20x	69K	5K	4K
diffInDays()	351K 351x	13K	15K	1K
startOfDay()	392K 49x	130K	20K	8K
endOfDay()	396K 198x	129K	20K	2K
isWeekend()	445K 23x	128K	59K	19K
isLeapYear()	419K 14x	125K	70K	29K
getComponents()	141K 5.6x	25K	47K	27K
addHours()	367K 92x	75K	24K	4K
addMinutes()	377K 94x	113K	23K	4K
addSeconds()	376K 94x	81K	23K	4K
formatUTC()	292K 146x	2K	12K	4K
formatInTZ()	38K 225x	2K	169	973

Performance Summary

react-native-date wins 15/16 on iOS and 16/16 on Android. Only addMonths() loses to date-fns on iOS - we're actively working on optimizing this.

Low-End Device Impact

The performance gap widens significantly on budget devices:

• format(): 25x faster on iOS → 54x faster on Android
• formatUTC(): 45x faster on iOS → 146x faster on Android

The native C++ implementation shines on low-end devices where JavaScript performance is constrained. Essential for apps targeting emerging markets.

Benchmark Methodology

Results obtained from the example app using the Benchmark tab. Each operation runs 1,000 iterations to calculate ops/sec. Run the example app on your own device to verify results.

Familiar API

Works like date-fns or Day.js - pick your style:

// Functional (date-fns style)
import { format, addDays, startOfMonth } from '@bernagl/react-native-date';
format(addDays(Date.now(), 7), 'yyyy-MM-dd');

// Chainable (Day.js style)
import { nativeDate } from '@bernagl/react-native-date';
nativeDate().addDays(7).format('yyyy-MM-dd');

Tree-Shakeable

The library is fully tree-shakeable. Only import what you need:

// Only these functions are included in your bundle
import { format, addDays } from '@bernagl/react-native-date';

For optimal bundle size, the chainable API can be imported separately:

// Functional API only (smaller bundle)
import { format, addDays } from '@bernagl/react-native-date';

// Chainable API (explicit import)
import { nativeDate } from '@bernagl/react-native-date/chain';

---

Features

• Fast - C++ core, no bridge overhead, synchronous calls
• Zero-config locales - Reads from OS, no plugins or imports
• 150+ locales - Every locale supported by iOS/Android
• Timezone support - Full IANA timezone database from the OS
• Timezone-aware predicates - Check "is today in Tokyo?" etc.
• Expo compatible - Works with Expo Dev Client (SDK 54+)
• Tiny footprint - No locale bundles, minimal JS
• Tree-shakeable - Only bundle what you use
• Type-safe - Full TypeScript support
• Two API styles - Functional or chainable

---

Requirements

Platform	Minimum Version
iOS	13.0+
Android	API 24+ (Android 7.0)
React Native	0.76+ (New Architecture)

---

Installation

npm install @bernagl/react-native-date react-native-nitro-modules

React Native CLI

cd ios && pod install

Expo

Requires Expo Dev Client (not Expo Go):

npx expo prebuild
npx expo run:ios

No additional setup. No locale configuration. Just install and use.

---

Quick Start

import {
  now,
  format,
  addDays,
  diffInDays,
  isToday,
  setLocale,
  getTimezone
} from '@bernagl/react-native-date';

// Current timestamp
const timestamp = now();

// Format (uses device locale automatically)
format(timestamp, 'EEEE, MMMM d, yyyy');
// "Sunday, November 30, 2025" (or localized)

// Date math
const nextWeek = addDays(timestamp, 7);
diffInDays(nextWeek, timestamp); // 7

// Predicates
isToday(timestamp); // true

// Timezone (from device)
getTimezone(); // "America/New_York"

// Change locale (optional - defaults to device language)
setLocale('es');
format(timestamp, 'EEEE, d MMMM'); // "domingo, 30 noviembre"

---

How Locales Work

The library uses native OS APIs - no JavaScript locale data needed:

Platform	Native Classes
iOS	NSLocale, NSDateFormatter
Android	java.util.Locale, DateFormatSymbols

Default behavior: If you never call setLocale(), the library automatically uses the device's language setting. Month names, day names, and formatting respect the user's preferences with zero configuration.

// User's device is set to French
format(Date.now(), 'EEEE d MMMM yyyy');
// "dimanche 30 novembre 2025" - automatic!

---

Next Steps

• API Reference - All functions
• Examples - Code samples
• Locales - Internationalization details