vite-plugin-minify-lottie-json

A Vite plugin that minifies Lottie animation JSON assets at build time, shrinking their size without breaking the animation.

Features

• Import via the *.json?lottie suffix — the plugin hooks into Vite's transform pipeline and minifies the file automatically. No build script or CLI step required.
• Works with both Vite flavors — compatible with rolldown-vite (Vite ≥ 8.0) and the classic rollup-vite (Vite < 8.0). The plugin auto-detects which engine is in use.
• Minifies After Effects expressions — expression code embedded in the Lottie file is treated as JavaScript and minified.
• Minifies marker text — After Effects marker comments that contain JSON are re-serialized without whitespace. Marker text that is not valid JSON is left untouched.
• Does not corrupt your animation — unlike some generic Lottie minifiers, it preserves expressions and marker data.

Installation

# npm
npm install --save-dev vite-plugin-minify-lottie-json

# yarn
yarn add --dev vite-plugin-minify-lottie-json

# pnpm
pnpm add --save-dev vite-plugin-minify-lottie-json

# bun
bun add --dev vite-plugin-minify-lottie-json

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from "vite";
import minifyLottieJson from "vite-plugin-minify-lottie-json";

export default defineConfig({
	plugins: [minifyLottieJson()],
});

Then import a Lottie JSON file with the ?lottie query suffix. The plugin intercepts the import and hands you the minified JSON as a parsed object — just like a regular *.json import, but with the content minified:

import animationData from "./assets/lotties/anim.json?lottie";

// lottie-web
import lottie from "lottie-web";
lottie.loadAnimation({
	container: document.querySelector("div"),
	renderer: "svg",
	loop: true,
	autoplay: true,
	animationData,
});

// @lottiefiles/dotlottie-web
import { DotLottie } from "@lottiefiles/dotlottie-web";
new DotLottie({
	autoplay: true,
	loop: true,
	canvas: document.querySelector("canvas"),
	data: animationData,
});

Only imports that use the ?lottie suffix are affected — regular *.json imports are handled by Vite as usual.

Options

The plugin accepts an optional options object:

minifyLottieJson({
	minifyJSEngine: "oxc", // default
});

minifyJSEngine

Controls which JavaScript engine is used to minify the After Effects expressions.

• Type: "oxc" | "swc" | "esbuild" | "terser"
• Default: "oxc"

The default engine, "oxc", is powered by oxc-minify, which is bundled with the plugin and needs no extra setup. The other engines are not bundled — if you choose one, install its package yourself:

| Engine | Package to install | | ----------- | -------------------- | | "oxc" | oxc-minify (bundled) | | "swc" | @swc/core | | "esbuild" | esbuild | | "terser" | terser |

# example: switch to the terser engine
npm install --save-dev terser

What gets minified

The plugin walks the Lottie document and minifies two specific parts:

After Effects expressions

In the Lottie format, an expression attached to an animated property is stored in the x field of that property (alongside a, k and ix). Its value is JavaScript code wrapped in a Bodymovin-style var $bm_rt assignment, for example:

{
	"a": 0,
	"k": [16, 4],
	"ix": 2,
	"x": "var $bm_rt;\n$bm_rt = [\n    value[0],\n    value[1] + thisComp.layer('Circle 1').effect('OffsetHeight')('Slider')\n];"
}

The plugin treats this value as JavaScript and minifies it down to a compact single line.

{"a":0,"k":[16,4],"ix":2,"x":"var $bm_rt=[value[0],value[1]+thisComp.layer(`Circle 1`).effect(`OffsetHeight`)(`Slider`)];"}

After Effects marker text

Marker comments live in the top-level markers array, where each marker's text is stored in its cm field:

{
	"tm": 0,
	"dr": 15,
	"cm": "{\r\n\"name\": \"NormalToPressed\"\r\n}"
}

The plugin treats the cm text as JSON and re-serializes it without whitespace:

{"tm":0,"dr":15,"cm":"{\"name\":\"NormalToPressed\"}"}

If the cm value is not valid JSON, it is left exactly as-is.

TypeScript

The plugin ships type declarations for the *.json?lottie import. There are two ways to register them:

Via tsconfig.json (preferred for TypeScript 6.0+)

Add the package's client entry to the types array:

{
	"compilerOptions": {
		"types": [
			"vite-plugin-minify-lottie-json/client"
		]
	}
}

Via vite-env.d.ts (preferred for TypeScript below 6.0)

Add a triple-slash reference to your vite-env.d.ts file (create it if it does not already exist):

/// <reference types="vite-plugin-minify-lottie-json/client" />

Either way, TypeScript will type the default export of a *.json?lottie import as an object.

Why not use lottie-minify?

There is already an existing tool, lottie-minify, for compressing Lottie files. This plugin deliberately does not build on it: in testing, running lottie-minify on these files corrupted them — for example, the After Effects expressions were stripped out entirely. This plugin instead performs a focused, format-aware minification that shrinks the file while keeping expressions and marker data intact.

License

MIT