142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
# sass-build
|
|
|
|
[sass-build] is an attempt to simplify the mundane task fo compiling sass. For what is worth, front-end developers probably don't need this package, yet all developers might find it useful due to it's simplicity and configuration.
|
|
|
|
## Misc
|
|
|
|
sass-build was originally intended as a CLI tool, but since its guts are js (typescript to be precise), it can be used in js as well.
|
|
|
|
sass-build differs between compiling a file, which only returns the content and building a file, which will actually output it to disk.
|
|
|
|
sass-build works with an abstract set of sass options that are mapped to actual sass options, depending on the compiler and api used.
|
|
|
|
## Installation
|
|
|
|
You can install sass-build using the following command:
|
|
|
|
```shell
|
|
npm install sass-build [--save-dev]
|
|
```
|
|
|
|
## CLI Usage
|
|
|
|
By executing sass-build with no args, it will look for a file named [`sass.config.js`][sass-config] and process it.
|
|
|
|
```shell
|
|
sass-build
|
|
```
|
|
|
|
To specify a different config use `-c`:
|
|
|
|
```shell
|
|
sass-build -c path/to/config.js
|
|
```
|
|
|
|
To compile a file, use `-f`:
|
|
|
|
```shell
|
|
sass-build -f path/to/file.scss
|
|
```
|
|
|
|
To build a file, supply the `-d` arg:
|
|
|
|
```shell
|
|
sass-build -f path/to/file.scss -d path/to/dest.css
|
|
```
|
|
|
|
To build multiple files, based on glob pattern, use `-g`:
|
|
|
|
```shell
|
|
sass-build -g "**/*.scss"
|
|
```
|
|
|
|
The default output location is `./dist`. To change it, supply the `-o` arg:
|
|
|
|
```shell
|
|
sass-build -g "**/*.scss" -o "/path/to/output/dir"
|
|
```
|
|
|
|
To migrate a [WebCompiler] config to a sassBuild compatible one use:
|
|
|
|
```shell
|
|
# migrate compilerconfig.json to sass.config.js
|
|
sass-build --migrate-compiler-config
|
|
|
|
# specify which config to which output
|
|
sass-build --migrate-compiler-config -c "path/to/config.json" -d "path/to/config.js"
|
|
```
|
|
|
|
## API Usage
|
|
|
|
```js
|
|
const { sassBuild, sassBuildFiles } = require('sass-build');
|
|
|
|
let file = '/path/to/file.scss';
|
|
let outFile = '/path/to/outFile.css';
|
|
|
|
const output = {
|
|
path: './my_dist', // specify output dir; defaults to './dist'
|
|
filename: '[name:toLower].css' // specify output file name; defaults to '[name].css'
|
|
};
|
|
const options = {
|
|
compiler: 'sass-embedded', // defaults to 'node-sass',
|
|
api: 'modern', // defaults to 'legacy'
|
|
sassOptions: {
|
|
minify: true // defaults to false
|
|
}
|
|
};
|
|
|
|
// single file
|
|
sassBuild(file, outFile); // compiles file and writes the result in outFile
|
|
sassBuild(file, outFile, options); // the same but with options
|
|
|
|
// Multiple files
|
|
sassBuildFiles('**/*.scss'); // compile all matched files to /dist
|
|
sassBuildFiles('**/*.scss', output ); // the same but with output options
|
|
sassBuildFiles('**/*.scss', output, options ); // the same but with options
|
|
```
|
|
|
|
## Sass Config
|
|
|
|
Config files are the preferred way of working with sass build. Here is a sample one:
|
|
|
|
```js
|
|
module.exports = {
|
|
extends: [
|
|
// use a predefined config:
|
|
// * ~ import enabled
|
|
// * postcss with autoprefixer and postcss-calc
|
|
// * caching
|
|
'sass-build:recommended'
|
|
],
|
|
build: [
|
|
{
|
|
// use packages/default as the folder in which all lookup is based. default is process.cwd()
|
|
cwd: 'packages/default',
|
|
// path to source file, relative to cwd
|
|
file: 'scss/all.scss',
|
|
// path to out file, relative to cwd
|
|
outFile: 'dist/all.css'
|
|
},
|
|
{
|
|
cwd: 'packages/fluent',
|
|
file: 'scss/all.scss',
|
|
outFile: 'dist/all.css',
|
|
// use different sass implementation
|
|
compiler: 'sass-embedded',
|
|
// use @use instead of @import syntax
|
|
api: 'modern'
|
|
}
|
|
]
|
|
};
|
|
```
|
|
|
|
|
|
## Contributing?
|
|
|
|
Sure.
|
|
|
|
[sass-build]: https://github.com/joneff/sass-build
|
|
[sass-config]: #sass-config
|
|
[WebCompiler]: https://marketplace.visualstudio.com/items?itemName=MadsKristensen.WebCompiler
|