API Reference: `@lottiefiles/relottie-parse`

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

It handles the first stage of the typical relottie processing pipeline.

Installation

This plugin is included by default when you use the main @lottiefiles/relottie package. However, if you are building a custom unified pipeline or need to interact with the parser directly, you can install it separately:

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

You will also typically need unified itself if using this package directly.

Usage

You add relottieParse to a unified processor instance using .use().

import { unified } from "unified";
import relottieParse from "@lottiefiles/relottie-parse";
import type { Root } from "@lottiefiles/last";

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

// Create a processor that only parses
const processor = unified().use(relottieParse);

// Parse the input string into a LAST tree
const tree: Root = processor.parse(inputLottie);

console.log(JSON.stringify(tree, null, 2));

When used with the main relottie() processor, this plugin is automatically included.

AST Output

The relottie-parse plugin transforms the input Lottie JSON string into a LAST (Lottie Abstract Syntax Tree). This tree is the standard representation used throughout the relottie ecosystem for analysis and transformations.

Key characteristics of the output LAST tree:

It follows the unist specification.
Nodes have a type (e.g., root, attribute, primitive).
Parent nodes (Root, Attribute, Element, Collection, ObjectNode, ArrayNode) have a Lottie-specific semantic title (e.g., version, layer-image, transform-opacity) derived from the Lottie specification. Use the TITLES export from @lottiefiles/last to reference these robustly.
By default, nodes include a position property detailing their location (line, column, offset) in the original Lottie JSON source string. This is crucial for error reporting and source mapping tools.
The Root node of the tree will have a hasExpressions: boolean flag, indicating whether the parser detected any Lottie expressions, which is important for Security Considerations.

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

Options

@lottiefiles/relottie-parse can be configured with an options object when added via .use(relottieParse, options). These options primarily control how the underlying momoa JSON parser operates and how relottie-parse itself constructs the LAST.

import { unified } from "unified";
import relottieParse, { type Options as RelottieParseOptions } from "@lottiefiles/relottie-parse";
// Options are typically a combination of momoa's and relottie-parse's specific ones.
// You might need to import momoa types if using its specific options directly.

// Example options structure (consult package types for exact and full definitions)
interface ParserOptions extends RelottieParseOptions {
  // momoa parser options
  mode?: "json" | "jsonc" | "json5"; // momoa option: 'json' (default), 'jsonc' (JSON with comments), 'json5' (JSON5 spec)
  ranges?: boolean; // momoa option: Include a 'range' property [startIndex, endIndex] on momoa AST nodes (default: false)
  // relottie-parse specific options
  position?: boolean; // Controls if 'position' (line, column, offset) is added to LAST nodes (default: true)
  sourcemap?: boolean;
  // 'module' or other specific options would be listed if available
}

const parseOptions: ParserOptions = {
  // momoa related options (example)
  mode: "json", // Strict JSON parsing
  ranges: false, // Don't include byte ranges from momoa if not needed

  // relottie-parse specific options
  position: true, // Ensure LAST nodes have line/column/offset (default)
  // sourcemap: false, // Example, check relottie-parse specifics
};

const processor = unified().use(relottieParse, parseOptions);

const inputLottie = '{"v":"5.5.7", "nm": /* comment */ "My Animation"}'; // JSONC example if mode was 'jsonc'
// const tree = processor.parse(inputLottie);

// The resulting 'tree' nodes will have 'position' fields if position:true.
// The parsing behavior (e.g., comment handling) depends on the 'mode'.

Key options include:

position: boolean (default: true by relottie-parse).
- If true, detailed positional information (start, end objects with line, column, offset) is attached to each node in the output LAST. This is inherited from unist and is invaluable for error reporting, linters, and source mapping.
- If false, this positional information is omitted, which can slightly reduce the memory footprint of the AST.
mode: 'json' | 'jsonc' | 'json5' (from momoa, default: 'json').
- Controls the parsing mode of the underlying momoa parser.
- 'json': Strict JSON according to RFC 8259.
- 'jsonc': JSON with JavaScript-style comments (single-line // and multi-line /* ... */).
- 'json5': The JSON5 specification, which allows comments, trailing commas, unquoted keys, and more.
- relottie-parse defaults to strict 'json'. If you need to parse Lottie files that might contain comments (e.g., jsonc), you would set this option.
ranges: boolean (from momoa, default: false).
- If true, momoa includes a range: [startIndex, endIndex] property on its AST nodes, indicating the 0-indexed start and end character offsets in the input string. relottie-parse uses this (if available and position is true) to help construct the more detailed position object for LAST nodes.
sourcemap: boolean (default: typically false or implicitly linked to position).
- The exact behavior of a sourcemap option would depend on its implementation in relottie-parse. Generally, if true, it would ensure that all necessary information for generating a source map (tying the AST back to the original source file) is meticulously collected. This is often synonymous with ensuring position data is present and accurate.

Always consult the specific documentation or TypeScript type definitions for @lottiefiles/relottie-parse and potentially momoa for the most accurate and complete list of supported options and their default values, as these can evolve.

Underlying Parser (`momoa`)

As noted in the source documentation, relottie-parse is built upon the momoa JSON parser. momoa parses the raw JSON into a preliminary JSON-AST, which relottie-parse then transforms into the Lottie-specific LAST structure with semantic title properties.

Security

Remember that parsing alone does not execute any code. However, the resulting LAST tree might contain representations of JavaScript expressions if they were present in the original Lottie JSON. Subsequent processing steps or plugins should handle these with care. See Security Considerations.

Next Steps

Learn about the structure this plugin produces: Guide: Working with LAST.
See how the parsed tree is serialized back to JSON: @lottiefiles/relottie-stringify.
Understand the full pipeline: API Reference.

Relottie Parse API - Lottie to LAST

API Reference: @lottiefiles/relottie-parse