Date and Time Formatting with strftime

Common errors

• TypeError: strftime is not a function

  cause Attempting to call `strftime` as a constructor (`new strftime()`) or calling methods on an incorrectly imported `strftime` object. This can also happen if a module bundler misinterprets the CJS default export.
  fix Ensure `strftime` is imported correctly as a function/object (e.g., `const strftime = require('strftime');`) and called directly or its methods (`strftime(...)`, `strftime.localize(...)`). Do not use `new` with `strftime`.

• SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined

  cause These errors occur when mixing CommonJS `require()` and ES module `import` syntax in incompatible JavaScript environments, or when a CJS module is incorrectly treated as an ESM module and vice-versa.
  fix In a file intended for ES Modules, ensure your `package.json` has `"type": "module"` or the file ends with `.mjs`. Use `import strftime from 'strftime';`. In a file intended for CommonJS, ensure `"type": "module"` is NOT in `package.json` or the file ends with `.cjs`. Then, use `const strftime = require('strftime');`.

• Incorrect padding for %-y (e.g., '01' instead of '1')

  cause Versions of `strftime` prior to `0.10.2` contained a bug where the `%-y` specifier would incorrectly include a leading zero instead of omitting it.
  fix Upgrade the `strftime` package to version `0.10.2` or later to resolve the incorrect padding behavior for `%-y`.

Warnings

• breaking The `v0.10.0` release removed old API methods (such as `strftimeTZ` and `strftimeUT`) that were previously deprecated in `v0.9`.
  Fix: Migrate any usage of `strftimeTZ` or `strftimeUT` to the unified `strftime.timezone(offset)` method, providing the timezone offset as minutes from GMT or an ISO 8601 string.
• breaking The `v0.9.0` release introduced a significant API unification and cleanup, alongside a major performance boost. This involved changes to how the library is used, deprecating older patterns.
  Fix: Review the `v0.9.0` changelog and updated usage examples to adapt to the new unified API. Specifically, be aware of changes related to timezone handling and the removal of previous functions like `strftimeTZ`.
• gotcha Due to changes in `Date.toString()` behavior in V8 (Node.js v10+, Chrome 66+), the `%Z` specifier for time zone names may not always return the expected short name, sometimes falling back to a longer name or a generic offset. Version `0.10.1` included an attempt to work around this, but inconsistencies can still occur across different environments.
  Fix: Upgrade to `strftime` version `0.10.1` or newer. If precise short time zone names are critical and environment inconsistencies persist, consider using explicit `strftime.timezone(offset)` with carefully chosen format strings.
• gotcha This package is distributed exclusively as a CommonJS module. Direct ES Module `import` statements (e.g., `import strftime from 'strftime';`) may not function correctly in pure ESM Node.js environments without a bundler or specific `package.json` configuration for CJS interoperability.
  Fix: For Node.js CommonJS projects, use `const strftime = require('strftime');`. In ES Module projects, while `import strftime from 'strftime';` can sometimes work due to Node.js's interoperability, using a bundler like Webpack or Rollup often provides more consistent results when importing CJS modules into an ESM context. Alternatively, consider dynamic `import('strftime')` if suitable for your application logic.

Install

• npm install strftime npm
• yarn add strftime yarn
• pnpm add strftime pnpm

Imports

• strftime
  wrong:

  import strftime from 'strftime';

  correct:

  const strftime = require('strftime');

  This package is distributed as a CommonJS module. While `import strftime from 'strftime'` might work with bundlers or Node.js's CJS interoperability layers, the canonical and most reliable import for Node.js environments remains `require()`. Direct ESM imports might require specific configuration or transpilation.
• localize

  const strftime = require('strftime');
  const it_IT_locale = { /* ... */ };
  const strftimeIT = strftime.localize(it_IT_locale);

  The `localize` method is called on the imported `strftime` function/object to create a new, locale-specific formatting function. This function then behaves identically to the default `strftime` but uses the provided locale data.
• localizeByIdentifier

  const strftime = require('strftime');
  const strftimeES = strftime.localizeByIdentifier('es_ES');

  This method simplifies loading pre-bundled locales using their string identifiers (e.g., 'it_IT', 'en_US'), returning a new localized `strftime` function. Refer to the documentation for a full list of bundled locales.
• timezone

  const strftime = require('strftime');
  const strftimeUTC = strftime.timezone(0);
  const strftimePDT = strftime.timezone('-0700');

  The `timezone` method creates a new `strftime` function that formats dates according to a specified timezone offset, which can be provided as minutes from GMT (number) or as an ISO 8601 string (e.g., '+HHMM' or '-HHMM').

Quickstart

This quickstart demonstrates basic date formatting, applying a custom locale, using a bundled locale identifier, and formatting dates with explicit timezone offsets using `strftime`.

const strftime = require('strftime');

// Get current date/time in default locale
const now = new Date();
console.log('Current time (default):', strftime('%B %d, %Y %H:%M:%S', now));

// Define a custom Italian locale
const it_IT_custom = {
  identifier: 'it-IT-custom',
  days: ['domenica', 'lunedi', 'martedi', 'mercoledi', 'giovedi', 'venerdi', 'sabato'],
  shortDays: ['dom', 'lun', 'mar', 'mer', 'gio', 'ven', 'sab'],
  months: ['gennaio', 'febbraio', 'marzo', 'aprile', 'maggio', 'giugno', 'luglio', 'agosto', 'settembre', 'ottobre', 'novembre', 'dicembre'],
  shortMonths: ['gen', 'feb', 'mar', 'apr', 'mag', 'giu', 'lug', 'ago', 'set', 'ott', 'nov', 'dic'],
  AM: 'AM', PM: 'PM', am: 'am', pm: 'pm',
  formats: {
    D: '%m/%d/%y', F: '%Y-%m-%d', R: '%H:%M',
    X: '%T', c: '%a %b %d %X %Y', r: '%I:%M:%S %p',
    T: '%H:%M:%S', v: '%e-%b-%Y', x: '%D'
  }
};

// Use a custom locale
const strftimeIT_custom = strftime.localize(it_IT_custom);
console.log('Current time (Italian custom):', strftimeIT_custom('%B %d, %Y %H:%M:%S', now));

// Use a bundled locale (e.g., French)
const strftimeFR = strftime.localizeByIdentifier('fr_FR');
console.log('Current time (French bundled):', strftimeFR('%A %d %B %Y %H:%M:%S', now));

// Format a specific date in a specific timezone (e.g., Pacific Daylight Time, -0700)
const specificDate = new Date(1678886400000); // March 15, 2023 12:00:00 UTC
const strftimePDT = strftime.timezone('-0700');
console.log('Specific date (PDT):', strftimePDT('%F %T %Z', specificDate));

// Format the same specific date in UTC
const strftimeUTC = strftime.timezone(0);
console.log('Specific date (UTC):', strftimeUTC('%F %T %Z', specificDate));