Getting Started

relottie is a tool that transforms Lotties with plugins. These plugins can inspect and change.

Feature highlights

  • ASTs (inspecting and changing content made easy)
  • plugins (plugins you can pick and choose from)

Intro

relottie is a ecosystem of plugins that work with the Lottie file format as structured data, specifically ASTs (abstract syntax trees). ASTs make it easy for programs to deal with Lottie files. We call those programs plugins. Plugins inspect and change trees. You can use the existing plugins or you can make your own.

Contents

What is this?

You can use plugins to change Lottie.

In:

{ "v": "5.5.2" }

Plugin:

import {visit} from 'unist-util-visit'
import type { Plugin, Node } from 'unified'
import type { Root } from '@lottiefiles/last'


const myRelottiePlugin: Plugin<[]> () {
  function transform (tree: Root, _file: VFile): void {
    visit(tree, (node) => {
      if (node.title === 'version') {
        node.title = "6.0.0"
      }
    })
  }


  return transform
}

Out:

{ "v": "6.0.0" }

You can use relottie for many different things. unified is the core project that transforms content with ASTs. relottie adds support for Lottie to unified. last is the Lottie AST that relottie uses.

This GitHub repository is a monorepo that contains the following packages:

  • last — Type definitions for Lottie Abstract Syntax Tree (last)
  • last-builder — Composable functions to easily build syntax tree (last) structures
  • relottie — a unified processor with support for parsing Lottie input and serializing Lottie as output
  • relottie-parse — plugin to take Lottie as input and turn it into a syntax tree last
  • relottie-stringify — plugin to take a syntax tree (last) and turn it into Lottie as output
  • relottie-cli — Command line interface to inspect and change Lottie files with relottie
  • relottie-extract-features — plugin to extract Lottie features from the document and store them in vfile

When should I use this?

relottie focusses on ASTs and providing an interface for plugins to transform them.

Depending on the input you have and output you want, you can use different parts of relottie. If the input is Lottie JSON file, you can use relottie-parse with unified. If the output is Lottie JSON file, you can use relottie-stringify with unified. If you need to transform LottieJSON to .lottie, you can dotlottie.js

Plugins

relottie plugins deal with Lottie. Some popular examples are:

These plugins are exemplary because what they do and how they do it is quite different, respectively to extend Lottie syntax, inspect trees, change trees, and define other output formats.

You can choose from the plugins that already exist. Here are three good ways to find plugins:

Some plugins are maintained by us here in the @lottiefiles organization while others are maintained by folks elsewhere. Anyone can make relottie plugins, so as always when choosing whether to include dependencies in your project, make sure to carefully assess the quality of relottie plugins too.

Examples

  • be the first one ;)

Syntax

relottie follows last definitions, lottie-types and lottie-docs title names (with a few changes) Some syntax extensions are supported through plugins.

We use momoa JSON parser for our parsing. See its documentation for more information.

Syntax tree

The syntax tree format used in relottie is last. It represents Lottie constructs as JSON objects.

In:

{ "v": "6.0.0" }

Out:

{
  "type": "root",
  "title": "animation",
  "hasExpressions": false,
  "position": {
    "start": {
      "line": 1,
      "column": 1,
      "offset": 0
    },
    "end": {
      "line": 1,
      "column": 17,
      "offset": 16
    }
  },
  "children": [
    {
      "type": "attribute",
      "key": {
        "type": "key",
        "position": {
          "start": {
            "line": 1,
            "column": 3,
            "offset": 2
          },
          "end": {
            "line": 1,
            "column": 6,
            "offset": 5
          }
        },
        "value": "v"
      },
      "title": "version",
      "position": {
        "start": {
          "line": 1,
          "column": 3,
          "offset": 2
        },
        "end": {
          "line": 1,
          "column": 15,
          "offset": 14
        }
      },
      "children": [
        {
          "type": "primitive",
          "value": "6.0.0",
          "position": {
            "start": {
              "line": 1,
              "column": 8,
              "offset": 7
            },
            "end": {
              "line": 1,
              "column": 15,
              "offset": 14
            }
          },
          "valueType": "string"
        }
      ]
    }
  ]
}

Types

The relottie organization and the unified as a whole is fully typed with TypeScript. Types for last are available in last. Also have a look at lottie-types.

For TypeScript to work, it is particularly important to type your plugins correctly. We strongly recommend using the Plugin type from unified with its generics and to use the node types for the syntax trees provided by last.

import type { Root } from '@lottiefiles/last';
import type { Plugin } from 'unified';


export function myRelottiePluginAcceptingOptions(options): Plugin<[Options?], Root> {
  // `options` is `Options?`.
  return function (tree, file) {
    // `tree` is `Root`.
  }
}

Compatibility

As of now, that is Node.js 16.0+, and 18.0+ (other versions have not been tested yet) Our projects sometimes work with older versions, but this is not guaranteed.

Security

As last properties can have expressions, and improper use of last can open you up to cross-site scripting cross-site scripting (XSS). Carefully assess each plugin and the risks involved in using them.

Setting up Monorepo

git clone https://github.com/LottieFiles/relottie.git


cd relottie


pnpm install

Running in dev mode

pnpm dev

Running test suite

pnpm test

Add a changelog message

We use changeset

pnpm changelog

Building

pnpm build

Linting

pnpm lint

Contribute

Any contributions are welcome.

Community & Support

  • Github issues. For bugs and errors you encounter using this player.
  • Discord. For hanging out with the community and sharing your awesome Lottie animations!

Acknowledgments

The initial release of this project was authored by @aidosmf