# Quick Start Guide for relottie
Get started with relottie quickly. This guide shows how to install relottie, parse a Lottie JSON, apply a transformation plugin, and generate modified Lottie JSON output.

# relottie Quick Start

This guide provides a minimal example to get you started with relottie's core functionality: parsing a Lottie JSON, applying a simple transformation plugin, and generating the modified Lottie JSON.

## Prerequisites

- Node.js (version 16.0+ or 18.0+ recommended).
- A package manager like `npm` or `yarn`.

## 1. Installation

First, install the core `relottie` processor. It includes the necessary parsing ([`@lottiefiles/relottie-parse`](/docs/tools/relottie/api/relottie-parse)) and stringifying ([`@lottiefiles/relottie-stringify`](/docs/tools/relottie/api/relottie-stringify)) capabilities.

We also install [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit), a common utility for traversing unist ASTs, which we'll use in our example plugin.

```bash
npm install @lottiefiles/relottie @lottiefiles/last unist-util-visit
# and
npm install unified vfile -D
```

## 2. Create Your Script

Create a TypeScript file (e.g., `transform-lottie.ts`) and add the following code:

```typescript
import { TITLES } from "@lottiefiles/last";
import type { Root, Attribute } from "@lottiefiles/last";
import { relottie } from "@lottiefiles/relottie";
import type { Plugin } from "unified";
import { CONTINUE, EXIT, visit } from "unist-util-visit";
import type { Data, VFile } from "vfile";

const { string: ST } = TITLES;

// --- Define the plugin options and default values ---
interface Options {
  ignore: boolean;
  version: string;
}

// --- Define the plugin options type ---
export type PluginOptions = Partial<Options>;

export const DEFAULT_OPTIONS: Options = {
  ignore: false,
  version: "6.0.0",
};

// --- You can pass any data between plugins using the `data` property of the vfile ---
export interface FileData extends Data {
  updateVersionData: {
    oldVersion: string;
  };
}

// --- Define a simple plugin ---
// This plugin finds the top-level 'v' (version) attribute and updates its value.
const updateVersionPlugin: Plugin<[PluginOptions?], Root> = (ops: PluginOptions = {}) => {
  const options: Options = { ...DEFAULT_OPTIONS, ...ops };
  const updateVersionData: FileData["updateVersionData"] = {
    oldVersion: options.version,
  };

  function transformer(tree: Root, file: VFile): void {
    // Check if the user wants to ignore the version update
    if (options.ignore) return;

    visit(tree, "attribute", (node: Attribute, _parent) => {
      // Check if the node is Version node
      if (node.title !== ST.version) return CONTINUE;

      const primitiveNode = node.children[0];

      if (!primitiveNode) throw new Error("Version attribute is missing a primitive node");

      if (typeof primitiveNode.value !== "string") throw new Error("Version attribute value is not a string");

      // Store the old version value in the file data
      updateVersionData.oldVersion = primitiveNode.value;

      // Update the version value to a new version
      primitiveNode.value = options.version;

      // Stop traversing immediately.
      return EXIT;
    });

    // Store the updated data in the file
    const pluginData: FileData = {
      updateVersionData,
    };

    // Attach the plugin data to the file for other plugins to use
    Object.assign(file.data, pluginData);
  }

  return transformer;
};

// --- Example usage of the plugin ---

// --- Input Lottie JSON ---
const lottie = '{"v":"5.5.2","w":100,"h":100,"fr":60,"ip":0,"op":60,"layers":[]}';

// Apply our custom plugin
const processor = relottie().use(updateVersionPlugin, { version: "6.0.0" });

// --- Process the Lottie ---
const file = await processor.process(lottie);
const updatedLottie = file.toString();

console.log(updatedLottie);
```

## 3. Run the Script

Execute your script using `tsx` or by compiling it first:

```bash
npx tsx playground.ts
```

## 4. Output

You should see the modified Lottie JSON printed to the console, with the version updated:

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

## Next Steps

This example demonstrates the fundamental parse -> transform -> stringify pipeline.

- Learn more about the underlying structure in [Core Concepts](/docs/tools/relottie/getting-started/core-concepts).
- Explore how to use different plugins for analysis in the [Analyzing Lottie Files Guide](/docs/tools/relottie/guides/analyzing-lottie-files).
- Dive deeper into creating your own transformations in the [Modifying Lottie Files Guide](/docs/tools/relottie/guides/modifying-lottie-files) and [Creating Plugins Guide](/docs/tools/relottie/guides/creating-plugins).
- Understand the AST structure in the [Working with LAST](/docs/tools/relottie/guides/working-with-last) guide.