Chrono Node

Common errors

• TypeError: chrono.ParsingComponent.dayjs is not a function

  cause Upgrading to chrono-node v2.9.0 without updating code that used the `dayjs` integration. The `dayjs` dependency and its related functions were removed in v2.9.0.
  fix Remove any calls to `ParsingComponent.dayjs()` or other `dayjs`-specific logic from your custom parsers or integrations. Refactor to use native JavaScript `Date` methods.

• Error: Cannot find module 'chrono-node' or undefined is not a function/object for chrono

  cause Incorrect import statement for ESM or CommonJS modules, or trying to use named imports when the library uses a namespace export, especially in mixed environments.
  fix For ESM, use `import * as chrono from 'chrono-node';`. For CommonJS, use `const chrono = require('chrono-node');`. Ensure your build configuration (webpack, rollup, TypeScript `moduleResolution`) correctly handles module types.

• Date results are in the past when expecting future dates (e.g., 'Friday' parses to last Friday)

  cause The parser defaults to the closest matching date. If 'Friday' has already passed in the current week relative to the reference date, it will pick the past Friday.
  fix Pass the `forwardDate: true` option in the `ParsingOption` object: `chrono.parseDate('Friday', referenceDate, { forwardDate: true });`

• Parsing results for relative dates (e.g., 'today', 'tomorrow') are incorrect when timezones are involved.

  cause The reference date's timezone might not be correctly applied during interpretation, especially when the system timezone differs from the intended reference timezone. This was explicitly fixed in v2.8.0 for some scenarios.
  fix Always provide a comprehensive `ParsingReference` object with both `instant` (a `Date` object) and `timezone` (a string like 'America/Los_Angeles' or a minute offset) to ensure consistent timezone-aware parsing.

Warnings

• breaking Chrono v2.0.0 changed its default behavior from attempting to parse all known languages to only international English. Code relying on auto-detection or parsing non-English text without explicit locale configuration will produce incorrect results or fail to parse.
  Fix: For non-English text, explicitly import and use the desired locale parser, e.g., `import { ja } from 'chrono-node'; ja.parseDate('...')` or `chrono.ja.parseDate('...')`. You can also create a custom Chrono instance with specific locales.
• breaking Version 2.9.0 removed the `dayjs` dependency and consequently deprecated and removed `ParsingComponent.dayjs()`. Any custom parsers or existing code relying on this function will break.
  Fix: Refactor custom components or code to use native JavaScript `Date` objects directly or other date utility libraries, as `chrono-node` now exclusively relies on native `Date` functionality.
• gotcha Incorrect date interpretation for relative terms (e.g., 'tomorrow', 'next Friday') can occur if the `ParsingReference` is not correctly set. The meaning of such terms is highly dependent on the `instant` and `timezone` provided in the reference.
  Fix: Always provide a `ParsingReference` object with both `instant` (the current `Date` or a specific reference point) and `timezone` (e.g., 'America/New_York' or a minute offset) to ensure consistent and accurate parsing relative to a specific context.
• gotcha The `forwardDate` parsing option, when `true`, forces Chrono to interpret relative dates (like 'Friday' or 'next month') as being in the future relative to the `reference` date. If not set, it may resolve to a past date if it's closer.
  Fix: If you consistently need dates to be in the future, explicitly set `{ forwardDate: true }` in the `ParsingOption` object when calling `chrono.parseDate` or `chrono.parse`.
• gotcha Version 2.8.0 introduced a fix where reference date calculations (e.g., for "1 day ago", "tomorrow at 9am") are now based on the *assigned timezone* of the reference instant/timestamp, rather than the system's local timezone. This change might subtly alter results for users relying on implicit system timezone behavior.
  Fix: Review existing code that provides reference instants and relies on system timezone interpretations for relative dates. Ensure that the `timezone` property within `ParsingReference` accurately reflects the intended time context for your parsing operations.

Install

• npm install chrono-node npm
• yarn add chrono-node yarn
• pnpm add chrono-node pnpm

Imports

• chrono
  wrong:

  import chrono from 'chrono-node';

  correct:

  import * as chrono from 'chrono-node';

  Chrono is exported as a namespace object, so use `* as chrono` for all exports in ESM. Default import (`import chrono from 'chrono-node'`) will likely result in `undefined` or an empty object in many environments.
• parseDate
  wrong:

  import { parseDate } from 'chrono-node/dist/chrono.js';

  correct:

  import { parseDate } from 'chrono-node';

  The `parseDate` function is a direct named export from the main package. Accessing internal paths like `dist/chrono.js` is not recommended and may break in future versions. You can also access it via the namespace import: `chrono.parseDate`.
• ParsedResult, ParsingReference, ParsingOption
  wrong:

  import { ParsedResult, ParsingReference, ParsingOption } from 'chrono-node';

  correct:

  import type { ParsedResult, ParsingReference, ParsingOption } from 'chrono-node';

  These are TypeScript types and interfaces. Use `import type` for type-only imports to ensure they are stripped during compilation, preventing potential runtime errors or unnecessary bundle size increases.
• chrono (CommonJS)

  const chrono = require('chrono-node');

  For CommonJS environments, the entire library is exported, accessible through `chrono.parseDate()` and `chrono.parse()`.

Quickstart

This quickstart demonstrates basic date parsing, advanced parsing with a reference date and timezone, and the use of the `forwardDate` option for future-only interpretations. It also shows how to get detailed parsing results.

import * as chrono from 'chrono-node';
import type { ParsingReference, ParsingOption } from 'chrono-node';

const text1 = 'An appointment on Sep 12-13 from 2 PM to 4 PM next Friday';
const text2 = 'Tomorrow at noon in New York';
const text3 = 'In 3 days';

// Basic parsing
const result1 = chrono.parseDate(text1);
console.log('Result 1 (basic):', result1?.toISOString());

// Parsing with a specific reference date and timezone
const referenceInstant = new Date('2025-02-27T10:00:00Z'); // UTC instant
const referenceOptions: ParsingReference = {
  instant: referenceInstant,
  timezone: 'America/Los_Angeles' // Reference timezone for interpretation
};
const result2 = chrono.parseDate(text2, referenceOptions);
console.log('Result 2 (ref + timezone):', result2?.toISOString());

// Parsing with the 'forwardDate' option to ensure future dates
const today = new Date('2025-03-01T12:00:00Z'); // Saturday, March 1, 2025
const forwardOptions: ParsingOption = { forwardDate: true };
const result3 = chrono.parseDate(text3, today, forwardOptions);
console.log('Result 3 (forwardDate):', result3?.toISOString());

// Full parsed result (including text, index, start/end components)
const detailedResult = chrono.parse('Book a meeting for next Tuesday at 3pm', new Date('2025-03-01T00:00:00Z'), { forwardDate: true });
if (detailedResult.length > 0) {
  console.log('Detailed result:', JSON.stringify(detailedResult[0], null, 2));
  console.log('  Extracted text:', detailedResult[0].text);
  console.log('  Parsed date:', detailedResult[0].date().toISOString());
}