v3.0.0

The first release in three years — and the first published automatically from CI with npm provenance. This is a major version because one packaging change is breaking for one group of users (CDN <script>-tag consumers — see below). If you use a bundler (Vite, webpack, Nuxt, etc.), upgrading requires no code changes — things that were silently broken now simply work.

📦 97% smaller install

lottie-web is no longer compiled into the library bundle. In 2.0.7 it was bundled and declared as a dependency, so every consumer downloaded it twice and bundlers couldn't dedupe or upgrade it.

	2.0.7	3.0.0
Unpacked size on npm	752 kB	23 kB
Library ESM bundle	425 kB	2.4 kB
Copies of lottie-web you ship	2	1 (from your own node_modules)

lottie-web remains a regular dependency — it installs automatically, your bundler resolves exactly one copy, and security/bug fixes in lottie-web 5.x reach you via npm update without waiting for a new lottie-web-vue release.

🐛 Fixed: the documented API now actually works

Two patterns straight from the README were broken in 2.0.7:

// ❌ 2.0.7: DefaultExport was undefined  →  ✅ 3.0.0: works
import LottieAnimation from "lottie-web-vue"

// ❌ 2.0.7: app.use() did nothing        →  ✅ 3.0.0: registers <LottieAnimation> globally
createApp(App).use(LottieAnimation).mount("#app")

Also fixed:

• SSR / Node imports no longer crash. 2.0.7's bundled lottie-web touched document at import time, breaking any server-side import (Nuxt SSR, vitest, etc.). 3.0.0 imports cleanly in Node — loadAnimation only runs on mount in the browser.
• The animation is destroyed exactly once on unmount (a duplicated onBeforeUnmount previously called destroy() twice).
• The speed prop is now reactive — changing it applies setSpeed() to the running animation instead of being ignored after mount.
• The npm tarball no longer ships stray build artifacts (dist/vite.svg, a leftover HelloWorld.vue.d.ts).
• Internals: the lottie AnimationItem is held in a shallowRef instead of a deep reactive proxy (avoids proxying the entire lottie instance).

⚠️ Breaking changes — who is affected and what to do

1. UMD / CDN <script> users must load lottie-web first. This is the reason for the major bump. The UMD build now expects a global lottie instead of carrying its own copy:

<!-- add this line BEFORE lottie-web-vue -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
<script src="https://unpkg.com/lottie-web-vue/dist/lottie-web-vue.umd.cjs"></script>

2. vue is now a peerDependency (^3.3.0) instead of a regular dependency. npm 7+ handles this automatically; it exists to stop a second copy of Vue being nested inside your node_modules — a classic source of "component not recognized" bugs. If you're pinned to Vue 3.2.x you'll see a peer warning; any Vue released since mid-2023 satisfies the range.

3. Node >= 22 is required to build the library (contributors only — the published files are plain ES2020 and run everywhere they did before).

Nothing else changed: all props (animationData, loop, autoPlay, speed), all events (@loopComplete, @complete, @enterFrame, @segmentStart, @stopped), and all nine exposed methods are identical to 2.0.7. The named export import { LottieAnimation } is byte-for-byte the same pattern as before.

🧪 Testing and release process

This release also adds the project's first test suite and CI. Every release now runs, on the tagged commit:

• 28 unit tests (Vitest + @vue/test-utils) covering props, events, exposed methods, and the export surface
• a pack-and-install smoke test that installs the built tarball into a throwaway project and checks ESM/CJS imports, TypeScript resolution, SSR, and tarball contents
• a browser E2E suite (Playwright) running a playground app against the packed tarball

Publishing is done from GitHub Actions via npm trusted publishing, so packages include a provenance attestation linking them to the exact commit and workflow run.

Known limitations (unchanged from 2.x)

Changing animationData, loop, or autoPlay after mount does not re-initialise the animation. Planned for a future minor release.

---

What's Changed

• v3.0.0: tests, packaging fixes, automated releases by @garbit in #23
• 3.0.0-rc.0 by @garbit in #27
• Fix release workflow: remove registry-url that shadowed OIDC trusted publishing by @garbit in #32
• 3.0.0 by @garbit in #33

Full Changelog: v2.0.7...v3.0.0