tailwindcss-animate-compiler

A modular Tailwind CSS 3 integration for Animate.css, powered by @twutils/postcss-animate-compiler.

It registers Animate.css base utilities and keyframes with Tailwind, supports class-level filtering, isolates every configured plugin instance, and exposes a bridge to the complete PostCSS animation compiler.

Features

• Registers Animate.css utilities through Tailwind's plugin API
• Generates purge-aware animation utilities with matchUtilities
• Supports custom class prefixes
• Includes or excludes individual animations
• Overrides global duration, delay, and iteration count
• Reads animation source files through a deterministic repository layer
• Uses isolated immutable configuration instead of shared global state
• Accepts advanced @twutils/postcss-animate-compiler options
• Separates configuration, source access, transforms, cataloging, processors, compilation, and framework adaptation

Installation

npm install tailwindcss-animate-compiler

The package installs Animate.css and @twutils/postcss-animate-compiler automatically. Tailwind CSS 3 is a peer dependency.

Tailwind configuration

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx,vue}'],
  plugins: [
    require('tailwindcss-animate-compiler')()
  ]
};

Use the generated classes:

<h1 class="animatecss animatecss-fadeIn">
  Fade in
</h1>

The default mapping is:

| Animate.css source | Generated utility | | --- | --- | | .animated | .animatecss | | .fadeIn | .animatecss-fadeIn | | .infinite | .animatecss-infinite | | .repeat-2 | .animatecss-repeat-2 | | .delay-2s | .animatecss-delay-2s | | .fast | .animatecss-fast |

Configuration

module.exports = {
  plugins: [
    require('tailwindcss-animate-compiler')({
      prefix: 'motion',
      classes: ['fadeIn', 'fadeOut', 'slideInUp', 'slideOutDown'],
      exclude: ['fadeOut'],
      duration: '750ms',
      delay: '100ms',
      iterationCount: 1,
      compiler: {
        prefixes: {
          animations: true,
          keyframes: true,
          synchronize: true
        },
        diagnostics: false
      }
    })
  ]
};

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | prefix | string | animatecss | Base Tailwind utility name | | classes | string[] or null | null | Animations to include | | exclude | string[] or null | null | Animations to remove | | duration | string, number, or null | null | --animate-duration | | delay | string, number, or null | null | --animate-delay | | iterationCount | string, number, or null | null | --animate-repeat | | compiler | object | {} | Advanced @twutils/postcss-animate-compiler options |

Arrays are deduplicated during normalization. classes: [] behaves like no inclusion filter. exclude is applied after classes, so exclusions always win.

Prefix configuration

require('tailwindcss-animate-compiler')({
  prefix: 'motion'
});

<div class="motion motion-bounce"></div>

The prefix can also come from the Tailwind theme:

module.exports = {
  theme: {
    animatecss: {
      prefix: 'motion'
    }
  },
  plugins: [
    require('tailwindcss-animate-compiler')()
  ]
};

An explicit plugin option takes precedence over the theme value.

Each plugin instance owns its prefix. Creating multiple configured instances does not mutate shared module state or leak one prefix into another build.

Animation filtering

Include only selected animations:

require('tailwindcss-animate-compiler')({
  classes: ['bounce', 'fadeIn', 'slideInUp']
});

Exclude animations from the complete catalog:

require('tailwindcss-animate-compiler')({
  exclude: ['hinge', 'jackInTheBox']
});

Combine both:

require('tailwindcss-animate-compiler')({
  classes: ['fadeIn', 'fadeOut', 'slideInUp'],
  exclude: ['fadeOut']
});

The compiler reads and indexes Animate.css source directories once per plugin invocation, then creates a filtered lookup for matchUtilities.

Timing overrides

require('tailwindcss-animate-compiler')({
  duration: '2s',
  delay: '250ms',
  iterationCount: 3
});

This compiles the Animate.css variable source through @twutils/postcss-animate-compiler:

:root {
  --animate-duration: 2s;
  --animate-delay: 250ms;
  --animate-repeat: 3;
}

Numbers are converted to strings. Empty values are rejected rather than silently producing invalid CSS.

Advanced compiler bridge

The compiler option is forwarded to @twutils/postcss-animate-compiler. This allows the Tailwind integration to use its prefixing, accessibility, analysis, and diagnostic capabilities.

require('tailwindcss-animate-compiler')({
  duration: '800ms',
  compiler: {
    prefixes: {
      animations: true,
      keyframes: true,
      synchronize: true,
      deduplicate: true
    },
    reducedMotion: true,
    analysis: {
      warnOnInfiniteAnimations: true
    },
    diagnostics: 'detailed'
  }
});

When timing values are provided, the integration owns the three Animate.css variables but merges the other custom-property and prefix settings.

Compiler-only processing is also supported:

require('tailwindcss-animate-compiler')({
  compiler: {
    reducedMotion: true,
    prefixes: false
  }
});

See the @twutils/postcss-animate-compiler documentation for its complete configuration.

Processing model

The plugin performs three ordered registration stages:

1. Variable processor reads _vars.css, applies optional compiler overrides, converts the result to CSS-in-JS, and registers it with addUtilities.
2. Utility processor reads _base.css, rewrites selectors with the configured prefix, and registers generic animation utilities.
3. Animation processor builds the animation catalog, applies include/exclude filters, flattens each utility with its keyframes, and registers the lookup with matchUtilities.

Tailwind plugin options + theme
              │
              ▼
      Configuration normalizer
              │
              ▼
       Compilation context
       ├── source repository
       ├── style transformer
       ├── PostCSS compiler
       └── animation catalog
              │
              ▼
       Ordered processors
       ├── variables
       ├── base utilities
       └── animations
              │
              ▼
       Tailwind plugin API

Package architecture

tailwindcss-animate-compiler/
├── index.js
└── src/
    ├── plugin.js
    ├── compiler.js
    ├── constants.js
    ├── config/
    │   └── normalize.js
    ├── core/
    │   ├── animation-catalog.js
    │   ├── context.js
    │   ├── css-compiler.js
    │   └── source-repository.js
    ├── processors/
    │   ├── animations.js
    │   ├── utilities.js
    │   └── variables.js
    └── transforms/
        ├── selectors.js
        └── styles.js

Responsibilities

• index.js is the stable public CommonJS entry.
• src/plugin.js adapts the compiler to Tailwind's plugin API.
• src/config/ validates and freezes user/theme configuration.
• src/core/source-repository.js owns Animate.css filesystem access.
• src/core/animation-catalog.js discovers, caches, filters, and flattens animation definitions.
• src/core/css-compiler.js bridges timing and advanced options to @twutils/postcss-animate-compiler.
• src/transforms/ handles AST parsing, selector rewriting, and CSS-in-JS conversion.
• src/processors/ contains focused Tailwind registration stages.
• src/compiler.js owns processor ordering.

Dependency flow remains one-directional:

index → plugin → compiler → processors → core/transforms → constants

Internal modules are not exposed through package exports, allowing the implementation to evolve without expanding the public API.

Requirements

• Node.js 14 or newer
• Tailwind CSS 3

Contributing

Issues and pull requests are welcome:

https://github.com/bumpvite/tailwindcss-animate-compiler/issues

License

MIT