Home

Awesome

relottie

CI GitHub contributors GitHub

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

Feature highlights

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:

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

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

Acknowledgments

The initial release of this project was authored by @aidosmf

License

MIT © LottieFiles