API Reference: @lottiefiles/relottie-stringify

@lottiefiles/relottie-stringify is the core unified plugin used by relottie to serialize a LAST (Lottie Abstract Syntax Tree) back into a Lottie JSON string.

In the unified ecosystem, this type of plugin is often referred to as a compiler. It handles the final stage of the typical relottie processing pipeline, converting the internal tree representation back into a usable Lottie file format.

AST Input

@lottiefiles/relottie-stringify expects a LAST (Lottie Abstract Syntax Tree) as its input. This tree is the standard unist-based representation used throughout the relottie ecosystem.

• The input tree should conform to the LAST specification, with nodes having appropriate type, title, children, value, etc., properties.

• The stringifier traverses this tree and reconstructs the Lottie JSON string based on the structure and values found in the LAST nodes.

For a detailed understanding of the LAST structure, please refer to the Guide: Working with LAST.

Installation

This plugin is included by default when you use the main @lottiefiles/relottie package. If building a custom unified pipeline or needing direct access to the stringifier, install it separately:

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

You will also typically need unified and potentially @lottiefiles/relottie-parse or a pre-existing LAST tree if using this package directly.

Usage

Typically, you don't interact with this plugin directly when using the main relottie() processor, as it's automatically included and run as the final step of .process().

However, if you have a LAST tree (perhaps generated by @lottiefiles/relottie-parse or @lottiefiles/last-builder) and want to stringify it explicitly, you can use it with the .stringify() method of a unified processor.

import { unified } from "unified";
import relottieParse from "@lottiefiles/relottie-parse"; // Need a tree source
import relottieStringify from "@lottiefiles/relottie-stringify";
import type { Root } from "@lottiefiles/last";
import { visit } from "unist-util-visit"; // For the modification example
import type { Attribute } from "@lottiefiles/last";

// Example from source documentation:
const processor = unified()
  .use(relottieParse) // Use parser to get a tree
  .use(() => (tree: Root) => {
    // Example transformer plugin
    visit(tree, "attribute", (node: Attribute) => {
      if (node.key === "v") {
        node.key = "new_v"; // Modify the tree
      }
    });
  })
  .use(relottieStringify); // Use stringify

const inputLottie = '{"v":"5.5.7"}';

// Process the input: parse -> transform -> stringify
const file = processor.processSync(inputLottie); // Using processSync for simplicity here
const outputJsonString = String(file);

console.log(outputJsonString);
// Output: { "new_v": "5.5.7" }

// --- OR --- Stringify an existing tree directly:

const existingTree: Root = processor.parse(inputLottie); // Get a tree
// (Modify existingTree if needed)
const stringifier = unified().use(relottieStringify);
const outputFromJsonDirect = stringifier.stringify(existingTree);

console.log(outputFromJsonDirect);
// Output: { "v": "5.5.7" } (if tree wasn't modified)

Options

@lottiefiles/relottie-stringify can accept an options object. One common option for JSON stringifiers is to control indentation:

import { unified } from "unified";
import relottieParse from "@lottiefiles/relottie-parse";
import relottieStringify, { type Options as RelottieStringifyOptions } from "@lottiefiles/relottie-stringify";
import type { Root } from "@lottiefiles/last";

// Example options (consult package types for exact and full definitions)
interface StringifyOpts extends RelottieStringifyOptions {
  space?: string | number; // Controls indentation of the output JSON
}

const stringifyOptions: StringifyOpts = {
  space: 2, // Indent with 2 spaces for pretty-printing
  // space: '\t', // Or indent with tabs
};

const inputLottie = '{"v":"5.5.7","nm":"Test Animation","layers":[]}';
const tree: Root = unified().use(relottieParse).parse(inputLottie);

// Processor with stringify options
const processorWithOpts = unified().use(relottieStringify, stringifyOptions);
const prettyJsonString = processorWithOpts.stringify(tree);

console.log(prettyJsonString);
/* Output:
{
  "v": "5.5.7",
  "nm": "Test Animation",
  "layers": []
}
*/

// Without options (compact output)
const processorWithoutOpts = unified().use(relottieStringify);
const compactJsonString = processorWithoutOpts.stringify(tree);
console.log("\nCompact output:");
console.log(compactJsonString);
// Output: {"v":"5.5.7","nm":"Test Animation","layers":[]}

• space: string | number (default: undefined, meaning no extra whitespace).

  • This option controls the indentation of the output JSON string, similar to the space argument in JSON.stringify().

  • If space is a number, it indicates the number of space characters to use as white space for indenting purposes (up to 10).

  • If space is a string, that string (or the first 10 characters of it) is used as white space.

  • If not provided or undefined, the JSON is generated without any extra white space, resulting in a compact output.

Always consult the specific documentation or TypeScript type definitions for @lottiefiles/relottie-stringify for the most accurate and complete list of supported options and their default values.

Converting to .lottie

While relottie-stringify outputs Lottie JSON, the source documentation notes that if you need to convert Lottie JSON to the compressed .lottie format, you should use other tools like dotlottie-js. relottie's focus is on the JSON representation and its AST.

Security

Stringifying a LAST tree is generally safe. However, ensure that the tree you are stringifying is trusted, especially if it originated from an untrusted source or has been modified by potentially unsafe plugins. The stringifier aims to produce valid JSON based on the input tree.

Next Steps

• Learn about the tree structure this plugin consumes: Guide: Working with LAST.

• See how trees are generated: @lottiefiles/relottie-parse.

• Understand the full pipeline: Core Concepts.