Lottie Lint

1.2.0 verified Fri May 01 auth: no javascript

A linting tool for Lottie animation JSON files. Current stable version is 1.2.0. It checks for performance issues, compatibility problems, and errors in Lottie animations. Key differentiators: provides granular reports with severity levels (error, warn, info, incompatible) and identifies incompatible features across platforms (iOS, Web, Android). Designed for use in CI/CD pipelines to catch Lottie issues early. Release cadence appears irregular, with a few minor versions since initial release.

Common errors

error TypeError: linter is not a function ↓

cause Using default import incorrectly with CommonJS (require) without .default.

fix

Use: const linter = require('lottie-lint').default;

error Cannot read property 'length' of undefined ↓

cause Passing a JSON string instead of a parsed object to the linter.

fix

Parse the string first: linter(JSON.parse(jsonString))

error undefined is not an object (evaluating 'reports.forEach') ↓

cause Destructuring incorrectly; linter returns an object, not an array.

fix

Ensure variable names match: const { reports } = linter(data);

Warnings

gotcha The linter function mutates the input JSON object (adds internal properties). ↓

fix Clone the JSON before passing to linter if preservation is needed: linter(JSON.parse(JSON.stringify(animation)))

gotcha The default export is a function that expects a JSON object, not a string. Passing a string will cause an error. ↓

fix Parse JSON string with JSON.parse() before calling linter.

gotcha The 'json' property in the return value is the input object (possibly mutated). It is not a JSON string. ↓

fix Use JSON.stringify() to get a JSON string if needed.

deprecated No deprecated warnings known for this package. ↓

fix N/A

Install

npm install lottie-lint

yarn add lottie-lint

pnpm add lottie-lint

Imports

default
wrong
```
import { linter } from 'lottie-lint';
```
correct
```
import linter from 'lottie-lint';
```
The package exports a default function, not a named export.
default (require)
wrong
```
const linter = require('lottie-lint');
```
correct
```
const linter = require('lottie-lint').default;
```
In Node.js with CommonJS, access the default export via .default property.
linter return value
wrong
```
const result = linter(lottieJson); const reports = result.reports;
```
correct
```
const { json, reports } = linter(lottieJson);
```
Destructure both json and reports from the returned object. json is the parsed JSON, reports is the array of lint issues.

Quickstart

Demonstrates how to import the linter, run it on a Lottie JSON object, and process the resulting reports.

import linter from 'lottie-lint';
import fs from 'fs';

// Read a Lottie JSON file
const lottieJson = JSON.parse(fs.readFileSync('animation.json', 'utf-8'));

// Run the linter
const { json, reports } = linter(lottieJson);

// Print each report
reports.forEach(report => {
  console.log(`[${report.type}] ${report.rule}: ${report.message}`);
  if (report.incompatible.length > 0) {
    console.log(`  Incompatible on: ${report.incompatible.join(', ')}`);
  }
});

// Check if there are any errors
const errors = reports.filter(r => r.type === 'error');
if (errors.length > 0) {
  process.exit(1);
}