js-build-tools 2.2.12 → 2.3.0

package/README.md

@@ -36,6 +36,9 @@ module.exports = {
   // The paths for directories to delete before build.
   cleanPaths: ['dist', 'browser'],
 
+  // The destination path for where generated CSS (from SASS files) should go
+  cssPath: 'browser/css',
+
   // The name of entry the distribution file.
   distMain: 'dist/main',
 
@@ -66,6 +69,12 @@ module.exports = {
   // Base directory of the project.
   rootPath: './',
 
+  // The directory were sass files will be stored
+  sassPath: 'sass',
+  
+  // The pattern for finding all sass files
+  sassSearch: 'sass/**/*.+(scss|sass)',
+
   // The directory where your source files are stored (the files you manually created).
   srcPath: 'src',
 
@@ -81,6 +90,9 @@ module.exports = {
 
   // Pattern for finding the TypeScript files
   tsSearch: 'src/**/*.ts',
+  
+  // Toggle SASS to CSS process on
+  useSass: false,
 
   // The path the tsconfig file for running typescript or false if no ts file given.
   useTsConfig: false,
@@ -102,6 +114,7 @@ const {
   defaultCmd,
   partials,
   readme,
+  sass,
   testFull,
   testQuick,
   typescript,
@@ -115,6 +128,7 @@ const {
 exports.build = build
 exports.default = defaultCmd
 exports.readme = readme
+exports.sass = sass
 exports.testFull = testFull
 exports.testQuick = testQuick
 exports.watchFull = watchFull
@@ -136,6 +150,48 @@ const babelConfig = require('js-build-tools/babel.config')
 module.exports = babelConfig
 ```
 
+### Configure HTML JS Documentation (optional)
+
+It may be desirable to generate HTML documentation for your JS files.
+
+Create a `.jsdoc.conf.js` file and add the following:
+
+```js
+const jsDocBase = require('js-build-tools/jsdoc.base')
+/* You will get a jsdoc config object with the following:
+ * {
+ *    plugins: ['plugins/markdown'],
+ *    source: {
+ *      include: [your configured distPath],
+ *      includePattern: '.+\\.js(doc|x)?$',
+ *      excludePattern: '((^|\\/|\\\\)_|.+\\.test\\..*)'
+ *    }
+ *  }
+ * You can manipulate the properties before returning in module.exports.
+ * This searches the defined 'distPath' for building the HTML JS Documentation
+ */
+module.exports = jsDocBase
+```
+
+### Configure SASS (optional)
+
+SASS support is built-in, this enables conversion of SASS files to CSS for web projects.
+
+Add the following to the exports in your `build-tools.config.js`:
+
+```js
+module.exports = {
+  // Output directory for your compiled css files, recommend css directory within your browser output directory
+  css: 'browser/css',
+  // Optional but nice to add (future support), add the directory where your sass files exist
+  sassPath: 'sass',
+  // Search pattern to find your SASS files (the below would be files ending in .scss or .sass in a directory called 'sass')
+  sassSearch: 'sass/**/*.+(scss|sass)',
+  // Enable SASS process
+  useSass: true,
+}
+```
+
 ### Configure TypeScript (optional)
 
 Create a `tsconfig.json` file in your project root with the following:
@@ -188,7 +244,9 @@ In your `package.json` file, add the following scripts:
   "scripts": {
     "build": "gulp build",
     "dev": "gulp",
+    "htmldocs": "jsdoc -R MAIN.md -c ./.jsdoc.conf.js -d docs",
     "readme": "gulp readme",
+    "sass": "gulp sass",
     "test": "gulp testFull",
     "test:quick": "gulp testQuick",
     "watch": "gulp watchFull",
@@ -612,6 +670,7 @@ Micro-functions used as components for the main gulp functions.
 
 * [partials](#module_partials)
     * [.tsFor([srcPath], [distPath])](#module_partials.tsFor) ⇒ <code>function</code>
+    * [.sassFor([srcSearch], [cssPath])](#module_partials.sassFor) ⇒ <code>stream.Stream</code>
     * [.runOnChange(path)](#module_partials.runOnChange) ⇒ <code>stream.Stream</code>
         * [~pathRegex](#module_partials.runOnChange..pathRegex)
     * [.removeDirectory(dirPath)](#module_partials.removeDirectory) ⇒ <code>Promise.&lt;\*&gt;</code>
@@ -637,6 +696,18 @@ Starting at the source directory, find all the ts files and convert them into th
 | [srcPath] | <code>string</code> \| <code>array</code> | <code>&quot;&#x27;&#x27;&quot;</code> | 
 | [distPath] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | 
 
+<a name="module_partials.sassFor"></a>
+
+### partials.sassFor([srcSearch], [cssPath]) ⇒ <code>stream.Stream</code>
+Build the CSS for a given source pattern.
+
+**Kind**: static method of [<code>partials</code>](#module_partials)  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| [srcSearch] | <code>string</code> \| <code>array</code> | <code>&quot;&#x27;src/config/path/sass/for&#x27;&quot;</code> | 
+| [cssPath] | <code>string</code> | <code>&quot;&#x27;css/config/path&#x27;&quot;</code> | 
+
 <a name="module_partials.runOnChange"></a>
 
 ### partials.runOnChange(path) ⇒ <code>stream.Stream</code>

package/dist/build.js

@@ -1,48 +1,53 @@
-'use strict'
-
-const bundle = require('./bundle')
-const bundleLint = require('./bundleLint')
-const bundleMinify = require('./bundleMinify')
-const {
-  clean,
-  distSeries
-} = require('./partials')
-const compileReadme = require('./compileReadme')
-const distLint = require('./distLint')
-const distMinify = require('./distMinify')
-const {
-  parallel,
-  series
-} = require('gulp')
-const gulpConfig = require('../gulp.config.js')
-const testFull = require('./testFull')
-
+'use strict'
+
+const bundle = require('./bundle')
+const bundleLint = require('./bundleLint')
+const bundleMinify = require('./bundleMinify')
+const {
+  clean,
+  distSeries
+} = require('./partials')
+const compileReadme = require('./compileReadme')
+const distLint = require('./distLint')
+const distMinify = require('./distMinify')
+const {
+  parallel,
+  series
+} = require('gulp')
+const gulpConfig = require('../gulp.config.js')
+const sass = require('./sass.js')
+const testFull = require('./testFull')
+
 /**
  * Runs several processes to build and validate the project.
  * Cleans, distributes (lint and minify), bundles (lint and minify), creates the readme, then runs the tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = function () {
-  const done = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : null
-  const distLintMinify = parallel(distLint, distMinify)
-  const bundleLintMinify = parallel(bundleLint, bundleMinify)
-  const buildActions = [clean, distSeries(), distLintMinify]
-  if (gulpConfig.get('useTsConfig')) {
-    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
-    buildActions.push(compileReadme)
-  }
-  if (!gulpConfig.get('nodeOnly')) {
-    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
-    buildActions.push(bundle)
-    buildActions.push(bundleLintMinify)
-  }
-  const runActions = [series(...buildActions)]
-  if (!gulpConfig.get('useTsConfig')) {
-    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
-    runActions.push(compileReadme)
-  }
-  runActions.push(testFull)
-  return parallel(...runActions)(done)
-}
-module.exports = build
+ */
+const build = function () {
+  const done = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : null
+  const distLintMinify = parallel(distLint, distMinify)
+  const bundleLintMinify = parallel(bundleLint, bundleMinify)
+  const buildActions = [clean, distSeries(), distLintMinify]
+  if (gulpConfig.get('useTsConfig')) {
+    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
+    buildActions.push(compileReadme)
+  }
+  if (!gulpConfig.get('nodeOnly')) {
+    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
+    buildActions.push(bundle)
+    buildActions.push(bundleLintMinify)
+  }
+  const runActions = [series(...buildActions)]
+  if (!gulpConfig.get('useTsConfig')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(compileReadme)
+  }
+  runActions.push(testFull)
+  if (gulpConfig.get('useSass')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(sass)
+  }
+  return parallel(...runActions)(done)
+}
+module.exports = build

package/dist/build.min.js

@@ -1 +1 @@
-"use strict";const bundle=require("./bundle"),bundleLint=require("./bundleLint"),bundleMinify=require("./bundleMinify"),{clean:clean,distSeries:distSeries}=require("./partials"),compileReadme=require("./compileReadme"),distLint=require("./distLint"),distMinify=require("./distMinify"),{parallel:parallel,series:series}=require("gulp"),gulpConfig=require("../gulp.config.js"),testFull=require("./testFull"),build=function(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:null;const i=parallel(distLint,distMinify),l=parallel(bundleLint,bundleMinify),u=[clean,distSeries(),i];gulpConfig.get("useTsConfig")&&u.push(compileReadme),gulpConfig.get("nodeOnly")||(u.push(bundle),u.push(l));const n=[series(...u)];return gulpConfig.get("useTsConfig")||n.push(compileReadme),n.push(testFull),parallel(...n)(e)};module.exports=build;
+"use strict";const bundle=require("./bundle"),bundleLint=require("./bundleLint"),bundleMinify=require("./bundleMinify"),{clean:clean,distSeries:distSeries}=require("./partials"),compileReadme=require("./compileReadme"),distLint=require("./distLint"),distMinify=require("./distMinify"),{parallel:parallel,series:series}=require("gulp"),gulpConfig=require("../gulp.config.js"),sass=require("./sass.js"),testFull=require("./testFull"),build=function(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:null;const i=parallel(distLint,distMinify),l=parallel(bundleLint,bundleMinify),s=[clean,distSeries(),i];gulpConfig.get("useTsConfig")&&s.push(compileReadme),gulpConfig.get("nodeOnly")||(s.push(bundle),s.push(l));const u=[series(...s)];return gulpConfig.get("useTsConfig")||u.push(compileReadme),u.push(testFull),gulpConfig.get("useSass")&&u.push(sass),parallel(...u)(e)};module.exports=build;

package/dist/partials/sassFor.js

@@ -0,0 +1,28 @@
+"use strict";
+
+const {
+  dest,
+  src
+} = require('gulp');
+const gulpConfig = require('../../gulp.config.js');
+const cssnano = require('gulp-cssnano');
+const rename = require('gulp-rename');
+const sass = require('gulp-sass')(require('sass'));
+
+/**
+ * Build the CSS for a given source pattern.
+ * @function
+ * @memberOf module:partials
+ * @param {string|array} [srcSearch='src/config/path/sass/for']
+ * @param {string} [cssPath='css/config/path']
+ * @returns {stream.Stream}
+ */
+const sassFor = function () {
+  let srcSearch = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : gulpConfig.get('sassSearch');
+  let cssPath = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : gulpConfig.get('cssPath');
+  return src(srcSearch).pipe(sass().on('error', sass.logError)) // Passes it through a gulp-sass, log errors to console
+  .pipe(dest(cssPath)).pipe(cssnano()).pipe(rename({
+    extname: '.min.css'
+  })).pipe(dest(cssPath));
+};
+module.exports = sassFor;

package/dist/partials.js

@@ -1,5 +1,5 @@
-'use strict'
-
+'use strict'
+
 /**
  * Micro-functions used as components for the main gulp functions.
  * @file
@@ -7,29 +7,31 @@
  * @version 2.0.0
  * @module partials
  * @memberOf module:js-build-tools
- */
-
-const addToReadme = require('./partials/addToReadme')
-const beginWatcher = require('./partials/beginWatcher')
-const clean = require('./partials/clean')
-const distFor = require('./partials/distFor')
-const distForSrc = require('./partials/distForSrc')
-const distSeries = require('./partials/distSeries')
-const minifyFor = require('./partials/minifyFor')
-const readmeTemplate = require('./partials/readmeTemplate')
-const removeDirectory = require('./partials/removeDirectory')
-const runOnChange = require('./partials/runOnChange')
-const tsFor = require('./partials/tsFor')
-module.exports = {
-  addToReadme,
-  beginWatcher,
-  clean,
-  distFor,
-  distForSrc,
-  distSeries,
-  minifyFor,
-  readmeTemplate,
-  removeDirectory,
-  runOnChange,
-  tsFor
-}
+ */
+
+const addToReadme = require('./partials/addToReadme')
+const beginWatcher = require('./partials/beginWatcher')
+const clean = require('./partials/clean')
+const distFor = require('./partials/distFor')
+const distForSrc = require('./partials/distForSrc')
+const distSeries = require('./partials/distSeries')
+const minifyFor = require('./partials/minifyFor')
+const readmeTemplate = require('./partials/readmeTemplate')
+const removeDirectory = require('./partials/removeDirectory')
+const runOnChange = require('./partials/runOnChange')
+const sassFor = require('./partials/sassFor')
+const tsFor = require('./partials/tsFor')
+module.exports = {
+  addToReadme,
+  beginWatcher,
+  clean,
+  distFor,
+  distForSrc,
+  distSeries,
+  minifyFor,
+  readmeTemplate,
+  removeDirectory,
+  runOnChange,
+  sassFor,
+  tsFor
+}

package/dist/partials.min.js

@@ -1 +1 @@
-"use strict";const addToReadme=require("./partials/addToReadme"),beginWatcher=require("./partials/beginWatcher"),clean=require("./partials/clean"),distFor=require("./partials/distFor"),distForSrc=require("./partials/distForSrc"),distSeries=require("./partials/distSeries"),minifyFor=require("./partials/minifyFor"),readmeTemplate=require("./partials/readmeTemplate"),removeDirectory=require("./partials/removeDirectory"),runOnChange=require("./partials/runOnChange"),tsFor=require("./partials/tsFor");module.exports={addToReadme:addToReadme,beginWatcher:beginWatcher,clean:clean,distFor:distFor,distForSrc:distForSrc,distSeries:distSeries,minifyFor:minifyFor,readmeTemplate:readmeTemplate,removeDirectory:removeDirectory,runOnChange:runOnChange,tsFor:tsFor};
+"use strict";const addToReadme=require("./partials/addToReadme"),beginWatcher=require("./partials/beginWatcher"),clean=require("./partials/clean"),distFor=require("./partials/distFor"),distForSrc=require("./partials/distForSrc"),distSeries=require("./partials/distSeries"),minifyFor=require("./partials/minifyFor"),readmeTemplate=require("./partials/readmeTemplate"),removeDirectory=require("./partials/removeDirectory"),runOnChange=require("./partials/runOnChange"),sassFor=require("./partials/sassFor"),tsFor=require("./partials/tsFor");module.exports={addToReadme:addToReadme,beginWatcher:beginWatcher,clean:clean,distFor:distFor,distForSrc:distForSrc,distSeries:distSeries,minifyFor:minifyFor,readmeTemplate:readmeTemplate,removeDirectory:removeDirectory,runOnChange:runOnChange,sassFor:sassFor,tsFor:tsFor};

package/dist/sass.js

@@ -0,0 +1,7 @@
+'use strict'
+
+const sassFor = require('./partials/sassFor')
+
+// Compile sass into CSS & auto-inject into browsers
+const sass = () => sassFor()
+module.exports = sass

package/dist/sass.min.js

@@ -0,0 +1 @@
+"use strict";const sassFor=require("./partials/sassFor"),sass=()=>sassFor();module.exports=sass;

package/dist/test-helpers/setUp.js

@@ -1,73 +1,77 @@
-"use strict";
-
-const fs = require('fs');
-// Import the configurations and override some of them in order to direct to the temp directory.
-const gulpConfig = require('../../gulp.config.js');
-const {
-  removeDirectory
-} = require('../partials');
-let tempDir = 'test-temp/';
-let srcPath = `${tempDir}src`;
-
+"use strict";
+
+const fs = require('fs');
+// Import the configurations and override some of them in order to direct to the temp directory.
+const gulpConfig = require('../../gulp.config.js');
+const {
+  removeDirectory
+} = require('../partials');
+let tempDir = 'test-temp/';
+let srcPath = `${tempDir}src`;
+
 /**
  * Update the gulp configurations with the test data. Set the test directory where temp files will be created for testing.
  * @function
  * @memberOf module:testHelpers
  * @param {string} testDir
- */
-const setDefaults = function () {
-  let testDir = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'test-temp';
-  tempDir = `${testDir}/`;
-  srcPath = `${tempDir}src`;
-  const distPath = `${tempDir}dist`;
-  const browserPath = `${tempDir}browser`;
-  gulpConfig.set('browserPath', browserPath);
-  gulpConfig.set('cleanPaths', [distPath, browserPath]);
-  gulpConfig.set('distMain', `${distPath}/main`);
-  gulpConfig.set('distPath', distPath);
-  gulpConfig.set('distSearch', `${distPath}/**/*.js`);
-  gulpConfig.set('readmeTemplate', `${tempDir}MAIN.md`);
-  gulpConfig.set('readmePath', tempDir);
-  gulpConfig.set('readmeSearch', `${srcPath}/**/!(*.test).js`);
-  gulpConfig.set('rootPath', tempDir);
-  gulpConfig.set('srcPath', srcPath);
-  gulpConfig.set('srcSearch', `${srcPath}/**/!(*.test).js`);
-  gulpConfig.set('tsSearch', `${srcPath}/**/*.ts`);
-  gulpConfig.set('watchSearch', `${srcPath}/**/*.js`);
-};
-exports.setDefaults = setDefaults;
-exports.gulpConfig = gulpConfig;
-
+ */
+const setDefaults = function () {
+  let testDir = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'test-temp';
+  tempDir = `${testDir}/`;
+  srcPath = `${tempDir}src`;
+  const distPath = `${tempDir}dist`;
+  const browserPath = `${tempDir}browser`;
+  const sassPath = `${tempDir}sass`;
+  gulpConfig.set('browserPath', browserPath);
+  gulpConfig.set('cleanPaths', [distPath, browserPath]);
+  gulpConfig.set('cssPath', `${browserPath}/css`);
+  gulpConfig.set('distMain', `${distPath}/main`);
+  gulpConfig.set('distPath', distPath);
+  gulpConfig.set('distSearch', `${distPath}/**/*.js`);
+  gulpConfig.set('readmeTemplate', `${tempDir}MAIN.md`);
+  gulpConfig.set('readmePath', tempDir);
+  gulpConfig.set('readmeSearch', `${srcPath}/**/!(*.test).js`);
+  gulpConfig.set('rootPath', tempDir);
+  gulpConfig.set('sassPath', sassPath);
+  gulpConfig.set('sassSearch', `${sassPath}/**/*.+(scss|sass)`);
+  gulpConfig.set('srcPath', srcPath);
+  gulpConfig.set('srcSearch', `${srcPath}/**/!(*.test).js`);
+  gulpConfig.set('tsSearch', `${srcPath}/**/*.ts`);
+  gulpConfig.set('watchSearch', `${srcPath}/**/*.js`);
+};
+exports.setDefaults = setDefaults;
+exports.gulpConfig = gulpConfig;
+
 /**
  * Ensure that the del has completed, recursively attempt to delete and recreate
  * @function
  * @memberOf module:testHelpers
  * @param {boolean} [exists=true]
  * @returns {Promise<*|void>}
- */
-const createTempDir = async function () {
-  let exists = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
-  if (exists) {
-    return removeDirectory(tempDir).then(removedDir => createTempDir(fs.existsSync(removedDir))).catch(error => console.error('Error: ', error));
-  }
-  return fs.mkdirSync(srcPath, {
-    recursive: true
-  });
-};
-exports.createTempDir = createTempDir;
-
+ */
+const createTempDir = async function () {
+  let exists = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+  if (exists) {
+    return removeDirectory(tempDir).then(removedDir => createTempDir(fs.existsSync(removedDir))).catch(error => console.error('Error: ', error));
+  }
+  return fs.mkdirSync(srcPath, {
+    recursive: true
+  });
+};
+exports.createTempDir = createTempDir;
+
 /**
  * In the Jest.beforeEach function call this one to set up the temp directory.
  * @function
  * @memberOf module:testHelpers
  * @returns {Promise<*|void>}
- */
-exports.beforeEach = () => createTempDir();
-
+ */
+exports.beforeEach = () => createTempDir();
+
 /**
  * In the Jest.afterEach function call this one to clean up and remove the temp directory.
  * @function
  * @memberOf module:testHelpers
  * @returns {Promise<*>}
- */
+ */
 exports.afterEach = () => removeDirectory(tempDir);

package/functions/build.js

@@ -7,6 +7,7 @@ const distLint = require('./distLint')
 const distMinify = require('./distMinify')
 const { parallel, series } = require('gulp')
 const gulpConfig = require('../gulp.config.js')
+const sass = require('./sass.js')
 const testFull = require('./testFull')
 
 /**
@@ -36,6 +37,10 @@ const build = (done = null) => {
     runActions.push(compileReadme)
   }
   runActions.push(testFull)
+  if (gulpConfig.get('useSass')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(sass)
+  }
   return parallel(
     ...runActions
   )(done)

package/functions/build.test.js

@@ -4,6 +4,7 @@ setUp.setDefaults('test-build')
 const gulpConfig = setUp.gulpConfig
 const build = require('./build')
 const clean = require('./partials/clean')
+const sass = require('./sass')
 const testFull = require('./testFull')
 const { countMatches } = require('./testHelpers')
 
@@ -78,6 +79,27 @@ const tsConfigContents = '{\n' +
   '  }\n' +
   '}'
 
+const sassContents = 'html\n' +
+  '  font-size: 62.5%\n' +
+  '  color: #444\n' +
+  '  font-size: 1em\n' +
+  '  line-height: 1.4\n' +
+  '  background-color: #fff\n' +
+  '\n' +
+  'html, body\n' +
+  '  width: 100%\n' +
+  '  height: 100%\n' +
+  '  margin: 0\n' +
+  '  padding: 0\n' +
+  '  position: absolute\n' +
+  '  text-align: center\n' +
+  '\n' +
+  'a\n' +
+  '  outline: none\n' +
+  '  text-decoration: none'
+
+const sassPath = gulpConfig.get('sassPath')
+
 beforeEach(
   () => setUp.beforeEach()
     .then(
@@ -86,6 +108,7 @@ beforeEach(
         const readmePath = gulpConfig.get('readmePath')
         const sourcesPath = `${srcPath}/sources`
         await fs.mkdirSync(sourcesPath)
+        await fs.mkdirSync(sassPath, { recursive: true })
         return fs.writeFileSync(`${readmePath}/MAIN.md`, mainMd)
       }
     )
@@ -189,6 +212,66 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('when nodeOnly false and useSass true: calls clean, distSeries, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull, sass', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const sourcesPath = `${srcPath}/sources`
+    const distPath = gulpConfig.get('distPath')
+    const browserFile = gulpConfig.get('browserName')
+    const browserPath = gulpConfig.get('browserPath')
+    const bundledFile = `${browserPath}/${browserFile}.js`
+    const readmePath = gulpConfig.get('readmePath')
+    const readmeFile = gulpConfig.get('readmeFile')
+    const sassFile = `${sassPath}/sassFor.sass`
+    fs.writeFileSync(sassFile, sassContents)
+    fs.writeFileSync(`${sourcesPath}/file1.js`, file1Contents)
+    fs.writeFileSync(`${sourcesPath}/file2.js`, file2Contents)
+    fs.writeFileSync(`${srcPath}/main.js`, mainFileContents)
+    gulpConfig.set('nodeOnly', false)
+    gulpConfig.set('useSass', true)
+    expect.assertions(16)
+    build(() => {
+      // Called 'clean'
+      expect(clean).toHaveBeenCalled()
+
+      // Created dist directory (distSeries)
+      expect(fs.existsSync(distPath)).toBeTruthy()
+
+      // Minify the dist files (distMinify)
+      expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
+      const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
+      // Used single quotes because of distLint
+      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+
+      // Created browser directory (bundle)
+      expect(fs.existsSync(browserPath)).toBeTruthy()
+
+      // Minify the browser files (bundleMinify)
+      expect(fs.existsSync(`${browserPath}/${browserFile}.min.js`)).toBeTruthy()
+      const bundledContents = fs.readFileSync(bundledFile).toString()
+      expect(countMatches(bundledContents, 'file1')).toEqual(7)
+      expect(countMatches(bundledContents, 'file2')).toEqual(7)
+
+      // Generated README.md (compileReadme)
+      const readmeContents = fs.readFileSync(`${readmePath}/${readmeFile}`).toString()
+      expect(countMatches(readmeContents, mainMd)).toEqual(1)
+      expect(countMatches(readmeContents, 'test-build')).toEqual(4)
+      expect(countMatches(readmeContents, 'file1')).toEqual(4)
+      expect(countMatches(readmeContents, 'file2')).toEqual(4)
+
+      // Ran 'testFull'
+      expect(testFull).toHaveBeenCalled()
+
+      // Ran 'sass'
+      const cssPath = gulpConfig.get('cssPath')
+      const cssContents = fs.readFileSync(`${cssPath}/sassFor.css`).toString()
+      expect(countMatches(cssContents, ';')).toEqual(13)
+      expect(countMatches(cssContents, '{')).toEqual(3)
+      expect(countMatches(cssContents, '}')).toEqual(3)
+
+      done()
+    })
+  }, 30000)
+
   test('when nodeOnly true and useTsConfig set: calls clean, tsFor, distFor, distLint, distMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')

package/functions/partials/sassFor.js

@@ -0,0 +1,22 @@
+const { dest, src } = require('gulp')
+const gulpConfig = require('../../gulp.config.js')
+const cssnano = require('gulp-cssnano')
+const rename = require('gulp-rename')
+const sass = require('gulp-sass')(require('sass'))
+
+/**
+ * Build the CSS for a given source pattern.
+ * @function
+ * @memberOf module:partials
+ * @param {string|array} [srcSearch='src/config/path/sass/for']
+ * @param {string} [cssPath='css/config/path']
+ * @returns {stream.Stream}
+ */
+const sassFor = (srcSearch = gulpConfig.get('sassSearch'), cssPath = gulpConfig.get('cssPath')) => src(srcSearch)
+  .pipe(sass().on('error', sass.logError)) // Passes it through a gulp-sass, log errors to console
+  .pipe(dest(cssPath))
+  .pipe(cssnano())
+  .pipe(rename({ extname: '.min.css' }))
+  .pipe(dest(cssPath))
+
+module.exports = sassFor

package/functions/partials/sassFor.test.js

@@ -0,0 +1,62 @@
+const fs = require('fs')
+const setUp = require('../test-helpers/setUp')
+setUp.setDefaults('test-sass-for')
+const gulpConfig = setUp.gulpConfig
+const sassFor = require('./sassFor')
+const { countMatches, logObject } = require('../testHelpers')
+
+const sassContents = 'html\n' +
+  '  font-size: 62.5%\n' +
+  '  color: #444\n' +
+  '  font-size: 1em\n' +
+  '  line-height: 1.4\n' +
+  '  background-color: #fff\n' +
+  '\n' +
+  'html, body\n' +
+  '  width: 100%\n' +
+  '  height: 100%\n' +
+  '  margin: 0\n' +
+  '  padding: 0\n' +
+  '  position: absolute\n' +
+  '  text-align: center\n' +
+  '\n' +
+  'a\n' +
+  '  outline: none\n' +
+  '  text-decoration: none'
+
+const sassPath = gulpConfig.get('sassPath')
+
+beforeEach(() => {
+  setUp.beforeEach()
+  return fs.mkdirSync(sassPath, { recursive: true })
+})
+
+afterEach(setUp.afterEach)
+
+describe('sassFor', () => {
+  test('copies the sass directory and converts it into css output', done => {
+    const sassFile = `${sassPath}/sassFor.sass`
+    fs.writeFileSync(sassFile, sassContents)
+    expect.assertions(7)
+    const oldContents = fs.readFileSync(sassFile).toString()
+    expect(countMatches(oldContents, ';')).toEqual(0)
+    expect(countMatches(oldContents, ' {')).toEqual(0)
+    expect(countMatches(oldContents, '\n' +
+      '    }')).toEqual(0)
+    const cssPath = gulpConfig.get('cssPath')
+    sassFor(sassFile)
+      .on('finish', () => {
+        expect(fs.existsSync(cssPath)).toBeTruthy()
+        const cssContents = fs.readFileSync(`${cssPath}/sassFor.css`).toString()
+        // Will add braces and semicolons
+        expect(countMatches(cssContents, ';')).toEqual(13)
+        expect(countMatches(cssContents, '{')).toEqual(3)
+        expect(countMatches(cssContents, '}')).toEqual(3)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
+})

package/functions/partials.js

@@ -17,6 +17,7 @@ const minifyFor = require('./partials/minifyFor')
 const readmeTemplate = require('./partials/readmeTemplate')
 const removeDirectory = require('./partials/removeDirectory')
 const runOnChange = require('./partials/runOnChange')
+const sassFor = require('./partials/sassFor')
 const tsFor = require('./partials/tsFor')
 
 module.exports = {
@@ -30,5 +31,6 @@ module.exports = {
   readmeTemplate,
   removeDirectory,
   runOnChange,
+  sassFor,
   tsFor,
 }

package/functions/partials.test.js

@@ -2,6 +2,6 @@ const partials = require('./partials')
 
 describe('partials', () => {
   test('is object with all partial exports', () => {
-    expect(Object.keys(partials).length).toBe(11)
+    expect(Object.keys(partials).length).toBe(12)
   })
 })

package/functions/sass.js

@@ -0,0 +1,6 @@
+const sassFor = require('./partials/sassFor')
+
+// Compile sass into CSS & auto-inject into browsers
+const sass = () => sassFor()
+
+module.exports = sass

package/functions/sass.test.js

@@ -0,0 +1,30 @@
+const fs = require('fs')
+const setUp = require('./test-helpers/setUp')
+setUp.setDefaults('test-sass')
+const gulpConfig = setUp.gulpConfig
+const sass = require('./sass')
+
+beforeEach(() => setUp.beforeEach().then(
+  () => {
+    const sassPath = gulpConfig.get('sassPath')
+    return fs.mkdirSync(sassPath, { recursive: true })
+  }
+))
+
+afterEach(setUp.afterEach)
+
+describe('sass', () => {
+  test('uses the configured paths', done => {
+    const sassPath = gulpConfig.get('sassPath')
+    expect.assertions(1)
+    sass()
+      .on('finish', () => {
+        expect(fs.existsSync(sassPath)).toBeTruthy()
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  }, 10000)
+})

package/functions/test-helpers/setUp.js

@@ -17,8 +17,10 @@ const setDefaults = (testDir = 'test-temp') => {
   srcPath = `${tempDir}src`
   const distPath = `${tempDir}dist`
   const browserPath = `${tempDir}browser`
+  const sassPath = `${tempDir}sass`
   gulpConfig.set('browserPath', browserPath)
   gulpConfig.set('cleanPaths', [distPath, browserPath])
+  gulpConfig.set('cssPath', `${browserPath}/css`)
   gulpConfig.set('distMain', `${distPath}/main`)
   gulpConfig.set('distPath', distPath)
   gulpConfig.set('distSearch', `${distPath}/**/*.js`)
@@ -26,6 +28,8 @@ const setDefaults = (testDir = 'test-temp') => {
   gulpConfig.set('readmePath', tempDir)
   gulpConfig.set('readmeSearch', `${srcPath}/**/!(*.test).js`)
   gulpConfig.set('rootPath', tempDir)
+  gulpConfig.set('sassPath', sassPath)
+  gulpConfig.set('sassSearch', `${sassPath}/**/*.+(scss|sass)`)
   gulpConfig.set('srcPath', srcPath)
   gulpConfig.set('srcSearch', `${srcPath}/**/!(*.test).js`)
   gulpConfig.set('tsSearch', `${srcPath}/**/*.ts`)

package/gulp.config.js

@@ -113,6 +113,7 @@ const setDefaults = {
   browserName: 'default',
   browserPath: 'browser',
   cleanPaths: ['dist', 'browser'],
+  cssPath: 'browser/css',
   distMain: 'dist/main',
   distPath: 'dist',
   distSearch: 'dist/**/*.js',
@@ -123,6 +124,8 @@ const setDefaults = {
   readmePath: './',
   readmeSearch: 'src/**/!(*.test).js',
   rootPath: './',
+  sassPath: 'sass',
+  sassSearch: 'sass/**/*.+(scss|sass)',
   srcPath: 'src',
   srcSearch: 'src/**/!(*.test).js',
   testOptions: {
@@ -138,6 +141,7 @@ const setDefaults = {
   },
   testPath: ['src'],
   tsSearch: 'src/**/*.ts',
+  useSass: false,
   useTsConfig: false,
   watchSearch: 'src/**/*.js'
 }

package/gulpfile.base.js

@@ -17,6 +17,7 @@ const distLint = require('./functions/distLint.js')
 const distMinify = require('./functions/distMinify.js')
 const gulpConfig = require('./gulp.config.js')
 const partials = require('./functions/partials.js')
+const sass = require('./functions/sass.js')
 const testFull = require('./functions/testFull.js')
 const testHelpers = require('./functions/testHelpers.js')
 const testQuick = require('./functions/testQuick.js')
@@ -36,6 +37,7 @@ module.exports = {
   gulpConfig,
   partials,
   readme: compileReadme,
+  sass,
   testFull,
   testHelpers,
   testQuick,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "2.2.12",
+  "version": "2.3.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "scripts": {
@@ -45,7 +45,9 @@
     "glob": "^10.3.10",
     "gulp": "^4.0.2",
     "gulp-babel": "^8.0.0",
+    "gulp-cssnano": "^2.1.3",
     "gulp-rename": "^2.0.0",
+    "gulp-sass": "^5.1.0",
     "gulp-standard": "^14.0.0",
     "gulp-typescript": "^6.0.0-alpha.1",
     "gulp-uglify-es": "^3.0.0",
@@ -53,6 +55,7 @@
     "jest-environment-jsdom": "^29.7.0",
     "jsdoc-to-markdown": "^8.0.0",
     "regenerator-runtime": "^0.14.1",
+    "sass": "^1.69.7",
     "vinyl-source-stream": "^2.0.0"
   },
   "files": [