chartjs-adapter-date-fns

chartjs-adapter-date-fns is a lightweight adapter that plugs date-fns into Chart.js’s time-scale axis system. Once imported alongside Chart.js and date-fns, it overrides Chart.js’s built-in _adapters._date object with implementations backed by date-fns’s parse, format, arithmetic, and boundary functions, covering everything from millisecond-level formatting to week, quarter, and year rollups.

Chart.js only ships a generic date-adapter interface and leaves the actual date engine to consumers, so teams already using date-fns elsewhere in their app can standardize on one date library instead of pulling in Moment.js or Luxon just to satisfy Chart.js’s time-scale requirements. The adapter itself has no configuration API beyond a side-effect import; locale support is handled entirely through Chart.js’s own adapters.date.locale scale option.

What You Get

• A full override of Chart.js’s _date adapter (parse, format, add, diff, startOf, endOf) backed entirely by date-fns
• Sensible default format strings for every Chart.js time unit, from millisecond up to year
• Locale support by passing any date-fns locale object through the scale’s adapters.date.locale option
• Both ESM and minified UMD bundle builds, plus a jsDelivr/unpkg CDN distribution

Common Use Cases

• Rendering a time-series line or bar chart where the x-axis needs to auto-format ticks from milliseconds up to years
• Standardizing on date-fns across an app that already avoids Moment.js or Luxon, including for Chart.js’s time scale
• Localizing chart axis labels and tooltips using a specific date-fns locale (e.g. de, ja, fr)
• Formatting dashboard time-series data (metrics, logs, financial data) with fine-grained per-unit tick formats

Under The Hood

Architecture The entire package is a single ~114-line src/index.js file that imports Chart.js’s internal _adapters registry and a set of date-fns functions, then calls _adapters._date.override({...}) once with an object literal implementing the seven-method Chart.js date-adapter contract (formats, parse, format, add, diff, startOf, endOf). There is no internal layering, class hierarchy, or caching beyond the format map and per-unit switch statements — Chart.js’s time scale calls straight into these methods with primitive timestamps and unit strings, and each method delegates directly to the matching date-fns function. This is a minimal, direct-delegation integration: if Chart.js ever changed the shape of its _adapters._date contract, the whole file would need to change in lockstep since there’s no compatibility shim.

Tech Stack The package declares zero runtime dependencies — only peerDependencies on chart.js (>=2.8.0) and date-fns (>=2.0.0) — plus a dev toolchain of Rollup 3 (with node-resolve and terser plugins) for producing ESM, CommonJS, and minified UMD bundle outputs, Karma 6 with Jasmine and Chrome/Firefox launchers for real-browser test execution, and ESLint 8 with the shared eslint-config-chartjs ruleset. It ships three distribution targets for different consumption paths: an ESM build, a CommonJS build via package exports, and a minified UMD bundle served from jsDelivr/unpkg for CDN use. There is no server, database, or build-time codegen — this is a pure browser-side plugin.

Code Quality Tests run in real browsers (not headless mocks) via Karma, driving actual Chart.js and date-fns behavior end-to-end across a single Jasmine spec file that exercises the adapter’s format presets and parse/format round-tripping. CI runs a GitHub Actions matrix across Ubuntu and Windows, reporting coverage to Coveralls for both Chrome and Firefox runs, and a separate workflow automates npm publishing on GitHub release — comprehensive process infrastructure for a small package, even though the test suite itself covers a limited set of scenarios. There are no TypeScript definitions in this package (consumers rely on Chart.js’s own types for the adapter shape) and error handling is minimal — malformed format strings would surface as uncaught date-fns exceptions rather than adapter-level validation.

API Design The entire integration surface is a single side-effect import (import 'chartjs-adapter-date-fns') — there is nothing to instantiate or configure directly; Chart.js’s time scale auto-detects the registered adapter. The only consumer-facing configuration point, locale selection, reuses an option Chart.js already exposes (adapters.date.locale) rather than inventing a new one, and peerDependencies correctly use version floors instead of exact pins to avoid duplicate-install conflicts. The README documents install, CDN usage, and locale configuration with runnable snippets. The main ergonomic wart is that importing the module mutates global Chart.js state as a side effect with no exported API signaling that — a new consumer has to read the README to understand what the bare import actually does.