API Reference: `@lottiefiles/relottie`

The @lottiefiles/relottie package provides the main entry point for working with the relottie ecosystem. It exports a pre-configured unified processor tailored for parsing, transforming, and stringifying Lottie JSON files.

This processor bundles the necessary core plugins:

@lottiefiles/relottie-parse for parsing Lottie JSON into a LAST tree.
@lottiefiles/relottie-stringify for serializing a LAST tree back into Lottie JSON.

Installation

npm install @lottiefiles/relottie
# or
yarn add @lottiefiles/relottie

Core Usage

You import the relottie function and call it to get a new processor instance.

import { relottie } from "@lottiefiles/relottie";

// Create a new processor instance
const processor = relottie();

This processor is now ready to use plugins and process Lottie data.

Key Methods

While the underlying unified processor has several methods, the primary ones you'll typically use with the relottie instance are:

`.use(plugin, [options])`

Adds a plugin to the processor's pipeline. Plugins run in the order they are added.

plugin: A unified plugin. This can be a transformer (to modify the tree), a parser (though relottie-parse is included by default), or a stringifier (though relottie-stringify is included by default). See Creating Plugins.
options (optional): Configuration options specific to the plugin being used.

Returns the processor instance (this), allowing chaining of .use() calls.

import { relottie } from "@lottiefiles/relottie";
import myCustomPlugin from "./my-custom-plugin";
import anotherPlugin from "another-relottie-plugin";

const processor = relottie()
  .use(myCustomPlugin, { setting: true }) // Use plugin with options
  .use(anotherPlugin); // Use another plugin

`.process(input)`

Processes the given input by running it through the full pipeline: parse -> transform (via .use() plugins) -> stringify.

input: The Lottie content to process. Can be a string, a Node.js Buffer, or a VFile.

Returns a Promise that resolves with a VFile object representing the processed file. The resulting Lottie JSON string is typically accessed via String(vfile).

import { relottie } from "@lottiefiles/relottie";
import { VFile } from "vfile"; // Example using VFile

const lottieString = '{"v":"5.5.7", ...}';
const lottieVFile = new VFile({ path: "animation.json", value: lottieString });

async function runProcessing() {
  try {
    const processor = relottie(); // Add .use(plugin) calls here if needed

    // Process a string
    const resultFromString = await processor.process(lottieString);
    console.log("Output from string:", String(resultFromString));

    // Process a VFile
    const resultFromVFile = await processor.process(lottieVFile);
    console.log("Output from VFile:", String(resultFromVFile));
    // You can also access data attached by plugins, e.g.:
    // console.log(resultFromVFile.data);
  } catch (error) {
    console.error("Processing failed:", error);
  }
}

runProcessing();

Other `unified` Methods (`.parse()`, `.stringify()`)

The relottie() processor instance is fundamentally a unified processor. Therefore, methods like .parse(input) (which only runs the parsing stage and returns the AST) and .stringify(tree) (which only runs the stringifying stage on a given AST) are also available. However, the examples in the relottie source documentation primarily focus on using .process() for the complete workflow and .use() for customization.

Example: Using a Plugin

import { relottie } from "@lottiefiles/relottie";
import type { Plugin } from "unified";
import type { Root } from "@lottiefiles/last";
import { visit } from "unist-util-visit";

// Simple plugin to add a description metadata field
const addDescriptionPlugin: Plugin<[], Root> = () => {
  return (tree) => {
    visit(tree, "element", (node) => {
      if (node.key === "meta" && node.title === "metadata") {
        // Simplified: assumes meta object exists and is ObjectNode
        if (node.children?.[0]?.type === "object") {
          // Check if description exists
          const hasDesc = node.children[0].children.some((attr) => attr.key === "d");
          if (!hasDesc) {
            // Add a description Attribute (needs last-builder for cleaner creation)
            // This is a simplified representation
            const descriptionNode = {
              type: "attribute",
              key: "d",
              title: "description",
              children: [{ type: "primitive", value: "Processed by relottie" }],
            };
            node.children[0].children.push(descriptionNode as any);
          }
        }
      }
    });
  };
};

const inputLottie = '{"v":"5.5.7","meta":{"a":"Author"},"layers":[]}';

async function addDescription() {
  const file = await relottie().use(addDescriptionPlugin).process(inputLottie);
  console.log(String(file));
  // Expected output (simplified): {"v":"5.5.7","meta":{"a":"Author","d":"Processed by relottie"},"layers":[]}
}

addDescription();

(Note: Programmatically adding nodes is cleaner using @lottiefiles/last-builder.)

Next Steps

Explore the LAST Specification to understand the tree structure.
Learn about the core plugins: relottie-parse and relottie-stringify.
See the Guides for practical usage examples.

relottie Processor API Reference

API Reference: @lottiefiles/relottie