Chart.js: three package entry points, one UMD file, and a docs URL that decides your version

The exports map has three doors and no back door

Most of what you need to know about consuming this library is in the exports map, and it is stricter than it looks. Three subpaths are published, the root ".", "./auto" and "./helpers", and each one carries its own types, import and require conditions:

"./helpers": {
    "types": "./helpers/helpers.d.ts",
    "import": "./helpers/helpers.js",
    "require": "./helpers/helpers.cjs"
}

The root points its types at ./dist/types.d.ts with import at ./dist/chart.js and require at ./dist/chart.cjs, and ./auto has the same shape. The consequence for a consumer is that a deep import into the build output, something like a file under dist, is not in the map and will fail in any bundler that respects exports, which is most of them today. The second consequence is quieter: type resolution depends on which of the three doors you came through, so a project that mixes the root import with a helpers import is resolving two declaration files.

One UMD file serves the CDN, and it is declared side-effectful

The distribution is three builds of one library. main is ./dist/chart.cjs for CommonJS, module is ./dist/chart.js, and both the jsdelivr and unpkg fields point at the same file, ./dist/chart.umd.min.js, so a script tag from either CDN gets the UMD bundle. The package also sets "type": "module", which tells Node and bundlers that .js here is ESM, and then lists exactly four files under sideEffects: ./auto/auto.js, ./auto/auto.cjs, ./dist/chart.umd.min.js and ./dist/chart.umd.js. Everything else is safe to tree-shake, and the two auto entry files are side effects on purpose, since that entry exists to register chart types. The practical reading: if you import the UMD build, the bundler keeps it whole, and if you import the root, only what you touch survives.

Karma means the test suite needs a browser, not Node

The development workflow is the part of the repository that shapes who can contribute. Scripts include autobuild as rollup -c -w, a build of rollup -c followed by pnpm emitDeclarations, and emitDeclarations itself as tsc --emitDeclarationOnly followed by pnpm copyDeclarations, which copies ./src/types/ into ./dist/types/. The dev script starts karma with ./karma.conf.cjs, and the tests live in test/. So the suite runs in a real browser rather than a simulated DOM, which is the right call for a canvas renderer and also a barrier: a contributor needs a working browser before a single assertion runs. Linting is spread across .eslintrc.yml, .eslintignore, .htmllintrc, .editorconfig and .codeclimate.yml, and the presence of an HTML linter says the documentation and sample pages are linted alongside the source.

composer.json sits next to package.json, and nobody syncs them here

There is a Composer manifest in the root of a JavaScript library, which means this project is also distributed to PHP projects through Packagist rather than only through npm. That is a real second channel with a real second consequence: the npm release and the Composer release are versioned separately, and nothing in this repository says how the two are kept in step or who does it. A PHP team requiring this package is not getting the artifact you get from npm, and a bug fixed in one channel is not automatically fixed in the other. MAINTAINING.md sits at the top level next to the manifests, so the process for maintainers is written down somewhere, but the README does not summarise it and does not mention the Composer channel at all.

The docs URL is the version, and every link in the README says version 4

The README is mostly a documentation index, and it makes one decision for you: all the links point to the new version 4 of the library, covering Introduction, Getting Started, General data structures, Configuration, Charts, Axes, Developers, Popular Extensions and Samples. For an older version you have to put the version in the URL yourself, which the README shows with an example pointing at a 2.9.4 documentation path. That is the whole versioning story for the docs, and it is the mechanism behind the most common way to get stuck. A search result, a blog post or a colleague's link from the 2.x era lands on /docs/latest/ by default, which is now version 4, where the API differs. Fix the habit early: read the version out of the URL before you copy anything out of the page.

4.5.1 shipped in October 2025 while master moved in September 2026

The release record and the commit record run at different speeds. Published versions are v4.5.1 on 2025-10-13, v4.5.0 on 2025-06-14 and v4.4.9 on 2025-04-15, and package.json carries 4.5.1 to match. The last push to the repository was on 2026-09-14 and the project is not archived, so work is landing on master with no release behind it. For an adopter that means two clocks to reason about: npm gives you a version that is up to eleven months old, and anyone building from the branch is running code no tag covers. A team that wants the fixes and not the surprises has to decide which of those it is, and MAINTAINING.md is the file that explains how releases happen.

Support questions go to Stack Overflow, not the issue tracker

The contributing section is short and it draws a boundary. Instructions for building and testing Chart.js are in the documentation rather than in the repository, and before submitting an issue or a pull request you are asked to read the contributing guidelines first. Support questions are directed to Stack Overflow with the chart.js tag. So the tracker is for defects and changes, and a how-do-I question filed there is off protocol, which is worth knowing before you spend an afternoon on a question that has an answer three pages into the configuration documentation. The docs and the samples are the intended first stop, the tag is the second, and the tracker is last, in that order.

Editorial conclusion

Adopt Chart.js when you want charts drawn straight onto a canvas with no runtime dependency on a charting framework, and take the versioned documentation URL rather than the versionless one. Do not adopt it expecting deep imports or a CommonJS-first layout, because the exports map only publishes the root, ./auto and ./helpers, and the package is marked as an ES module. Before pinning, check that 4.5.1 from 2025-10-13 is acceptable against a repository whose last push was 2026-09-14, since the two move at different speeds, and read the browser list in .browserslistrc, which the README does not summarise.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes