date-fns-toolkit

A comprehensive toolkit for working with dates in JavaScript, including global timezone support and React integration.

Features

• ✅ All-in-one package - includes date-fns and date-fns-tz functionality
• ✅ Global default timezone - set once, use everywhere
• ✅ All date-fns functions are timezone-aware: Every function from date-fns and date-fns-tz uses the global timezone
• ✅ Tree-shakable individual functions - include only what you use
• ✅ React hooks for timezone-aware date handling in components
• ✅ Consistent timezone handling - no more timezone conversion bugs
• ✅ TypeScript support - with full type definitions

Installation

1# Using npm
2npm install date-fns-toolkit
3
4# Using yarn
5yarn add date-fns-toolkit
6
7# Using pnpm
8pnpm add date-fns-toolkit

No need to install date-fns or date-fns-tz separately - they're included in the package!

Usage

Core date-fns functionality

Most date-fns and all date-fns-tz functions are re-exported from this package:

1// Import directly from date-fns-toolkit instead of date-fns
2import { 
3  parse,
4  differenceInDays,
5  formatDistance
6} from 'date-fns-toolkit';
7
8// date-fns-tz functions are also available
9import { 
10  formatInTimeZone,
11  toZonedTime 
12} from 'date-fns-toolkit';
13
14// Use just like you would with date-fns and date-fns-tz
15const formattedDate = formatDistance(new Date(), new Date(2021, 0, 1));

Note: Some core date-fns functions (like format, addDays, etc.) are overridden with timezone-aware versions. If you need the original behavior, import directly from date-fns.

Setting a Global Default Timezone

1import { setDefaultTimezone, formatDateTime, addDays } from 'date-fns-toolkit';
2
3// Set the default timezone for your entire application
4setDefaultTimezone('America/New_York');
5
6// Now you can use date utilities without specifying timezone
7const now = new Date();
8console.log(`Current date and time: ${formatDateTime(now)}`);
9console.log(`Tomorrow: ${formatDateTime(addDays(now, 1))}`);
10
11// You can still override the timezone for specific calls
12console.log(`Tokyo time: ${formatDateTime(now, 'Asia/Tokyo')}`);

Individual Functions with Default Timezone

1import React from 'react';
2// Import only the functions you need
3import { formatDateTime, addDays, isBefore } from 'date-fns-toolkit';
4
5function EventItem({ event }) {
6  // Uses the global default timezone
7  const displayTime = formatDateTime(event.startTime);
8  
9  // Get tomorrow
10  const tomorrow = addDays(new Date(), 1);
11  
12  // Check if event is before tomorrow
13  const isToday = isBefore(event.startTime, tomorrow);
14  
15  return (
16    <div>
17      <h3>{event.title}</h3>
18      <p>Time: {displayTime}</p>
19      {isToday && <span>Today!</span>}
20    </div>
21  );
22}

React Hook with Default Timezone

1import React from 'react';
2import { useDateTimezone } from 'date-fns-toolkit';
3
4function ClockDisplay() {
5  // Hook will use the global default timezone if none provided
6  const dateUtils = useDateTimezone();
7  const [time, setTime] = React.useState(new Date());
8  
9  React.useEffect(() => {
10    const timer = setInterval(() => setTime(new Date()), 1000);
11    return () => clearInterval(timer);
12  }, []);
13  
14  return (
15    <div>
16      <h2>Current Time</h2>
17      <p>{dateUtils.formatDateTime(time)}</p>
18      <p>Timezone: {dateUtils.getTimezone()}</p>
19    </div>
20  );
21}

Using TimezoneProvider with Global Sync

1import React from 'react';
2import { TimezoneProvider, useTimezoneContext } from 'date-fns-toolkit';
3
4function App() {
5  return (
6    // syncWithGlobal will update the global default when context changes
7    <TimezoneProvider syncWithGlobal={true}>
8      <AppContent />
9    </TimezoneProvider>
10  );
11}
12
13function AppContent() {
14  const { timezone, setTimezone } = useTimezoneContext();
15  
16  const handleTimezoneChange = (e) => {
17    // This will update both context AND the global default
18    setTimezone(e.target.value);
19  };
20  
21  return (
22    <div>
23      <h1>Timezone Settings</h1>
24      <select value={timezone} onChange={handleTimezoneChange}>
25        <option value="America/New_York">New York</option>
26        <option value="Europe/London">London</option>
27        <option value="Asia/Tokyo">Tokyo</option>
28      </select>
29      
30      {/* All components will use the selected timezone */}
31      <DateDisplay />
32      <EventCalendar />
33    </div>
34  );
35}

API Reference

Core Date Functions

All functions from date-fns and date-fns-tz are available:

1import { 
2  format,
3  parse,
4  addDays,
5  addMonths,
6  differenceInDays,
7  isAfter,
8  isBefore,
9  formatInTimeZone,
10  toZonedTime,
11  fromZonedTime 
12  // ...and many more
13} from 'date-fns-toolkit';

For documentation on these functions, refer to:

• date-fns documentation
• date-fns-tz documentation

Global Configuration

setDefaultTimezone(timezone: string): void

Sets the global default timezone for all date functions.

1import { setDefaultTimezone } from 'date-fns-toolkit';
2
3setDefaultTimezone('America/New_York');

getDefaultTimezone(): string

Gets the current global default timezone.

1import { getDefaultTimezone } from 'date-fns-toolkit';
2
3console.log(`Current timezone: ${getDefaultTimezone()}`);

React Hooks

useDateTimezone(timezone?: string)

Hook that returns timezone-aware date utility functions.

• If timezone is provided, it will use that timezone
• If not provided, it will use the global default timezone

1const dateUtils = useDateTimezone('Europe/Paris');
2// OR
3const dateUtils = useDateTimezone(); // Uses global default

useTimezoneContext()

Hook to access the timezone context when using TimezoneProvider.

1const { timezone, setTimezone } = useTimezoneContext();

Components

TimezoneProvider

Context provider for application-wide timezone settings.

Props:

• children: React children
• defaultTimezone: (optional) Initial timezone to use. Falls back to global default if not provided
• syncWithGlobal: (optional, default: false) When true, changes to context timezone will also update the global default

Toolkit Utility Functions

All toolkit utility functions accept an optional timezone parameter. If not provided, they use the global default timezone.

Format Functions

• format(date, formatString, timezone?, options?)
• formatDateShort(date, timezone?)
• formatDateLong(date, timezone?)
• formatDateTime(date, timezone?)
• formatTime(date, timezone?)

Conversion Functions

• toDate(date, timezone?)
• toZonedTime(date, timezone?)
• fromZonedTime(zonedDate, timezone?)

Parsing Functions

• parseInTimeZone(dateString, formatString, timezone?)

Date Operations

• addDays(date, amount, timezone?)
• subDays(date, amount, timezone?)
• addMonths(date, amount, timezone?)
• subMonths(date, amount, timezone?)
• addYears(date, amount, timezone?)
• subYears(date, amount, timezone?)
• startOfDay(date, timezone?)
• endOfDay(date, timezone?)

Comparison Functions

• isBefore(date1, date2, timezone?)
• isAfter(date1, date2, timezone?)
• isSameDay(date1, date2, timezone?)

Next.js Compatibility

If you're using date-fns-toolkit with Next.js, you might encounter module loading issues. We've provided a detailed guide to help you resolve them:

Next.js Usage Guide

We also have a complete example of using date-fns-toolkit in a Next.js application:

Next.js Example

Quick fix: Add this to your next.config.js:

1/** @type {import('next').NextConfig} */
2const nextConfig = {
3  webpack: (config) => {
4    // Fix for date-fns-toolkit module parse error
5    config.module.rules.push({
6      test: /node_modules\/date-fns-toolkit\/dist\/index\.esm\.js$/,
7      type: 'javascript/auto',
8      resolve: {
9        fullySpecified: false
10      }
11    });
12    
13    return config;
14  }
15};
16
17module.exports = nextConfig;

Universal Compatibility

date-fns-toolkit is designed to work in all JavaScript environments:

• Node.js: Works in both CommonJS and ESM environments
• Browsers: Works with all modern bundlers and browsers
• React: Includes React-specific hooks and components
• Next.js: Special compatibility with Next.js (see Next.js Usage Guide)

Module Formats

The package provides multiple module formats to ensure compatibility:

• CommonJS: dist/index.js (for Node.js and most bundlers)
• ESM: dist/index.mjs (for modern bundlers and environments)
• Legacy ESM: dist/index.esm.js (for backward compatibility)

In most cases, your bundler or environment will automatically choose the right format.

Latest Version

Current version: 1.3.0

Changelog and Release Notes

• Changelog - Brief summary of changes in each version
• Full Changelog - Detailed history of all changes
• Release Notes & Migration Guides - Release notes and upgrade instructions

Why Use This Library?

1. All-in-one: Includes date-fns and date-fns-tz functionality in a single package
2. Global default timezone: Set once, use everywhere - solves a major pain point with date-fns-tz
3. Flexibility: Choose between global defaults, explicit parameters, or React context
4. Tree-shaking: Only include the functions you actually use
5. React integration: First-class support for React with hooks and context
6. TypeScript support: Full type definitions for better development experience

License

MIT

Support

If you find my packages helpful or are interested in the platform I'm building, I'd really appreciate a coffee! Your support helps me dedicate more time to open source projects and platform development.