Compiler options
The options described here can be used in both .NET and CLI.
Configuration file
Cascadium has the option to run directly from the command line or read a configuration from an JSON file, which provides more options to the compiler.
Example configuration file:
{
"merge": "all",
"pretty": false,
"useVarShortcut": true,
"mergeOrderPriority": "preserveLast",
"inputDirectories": [
"./style/priority-folder"
"./style"
],
"inputFiles": [
"file1.xcss",
"file2.xcss"
],
"extensions": [
".css" // .xcss is included by default
],
"excludePatterns": [
"node_modules",
"vendor"
],
"outputFile": "./dist/app.css",
"atRulesRewrites": {
"media mobile": "media (max-width: 700px)",
"media tablet": "media (max-width: 1200px)",
"media desktop": "media (max-width: 1980px)",
"media ultrawide": "media (min-width: 1981px)"
},
"converters": [
{
"matchProperty": "$location",
"argumentCount": 1,
"output": {
"left": "$1",
"top": "$1"
}
}
]
}
The ideal way for you to configure a project and use Cascadium
in it is to create a cascadium.json file in the root directory
of your project and configure it in the best way, as in the example above.
After creating your cascadium.json file, you can launch
Cascadium with:
cascadium -c cascadium.json --watch
Pretty
Type: boolean
Determines whether the CSS output should be exported indented and well-formatted.
Syntaxes and usages:
cascadium --p:pretty false
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
Pretty = false
});
{
"pretty": false
}
Example:
div {
background-color: red;
> span {
color: yellow;
}
& :hover {
background-color: blue;
}
}
div {
background-color: red;
}
div > span {
color: yellow;
}
div:hover {
background-color: blue;
}
div{background-color:red}div>span{color:yellow}div:hover{background-color:blue}
KeepNestingSpace
Type: boolean
Determines whether the space between the & operator and the selector should be keept.
Syntaxes and usages:
cascadium --p:keepNestingSpace false
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
KeepNestingSpace = false
});
{
"keepNestingSpace": false
}
Example:
div {
& :hover {
background-color: blue;
}
&:active {
background-color: red;
}
}
div :hover {
background-color: blue;
}
div:active {
background-color: red;
}
div:hover {
background-color: blue;
}
div:active {
background-color: red;
}
Merge
Type: MergeOption { None | Selectors | AtRules | Declarations | All }
Determines whether equals rules and at-rules declarations should be merged or not.
Merge is not recommended for use with the watch mode, as it can increase compilation time. Additionally, it's a good idea to always debug Merge results, as the result .css file may produce a different style than it would be without the merge. Merge is recommended for very bad style sheets and those with semantic problems.
Syntaxes and usages:
cascadium --p:merge all
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
Merge = MergeOption.All
});
{
"merge": "all"
}
Example:
div {
color: red;
font-family: Arial;
> .card {
background-color: gainsboro;
}
@media abc {
border: none;
}
}
div {
position: relative;
}
span {
position: relative;
}
div > .card {
color: black;
}
@media abc {
div {
outline-offset: 2px;
}
}
div {
color: red;
font-family: Arial;
}
div > .card {
background-color: gainsboro;
}
div {
position: relative;
}
span {
position: relative;
}
div > .card {
color: black;
}
@media abc {
div {
border: none;
}
}
@media abc {
div {
outline-offset: 2px;
}
}
div { /* merged */
color: red;
font-family: Arial;
position: relative;
}
div > .card {
background-color: gainsboro;
color: black;
}
@media abc {
div {
border: none;
}
}
@media abc {
div {
outline-offset: 2px;
}
}
div {
color: red;
font-family: Arial;
}
div > .card {
background-color: gainsboro;
}
div {
position: relative;
}
span {
position: relative;
}
div > .card {
color: black;
}
@media abc { /* merged */
div {
border: none;
}
div {
outline-offset: 2px;
}
}
div {
color: red;
font-family: Arial;
}
div > .card {
background-color: gainsboro;
}
span, div { /* merged */
position: relative;
}
div > .card {
color: black;
}
@media abc {
div {
border: none;
}
}
@media abc {
div {
outline-offset: 2px;
}
}
div {
color: red;
font-family: Arial;
position: relative;
}
span {
position: relative;
}
div > .card {
background-color: gainsboro;
color: black;
}
@media abc {
div {
border: none;
outline-offset: 2px;
}
}
MergeOrderPriority
Type: MergeOrderPriority { PreserveLast | PreserveFirst }
Determines the order in which orders are created when using the merger
Syntaxes and usages:
cascadium --p:mergeOrderPriority PreserveLast
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
MergeOrderPriority = MergeOrderPriority.PreserveLast
});
{
"mergeOrderPriority": "PreserveLast"
}
Example:
div {
color: red;
}
nav {
background-color: blue;
}
div {
font-family: Arial;
}
div {
color: red;
font-family: Arial;
}
nav {
background-color: blue;
}
nav {
background-color: blue;
}
div {
color: red;
font-family: Arial;
}
UseVarShortcut
Type: boolean
Determines whether the Cascadium compiler should automatically
rewrite --variable to var(--variable)
Syntaxes and usages:
cascadium --p:useVarShortcut false
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
UseVarShortcut = false
});
{
"useVarShortcut": false
}
Example:
:root {
--bg-color: rose;
}
html, body {
background-color: --bg-color;
background: url('--bg-color'); // safe escape
}
:root {
--bg-color: rose;
}
html, body {
background-color: var(--bg-color);
background: url('--bg-color');
}
:root {
--bg-color: rose;
}
html, body {
background-color: --bg-color; /* syntax error */
background: url('--bg-color');
}
AtRulesRewrites
Type: array
Specifies an list of @-rules which will be replaced by the specified values.
Syntaxes and usages:
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
AtRulesRewrites =
{
{ "media mobile", "media only screen and (max-width: 712px)" },
{ "abcdef", "media (max-width: 1000px)" }
}
});
{
"atRulesRewrites": {
"media mobile": "media only screen and (max-width: 712px)",
"abcdef": "media (max-width: 1000px)"
}
}
Example:
div {
color: red;
}
@media mobile {
div {
color: green;
}
}
@abcdef {
div {
color: blue;
}
}
div {
color: red;
}
@media only screen and (max-width: 712px) {
div {
color: green;
}
}
@media (max-width: 1000px) {
div {
color: blue;
}
}
Converters
Type: array
Specifies an list of CSSConverter which will be used in the CSS Compiler.
Syntaxes and usages:
Cascadium.CascadiumCompiler.Compile(xcss, new CascadiumOptions()
{
Pretty = true,
Converters =
{
new StaticCSSConverter()
{
MatchProperty = "$size",
ArgumentCount = 2,
Output =
{
{ "width", "$1" },
{ "height", "$2" }
}
},
new StaticCSSConverter()
{
MatchProperty = "border",
ArgumentCount = null,
Output =
{
{ "-webkit-border", "$*" },
{ "-moz-border", "$*" },
{ "-ms-border", "$*" },
{ "-o-border", "$*" },
{ "border", "$*" }
}
},
// any other converter which implements CSSConverter
}
});
"converters": [
{
"matchProperty": "$size",
"argumentCount": 2,
"output": {
"width": "$1",
"height": "$2"
}
},
{
"matchProperty": "border",
"argumentCount": null,
"output": {
"-webkit-border": "$*",
"-moz-border": "$*",
"-ms-border": "$*",
"-o-border": "$*",
"border": "$*"
}
}
]
Example:
div {
$size: 200px 400px;
border: 12px solid yellow;
}
div {
width: 200px;
height: 400px;
-webkit-border: 12px solid yellow;
-moz-border: 12px solid yellow;
-ms-border: 12px solid yellow;
-o-border: 12px solid yellow;
border: 12px solid yellow;
}