# { } scss-to-css
### Recursively compile all SCSS files into minified CSS
## ⚡ Installation
As a **global utility**:
```
$ npm install -g @adamlui/scss-to-css
```
As a **dev dependency** (e.g. for build scripts), from your project root:
```
$ npm install -D @adamlui/scss-to-css
```
As a **runtime dependency** (e.g. for on-the-fly compilation), from your project root:
```
$ npm install @adamlui/scss-to-css
```
## 💻 Command line usage
The basic **global command** is:
```
$ scss-to-css
```
Sample output:
**📝 Note:** Source maps are also generated by default unless `-S` or `--no-source-maps` is passed.
#
To specify **input/output** paths:
```
$ scss-to-css [input_path] [output_path]
```
- `[input_path]`: Path to SCSS file or directory containing SCSS files to be compiled, relative to the current working directory.
- `[output_path]`: Path to file or directory where CSS + source map files will be stored, relative to input root (if not provided, `css/` is used).
**📝 Note:** If folders are passed, files will be processed recursively unless `-R` or `--no-recursion` is passed.
#
To use as a **package script**, in your project's `package.json`:
```json
"scripts": {
"build:css": ""
},
```
Replace `` with `scss-to-css` + optional args. Then, `npm run build:css` can be used to run the command.
#
### Example commands
Compile all SCSS files in the **current directory** (outputs to `css/`):
```
$ scss-to-css
```
Compile all SCSS files in a **specific directory** (outputs to `css/path/to/your/directory/`):
```
$ scss-to-css path/to/your/directory
```
Compile a **specific file** (outputs to `css/path/to/your/file.min.css`):
```
$ scss-to-css path/to/your/file.scss
```
Specify both **input and output** directories (outputs to `output_folder/`):
```
$ scss-to-css input_folder output_folder
```
**📝 Note:** Output CSS is minified unless `-M` or `--no-minify` is passed.
#
### Command line options
```
Boolean options:
-n, --dry-run Don't actually compile the file(s), just
show if they will be processed.
-d, --include-dotfolders Include dotfolders in file search.
-S, --no-source-maps Prevent source maps from being generated.
-M, --no-minify Disable minification of output CSS.
-R, --no-recursion Disable recursive file searching.
-r, --relative-output Output files relative to each source file instead of to input root.
-c, --copy Copy compiled CSS to clipboard instead of
writing to file if single source file is
processed.
-q, --quiet Suppress all logging except errors.
Parameter options:
--ignores="dir/,file1.scss,file2.sass" Files/directories to exclude from
compilation.
--comment="comment" Prepend header comment to
compiled CSS. Separate by
line using '\n'.
--ui-lang="code" ISO 639-1 code of language to display UI in.
--config="path/to/file" Load custom config file.
Commands:
-i, --init Create config file (in project root).
-h, --help Display help screen.
-v, --version Show version number.
--stats Show npm stats.
--debug [targetKey] Show debug logs.
```
#
### Configuration file
**scss-to-css** can be customized using a `scss-to-css.config.mjs` or `scss-to-css.config.js` placed in your project root.
Example defaults:
```js
export default {
dryRun: false, // don't actually minify the file(s), just show if they will be processed
includeDotFolders: false, // include dotfolders in file search
noSourceMaps: false, // prevent source maps from being generated
noMinify: false, // disable minification of output CSS
noRecursion: false, // disable recursive file searching
relativeOutput: false, // output files relative to each src file instead of to input root
copy: false, // copy compiled CSS to clipboard instead of write to file if single file processed
quietMode: false, // suppress all logging except errors
ignores: '', // files/dirs to exclude from minification
comment: '' // header comment to prepend to minified code
}
```
💡 Run `scss-to-css init` to generate a template `scss-to-css.config.mjs` in your project root.
## 🔌 API usage
You can also import **scss-to-css** into your app to use its API methods, both as an ECMAScript module or a CommonJS module.
#### ECMAScript*:
```js
import scssToCSS from '@adamlui/scss-to-css'
```
#### CJS:
```js
const scssToCSS = require('@adamlui/scss-to-css')
```
###### _*Node.js version 14 or higher required_
#
### `compile(input[, options])`
💡 Compiles SCSS based on the string input supplied.
If **source code** is passed, it is directly compiled, then an object containing `srcPath` + `code` + `srcMap` + `error` is returned:
```js
const srcCode = 'h1 { font-size: 40px ; code { font-face: Roboto Mono }}',
compileResult = scssToCSS.compile(srcCode)
console.log(compileResult.error) // outputs runtime error, or `undefined` if no error
console.log(compileResult.code) // outputs minified CSS: 'h1{font-size:40px}h1 code{font-face:Roboto Mono}'
```
If a **file path** is passed, the file's code is loaded then compiled to CSS, returning an object like above.
If a **directory path** is passed, SCSS files are searched for (recursively by default), each one's code is loaded then compiled, then an array of objects containing `srcPath` + `code` + `srcMap` + `error` is returned:
```js
// Outputs paths to SCSS files in working directory + all nested directories
const compileResults = scssToCSS.compile('.')
compileResults.forEach(result => console.log(result.srcPath))
// Outputs compiled CSS from 2nd SCSS file if found, or `undefined` if not found
console.log(compileResults[1].code)
```
Options are boolean, passed as object properties. For example:
```js
// Returns array of data objects where `.code` contains unminified CSS
scssToCSS.compile(inputDir, { minify: false })
```
Available parameters (and their default settings) are:
Name | Type | Desciption | Default value
-----------------|---------|-------------------------------------------------------------------------|---------------
`recursive` | Boolean | Recursively search for nested files if dir path passed. | `true`
`verbose` | Boolean | Show logging in console/terminal. | `true`
`dotFolders` | Boolean | Include dotfolders in file search. | `false`
`minify` | Boolean | Minify output CSS. | `true`
`sourceMaps` | Boolean | Generate CSS source maps. | `true`
`relativeOutput` | Boolean | Output files relative to each source file instead of to input root. | `false`
`ignores` | Array | Files/dirs to exclude from compilation. | `[]`
`comment` | String | Header comment to prepend to compiled CSS. Separate by line using '\n'. | `''`
#
### `findSCSS(searchDir[, options])`
💡 Searches for all SCSS files within the `searchDir` string passed (useful for discovering what files [`compile()`](#compileinput-options) will process) and returns an array containing their filepaths.
Options are boolean, passed as object properties. For example:
```js
// Search for SCSS files in exactly assets/scss
const searchResults = scssToCSS.findSCSS('assets/scss', { recursive: false })
console.log(searchResults)
/* sample output:
findSCSS() » Searching for SCSS files...
findSCSS() » Search complete! 2 files found.
findSCSS() » Check returned array.
[
'E:\\js\\utils\\scss-to-css\assets\\scss\\foo.scss',
'E:\\js\\utils\\scss-to-css\assets\\scss\\bar.sass'
]
*/
```
Available parameters (and their default settings) are:
Name | Type | Desciption | Default value
--------------|---------|----------------------------------------------------------|---------------
`recursive` | Boolean | Recursively search for nested files in searchDir passed. | `true`
`verbose` | Boolean | Show logging in console/terminal. | `true`
`dotFolders` | Boolean | Include dotfolders in file search. | `false`
`ignores` | Array | Files/dirs to exclude from search results. | `[]`
## 🏛️ MIT License
**Copyright © 2024 [Adam Lui](https://github.com/adamlui) & contributors**
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## 🛠️ Related utilities
### [ minify.js](https://github.com/adamlui/minify.js/#readme) 
> Recursively minify all JavaScript files.
[Install](https://github.com/adamlui/minify.js/tree/main/node.js/#-installation) /
[Readme](https://github.com/adamlui/minify.js/tree/main/node.js/#readme) /
[CLI usage](https://github.com/adamlui/minify.js/tree/main/node.js/#-command-line-usage) /
[API usage](https://github.com/adamlui/minify.js/tree/main/node.js/#-api-usage) /
[Discuss](https://github.com/adamlui/minify.js/discussions)
**More JavaScript utilities** /
Discuss /
Report bug /
Report vulnerability /
Back to top ↑
