Expose config and pathBuilder. (#57)

* Exposed config and pathBuilder * pathBuilder is now a function. * Added pathbuilder update function to allow paths to be updated using latest config values. * Service worker path updated. * Spelling mistaxe. * Updated readme and changelog. * Bumped package version. * Updated changelog. * Updated readme contents. * Updated readme. * Updated readme. * Updated readme. * Removed option default parameter and simplified condition. * Fixed changelog order. * Removed let statement. * Updated lint documentation.
justeat · Aug 7, 2017 · baa1528 · baa1528
1 parent e583ece
commit baa1528
Show file tree

Hide file tree

Showing 7 changed files with 243 additions and 68 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,20 @@
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+
+v4.0.0
+------------------------------
+*August 04, 2017*
+
+### Changed
+- The return value is now an object containing the `build`, `config`, and `pathBuilder` objects instead of the `build` function.
+- Service worker path no longer contains the service worker filename.
+
+### Added
+- The Readme *Setup* section was updated to reflect the changes to the default return value.
+- The Readme *Path Builder* section was added.
+
+
 v3.8.0
 ------------------------------
 *August 03, 2017*

diff --git a/README.md b/README.md
@@ -9,72 +9,111 @@ Gulp build tasks for use across Fozzie modules.
 
 ## Contents
 
-- [Requirements](#requirements)
 - [Setup](#setup)
+  - [Optional setup](#optional-setup)
+    - [Transpile es2015 code](#transpile-es2015-code)
+    - [JavaScript Linting](#javascript-linting)
+    - [CSS Linting](#css-linting)
+  - [Config and pathBuilder](#config-and-pathbuilder)
+    - [Config object](#config-object)
+    - [pathBuilder object](#pathbuilder-object)
 - [The Gulp Tasks](#the-gulp-tasks)
   - [Development only tasks](#development-only-tasks)
 - [Options](#options)
   - [Other options](#other-options)
+- [Path Builder](#path-builder)
 
-## Requirements
 
-In order for some of the tasks to be able to run you'll need to prepare your project by following these steps:
+## Setup
 
-1. Install gulp as a dependency
+First, add `gulp` and `gulp-build-fozzie` as dependencies
 
-    ```bash
-    yarn add gulp
-    ```
+```bash
+yarn add gulp @justeat/gulp-build-fozzie
+```
 
-1. To ensure that the [`scripts:bundle`](#scriptsbundle) task can transpile es2015 code, add the `babel-preset-es2015` preset to the project:
+Next, inside your `gulpfile.js`, require the build function from `@justeat/gulp-build-fozzie`, then pass `gulp` as the first argument.
 
-    ```bash
-    yarn add babel-preset-es2015
-    ```
+```js
+const gulp = require('gulp');
+const { build } = require('@justeat/gulp-build-fozzie');
 
-    Then add a `.babelrc` file, with the `babel-preset-es2015` preset, to the root of your project:
+build(gulp, /*options*/);
+```
 
-    ```javascript
-    {
-        "presets": ["es2015"]
-    }
-    ```
+You can optionally [pass in options which will override the default config values](#options).
 
-    If you do not add a `.babelrc` file (you may be writing es5 code for example) then the code will be bundled up as is.
+That's it! You can now run any of [the Gulp tasks](#the-gulp-tasks).
 
-1. Add an `.eslintrc` file to the root of your project. The recommended eslint configuration for fozzie modules can be found in [`/fozzie-config/.eslintrc`](https://github.com/justeat/gulp-build-fozzie/fozzie-config/.eslintrc) – simply add the contents of this into your projects `.eslintrc` file to use the JS linting rules we recommend when running the [`scripts:lint`](#scriptslint) task.
+### Optional setup
 
-1. To use our recommended fozzie stylelint linting rules, add the following into your `package.json` file:
+#### Transpile es2015 code
 
-    ```
-    "stylelint": {
-        "extends": "@justeat/stylelint-config-fozzie"
-    }
-    ```
+To ensure that the [`scripts:bundle`](#scriptsbundle) task can transpile es2015 code, add the `babel-preset-es2015` preset to the project:
 
-    If you wish to extend these rules, you can also define your own `.stylelintrc` file in the root of your project with the rules that you wish to override.
+```bash
+yarn add babel-preset-es2015
+```
 
+Then add a `.babelrc` file, with the `babel-preset-es2015` preset, to the root of your project:
 
-## Setup
+```json
+{
+    "presets": ["es2015"]
+}
+```
 
-To integrate these tasks into your project you need to complete the following steps:
+If you do not add a `.babelrc` file (you may be writing es5 code for example) then the code will be bundled up as is.
 
-Add `@justeat/gulp-build-fozzie` to your project
+#### JavaScript Linting
 
-```bash
-yarn add @justeat/gulp-build-fozzie
+Add an `.eslintrc` file to the root of your project with the following content to use the JS linting rules we recommend when running the [`scripts:lint`](#scriptslint) task:
+
+```json
+{
+    "extends": "@justeat/eslint-config-fozzie"
+}
 ```
 
-Inside your gulpfile require and then run `@justeat/gulp-build-fozzie` passing `gulp` as the first argument, You can optionally [pass in options here which will override the defaults](#options).
+If you wish to extend or override these rules you can simply add them after the `extends` line in the `.eslintrc` file.
 
-```js
-const gulp = require('gulp');
-const build = require('@justeat/gulp-build-fozzie');
+[For more information on how you can configure eslint check out the documentation](http://eslint.org/docs/user-guide/configuring).
 
-build(gulp, /*options*/);
+#### CSS Linting
+
+To use our recommended fozzie stylelint linting rules add the following into your `package.json` file:
+
+```json
+"stylelint": {
+    "extends": "@justeat/stylelint-config-fozzie"
+}
 ```
 
-That's it! You can now run any of [the Gulp tasks](#the-gulp-tasks).
+If you wish to extend or override these rules you can simply add them after the `extends` line in the `package.json` file.
+
+[For more information on how you can configure stylelint check out the documentation](https://stylelint.io/user-guide/configuration/).
+
+### Config and pathBuilder
+
+You can also access the `config` and `pathBuilder` objects which are used inside of `gulp-build-fozzie` by requiring them:
+
+```js
+const { config, pathBuilder } = require('@justeat/gulp-build-fozzie');
+```
+
+These are exposed for convenience, and means that you do not need to manually build paths and maintain a separate config object for any custom tasks in your project. It also reduces duplication and prevents bugs which can arise from specifying incorrect paths.
+
+#### `config` object
+
+This is the config object which is used inside of `gulp-build-fozzie`, if you have passed any options via the `build` method they will be available here.
+
+See the [Options](#options) section below for the details of this object.
+
+#### `pathBuilder` object
+
+The `pathBuilder` object is used inside of `gulp-build-fozzie` in order to build the paths used in the gulp tasks.
+
+See the [Path Builder](#path-builder) section below for details on which paths are available.
 
 
 ## The Gulp Tasks
@@ -611,15 +650,15 @@ Root dist directory for your assets.
 
   Default: `true`
 
-  Shoud file sizes be displayed when a task is run?
+  Should file sizes be displayed when a task is run?
 
 - #### `showFiles`
 
   Type: `boolean`
 
   Default: `true`
 
-  Shoud file names be displayed when a task is run?
+  Should file names be displayed when a task is run?
 
 
 ### `gulp`
@@ -652,3 +691,99 @@ The following options are also present in the config but cannot be overridden.
   Type: `boolean`
 
   Set to the opposite value of `isProduction`
+
+
+## Path Builder
+
+You can access the `pathBuilder` paths like this.
+
+```js
+const { pathBuilder } = require('@justeat/gulp-build-fozzie');
+
+gulp.task('scss', () => gulp.src(`${pathBuilder.scssSrcDir}/**`)
+
+...
+```
+
+These are the paths which the `pathBuilder` object provides.
+
+### CSS
+
+- #### `scssSrcDir`
+
+  Default: `'src/scss'`
+
+
+- #### `cssDistDir`
+
+  Default: `'dist/css'`
+
+
+- #### `jsSrcDir`
+
+  Default: `'src/js'`
+
+
+- #### `jsDistDir`
+
+  Default: `'dist/js'`
+
+
+- #### `imgSrcDir`
+
+  Default: `'src/img'`
+
+
+- #### `imgDistDir`
+
+  Default: `'dist/img'`
+
+
+- #### `swOutputPath`
+
+  Default: `'.'`
+
+
+- #### `swSrcDir`
+
+  Default: `'src/sw'`
+
+
+- #### `swDistDir`
+
+  Default: `'dist/sw'`
+
+
+- #### `docsSrcDir`
+
+  Default: `'./docs/src'`
+
+
+- #### `docsDistDir`
+
+  Default: `'./docs/dist'`
+
+
+- #### `docsTemplateDir`
+
+  Default: `'./docs/src/templates'`
+
+
+- #### `docsDataDir`
+
+  Default: `'./docs/src/data'`
+
+
+- #### `docsCssDistDir`
+
+  Default: `'./docs/dist/assets/css'`
+
+
+- #### `docsJsDistDir`
+
+  Default: `'./docs/dist/assets/js'`
+
+
+- #### `docsImgDistDir`
+
+  Default: `'./docs/dist/assets/img'`
diff --git a/index.js b/index.js
@@ -12,13 +12,18 @@
  */
 
 const requireDir = require('require-dir');
-const config = require('./config');
 const gulp = require('gulp');
+const config = require('./config');
+const pathBuilder = require('./pathBuilder');
+
+const build = (srcGulp, options) => {
 
-module.exports = function build (srcGulp, options = {}) {
-    // Update config with custom values — these values will
-    // persist across all further requires in other files.
-    config.update(options);
+    if (options) {
+        // Update config & pathBuilder with custom values — these values will
+        // persist across all further requires in other files.
+        config.update(options);
+        pathBuilder.update(config);
+    }
 
     // Assign existing gulp tasks so that they are not lost.
     gulp.tasks = srcGulp.tasks;
@@ -31,3 +36,9 @@ module.exports = function build (srcGulp, options = {}) {
         requireDir('./tasks-dev', { recurse: false });
     }
 };
+
+module.exports = {
+    build,
+    config,
+    pathBuilder
+};
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@justeat/gulp-build-fozzie",
-  "version": "3.8.0",
+  "version": "4.0.0",
   "description": "Gulp build tasks for use across Fozzie modules",
   "main": "index.js",
   "author": "Damian Mullins <[email protected]> (http://www.damianmullins.com)",

diff --git a/pathBuilder.js b/pathBuilder.js
@@ -1,30 +1,45 @@
-const config = require('./config');
+const baseConfig = require('./config');
 
-const docsSrcDir = `${config.docs.rootDir}/${config.docs.srcDir}`;
-const docsDistDir = `${config.docs.rootDir}/${config.docs.distDir}`;
 
-const pathBuilder = {
+const buildPaths = config => {
 
-    scssSrcDir: `${config.assetSrcDir}/${config.css.scssDir}`,
-    cssDistDir: `${config.assetDistDir}/${config.css.cssDir}`,
+    const docsSrcDir = `${config.docs.rootDir}/${config.docs.srcDir}`;
+    const docsDistDir = `${config.docs.rootDir}/${config.docs.distDir}`;
 
-    jsSrcDir: `${config.assetSrcDir}/${config.js.jsDir}`,
-    jsDistDir: `${config.assetDistDir}/${config.js.jsDir}`,
+    return {
+        scssSrcDir: `${config.assetSrcDir}/${config.css.scssDir}`,
+        cssDistDir: `${config.assetDistDir}/${config.css.cssDir}`,
 
-    imgSrcDir: `${config.assetSrcDir}/${config.img.imgDir}`,
-    imgDistDir: `${config.assetDistDir}/${config.img.imgDir}`,
+        jsSrcDir: `${config.assetSrcDir}/${config.js.jsDir}`,
+        jsDistDir: `${config.assetDistDir}/${config.js.jsDir}`,
 
-    swOutputPath: `${config.webRootDir}/${config.sw.outputFile}`,
-    swSrcDir: `${config.assetSrcDir}/${config.sw.swDir}`,
-    swDistDir: `${config.assetDistDir}/${config.sw.swDir}`,
+        imgSrcDir: `${config.assetSrcDir}/${config.img.imgDir}`,
+        imgDistDir: `${config.assetDistDir}/${config.img.imgDir}`,
 
-    docsSrcDir,
-    docsDistDir,
-    docsTemplateDir: `${docsSrcDir}/${config.docs.templDir}`,
-    docsDataDir: `${docsSrcDir}/${config.docs.dataDir}`,
-    docsCssDistDir: `${docsDistDir}/${config.docs.assetDir}${config.css.cssDir}`,
-    docsJsDistDir: `${docsDistDir}/${config.docs.assetDir}${config.js.jsDir}`,
-    docsImgDistDir: `${docsDistDir}/${config.docs.assetDir}${config.img.imgDir}`
+        swOutputPath: `${config.webRootDir}`,
+        swSrcDir: `${config.assetSrcDir}/${config.sw.swDir}`,
+        swDistDir: `${config.assetDistDir}/${config.sw.swDir}`,
+
+        docsSrcDir,
+        docsDistDir,
+        docsTemplateDir: `${docsSrcDir}/${config.docs.templDir}`,
+        docsDataDir: `${docsSrcDir}/${config.docs.dataDir}`,
+        docsCssDistDir: `${docsDistDir}/${config.docs.assetDir}${config.css.cssDir}`,
+        docsJsDistDir: `${docsDistDir}/${config.docs.assetDir}${config.js.jsDir}`,
+        docsImgDistDir: `${docsDistDir}/${config.docs.assetDir}${config.img.imgDir}`
+    };
+};
+
+const pathBuilder = () => {
+
+    let paths = buildPaths(baseConfig);
+
+    paths.update = config => {
+        const updated = buildPaths(config);
+        paths = Object.assign(paths, updated);
+    };
+
+    return paths;
 };
 
-module.exports = pathBuilder;
+module.exports = pathBuilder();