What is relottie?

relottie is a powerful ecosystem designed to process Lottie JSON files using plugins.

Instead of treating Lottie files as raw JSON (that hard to reason about), relottie parses them into a structured format called an Abstract Syntax Tree (AST). This tree representation is based on the unist specification and named as LAST (Lottie Abstract Syntax Tree), makes it incredibly easy to understand, inspect, and modify the contents of a Lottie file.

The Core Idea: ASTs + Plugins

1. Processor: relottie takes your Lottie JSON text file as input and processes it into necessary unified.js interfaces for other plugin programs.

2. AST Transformation: first, it parses the Lottie JSON into a JSON-AST using Momoa parser and then transforms it to last tree using the parser plugin (relottie-parse).

3. Plugin Magic: You apply one or more transformer plugins. Each plugin can traverse the last tree, analyze nodes, or make specific changes.

4. Stringifying: Finally, a compiler plugin (relottie-stringify) converts the (potentially modified) last tree back into a valid Lottie JSON text output.

Example: A Simple Transformation

Imagine you want to update the Lottie version number within a file.

Input Lottie JSON:

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

A Simple relottie Plugin (Conceptual):

const findFramerate: Plugin<[PluginOptions?], Root> = (_ops: PluginOptions = {}) => {
  return function (tree: Root, file: VFile): void {
    visit(tree, "attribute", (node: Attribute, _parent) => {
      if (node.title !== "framerate") return CONTINUE;

      console.log(node);

      return EXIT;
    });
  };
};

(Note: This is a basic plugin. See Creating Plugins for more.)

console.log yields the framerate feature's node

{
  type: 'attribute',
  key: {
    type: 'key',
    position: { start: [Object], end: [Object] },
    value: 'fr'
  },
  title: 'framerate',
  position: {
    start: { line: 1, column: 30, offset: 29 },
    end: { line: 1, column: 37, offset: 36 }
  },
  children: [
    {
      type: 'primitive',
      value: 60,
      position: [Object],
      valueType: 'number'
    }
  ]
}

Built on unified

relottie leverages the robust unified.js project. unified provides the core engine for processing content through plugins and ASTs. relottie extends unified by adding the specific knowledge required to create new plugins or communicate with existing programs within the unist specifications, such as Notably, remark (markdown), rehype (HTML), and retext (natural language) and more. In addition, unified has hundreds of utilities that could help to edit LAST tree structure and create your own relottie plugin.

The relottie Ecosystem Packages

The relottie project is organized as a monorepo containing several key packages:

• @lottiefiles/last: Defines the TypeScript types for the Lottie Abstract Syntax Tree (last).

• @lottiefiles/last-builder: Provides helper functions to construct last trees programmatically.

• @lottiefiles/relottie: The main processor that orchestrates parsing, plugin execution, and stringifying.

• @lottiefiles/relottie-parse: The core parser plugin that transforms Lottie JSON into a last tree.

• @lottiefiles/relottie-stringify: The core compiler plugin that serializes a last tree back into Lottie JSON text.

• @lottiefiles/relottie-cli: A command-line tool for using relottie to inspect and change Lottie files.

• Transformer Plugins: Like @lottiefiles/relottie-extract-features and @lottiefiles/relottie-metadata for specific analysis tasks.

You can mix and match these tools and plugins, or even create your own, to build powerful Lottie processing pipelines.

Next, let's explore Why use relottie?.