0
# postcss-normalize-timing-functions
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: postcss-normalize-timing-functions
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install postcss-normalize-timing-functions`
10
- **Node.js**: ^18.12.0 || ^20.9.0 || >=22.0
11
- **PostCSS**: ^8.4.32 (peer dependency)
12

13
## Core Imports
14

15
```javascript
16
const postcssNormalizeTimingFunctions = require("postcss-normalize-timing-functions");
17
```
18

19
For TypeScript/ESM usage:
20

21
```typescript
22
import postcssNormalizeTimingFunctions from "postcss-normalize-timing-functions";
23
```
24

25
## Basic Usage
26

27
```javascript
28
const postcss = require("postcss");
29
const postcssNormalizeTimingFunctions = require("postcss-normalize-timing-functions");
30

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

35
console.log(result.css);
36
```
37

38
**Input CSS:**
39
```css
40
div {
41
  animation: fade 3s cubic-bezier(0.42, 0, 1, 1);
42
  transition: color 0.5s steps(1, start);
43
}
44
```
45

46
**Output CSS:**
47
```css
48
div {
49
  animation: fade 3s ease-in;
50
  transition: color 0.5s step-start;
51
}
52
```
53

54
## Capabilities
55

56
### Plugin Creator Function
57

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

60
```typescript { .api }
61
/**
62
 * Creates a PostCSS plugin that normalizes timing functions
63
 * @returns PostCSS plugin instance
64
 */
65
function pluginCreator(): import("postcss").Plugin;
66
```
67

68
The plugin processes CSS declarations matching the regex pattern `/^(-\w+-)?(animation|transition)(-timing-function)?$/i`:
69
- `animation` and `animation-timing-function` properties
70
- `transition` and `transition-timing-function` properties  
71
- Including vendor-prefixed versions (e.g., `-webkit-animation`, `-moz-transition-timing-function`)
72

73
### Plugin Properties
74

75
```typescript { .api }
76
/**
77
 * PostCSS plugin marker indicating this is a valid PostCSS plugin
78
 */
79
pluginCreator.postcss: true;
80
```
81

82
## Transformations
83

84
### Cubic-Bezier Normalization
85

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

88
- `cubic-bezier(0.25, 0.1, 0.25, 1)` → `ease`
89
- `cubic-bezier(0, 0, 1, 1)` → `linear`
90
- `cubic-bezier(0.42, 0, 1, 1)` → `ease-in`
91
- `cubic-bezier(0, 0, 0.58, 1)` → `ease-out`
92
- `cubic-bezier(0.42, 0, 0.58, 1)` → `ease-in-out`
93

94
### Steps Function Normalization
95

96
The plugin optimizes steps() functions:
97

98
- `steps(1, start)` or `steps(1, jump-start)` → `step-start`
99
- `steps(1, end)` or `steps(1, jump-end)` → `step-end`
100
- `steps(n, end)` or `steps(n, jump-end)` → `steps(n)` (removes redundant end parameter)
101

102
### Case Insensitive
103

104
All transformations work regardless of case:
105
- `CUBIC-BEZIER(0.25, 0.1, 0.25, 1)` → `ease`
106
- `STEPS(1, START)` → `step-start`
107

108
## Configuration
109

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

112
## Error Handling
113

114
The plugin safely handles:
115
- Invalid cubic-bezier parameters (skipped, not transformed)
116
- Malformed steps() functions (skipped, not transformed)
117
- CSS custom properties/variables (preserved unchanged)
118
- Missing or incomplete function parameters (preserved unchanged)
119

120
## PostCSS Integration
121

122
```javascript
123
// With PostCSS CLI configuration file
124
module.exports = {
125
  plugins: [
126
    require("postcss-normalize-timing-functions")(),
127
    // other plugins...
128
  ]
129
};
130

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

134
postcss([
135
  require("postcss-normalize-timing-functions")(),
136
])
137
  .process(css, { from: "input.css", to: "output.css" })
138
  .then(result => {
139
    console.log(result.css);
140
  });
141
```
142

143
## TypeScript Support
144

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

147
```typescript { .api }
148
declare function pluginCreator(): import("postcss").Plugin;
149
declare namespace pluginCreator {
150
  let postcss: true;
151
}
152

153
export = pluginCreator;
154
```