Document executable (CLI) --with argument

[igregson]

Is there a reason that the --with argument for the executable (CLI) isn't documented?

It took me lots of digging to find it, and I'm still not 100% clear on how it works. It's origins:
this PR: #398
and this issue: #397

4 years (!) later, it's in the code, here: https://github.com/stylus/stylus/blob/master/bin/stylus#L312

Context / Use-Case

I'm trying to figure out how to use postcss plugins with Stylus, via an NPM script development-env setup. There's just been this awesome stylus plugin put together, but it doesn't seem possible to use it via Stylus' CLI. Essentially, it needs an array of postcss plugins passed to it (which it includes as a function argument in its exported function (source: https://github.com/seaneking/poststylus/blob/master/index.js#L7)). Not sure if this is more of a topic for here or there (issue created there: madeleineostoja/poststylus#1).

I'd be happy to submit a PR for the --with argument, only I'm not 100% clear on its usage!
Can anyone explain?

[Panya]

The --with option just accepts any valid JS expression and passes its value to a plugin. It easily can be used with poststylus (suppose we have autoprefixer and lost):
stylus --use poststylus --with '[require("autoprefixer"), require("lost")]' test.styl

Feel free to document this and send a PR :)

[igregson]

Thanks for sharing good news, @Panya :)

I'm still having some trouble getting this to work via an NPM build script.

Here's what I've got:

"scripts": {
  "css:watch": "stylus --compress --use poststylus --with '[require(\"autoprefixer\"), require(\"lost\")]  ./app/assets-src/src-css/ --out ./app/assets/css",
},

This throws the following error:

              throw err;
                    ^
ParseError: node_modules/lost/lost.js:5:69
   1| /**
   2|  * Module dependencies
   3|  */
   4| var postcss = require('postcss'),
   5|     assign = require('object-assign');
--------------------------------------------------------------------------^
   6| 
   7| 
   8| /**

expected "indent", got ";"

Could it be the backslashes \ (which seem necessary to escape the double quotes inside of the JSON)?

[Panya]

You forgot ' after the closing ]:

"scripts": {
  "css:watch": "stylus --compress --use poststylus --with '[require(\"autoprefixer\"), require(\"lost\")]'  ./app/assets-src/src-css/ --out ./app/assets/css",
},

[madeleineostoja]

everything @Panya said is right, but FIY this method won't work with poststylus because the require() is evaluated from the home of the stylus binary, rather than project root (so it'll complain that it can't find the module). See my comment on madeleineostoja/poststylus#1

[Panya]

@seaneking yep, but you actually can use postcss plugins if they have been installed globally. Basically, all plugins that used with Stylus CLI should be installed globally.

[madeleineostoja]

yep so that's one solution, just make sure stylus and your postcss plugins are installed in the same place (either install plugins globally or stylus locally)

[igregson]

Thanks folks :)