README
tramix
Transparent CSS mixins with PostCSS and JavaScript.
tramix allows you to write transparent mixins in JavaScript to be used in your CSS. The result is simple, native-feeling, and DRY CSS.
Install
npm i -D tramix
or, for yarn users:
yarn add --dev tramix
Usage
Configuration
Configuration for tramix is extremely simple, opens up a world of possibilities. In order to get set up, you just need to add tramix to your PostCSS configuration.
If your configuration lives in your package.json
or .postcssrc
:
"plugins": {
"tramix": {
"include": './path/from/package/to/mixins.js'
}
}
If your configuration lives in a .js
config file, be sure to remember to make the include
path the path to your main mixins file relative to your package.json
:
plugins: [
require('tramix')({
include: './path/from/package/to/mixins.js'
})
];
Defining Mixins
tramix accepts a single point of entry for mixins. Each named export of that entry point should be a mixin function that takes one or two arguments: value
and rule
. This can be done by defining all mixins in one file and exporting them each by name (not-recommended), or defining mixins in different files, importing them into the entry mixins file, and exporting them by name there (recommended).
In this example, the mixin we are exporting is theme
. When tramix encounters a CSS rule with a theme
declaration, it will process the declaration based on your provided function.
Exported mixins should return an object of CSS-compatible key/value pairs. (camelCase properties are acceptable, i.e: backgroundColor
for the CSS equivalent background-color
.)
// mixins.js
const themes = {
blue: {
color: 'white',
backgroundColor: 'blue'
},
invalid: (value) => ({
theme: `invalid value: ${value}`
})
};
exports.theme = (value, rule) => {
return value in themes ? themes[value] : themes.invalid(value);
};
In the above example, if theme: blue;
is found in a CSS rule, it will transform it into color: white; background-color: blue;
. But if something like theme: red;
is found (which is not a supported value for this mixin), then the output CSS would be theme: 'invalid value: red
.
Dynamic Mixins
Whereas mixins are just fine for keeping your code DRY, tramix offers the rule
parameter in your mixin declarations that allows you to inspect the rule currently being parsed and return your new declarations to be applied to it based off of its current state. The rule
parameter is a plain Object
version of the current state of the rule
while this declaration is being processed.
Here is an exmple where we simplify the justify-content
and align-items
properties that accompany display: flex;
.
Note: When an element has display: flex;
it defaults also to flex-direction: row;
. When flex-direction is row
or row-reverse
, then justify-content
controls horizontal alignment and align-items
controls vertical alignment. When flex-direction is column
or column-reverse
, then justify-content
controls vertical alignment and align-items
controls horizontal alignment. Confusing, right?
.classy {
display: flex;
flex-direction: column;
flexalignx: space-between;
flexaligny: center;
}
exports.flexAlignX = (value, rule) => {
const decls = {};
if (['row', 'row-reverse'].includes(rule['flex-direction'])) {
decls.justifyContent = value;
} else if (['column', 'column-reverse'].includes(rule['flex-direction'])) {
decls.alignItems = value;
}
};
exports.flexAlignY = (value, rule) => {
const decls = {};
if (['row', 'row-reverse'].includes(rule['flex-direction'])) {
decls.alignItems = value;
} else if (['column', 'column-reverse'].includes(rule['flex-direction'])) {
decls.justifyContent = value;
}
return decls;
};
Now, the output of our mixins will be:
.classy {
display: flex;
flex-direction: column;
align-items: space-between;
justify-content: center;
}
Caveats
- You should not use simple mixin names that could potentially be introduced into the CSS spec in the future. For this reason,
camelCase
mixin names are advised. - You should not use mixin names beginning with uncommon characters (!, #, etc) because it will absolutely break your CSS linter (lol) and potentially break your CSS transpiling as a whole. "