relottie Quick Start

This guide provides a minimal example to get you started with relottie's core functionality: parsing a Lottie JSON, applying a simple transformation plugin, and generating the modified Lottie JSON.

Prerequisites

Node.js (version 16.0+ or 18.0+ recommended).
A package manager like npm or yarn.

1. Installation

First, install the core relottie processor. It includes the necessary parsing (@lottiefiles/relottie-parse) and stringifying (@lottiefiles/relottie-stringify) capabilities.

We also install unist-util-visit, a common utility for traversing unist ASTs, which we'll use in our example plugin.

npm install @lottiefiles/relottie @lottiefiles/last unist-util-visit
# and
npm install unified vfile -D

2. Create Your Script

Create a TypeScript file (e.g., transform-lottie.ts) and add the following code:

import { TITLES } from "@lottiefiles/last";
import type { Root, Attribute } from "@lottiefiles/last";
import { relottie } from "@lottiefiles/relottie";
import type { Plugin } from "unified";
import { CONTINUE, EXIT, visit } from "unist-util-visit";
import type { Data, VFile } from "vfile";

const { string: ST } = TITLES;

// --- Define the plugin options and default values ---
interface Options {
  ignore: boolean;
  version: string;
}

// --- Define the plugin options type ---
export type PluginOptions = Partial<Options>;

export const DEFAULT_OPTIONS: Options = {
  ignore: false,
  version: "6.0.0",
};

// --- You can pass any data between plugins using the `data` property of the vfile ---
export interface FileData extends Data {
  updateVersionData: {
    oldVersion: string;
  };
}

// --- Define a simple plugin ---
// This plugin finds the top-level 'v' (version) attribute and updates its value.
const updateVersionPlugin: Plugin<[PluginOptions?], Root> = (ops: PluginOptions = {}) => {
  const options: Options = { ...DEFAULT_OPTIONS, ...ops };
  const updateVersionData: FileData["updateVersionData"] = {
    oldVersion: options.version,
  };

  function transformer(tree: Root, file: VFile): void {
    // Check if the user wants to ignore the version update
    if (options.ignore) return;

    visit(tree, "attribute", (node: Attribute, _parent) => {
      // Check if the node is Version node
      if (node.title !== ST.version) return CONTINUE;

      const primitiveNode = node.children[0];

      if (!primitiveNode) throw new Error("Version attribute is missing a primitive node");

      if (typeof primitiveNode.value !== "string") throw new Error("Version attribute value is not a string");

      // Store the old version value in the file data
      updateVersionData.oldVersion = primitiveNode.value;

      // Update the version value to a new version
      primitiveNode.value = options.version;

      // Stop traversing immediately.
      return EXIT;
    });

    // Store the updated data in the file
    const pluginData: FileData = {
      updateVersionData,
    };

    // Attach the plugin data to the file for other plugins to use
    Object.assign(file.data, pluginData);
  }

  return transformer;
};

// --- Example usage of the plugin ---

// --- Input Lottie JSON ---
const lottie = '{"v":"5.5.2","w":100,"h":100,"fr":60,"ip":0,"op":60,"layers":[]}';

// Apply our custom plugin
const processor = relottie().use(updateVersionPlugin, { version: "6.0.0" });

// --- Process the Lottie ---
const file = await processor.process(lottie);
const updatedLottie = file.toString();

console.log(updatedLottie);

3. Run the Script

Execute your script using tsx or by compiling it first:

npx tsx playground.ts

4. Output

You should see the modified Lottie JSON printed to the console, with the version updated:

{ "v": "6.0.0", "w": 100, "h": 100, "fr": 60, "ip": 0, "op": 60, "layers": [] }

Next Steps

This example demonstrates the fundamental parse -> transform -> stringify pipeline.

Learn more about the underlying structure in Core Concepts.
Explore how to use different plugins for analysis in the Analyzing Lottie Files Guide.
Dive deeper into creating your own transformations in the Modifying Lottie Files Guide and Creating Plugins Guide.
Understand the AST structure in the Working with LAST guide.

Quick Start Guide for relottie