Frequently Asked Questions
Quick answers to common questions about recurring-dates.
Does this library have any external dependencies?
No external dependencies at all. recurring-dates is built entirely on the native JavaScript Date API and the built-in Intl API including timezone support. React is an optional peer dependency required only for the useRecurringDates hook.
What date library does this use internally?
None. The library does not use moment.js, date-fns, dayjs, or any other date library. All parsing, formatting, arithmetic, and timezone handling is implemented with the native Date object and Intl.DateTimeFormat.
Can I use this without React?
Yes. generateRecurringDates and getRecurringDates are plain JavaScript functions with no framework dependency. Only the useRecurringDates hook requires React (v17, v18, or v19).
Which date formats are supported?
Six formats are supported: "DD-MM-YYYY" (default), "MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", and "MMM DD YYYY". The same FORMAT value must be used for all date fields (STARTS_ON, ENDS_ON, EXCLUDE_DATES) and is also used for the output dates array.
How does INTERVAL work?
INTERVAL controls how many cycles to skip between occurrences. INTERVAL: 1 (default) means every cycle. INTERVAL: 2 on weekly means every other week. INTERVAL: 3 on daily means every 3rd day. INTERVAL: 3 on monthly means quarterly.
What happens when ENDS_ON is before STARTS_ON?
Validation catches this and returns { dates: [], error: "Start Date must be before End Date" }. No exception is thrown all errors are returned as a safe value in the error field.
Can I generate the last Friday of every month?
Yes. Use yearly frequency with WEEK_ORDINALS: ["LAST"], WEEK_DAYS: ["FRI"], and MONTH_NAMES listing all 12 months: ["JAN","FEB","MAR","APR","MAY","JUN","JUL","AUG","SEP","OCT","NOV","DEC"].
Does EXCLUDE_DATES remove dates before or after generation?
After. Dates are first generated based on the frequency rules, then any entries in EXCLUDE_DATES are filtered out before the result is returned. EXCLUDE_DATES values must use the same FORMAT as all other dates.
What is the difference between generateRecurringDates and getRecurringDates?
They are functionally identical. getRecurringDates is a convenience alias that always returns a RecurringDatesResult object it will never be undefined. Use whichever name suits your codebase.
How do I use the TIMEZONE option?
Pass any IANA timezone identifier as the TIMEZONE config key, for example TIMEZONE: "America/New_York" or TIMEZONE: "Asia/Tokyo". Dates are then generated relative to that timezone. Omitting TIMEZONE uses the system's local timezone. Use getUserTimezone() to auto-detect the user's browser timezone.
What are the Frequency, Day, Month, Ordinal, Format constant objects?
v1.0.3 introduced named constant objects so you can write Frequency.WEEKLY instead of "W", Day.MON instead of "MON", Month.JAN instead of "JAN", and so on. Import them individually or use the Recurrence namespace: import { Recurrence } from "recurring-dates".
Is there a CDN / UMD build?
Yes. A UMD bundle is published to npm and available via jsDelivr. Load it with a <script> tag and access the library via window.RecurringDates. See the Installation page for the exact URL.
How do I handle validation errors?
Check the error field on the returned object: if (result.error) { console.error(result.error); }. The dates array will be an empty array when an error is present, so it is always safe to iterate result.dates.
Is the output dates array sorted?
Yes. The dates array is always returned in ascending chronological order regardless of the order in which dates were generated internally.
Can I combine weekly and monthly patterns in one call?
No. Each call targets a single frequency type. To combine patterns, make two separate calls and merge the arrays, then sort or deduplicate as needed.