transform-to-matrix-loader

Webpack loader that converts CSS transform properties to matrix3d format.

Features

• Converts all CSS transform functions to matrix3d
• Supports 2D and 3D transforms
• Handles multiple transform functions in a single declaration
• Configurable output options

Supported Transform Functions

• translate, translateX, translateY, translateZ, translate3d
• scale, scaleX, scaleY, scaleZ, scale3d
• rotate, rotateX, rotateY, rotateZ, rotate3d
• skew, skewX, skewY
• perspective
• matrix, matrix3d

Installation

npm install transform-to-matrix-loader --save-dev

Usage

Webpack Configuration

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'transform-to-matrix-loader',
            options: {
              // Options (optional)
              preserveOriginal: false,  // Keep original transform
              commentOriginal: false     // Comment out original transform
            }
          }
        ]
      }
    ]
  }
};

Examples

Input CSS:

.box {
  transform: translate(100px, 50px) rotate(45deg) scale(1.5);
}

.element {
  transform: rotateX(30deg) translateZ(100px);
}

.skewed {
  transform: skewX(15deg) skewY(10deg);
}

Output CSS (default):

.box {
  transform: matrix3d(1.06066, 1.06066, 0, 0, -1.06066, 1.06066, 0, 0, 0, 0, 1.5, 0, 100, 50, 0, 1);
}

.element {
  transform: matrix3d(1, 0, 0, 0, 0, 0.866025, 0.5, 0, 0, -0.5, 0.866025, 0, 0, 0, 100, 1);
}

.skewed {
  transform: matrix3d(1, 0.176327, 0, 0, 0.267949, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
}

Options

preserveOriginal

Type: Boolean Default: false

Keep the original transform and add the matrix3d version.

{
  loader: 'transform-to-matrix-loader',
  options: {
    preserveOriginal: true
  }
}

Output:

.box {
  transform: translate(100px, 50px) rotate(45deg);
  transform: matrix3d(...);
}

commentOriginal

Type: Boolean Default: false

Comment out the original transform and use matrix3d.

{
  loader: 'transform-to-matrix-loader',
  options: {
    commentOriginal: true
  }
}

Output:

.box {
  /* transform: translate(100px, 50px) rotate(45deg); */
  transform: matrix3d(...);
}

test

Type: RegExp Default: /transform\s*:\s*([^;]+);/g

Custom regex pattern to match transform properties.

Programmatic Usage

You can also use the loader's utility functions directly:

const { parseTransform, matrixToCSS } = require('transform-to-matrix-loader');

const transformStr = 'translate(100px, 50px) rotate(45deg)';
const matrix = parseTransform(transformStr);
const matrix3dStr = matrixToCSS(matrix);

console.log(matrix3dStr);
// Output: matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 100, 50, 0, 1)

How It Works

1. The loader parses the CSS file and finds all transform properties
2. For each transform property, it:
   • Parses the transform functions (translate, rotate, scale, etc.)
   • Converts each function to a 4x4 transformation matrix
   • Multiplies the matrices together in the correct order
   • Converts the final matrix to matrix3d() CSS format
3. Replaces the original transform with the matrix3d version

Matrix Math

All transforms are represented as 4x4 matrices in column-major order:

[m0  m4  m8  m12]
[m1  m5  m9  m13]
[m2  m6  m10 m14]
[m3  m7  m11 m15]

The matrix3d() function takes all 16 values: matrix3d(m0, m1, m2, ..., m15)

Browser Support

The generated matrix3d() is supported in all modern browsers that support CSS 3D transforms.

License

ISC