style-vendorizer

Tiny CSS vendor prefixer and property alias mapper for runtime styling solutions.


Usage

Install the library with a package manager, e.g. npm:

``shell
npm install style-vendorizer
`

After that, import transformer functions on demand. A recommended starting point is shown below:

`js
import {
cssPropertyAlias,
cssPropertyPrefixFlags,
cssValuePrefixFlags,
} from "style-vendorizer";

function styleDeclaration(property, value) {
let cssText = "";

/ Resolve aliases, e.g. gap -> grid-gap /
const propertyAlias = cssPropertyAlias(property);
if (propertyAlias) cssText += ${propertyAlias}:${value};;

/ Prefix properties, e.g. backdrop-filter -> -webkit-backdrop-filter /
const propertyFlags = cssPropertyPrefixFlags(property);
if (propertyFlags & 0b001) cssText += -webkit-${property}:${value};;
if (propertyFlags & 0b010) cssText += -moz-${property}:${value};;
if (propertyFlags & 0b100) cssText += -ms-${property}:${value};;

/ Prefix values, e.g. position: "sticky" -> position: "-webkit-sticky" /
/ Notice that flags don't overlap and property prefixing isn't needed here /
const valueFlags = cssValuePrefixFlags(property, value);
if (valueFlags & 0b001) cssText += ${property}:-webkit-${value};;
else if (valueFlags & 0b010) cssText += ${property}:-moz-${value};;
else if (valueFlags & 0b100) cssText += ${property}:-ms-${value};;

/ Include the standardized declaration last /
/ https://css-tricks.com/ordering-css3-properties/ /
cssText += ${property}:${value};;

return cssText;
}
`

Prefix flags may be defined in TypeScript without any overhead as follows:

`ts
const enum CSSPrefixFlags {
"-webkit-" = 1 << 0, // 0b001
"-moz-" = 1 << 1, // 0b010
"-ms-" = 1 << 2, // 0b100
}

/ Magic numbers from the previous snippet should be replaced like below: /
if (flags & CSSPrefixFlags["-webkit-"]) cssText += "...";
if (flags & CSSPrefixFlags["-moz-"]) cssText += "...";
if (flags & CSSPrefixFlags["-ms-"]) cssText += "...";
`

Browser Support

Every browser in the default Browserslist configuration is supported and tested against:

- Baidu Browser for Android 7.12+
- Chrome 57+
- Edge 16+
- Firefox 48+
- Internet Explorer 11
- KaiOS Browser 2.5+
- Opera 46+
- Safari 12.2+
- Samsung Internet Browser 11.1+
- QQ Browser for Android 10.4+
- UC Browser for Android 12.12+

Quirks

- Function values are only prefixed for longhand properties. This guarantees that only the start of each value is compared, for efficiency:

`js
// Prints "1 0"
console.log(
cssPropertyPrefixFlags(
"background-image", // Longhand
"image-set('example.png' 1x, 'example-2x.png' 2x)", // Prefixed
),
cssPropertyPrefixFlags(
"background", // Shorthand
"image-set('example.png' 1x, 'example-2x.png' 2x)", // Not prefixed
),
);
`

- CSS Grid works in IE 11 only when using the following longhand properties:
- grid-template-rows, grid-template-columns
- grid-row-start, grid-column-start
- -ms-grid-row-span and -ms-grid-column-span (along with grid-row-end and grid-column-end for cross-browser compatibility)
- align-self, justify-self
- cross-fade() and element()` functions are not prefixed, due to the lack of standard implementations.
- Selectors are not yet supported.

Acknowledgements

This project was heavily inspired by tiny-css-prefixer. Test vectors are obtained from @mdn/browser-compat-data.