# Relottie Stringify API - LAST to Lottie
Discover relottie-stringify, the Relottie plugin to serialize a Lottie Abstract Syntax Tree (LAST) back into a Lottie JSON string.

# API Reference: `@lottiefiles/relottie-stringify`

`@lottiefiles/relottie-stringify` is the core [unified](https://unifiedjs.com/) plugin used by relottie to serialize a [LAST (Lottie Abstract Syntax Tree)](/docs/tools/relottie/guides/working-with-last) 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)](/docs/tools/relottie/guides/working-with-last)** 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**](/docs/tools/relottie/guides/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:

```bash
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.

```typescript
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:

```typescript
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`](/docs/tools/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**](/docs/tools/relottie/guides/working-with-last).
- See how trees are generated: [`@lottiefiles/relottie-parse`](/docs/tools/relottie/api/relottie-parse).
- Understand the full pipeline: [Core Concepts](/docs/tools/relottie/getting-started/core-concepts).