stylus-supremacy

Stylus Supremacy

Stylus Supremacy is a Node.js script for formatting Stylus files. You may say this is a beautifier for Stylus.

Command-line usage

First thing first, you must install this script via NPM.

npm install stylus-supremacy -g

Aftherthat, specifying a source Stylus file follows the command. The formatted content will be printed to the output stream (console/terminal).

stylus-supremacy ./path/to/your/file.styl

In case you want to format multiple files at a time, you can specify the path in glob pattern.

stylus-supremacy ./**/*.styl

The default formatting options will be used, unless you specify your own options explicitly. The parameter --options and -p can be used interchangably.

stylus-supremacy ./path/to/your/file.styl --options ./path/to/your/options.json

You may write the formatted content to a file (or many files, if the pattern matches more than one files) by specifying --outDir or -o, and followed by the path to an output directory.

node stylus-supremacy ./path/to/your/file.styl --outDir ./path/to/output/directory

Alternatively, you may overwrite the original file with the formatted output by specifying --replace or -r parameter.

stylus-supremacy ./path/to/your/file.styl --replace

Note that --outDir and --replace will not work together. You have to choose just one.

Programming usage

Once you have stylus-supremacy installed, you simply include stylus-supremacy and call its format function with a string of Stylus content and an object of formatting options as arguments.

const stylusSupremacy = require('stylus-supremacy')

const stylusContent = `
body
  display none
`

const formattingOptions = {
  insertColons: true,
  insertSemicolons: true,
  insertBraces: true
}

const result = stylusSupremacy.format(stylusContent, formattingOptions)
console.log(result.text)

The result object above contains 3 values: text, tree and warnings.

The result.text is the string of formatted Stylus output.

body {
  display: none;
}

The result.tree is an object generated by Stylus internal parser, which represents the whole Stylus input in a tree structure. This is useful for debugging purposes.

The result.warnings is an array of warning objects genereted by the format function. This array should be empty, unless some tokens could not be recognized, which may lead to a lost in translation. In that case, please open an issue in our repository to help improving

Editor extension usage

If you are using Visual Studio Code, you might be interested in Stylus Supremacy extension.

Currently, there are no extensions for other editor.

Formatting options

You can find a sample JSON file containing the default formatting options here.

Options	Default value	Possible values
insertColons	true	true for always inserting a colon after a property name, otherwise false.
insertSemicolons	true	true for always inserting a semi-colon after a property value, a variable declaration, a variable assignment and a function call, otherwise false.
insertBraces	true	true for always inserting a pair of curly braces between a selector body, a mixin body, a function body and any @block bodies, otherwise false.
insertNewLineBetweenGroups	1	This represents a number of new-line between different type of groups.
insertNewLineBetweenSelectors	false	true for always inserting a new-line between selectors, otherwise false.
insertNewLineBeforeElse	false	true for always inserting a new-line before else keyword, otherwise false.
insertSpaceBeforeComment	true	true for always inserting a white-space before a comment, otherwise false.
insertSpaceAfterComment	true	true for always inserting a white-space after a comment, otherwise false.
insertSpaceAfterComma	true	true for always inserting a white-space after a comma, otherwise false. Commas appear in serveral places, for example, a function parameter list, a function call, object properties and so on.
insertSpaceInsideParenthesis	false	true for always inserting a white-space after an open parenthesis and before a close parenthesis, otherwise false.
insertParenthesisAroundIfCondition	true	true for always inserting a pair of parentheses between if-condition, otherwise false.
insertLeadingZeroBeforeFraction	true	true for always inserting a zero before a number that between 1 and 0, otherwise false.
tabStopChar	"\t"	This represents a tab-stop string. You may change this to 2-white-space sequence or anything.
newLineChar	"\n"	This represents a new-line character. You may change this to "\r\n" if you are using Microsoft Windows.
quoteChar	"'"	This represents a quote character that is used to begin and terminate a string. You must choose either single-quote or double-quote.
sortProperties	false	This can be either false for doing nothing about the CSS property order, "alphabetical" for sorting CSS properties from A to Z, "grouped" for sorting CSS properties according to Stylint predefined order, or an array of property names will sort the properties accordingly (for example, ["display", "margin", "padding"]).
alwaysUseImport	false	true for always using @import over @require. The difference between @import and @require is very subtle. Please refer to the offical guide.
alwaysUseNot	false	true for always using not keyword over ! operator, otherwise false.
alwaysUseAtBlock	false	true for always using @block, otherwise false.
alwaysUseExtends	false	true for always using @extends over @extend, otherwise false.
alwaysUseZeroWithoutUnit	false	true for always using 0 without unit in property values, otherwise false.
reduceMarginAndPaddingValues	false	true for always using margin x over margin x x x x, margin x y over margin x y x y where x, y is a property value, otherwise false.

Stylint compatibility

If you are using Stylint as a Stylus linter and wanting to use .stylintrc file as a formatting options, simply pass the .stylintrc file via --options parameter or pass a JSON of Stylint options as a second patameter of the format function. The Stylint options will be recognized by the command automatically.

stylus-supremacy ./path/to/your/file.styl --options ./path/to/your/.stylintrc

Ultimately, you can pass a JSON containing both Stylint options and Stylus Supremacy formatting options at the same time, but keep in mind that the latter will always have a higher priority.

const stylusSupremacy = require('stylus-supremacy')

const stylusContent = `
body
  display none
`

const formattingOptions = {
  colons: 'always', // From Stylint
  insertColons: false // From Stylus Supremacy
}

const result = stylusSupremacy.format(stylusContent, formattingOptions)
console.log(result.text)

The result.text has no colons between display and none since insertColons is false eventhough colons says otherwise. This is because the values of Stylus Supremacy formatting option are more important than Stylint options.

body {
  display none;
}

Note that "always" in Stylint is equivalent to true; "never" is equivalent to false, otherwise the default formatting options will be used.

Stylint options	Equivalent options in Stylus Supremacy
blocks	alwaysUseAtBlock
brackets	insertBraces
colons	insertColons
colors	Not applicable
commaSpace	insertSpaceAfterComma
commentSpace	insertSpaceAfterComment
cssLiteral	Not applicable
depthLimit	Not applicable
duplicates	Not applicable
efficient	reduceMarginAndPaddingValues
exclude	Not applicable
extendPref	alwaysUseExtends
globalDupe	Not applicable
groupOutputByFile	Not applicable
indentPref	tabStopChar
leadingZero	insertLeadingZeroBeforeFraction
maxErrors	Not applicable
maxWarnings	Not applicable
mixed	Not applicable
namingConvention	Not applicable
namingConventionStrict	Not applicable
none	Not applicable
noImportant	Not applicable
parenSpace	insertSpaceInsideParenthesis
placeholder	Not applicable
prefixVarsWithDollar	Not applicable
quotePref	quoteChar; the values "single" and "double" will be converted to "'" and "\"" respectively.
reporterOptions	Not applicable
semicolons	insertSemicolons
sortOrder	sortProperties
stackedProperties	Not applicable
trailingWhitespace	Not applicable
universal	Not applicable
valid	Not applicable
zeroUnits	alwaysUseZeroWithoutUnit
zIndexNormalize	Not applicable

Release notes

See https://github.com/ThisIsManta/stylus-supremacy/releases

Limitations and known issues

• Both single-line and multi-line comments may be dropped out because Stylus internal parser did not play well with comments as its purpose was to create an input for CSS transpilation.
  The original Stylus file:

  .class1 /* comment-1 */, .class2 /* comment-2 */ {
    display: none;
  }
  

  The formatted output:

  .class1, .class2 { /* comment-2 */
    display: none;
  }
  

  You can see that /* comment-1 */ is missing in the output.

Future work

See https://github.com/ThisIsManta/stylus-supremacy/projects/4