{"id":12087,"library":"strftime","title":"Date and Time Formatting with strftime","description":"strftime is a JavaScript utility library that provides `strftime`-style date and time formatting, mimicking the functionality found in C's `strftime` function and Ruby's extensions. The current stable version is `0.10.3`, primarily receiving maintenance updates and bug fixes rather than active feature development. This is indicated by its infrequent release cadence since 2016's planned v1.0 release that never materialized. Key differentiators include its support for various format specifiers (including Ruby extensions), robust localization capabilities through custom locale objects or bundled identifiers, and timezone handling via offsets. It is designed to work both in Node.js environments and web browsers, offering a consistent API for formatting `Date` objects into human-readable strings. The library aims for broad compatibility, even supporting very old Node.js versions.","status":"maintenance","version":"0.10.3","language":"javascript","source_language":"en","source_url":"git://github.com/samsonjs/strftime","tags":["javascript","strftime","format","string","time","date"],"install":[{"cmd":"npm install strftime","lang":"bash","label":"npm"},{"cmd":"yarn add strftime","lang":"bash","label":"yarn"},{"cmd":"pnpm add strftime","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import strftime from 'strftime';","symbol":"strftime","correct":"const strftime = require('strftime');"},{"note":"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.","symbol":"localize","correct":"const strftime = require('strftime');\nconst it_IT_locale = { /* ... */ };\nconst strftimeIT = strftime.localize(it_IT_locale);"},{"note":"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.","symbol":"localizeByIdentifier","correct":"const strftime = require('strftime');\nconst strftimeES = strftime.localizeByIdentifier('es_ES');"},{"note":"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').","symbol":"timezone","correct":"const strftime = require('strftime');\nconst strftimeUTC = strftime.timezone(0);\nconst strftimePDT = strftime.timezone('-0700');"}],"quickstart":{"code":"const strftime = require('strftime');\n\n// Get current date/time in default locale\nconst now = new Date();\nconsole.log('Current time (default):', strftime('%B %d, %Y %H:%M:%S', now));\n\n// Define a custom Italian locale\nconst it_IT_custom = {\n  identifier: 'it-IT-custom',\n  days: ['domenica', 'lunedi', 'martedi', 'mercoledi', 'giovedi', 'venerdi', 'sabato'],\n  shortDays: ['dom', 'lun', 'mar', 'mer', 'gio', 'ven', 'sab'],\n  months: ['gennaio', 'febbraio', 'marzo', 'aprile', 'maggio', 'giugno', 'luglio', 'agosto', 'settembre', 'ottobre', 'novembre', 'dicembre'],\n  shortMonths: ['gen', 'feb', 'mar', 'apr', 'mag', 'giu', 'lug', 'ago', 'set', 'ott', 'nov', 'dic'],\n  AM: 'AM', PM: 'PM', am: 'am', pm: 'pm',\n  formats: {\n    D: '%m/%d/%y', F: '%Y-%m-%d', R: '%H:%M',\n    X: '%T', c: '%a %b %d %X %Y', r: '%I:%M:%S %p',\n    T: '%H:%M:%S', v: '%e-%b-%Y', x: '%D'\n  }\n};\n\n// Use a custom locale\nconst strftimeIT_custom = strftime.localize(it_IT_custom);\nconsole.log('Current time (Italian custom):', strftimeIT_custom('%B %d, %Y %H:%M:%S', now));\n\n// Use a bundled locale (e.g., French)\nconst strftimeFR = strftime.localizeByIdentifier('fr_FR');\nconsole.log('Current time (French bundled):', strftimeFR('%A %d %B %Y %H:%M:%S', now));\n\n// Format a specific date in a specific timezone (e.g., Pacific Daylight Time, -0700)\nconst specificDate = new Date(1678886400000); // March 15, 2023 12:00:00 UTC\nconst strftimePDT = strftime.timezone('-0700');\nconsole.log('Specific date (PDT):', strftimePDT('%F %T %Z', specificDate));\n\n// Format the same specific date in UTC\nconst strftimeUTC = strftime.timezone(0);\nconsole.log('Specific date (UTC):', strftimeUTC('%F %T %Z', specificDate));","lang":"javascript","description":"This quickstart demonstrates basic date formatting, applying a custom locale, using a bundled locale identifier, and formatting dates with explicit timezone offsets using `strftime`."},"warnings":[{"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.","message":"The `v0.10.0` release removed old API methods (such as `strftimeTZ` and `strftimeUT`) that were previously deprecated in `v0.9`.","severity":"breaking","affected_versions":">=0.10.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.10.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"TypeError: strftime is not a function"},{"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');`.","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.","error":"SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined"},{"fix":"Upgrade the `strftime` package to version `0.10.2` or later to resolve the incorrect padding behavior for `%-y`.","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.","error":"Incorrect padding for %-y (e.g., '01' instead of '1')"}],"ecosystem":"npm"}