# relottie Processor API Reference
API reference for the relottie package. Learn how to use the main entry point for parsing, transforming, and stringifying Lottie JSON files.

# 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](https://unifiedjs.com/) processor tailored for parsing, transforming, and stringifying Lottie JSON files.

This processor bundles the necessary core plugins:

- [`@lottiefiles/relottie-parse`](/docs/tools/relottie/api/relottie-parse) for parsing Lottie JSON into a [LAST](/docs/tools/relottie/guides/working-with-last) tree.
- [`@lottiefiles/relottie-stringify`](/docs/tools/relottie/api/relottie-stringify) for serializing a LAST tree back into Lottie JSON.

## Installation

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

```typescript
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](https://github.com/unifiedjs/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](/docs/tools/relottie/guides/creating-plugins).
- **`options` (optional)**: Configuration options specific to the `plugin` being used.

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

```typescript
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](https://github.com/vfile/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)`.

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

```typescript
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`](/docs/tools/relottie/api/last-builder).)_

## Next Steps

- Explore the [LAST Specification](/docs/tools/relottie/guides/working-with-last) to understand the tree structure.
- Learn about the core plugins: [`relottie-parse`](/docs/tools/relottie/api/relottie-parse) and [`relottie-stringify`](/docs/tools/relottie/api/relottie-stringify).
- See the [Guides](/docs/tools/relottie/guides) for practical usage examples.