Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lottie
✓ import { lottie } from 'vite-plugin-lottie'
✗ import lottie from 'vite-plugin-lottie'
Named export, not default.
animationData
✓ import animationData from './animation.json?lottie'
✗ import animationData from './animation.json'
Must append ?lottie query to trigger the plugin.
vite-plugin-lottie/client
✓ /// <reference types="vite-plugin-lottie/client" />
✗ import 'vite-plugin-lottie/client'
Triple-slash directive for TypeScript type augmentation; not a runtime import.
Setup Vite plugin in config and use ?lottie import in Vue component to load animation.
// vite.config.ts
import { defineConfig } from 'vite'
import { lottie } from 'vite-plugin-lottie'
export default defineConfig({
plugins: [lottie()],
})
// App.vue
<script setup lang="ts">
import Lottie from 'lottie-web'
import animationData from './animation.json?lottie'
import { onMounted } from 'vue'
onMounted(() => {
Lottie.loadAnimation({
container: document.getElementById('lottie-container'),
renderer: 'svg',
loop: true,
autoplay: true,
animationData: animationData
})
})
</script>
<template>
<div id="lottie-container" style="width: 200px; height: 200px;"></div>
</template>
Errors
Common errors & fixes
Cannot find module './animation.json?lottie' or its corresponding type declarations.
TypeScript does not know about the ?lottie query suffix without type augmentation.
fixAdd /// <reference types="vite-plugin-lottie/client" /> in a .d.ts file or in your tsconfig's include.
Failed to load import './animation.json' from 'src/App.vue'. Unexpected token '}' in JSON at position...
Importing a .json file without the ?lottie query, causing Vite to treat it as plain JSON.
fixChange import to './animation.json?lottie'.
Lottie is not defined
Missing lottie-web runtime dependency; the plugin does not include Lottie player.
fixInstall lottie-web: npm install lottie-web
Audit
Dependencies
viterequiredpeer dependency required for plugin to function
lottie-weboptionalruntime dependency for Lottie player; must be installed separately