# Anime.js v4 ships as ES modules, and the npm package contains nothing but dist

> A MIT-licensed animation engine whose documented entry point is a single named import, whose keyword list promises considerably more than its README explains, and whose published tarball is the built output alone. Good for a bundler-based front end, awkward if you need to read the source or run the examples from an installed package.

**juliangarnier/anime** — Anime.js is a JavaScript animation engine for DOM elements, SVG, JavaScript objects, and timeline-based motion.

- Repository: https://github.com/juliangarnier/anime
- Website: https://animejs.com
- Stars: 73,188 · Forks: 4,948
- Language: JavaScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/juliangarnier-anime

## The documented entry point is one named import and nothing else

Version 4 is described as working by importing ES modules, and the README gives exactly one example, which doubles as the shortest possible description of the API:

```javascript
import {
  animate,
  stagger,
} from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true
});
```

Four things are visible in those lines. The target is a CSS selector, so elements are addressed the way a stylesheet addresses them rather than through a ref you hold. Properties are given as keys, and a property can take an object with a from value, which is how the rotation starts at -180 rather than at 0. Timing is expressed in a key called duration rather than as a separate options object. And loop and alternate are booleans on the same call rather than chained methods.

The package metadata backs up that ES module framing rather than contradicting it. The type field is set to module, the main entry points at a CommonJS build, the module field at the ESM build, and the exports map carries types, require, import and default conditions for the root plus separate subpath entries for timer and animation. So a CommonJS consumer is still served, through index.cjs, even though the documented path is the import above.

## The published package is dist alone, so src and examples never reach npm

The files array in package.json contains one entry, dist. That is the entire contents of the npm tarball. Everything else in the repository, the src/ tree, the twenty-six example directories under examples/, the rollup config, the two tsconfig files, the tests directory and the assets, is reachable by cloning but is not installed alongside the package.

The practical consequences are specific. If you want to read the implementation to understand how a property is interpolated, you need the repository rather than node_modules. If you want to run the examples, you need the repository, which is why the open:examples script exists and why it starts a local server instead of serving anything from the installed package. And if you need to patch a behaviour, you are forking rather than overriding, because there is no source in the install to patch.

There is a second, subtler effect on bundlers. The sideEffects field is narrowed to two globs, the adapters directory under dist/modules and the same path under src, which is a declaration that everything else in the package is side-effect free and safe to tree-shake. That is a useful and deliberate claim for a library, and it also means an incorrect import of an adapter that is not actually used can be dropped entirely rather than initialised, so adapter-dependent behaviour has to be verified in a production build rather than assumed from a development run.

## The keyword list promises far more surface than the README describes

The README's own description is narrow: a JavaScript animation library that works with CSS properties, SVG, DOM attributes and JavaScript objects, with a simple API. The keywords field in package.json tells a different story. Alongside the expected entries of animation, timeline, easings and cubic-bezier, it lists timer, animatable, draggable, scope, scroll, spring, splitText, WAAPI, Canvas, WebGL, and two spellings of three.js.

That is not padding. Each of those names corresponds to something a front-end developer would otherwise build by hand: drag behaviour with inertia, scroll-linked and sticky motion, spring and bezier easing, text splitting for per-character reveals, and rendering targets that are not the DOM at all. A library that animates a canvas context or drives a WebGL scene through the same timeline it uses for a stylesheet is a different proposition from one that tweens CSS.

The gap has a cost. The README is 346 words and none of these capabilities are described in it, so a reader evaluating the library from the repository alone has to infer the surface from a keyword array and then confirm it on the documentation site at animejs.com/documentation, which the README points to for the full documentation. If your requirement is one of the keywords, budget for that extra step before you commit.

## Twenty-six example directories are the real feature list

Because the README is short, the examples directory does the work, and it is organised well enough to be read as a capability map. The timeline group is the largest: timeline-50K-stars, timeline-refresh-starlings, timeline-seamless-loop and timeline-stress-test, which between them cover a large object count, incremental refresh, looping without a seam and load behaviour. Adjacent to them sit clock-playback-controls, irregular-playback-typewriter and text, which are about controlling playback rather than composing it.

The input and scroll group is the second cluster. draggable-playground, draggable-infinite-auto-carousel, draggable-mouse-scroll-snap-carousel and animatable-follow-cursor cover pointer interaction, and onscroll-sticky and onscroll-responsive-scope cover scroll-linked animation with a scoped target. Layout and rendering follow: auto-layout, layered-css-transforms, advanced-grid-staggering, stagger, svg-graph, svg-line-drawing, canvas-2d and threejs.

Two names in that list are worth pausing on. canvas-2d and threejs confirm that the animation engine is not confined to the DOM, which matches the Canvas and WebGL keywords and contradicts any assumption built from the README sentence alone. And the four timeline examples are the closest thing the repository offers to a performance argument, though none of them states a frame budget, a measured duration or a device, so they demonstrate that the scenarios work rather than how fast they run.

## Type declarations are described as landing in types/ and published from dist/modules

The npm script table in the README describes two scripts that generate type declarations. The dev script watches for changes in src/**/*.js, bundles the ESM version to lib/ and creates type declarations in types/. The build script bundles ESM, UMD, CJS and IIFE versions to lib/ and creates type declarations in types/. Both mention a types/ directory and a lib/ directory, neither of which appears in the repository's top level.

The top level instead holds dist/, src/, tests/, examples/, assets/, rollup.config.js, tsconfig.json and tsconfig.types.json. And package.json points its types field at ./dist/modules/index.d.ts, with the exports map repeating that path for the root, the timer subpath and the animation subpath, while the browser bundle fields for jsdelivr and unpkg point at ./dist/bundles/anime.umd.min.js.

So the two documents disagree about where the output lands, and a reader trying to reproduce a build will produce a lib/ and types/ tree that is not the tree that gets published. The presence of two tsconfig files, one for the project and one for the types, suggests the distinction is deliberate inside the build even though the README describes a single output directory. It is a small documentation defect, and it is the kind that costs an hour the first time you hit it.

## Migrating from v3 means leaving the repository for a wiki page

The README has no upgrade notes. What it has is a link, and the link goes to the project's GitHub wiki at Migrating-from-v3-to-v4. Anyone arriving from v3 therefore learns that the API changed from a source that is not versioned with the code and is not covered by the repository's release process.

The release history suggests the pace of that change. v4.4.0 and v4.4.1 shipped on consecutive days in April 2026, and v4.5.0 followed on 2026-06-22. The repository's last push was on 2026-08-21, so the default branch is ahead of the newest published version by more than a month. The package.json version field reads 4.5.0, which matches the latest release rather than the branch tip, so a clone and an install can differ.

The four distribution formats named in the build script matter for that upgrade too. ESM, UMD, CJS and IIFE are all produced, and the CDN fields serve the UMD minified bundle, so a page that loads Anime.js from a script tag is on a different artefact from a page that imports the ESM modules, and the two can drift between releases. If you are migrating, pin the exact version on both sides of the change and read the wiki guide first, because the import shape in the README example is the v4 shape and will not match v3 code.

## Conclusion

Anime.js v4 suits a front-end project already on a bundler that wants one library covering CSS properties, SVG attributes and plain JavaScript objects without writing three animation paths by hand, and the keyword surface suggests it also covers drag, scroll-linked motion and canvas work if you need those. It does not suit a project that needs the source or the examples at install time, because the published package contains only dist, so plan to clone the repository for either. Before migrating from v3, read the migration guide in the project wiki rather than the README, since v4 changed the import shape and the README carries no upgrade notes, and check which of the features in the keyword list you actually need against the documentation site, because the README describes a much smaller surface than the library ships.

## FAQ

### How do I use anime.js?

Version 4 is used by importing ES modules. The README example imports animate and stagger from animejs, then calls animate with a CSS selector as the target and a property object containing values such as x, rotate with a from value, duration, a delay built from stagger, an ease name, and loop and alternate booleans. The full documentation is at animejs.com/documentation.

### How do I install anime js?

It is published to npm as animejs, and version 4 is consumed as ES modules. A CommonJS build is also published at ./dist/modules/index.cjs through the package exports map, and a UMD minified bundle is served from the jsdelivr and unpkg fields. The repository itself is cloned with git, and the README's development instructions begin with npm i.

### What does the Anime.js npm package actually contain?

Only the dist directory, because the files array in package.json lists dist and nothing else. The src tree, the rollup config, the tests and the twenty-six example directories exist in the repository but are not installed with the package, so reading the implementation or running the examples requires a clone rather than an install.

## Sources

- [Official documentation](https://animejs.com)
- [Official README](https://github.com/juliangarnier/anime#readme)
- [Project repository](https://github.com/juliangarnier/anime)
- [Release notes](https://github.com/juliangarnier/anime/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/juliangarnier-anime