{"id":20093145,"url":"https://github.com/lottiefiles/relottie","last_synced_at":"2025-04-05T04:08:56.294Z","repository":{"id":176564920,"uuid":"653536236","full_name":"LottieFiles/relottie","owner":"LottieFiles","description":"Lottie processor powered by plugins","archived":false,"fork":false,"pushed_at":"2025-03-23T08:23:09.000Z","size":20446,"stargazers_count":49,"open_issues_count":2,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-02T13:49:01.918Z","etag":null,"topics":["abstract-syntax-tree","ast","dotlottie","javascript","last","lottie","parser","typescript","unified"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LottieFiles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-14T08:39:13.000Z","updated_at":"2025-03-23T08:06:40.000Z","dependencies_parsed_at":"2024-09-02T11:36:02.310Z","dependency_job_id":"3fa5ed9f-cde3-47b2-9a5c-85efbf7404a4","html_url":"https://github.com/LottieFiles/relottie","commit_stats":{"total_commits":179,"total_committers":8,"mean_commits":22.375,"dds":"0.36871508379888274","last_synced_commit":"65ea63715af110664e9fff86f584de3da6c62f8d"},"previous_names":["lottiefiles/relottie"],"tags_count":148,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LottieFiles%2Frelottie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LottieFiles%2Frelottie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LottieFiles%2Frelottie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LottieFiles%2Frelottie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LottieFiles","download_url":"https://codeload.github.com/LottieFiles/relottie/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284943,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract-syntax-tree","ast","dotlottie","javascript","last","lottie","parser","typescript","unified"],"created_at":"2024-11-13T16:46:02.225Z","updated_at":"2025-04-05T04:08:56.250Z","avatar_url":"https://github.com/LottieFiles.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# relottie\n\n![CI](https://github.com/lottiefiles/relottie/workflows/Release/badge.svg)\n![GitHub contributors](https://img.shields.io/github/contributors/LottieFiles/relottie)\n![GitHub](https://img.shields.io/github/license/LottieFiles/relottie)\n\n**relottie** is a tool that transforms Lotties with plugins. These plugins can inspect and change.\n\n## Feature highlights\n\n* [x] **[ASTs][syntax-tree]** (inspecting and changing content made easy)\n* [x] **[plugins][]** (plugins you can pick and choose from)\n\n## Intro\n\nrelottie is a ecosystem of plugins that work with the Lottie file format as structured data, specifically ASTs (abstract syntax trees).\nASTs make it easy for programs to deal with Lottie files.\nWe call those programs plugins.\nPlugins inspect and change trees.\nYou can use the existing plugins or you can make your own.\n\n*   to learn Lottie, see this [lottie-docs][] and [what-is-lottie][]\n*   for more about us, see [lottiefiles][]\n*   for help, see [contribute][]\n*   for more about [unified][], see [unifiedjs.com][]\n\n## Contents\n\n*   [What is this?](#what-is-this)\n*   [When should I use this?](#when-should-i-use-this)\n*   [Plugins](#plugins)\n*   [Examples](#examples)\n*   [Syntax](#syntax)\n*   [Syntax tree](#syntax-tree)\n*   [Types](#types)\n*   [Compatibility](#compatibility)\n*   [Security](#security)\n*   [Setting up monorepo](#setting-up-monorepo)\n*   [Contribute](#contribute)\n*   [Community \u0026 Support](#community-\u0026-support)\n*   [Acknowledgments](#acknowledgments)\n*   [License](#license)\n\n## What is this?\n\nYou can use plugins to change Lottie.\n\n**In**:\n\n```javascript\n{ \"v\": \"5.5.2\" }\n```\n\n**Plugin**:\n\n```ts\nimport {visit} from 'unist-util-visit'\nimport type { Plugin, Node } from 'unified'\nimport type { Root } from '@lottiefiles/last'\n\nconst myRelottiePlugin: Plugin\u003c[]\u003e () {\n  function transform (tree: Root, _file: VFile): void {\n    visit(tree, (node) =\u003e {\n      if (node.title === 'version') {\n        node.title = \"6.0.0\" \n      }\n    })\n  }\n\n  return transform\n}\n```\n\n**Out**:\n\n```javascript\n{ \"v\": \"6.0.0\" }\n```\n\nYou can use relottie for many different things.\n**[unified][]** is the core project that transforms content with ASTs.\n**relottie** adds support for Lottie to unified.\n**[last][]** is the Lottie AST that relottie uses.\n\nThis GitHub repository is a monorepo that contains the following packages:\n\n*   [`last`][last]\n    — Type definitions for Lottie Abstract Syntax Tree (last)\n*   [`last-builder`][last-builder]\n    — Composable functions to easily build syntax tree (last) structures\n*   [`relottie`][relottie-pkg]\n    — a unified processor with support for parsing Lottie input and serializing Lottie as output\n*   [`relottie-parse`][relottie-parse]\n    — plugin to take Lottie as input and turn it into a syntax tree [last][]\n*   [`relottie-stringify`][relottie-stringify]\n    — plugin to take a syntax tree (last) and turn it into Lottie as output\n*   [`relottie-cli`][relottie-cli]\n    — Command line interface to inspect and change Lottie files with relottie\n* [`relottie-extract-features`][relottie-extract-features]\n    — plugin to extract Lottie features from the document and store them in vfile\n* [`relottie-metadata`][relottie-metadata]\n    — plugin to extract Lottie metadata from the document and store them in `vfile.data`\n\n\n## When should I use this?\n\nrelottie focusses on ASTs and providing an interface for plugins to transform them.\n\nDepending on the input you have and output you want, you can use different parts\nof relottie.\nIf the input is Lottie JSON file, you can use `relottie-parse` with [unified].\nIf 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][]\n\n## Plugins\n\nrelottie plugins deal with Lottie.\nSome popular examples are:\n\n*   [relottie-style][]\n\nThese plugins are exemplary because what they do and how they do it is quite\ndifferent, respectively to extend Lottie syntax, inspect trees, change trees,\nand define other output formats.\n\nYou can choose from the plugins that already exist.\nHere are three good ways to find plugins:\n\n*   [List of LF plugins][list-of-plugins]\n    — list of all plugins\n*   [`relottie-plugin` topic][topic]\n    — any tagged repo on GitHub\n\nSome plugins are maintained by us here in the [`@lottiefiles`][lottiefiles] organization while\nothers are maintained by folks elsewhere.\nAnyone can make relottie plugins, so as always when choosing whether to include\ndependencies in your project, make sure to carefully assess the quality of\nrelottie plugins too.\n\n## Examples\n\n*   be the first one ;)\n\n## Syntax\n\nrelottie follows [last][] definitions, [lottie-types][] and [lottie-docs][] title names (with a few changes) Some syntax extensions are supported through plugins.\n\nWe use [momoa][] JSON parser for our parsing.\nSee its documentation for more information.\n\n## Syntax tree\n\nThe syntax tree format used in relottie is [last][].\nIt represents Lottie constructs as JSON objects.\n\n**In**:\n\n```javascript\n{ \"v\": \"6.0.0\" }\n```\n\n**Out**:\n\n```json\n{\n  \"type\": \"root\",\n  \"title\": \"animation\",\n  \"hasExpressions\": false,\n  \"position\": {\n    \"start\": {\n      \"line\": 1,\n      \"column\": 1,\n      \"offset\": 0\n    },\n    \"end\": {\n      \"line\": 1,\n      \"column\": 17,\n      \"offset\": 16\n    }\n  },\n  \"children\": [\n    {\n      \"type\": \"attribute\",\n      \"key\": {\n        \"type\": \"key\",\n        \"position\": {\n          \"start\": {\n            \"line\": 1,\n            \"column\": 3,\n            \"offset\": 2\n          },\n          \"end\": {\n            \"line\": 1,\n            \"column\": 6,\n            \"offset\": 5\n          }\n        },\n        \"value\": \"v\"\n      },\n      \"title\": \"version\",\n      \"position\": {\n        \"start\": {\n          \"line\": 1,\n          \"column\": 3,\n          \"offset\": 2\n        },\n        \"end\": {\n          \"line\": 1,\n          \"column\": 15,\n          \"offset\": 14\n        }\n      },\n      \"children\": [\n        {\n          \"type\": \"primitive\",\n          \"value\": \"6.0.0\",\n          \"position\": {\n            \"start\": {\n              \"line\": 1,\n              \"column\": 8,\n              \"offset\": 7\n            },\n            \"end\": {\n              \"line\": 1,\n              \"column\": 15,\n              \"offset\": 14\n            }\n          },\n          \"valueType\": \"string\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Types\n\nThe relottie organization and the unified as a whole is fully typed\nwith [TypeScript][].\nTypes for last are available in [last][]. Also have a look at [lottie-types][].\n\nFor TypeScript to work, it is particularly important to type your plugins\ncorrectly.\nWe strongly recommend using the `Plugin` type from [unified][] with its generics\nand to use the node types for the syntax trees provided by [last][].\n\n```ts\nimport type { Root } from '@lottiefiles/last';\nimport type { Plugin } from 'unified';\n\nexport function myRelottiePluginAcceptingOptions(options): Plugin\u003c[Options?], Root\u003e {\n  // `options` is `Options?`.\n  return function (tree, file) {\n    // `tree` is `Root`.\n  }\n}\n```\n\n## Compatibility\n\nAs of now, that is Node.js 16.0+, and 18.0+ (other versions have not been tested yet)\nOur projects sometimes work with older versions, but this is not guaranteed.\n\n## Security\n\nAs last properties can have [expressions][], and improper use of **last** can open you up to cross-site scripting [cross-site scripting (XSS)][XSS]. Carefully assess each plugin and the risks involved in using them.\n\n## Setting up Monorepo\n\n    git clone https://github.com/LottieFiles/relottie.git\n\n    cd relottie\n\n    pnpm install\n\n### Running in dev mode\n\n    pnpm dev\n\n### Running test suite\n\n    pnpm test\n\n### Add a changelog message\n\nWe use [changeset][]\n\n    pnpm changelog\n\n### Building\n\n    pnpm build\n\n### Linting\n\n    pnpm lint\n\n## Contribute\n\nAny contributions are welcome.\n\n## Community \u0026 Support\n\n*   [Github issues][issues]. For bugs and errors you encounter using this player.\n*   [Discord][lf-discord]. For hanging out with the community and sharing your awesome Lottie animations!\n\n## Acknowledgments\n\n*   [unified][]\n*   [momoa][]\n*   [lottie-docs][]\n\nThe initial release of this project was authored by\n[**@aidosmf**][author]\n\n## License\n\n[MIT](license) © [LottieFiles][lottiefiles]\n\n[author]: http://github.com/aidosmf\n\n[unified]: https://github.com/unifiedjs/unified\n\n[unifiedjs.com]: https://unifiedjs.com/\n\n[build]: https://github.com/LottieFiles/relottie/actions\n\n[typescript]: https://www.typescriptlang.org\n\n[momoa]: https://github.com/humanwhocodes/momoa\n\n[list-of-plugins]: https://github.com/LottieFiles/relottie/tree/main/packages\n\n[changeset]: https://github.com/changesets/changesets\n\n[what-is-lottie]: https://lottiefiles.com/what-is-lottie\n\n[lottiefiles]: https://github.com/LottieFiles\n\n[topic]: https://github.com/topics/relottie-plugin\n\n[issues]: https://github.com/LottieFiles/relottie/issues\n\n[lottie-docs]: https://lottiefiles.github.io/lottie-docs/\n\n[relottie]: https://github.com/LottieFiles/relottie\n\n[last]: https://github.com/LottieFiles/relottie/tree/main/packages/last\n\n[last-builder]: https://github.com/LottieFiles/relottie/tree/main/packages/last-builder\n\n[relottie-pkg]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie\n\n[relottie-parse]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie-parse\n\n[relottie-style]: https://www.npmjs.com/package/@lottiefiles/relottie-style\n\n[relottie-stringify]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie-stringify\n\n[relottie-cli]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie-cli\n\n[relottie-extract-features]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie-extract-features\n\n[relottie-metadata]: https://github.com/LottieFiles/relottie/tree/main/packages/relottie-metadata\n\n[lottie-types]: https://www.npmjs.com/package/@lottie-animation-community/lottie-types\n\n[dotlottie.js]: https://github.com/dotlottie/dotlottie-js/\n\n[expressions]: https://lottiefiles.github.io/lottie-docs/expressions/#expressions\n\n[lf-discord]: https://discord.com/invite/6K3fm7yE9v\n\n[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting\n\n[syntax]: #syntax\n\n[syntax-tree]: #syntax-tree\n\n[plugins]: #plugins\n\n[contribute]: #contribute\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flottiefiles%2Frelottie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flottiefiles%2Frelottie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flottiefiles%2Frelottie/lists"}