postcss-normalize-timing-functions

postcss-normalize-timing-functions is a PostCSS plugin that normalizes CSS animation and transition timing functions by converting verbose cubic-bezier() and steps() functions to shorter named equivalents, reducing file size and improving readability.

Package Information

• Package Name: postcss-normalize-timing-functions
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install postcss-normalize-timing-functions
• Node.js: ^18.12.0 || ^20.9.0 || >=22.0
• PostCSS: ^8.4.32 (peer dependency)

Core Imports

const postcssNormalizeTimingFunctions = require("postcss-normalize-timing-functions");

For TypeScript/ESM usage:

import postcssNormalizeTimingFunctions from "postcss-normalize-timing-functions";

Basic Usage

const postcss = require("postcss");
const postcssNormalizeTimingFunctions = require("postcss-normalize-timing-functions");

// Apply the plugin to CSS
const result = await postcss([postcssNormalizeTimingFunctions()])
  .process(cssString, { from: undefined });

console.log(result.css);

Input CSS:

div {
  animation: fade 3s cubic-bezier(0.42, 0, 1, 1);
  transition: color 0.5s steps(1, start);
}

Output CSS:

div {
  animation: fade 3s ease-in;
  transition: color 0.5s step-start;
}

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance that normalizes timing functions in CSS declarations.

/**
 * Creates a PostCSS plugin that normalizes timing functions
 * @returns PostCSS plugin instance
 */
function pluginCreator(): import("postcss").Plugin;

The plugin processes CSS declarations matching the regex pattern /^(-\w+-)?(animation|transition)(-timing-function)?$/i:

• animation and animation-timing-function properties
• transition and transition-timing-function properties
• Including vendor-prefixed versions (e.g., -webkit-animation, -moz-transition-timing-function)

Plugin Properties

/**
 * PostCSS plugin marker indicating this is a valid PostCSS plugin
 */
pluginCreator.postcss: true;

Transformations

Cubic-Bezier Normalization

The plugin converts cubic-bezier functions to named timing function equivalents:

• cubic-bezier(0.25, 0.1, 0.25, 1) → ease
• cubic-bezier(0, 0, 1, 1) → linear
• cubic-bezier(0.42, 0, 1, 1) → ease-in
• cubic-bezier(0, 0, 0.58, 1) → ease-out
• cubic-bezier(0.42, 0, 0.58, 1) → ease-in-out

Steps Function Normalization

The plugin optimizes steps() functions:

• steps(1, start) or steps(1, jump-start) → step-start
• steps(1, end) or steps(1, jump-end) → step-end
• steps(n, end) or steps(n, jump-end) → steps(n) (removes redundant end parameter)

Case Insensitive

All transformations work regardless of case:

• CUBIC-BEZIER(0.25, 0.1, 0.25, 1) → ease
• STEPS(1, START) → step-start

Configuration

This plugin requires no configuration options. It works automatically when added to your PostCSS plugin list.

Error Handling

The plugin safely handles:

• Invalid cubic-bezier parameters (skipped, not transformed)
• Malformed steps() functions (skipped, not transformed)
• CSS custom properties/variables (preserved unchanged)
• Missing or incomplete function parameters (preserved unchanged)

PostCSS Integration

// With PostCSS CLI configuration file
module.exports = {
  plugins: [
    require("postcss-normalize-timing-functions")(),
    // other plugins...
  ]
};

// With build tools (webpack, etc.)
const postcss = require("postcss");

postcss([
  require("postcss-normalize-timing-functions")(),
])
  .process(css, { from: "input.css", to: "output.css" })
  .then(result => {
    console.log(result.css);
  });

TypeScript Support

Full TypeScript support is provided via type definitions that properly integrate with PostCSS's plugin system.

declare function pluginCreator(): import("postcss").Plugin;
declare namespace pluginCreator {
  let postcss: true;
}

export = pluginCreator;