📃🍞 Fresh-made stylesheets for the whole family
An alternative to postcss-cli for sass users. Compile sass files to CSS and transform using postcss, all in one command.
Using npm (or your package manager of choice):
npm install sheetloaf
Sheetloaf also requires a peer dependency of postcss, so go ahead and run:
npm install postcss
With a few exceptions, efforts have been made to match the postcss-cli option interface. See "Sass Options" for differences.
Usage:
sheetloaf [input.scss] [OPTIONS] [-o|--output output.css] [--watch|-w]
sheetloaf <input.scss>... [OPTIONS] --dir <output-directory> [--watch|-w]
sheetloaf <input-directory> [OPTIONS] --dir <output-directory> [--watch|-w]
sheetloaf <input-glob-pattern> [OPTIONS] --dir <output-directory> [--watch|-w]
Basic options:
-o, --output Output file [string]
-d, --dir Output directory [string]
-w, --watch Watch files for changes and recompile as needed [boolean]
Options for use without a postcss config file:
-u, --use List of postcss plugins to use [array]
Options for use with --dir:
--ext Override the output file extension; for use with --dir [string]
--base Mirror the directory structure relative to this path [string]
in the output directory, for use with --dir
Sass options:
-s, --style Output style. Possible values are "expanded", [string]
or "compressed". Default: "expanded".
--[no-]source-map Whether to generate source maps. Default is on. [boolean]
--embed-source-map Tells Sass to embed the contents of the source [boolean]
map file in the generated CSS, rather than
creating a separate file and linking to it
from the CSS.
--embed-sources Embed the entire contents of the Sass files that [boolean]
contributed to the generated CSS in the source map.
This may produce very large source maps, but it
guarantees that the source will be available on
any computer no matter how the CSS is served.
-–source-map-urls Controls how the source maps that Sass generates [string]
link back to the Sass files that contributed to
the generated CSS. Possible values are "relative"
or "absolute". Default: "relative".
--silence-deprecation This option tells Sass to silence a particular [string]
type of deprecation warning if you wish to
temporarily ignore the deprecation.
-I, --load-path Adds an additional load path for Sass to look [string]
for stylesheets.
-p, --pkg-importer Built-in importer(s) to use for pkg: URLs. [string]
[node] Load files like Node.js package resolution.
Advanced options:
--poll Use polling for file watching. Can optionally pass [boolean]
polling interval; default 100 ms
--async Use Sass's compileAsyc/compileStringAsync functions. [boolean]
This will be slower in most cases.
--[no-]error-css This flag tells Sass whether to emit a CSS file [boolean]
when an error occurs during compilation. This
CSS file describes the error in a comment and in
the content property of body::before, so that
you can see the error message in the browser
without needing to switch back to the terminal.
--config Set a custom directory to look for a config file [string]
Misc:
-v, --version Show version number [boolean]
-h, --help Show help [boolean]
sheetloaf scss/style.scss --output css/style.css --style compressed --use autoprefixer
Above is an example of transforming a sass file, compressing the output and using the postcss plugin autoprefixer to add vendor prefixes. Note that postcss plugins will need to be installed separately, so to use autoprefixer you'd first run:
npm install autoprefixer
You may also specify a glob pattern or directory as input like so:
sheetloaf "scss/**/*.scss" --dir css --style compressed --use autoprefixer
sheetloaf scss --dir css --style compressed --use autoprefixer
In this case we're using the --dir option in place of output. Sheetloaf will automatically ignore partial files whose names begin with _.
For best results when using a glob pattern, make sure to use quotes to avoid side-issues. See https://medium.com/@jakubsynowiec/you-should-always-quote-your-globs-in-npm-scripts-621887a2a784
Sheetloaf also allows for piping!
// stdin
cat scss/style.scss | sheetloaf --use autoprefixer --output css/style.css
// stdout
sheetloaf scss/style.scss --use autoprefixer > style.css
// stdout and logging to stderr
sheetloaf scss/style.scss --use autoprefixer 2> error.txt 1> style.css
// all together now!
cat scss/style.scss | sheetloaf --use autoprefixer 2> error.txt 1> style.css
I'll try.
Postcss-scss combined with other plugins like postcss-mixins gets you in the ballpark, but in my experience there are areas of sass syntax that get missed. Sheetloaf ensures all syntax in dart-sass is covered and rendered.
This works great with single files but when you've got a filewatcher on multiple files this isn't possible.
You could do something like render sass files, output them to a temp folder, and then when those files are modified, check that with chokidar and then call postcss-cli on them to do the rest of the job. This is what I did for a while and I found it to an extremely fiddly and inelegant solution.
For complex projects a more full-featured tool may be more useful, or if you prefer prefer processing all of your scripts/styles/etc in one place.
The benefit of Sheetloaf is fewer dependencies and build simplicity. I've used this tool for all of my personal web projects, and figured I'd polish it up and see if it helps anyone else.
Yes, but you should use postcss-cli in that case, as you'll be incurring a performance hit for no good reason. This project is intended to simplify the two-step process of rendering Sass files and then transforming the output with PostCSS.
Likewise, if all you're looking for is to compile Sass with no transformations, you can stick with dart-sass.
I don't currently see a good use case for including these, since sheetloaf is currently intended to only be used with Sass files. I'm open to be proven wrong though!