Skip to content

Gulp build tasks for use across Fozzie modules

License

Notifications You must be signed in to change notification settings

justeat/gulp-build-fozzie

Repository files navigation

gulp-build-fozzie 🐻

npm version Build Status Coverage Status

Gulp build tasks for use across Fozzie modules.

Contents

Setup

First, add gulp and gulp-build-fozzie as dependencies

yarn add gulp @justeat/gulp-build-fozzie

Next, inside your gulpfile.js, require the build function from @justeat/gulp-build-fozzie, then pass gulp as the first argument.

const gulp = require('gulp');
const { build } = require('@justeat/gulp-build-fozzie');

build(gulp, /*options*/);

You can optionally pass in options which will override the default config values.

That's it! You can now run any of the Gulp tasks.

Optional setup

Transpile es2015 code

To ensure that the scripts:bundle task can transpile es2015 code, add the babel-preset-es2015 preset to the project:

yarn add babel-preset-es2015

Then add a .babelrc file, with the babel-preset-es2015 preset, to the root of your project:

{
    "presets": ["es2015"]
}

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.

JavaScript Linting

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 task:

{
    "extends": "@justeat/eslint-config-fozzie"
}

If you wish to extend or override these rules you can simply add them after the extends line in the .eslintrc file.

For more information on how you can configure eslint check out the documentation.

CSS Linting

To use our recommended fozzie stylelint linting rules add the following into your package.json file:

"stylelint": {
    "extends": "@justeat/stylelint-config-fozzie"
}

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.

Config and pathBuilder

You can also access the config and pathBuilder objects which are used inside of gulp-build-fozzie by requiring them:

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 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 section below for details on which paths are available.

The Gulp Tasks

css

Runs the following tasks

  • scss:lint

    Lint all SCSS files in the source directory — this runs before the css:bundle task.

  • css:lint

    Lint all CSS files in the dist directory — this runs after the css:bundle task.

  • clean:css

    Removes any CSS already in the dist directory.

  • clean:assets

    Removes any imported assets in the imported assets directory.

  • copy:assets

    Copies assets from packages to the imported assets directory.

  • css:bundle

    Performs a variety of tasks including;

    • Pull in Eyeglass modules
    • Run postcss plugins
    • Minify the CSS
    • Add hashed version to file name
    • Output bundle to the dist directory

scripts

Runs the following tasks

  • scripts:lint

    Lint all JavaScript in the source directory.

  • scripts:test

    Runs any unit tests found in the JavaScript source directory using Jest.

  • clean:scripts

    Removes any JavaScript already in the dist directory.

  • scripts:bundle

    Performs a variety of tasks including;

    • ES2015 transpilation using Babel
    • Bundle all code into a single file
    • Generate sourcemap files
    • Minify the JavaScript
    • Add hashed version to file name
    • Output bundle to the dist directory

images

Runs the following tasks

  • clean:images

    Removes any images already in the dist directory.

  • images:optimise

    Optimises all images found in the source directory then copies them to the dist directory.

  • images:svg-sprite

Generate an SVG sprite and copy into the dist directory

service-worker

Runs the following tasks

  • service-worker:locate

Discovers scripts in the service worker directory.

  • service-worker:copy

Copies the worker's internal scripts to the dist directory.

  • service-worker:write

Generates a service worker to pre-cache the assets defined in the config.

copy:js, copy:css, copy:img & copy:fonts

Each of these tasks copies the specified set of assets from the src to the dist asset folders.

See the config section for details on how to configure these tasks.

watch

Runs the default task then the following watch tasks.

  • watch:css

Runs the css task when a CSS file is changed.

  • watch:scripts

Runs the scripts task when a JavaScript file is changed.

  • watch:scripts:test

Runs the scripts:lint and scripts:test tasks when a JavaScript unit test file is changed.

  • watch:images

Runs the images task when an image file is changed.

watch:docs

Runs the same tasks as watch as well as the following watch tasks.

  • watch:docs:templates

Runs the assemble task when documentation files are changed.

Development only tasks

  • docs

This will build a fresh copy of any documentation found in the docs directory using Assemble, then call the watch task which will watch for any file changes, and finally call the browserSync:docs task which reloads the web page when changes are detected in the docs/dist directory.

  • clean:docs

Removes document files already in the docs dist directory.

  • browserSync:docs

Refreshes the browser when changes to the docs dist directory are detected.

  • assemble

Generates the documentation files.

Options

Here is the outline of the configuration options, descriptions of each are below.

{
    webRootDir,
    assetSrcDir,
    assetDistDir,
    css: {
        scssDir,
        cssDir,
        lintPaths,
        sourcemaps
    },
    js: {
        srcFile,
        jsDir,
        lintPaths,
        distFile,
        applyRevision
    },
    img: {
        imgDir,
        svgSpriteFilename
    },
    importedAssets: {
        importedAssetsDir,
        importedAssetsSrcGlob
    },
    sw: {
        isEnabled,
        swDir,
        outputFile,
        staticFileGlobs,
        dynamicFileRegex,
        dynamicFileStrategy,
        importScripts,
        cacheId
    },
    copy: {
        js,
        css,
        img,
        fonts
    },
    docs: {
        rootDir,
        srcDir,
        distDir,
        assetDir,
        templDir,
        dataDir,
        outputAssets,
        remoteBase,
        helpers
    },
    fonts: {
      fontsDir
    },
    misc: {
        showFileSize,
        showFiles
    },
    gulp: {
        changeEvent,
        onError
    },
    isProduction,
    isDev
}

webRootDir

Type: string

Default: '.'

The root directory of your website.

assetSrcDir

Type: string

Default: 'src'

Root source directory for your assets.

assetDistDir

Type: string

Default: 'dist'

Root dist directory for your assets.

css

  • scssDir

    Type: string

    Default: 'scss'

    The directory where your SCSS files reside.

  • cssDir

    Type: string

    Default: 'css'

    The bundled CSS file will be output to this directory.

  • lintPaths

    Type: array

    Default: ['']

    Allows additional paths to be included or excluded from the linting task.

    By default, the task will lint all .scss files within the scssDir directory.

  • sourcemaps

    Type: boolean

    Default: isDev

    Turns sourcemaps on or off.

js

  • srcFile

    Type: string

    Default: 'index.js'

    The filename for the entry point to your es2015 code.

  • jsDir

    Type: string

    Default: 'js'

    Name of the directory where your JavaScript files are kept.

    Compiled JavaScript files will be placed inside a directory with the same name.

  • lintPaths

    Type: array

    Default: ['']

    Allows additional paths to be included or excluded from the JS linting task.

    By default, the task will lint all files within the jsDir directory.

  • distFile

    Type: string

    Default: 'script.js'

The filename for the bundled JavaScript.

  • applyRevision

    Type: boolean

    Default: true

    Will add a content hash to the filename.

img

  • imgDir

    Type: string

    Default: 'img'

    Name of the directory where your image files are kept.

    Processed image files will be placed inside a directory with the same name.

  • svgSpriteFilename

    Type: string

    Default: 'sprite.svg'

    Filename of the SVG sprite which is generated from any SVG assets found in the image directory.

importedAssets

  • importedAssetsDir

    Type: string

    Default: 'imported-assets'

    Name of the directory where assets from node_modules will be copied to.

  • importedAssetsSrcGlob

    Type: string

    Default: 'node_modules/@justeat/*/'

    Glob of packages containing assets to be copied to importedAssetsDir.

sw

  • isEnabled

    Type: boolean

    Default: false

    Determines whether the service worker is generated or not.

  • swDir

    Type: string

    Default: 'sw'

    Name of the directory where your service worker's custom internal scripts are kept in.

    Scripts here will be placed inside a directory with the same name.

  • outputFile

    Type: string

    Default: 'service-worker.js'

    The name of the generated service worker file, to be placed in the root of your application.

  • staticFileGlobs

    Type: array

    Default: []

    The static files in your application to be cached by the service worker.

  • dynamicFileRegex

    Type: array

    Default: []

    An array of regex to match the dynamic content or API calls to cache e.g. [/^https:\/\/example\.com\/api/, /^https:\/\/fonts.googleapis.com\/css/].

  • dynamicFileStrategy

    Type: string

    Default: cacheFirst

    The cache strategy to be used for content matched by dynamicFileRegex - these correspond to the sw-toolbox handlers.

  • importScripts

    Type: array

    Default: []

    Any additional internal scripts to include, aside from those in swDir.

  • cacheId

    Type: string

    Default: ''

    An optional string used to differentiate caches on the same origin during local development.

copy

  • js, css img & fonts

    Type: Object

    Default: {}

    copy.js, copy.css, copy.img and copy.fonts each take an object list of assets in the format:

      copy:
        js: {
          prism: {
              path: '/libs/**/*',
              dest: '/libs',
              revision: false
          }
        }
      }

    In which:

    • path is a string specifying the path within the relevant asset src folder of the asset to be copied.
    • dest is a string specifying that destination folder for the asset to be copied to, within the relevant asset dist folder.
    • revision is a boolean such that if it is true, the asset will be revision hashed when copied to it’s destination.

    path and dest must always be defined for each asset you wish to copy.

    The object key (which in the above example is prism) of each asset is simply for your own use to identify each asset in your config.

docs

  • rootDir

    Type: string

    Default: './docs'

    Root directory where your documentation files reside.

    By default your source files will be searched for in docs/src, and the generated content will be output to docs/dist.

  • srcDir

    Type: string

    Default: 'src'

    The source directory for your documentation template files.

    By default the documentation task will use the path docs/src – with the src part of this path controlled by this config variable.

  • distDir

    Type: string

    Default: 'dist'

    The directory your documentation will be compiled to.

    By default the documentation task will use docs/dist – with the dist part of this path controlled by this config variable.

  • assetDir

    Type: string

    Default: 'assets/'

    The directory your generated assets will be placed inside the documentation directory.

    By default the documentation task will use docs/dist/assets/ – with the assets/ part of this path controlled by this config variable.

  • templDir

    Type: string

    Default: 'templates'

    The name of the directory where your documentation template files are kept.

  • dataDir

    Type: string

    Default: 'data'

    The name of the directory where your documentation data files are kept.

  • outputAssets

    Type: boolean

    Default: false

    Indicates whether or not the JavaScript, CSS and image files should be placed into the docs/dist/assets/ directory.

  • remoteBase

    Type: string

    Default: ''

    Applies a base path to asset URLs when publishing documentation to Github pages. By default this is set to be an empty string.

  • helpers

    Type: object

    Default: { }

    Can pass in an object set of functions, which will be exposed in handlebars as helper functions in the documentation tasks when called using their object key.

    For example:

    {
      'toLowercase': (input) => { return input.toLowerCase(); }
    }

    Will expose the helper toLowercase so that using {{toLowercase name}} within a handlebars template will convert the handlebars string name to lowercase.

fonts

  • fontsDir

    Type: string

    Default: 'fonts'

    Name of the directory where your font files are kept.

misc

  • showFileSize

    Type: boolean

    Default: true

    Should file sizes be displayed when a task is run?

  • showFiles

    Type: boolean

    Default: true

    Should file names be displayed when a task is run?

gulp

  • changeEvent

    Type: function

    Event which fires when a file is modified.

  • onError

    Type: function

    Event which fires when an error occurs.

Other options

The following options are also present in the config but cannot be overridden.

  • isProduction

    Type: boolean

    Set to true when the --prod flag is passed.

  • isDev

    Type: boolean

    Set to the opposite value of isProduction

Path Builder

You can access the pathBuilder paths like this.

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'

  • importedAssetsDistDir

    Default: 'dist/imported-assets'

  • 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'

  • fontsSrcDir

    Default: 'src/fonts'

  • fontsDistDir

    Default: 'dist/fonts'