Animarte NPM | npm.io

Animarte

📽️ Animarte

🎯 Goal

This project is a dependency-free library that aims to provide a set of pre-made animations, avoiding rework and Control+C/Control+V between projects.

Note: Click here to see all animations already available!

📜 Some details

This project was created using tools to make development as easy as possible:

Node.JS It is only necessary to globally install the following packages that facilitate development.
Sass CSS preprocessor that, in addition to adding extra features, encourages an architecture to only organize style files.
Live Server or Python Serve the project locally to test and preview changes during development.

🪬 Overview

🧑‍💻 Developers

Lucas Coutinho
- Website: https://lucasmc64.dev
- GitHub: https://github.com/lucasmc64
- GitLab: https://gitlab.com/lucasmc64
- LinkedIn: https://www.linkedin.com/in/lucasmc64/

🔗 Useful links

Board: https://tree.taiga.io/project/lucasmarcal-animarte

Repository: https://gitlab.com/lucasmc64/animarte

CDN: https://unpkg.com/browse/animarte@latest/

Website: https://animarte.lucasmc64.dev

🐙 Repository details

Below is the branch structure/pattern created for this project:

main: If there is more than one developer or the sprint tasks are divided, this will be the place to gather the codes and resolve conflicts before the modifications go to testing.
TG-(number): It covers all the code produced to meet the needs exposed by a task and uses the same code as the task created in Taiga.

🎨 How to use it in my project?

🙌 Classic scripts

The project is also exported using UMD, which means that all variables and classes such as the Animarte class and the animations array are exposed globally, and can be used in any script imported after the library.

Note: You should change X.Y.Z to the library version number according to your needs, this is just an example. It is recommended to always use the latest version.
It is recommended that you pin to the latest stable version of the lib. However, if you always want to use the latest version, you can also use latest instead of a predefined version number. Be careful though, breaking changes may be introduced and your project may need to adapt to the changes.

<!DOCTYPE html>

<html>
  <head>
    <!-- ... -->

    <link
      rel="stylesheet"
      href="https://unpkg.com/animarte@X.Y.Z/animarte.css"
    />
    <script src="https://unpkg.com/animarte@X.Y.Z/animarte.js" defer></script>

    <!-- ... -->
  </head>

  <body>
    <div id="loading-animation"></div>
  </body>
</html>

"use strict";

new Animarte({
  animation: "ellipsis",
  variant: "agitated,
  parentElement: document.getElementById("loading-animation"),
});

📦️ ES6 Modules

The HTML is very similar to the classic scripts version, just change the .js extension to .mjs, which will result in something similar to this:

Note: Please read the previous section to get the details involved in importing CSS and choosing a package version, they are the same here.

<script src="https://unpkg.com/animarte@X.Y.Z/animarte.mjs" defer></script>

import { Animarte } from "animarte";

new Animarte({
  animation: "ellipsis",
  variant: "agitated,
  parentElement: document.getElementById("loading-animation"),
});

⚛️ React

Install the lib using your favorite package manager.

npm install animarte

Since the library was designed primarily to be used with vanilla JS, a helper component needs to be created to encapsulate Animarte's behavior and make it simple to reuse throughout the application.

Note: There is TypeScript support, and even if your project doesn't use the JS superset, it should help VSCode and other editors provide autocomplete/code suggestions.

import { useEffect, useRef } from "react";
import { Animarte, AnimarteProps } from "animarte";

import "animarte/animarte.css";

// Example using Vite, React and TypeScript extraxcted from the Animarte website
export const AnimarteWrapper = (props: AnimarteProps) => {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (ref.current) {
      new Animarte({
        ...props,
        parentElement: ref.current,
      });
    }

    return () => {
      // Required to avoid animation duplication when React is in Strict Mode
      if (ref.current) {
        ref.current.innerHTML = "";
      }
    };
  }, [ref.current]);

  return <div className="animarte-wrapper" ref={ref} />;
};

🤔 How do I run the project on my machine?

The first step is to clone the project, either via terminal or even by downloading the compressed file (.zip). After that, go ahead.

🛠️ Requirements

NodeJS and NPM
(Optional) Python
(Optional) Yarn

🔍️ Installing dependencies

With Node.JS installed, access the project directory via terminal and run the npm install command. If you prefer to use Yarn, just run the yarn command. Now, you will need to install the sass package globally which is responsible for processing the .scss files and generating the .css files.

# Using NPM
npm i -g sass

# Using Yarn
yarn global add sass

Now, if you intend to use live-server to serve CSS, you will also need to install it globally.

If you prefer to use Python for this, you don't need to install anything else.

# Using NPM
npm i -g live-server

# Using Yarn
yarn global add live-server

If you prefer to use Python, you can modify the NPM Script start as follows:

"start": "gulp watchAll & python3 -m http.server 5645"

✨ Running the project

With the dependencies properly installed, still in the terminal, run npm start or yarn start.

If the port has not been manually changed and the default port is free, simply access access the address http://127.0.0.1:5645/demo in your favorite browser, to see the project running.