justeatgulp-build-fozzie :bear:
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-fozzieNext, 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 a .babelrc file, with the @babel/preset-env preset, to the root of your project:
{
"presets": ["@babel/preset-env"]
}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.
N.b. You may also find that you get an error when adding eslint which reads Parsing error: Cannot read property 'ecmaFeatures' of undefined. If you see this message, then add this to your package.json followed by running yarn install:
"resolutions": {
"espree": "3.5.4"
}This is a temporary fix dependent on the progress of this issue open on ESLint.
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:lintLint all SCSS files in the source directory — this runs before the
css:bundletask.This task will also automatically fix any errors that it can (through stylelint's autofix setting).
css:lintLint all CSS files in the dist directory — this runs after the
css:bundletask.clean:cssRemoves any CSS already in the dist directory.
css:bundlePerforms a variety of tasks including;
- Makes environment variables available to Sass
- 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:lintLint all JavaScript in the source directory. This task will also attempt to automatically fix any rules via the ESLint
--fixflag.scripts:testRuns any unit tests found in the JavaScript source directory using Jest.
scripts:test:coverageRuns the JS unit tests and display a coverage report once complete.
clean:scriptsRemoves any JavaScript already in the dist directory.
Custom Tasks
The names of custom tasks can be passed into the config object to be run here. See
customTasksfor more details.
scripts:bundlePerforms 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
logger:createFile
Adds the server-side file required for the errorLogger to be inserted into the filesystem.
images
Runs the following tasks
clean:imagesRemoves any images already in the dist directory.
images:optimiseOptimises all images found in the source directory then copies them to the dist directory.
images:svg-spriteGenerate an SVG sprite and copy into the dist directory
It also runs the copy:img and copy:assets tasks.
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 & copy:docs
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
Builds a fresh copy of any documentation found in the config.docs.rootDir directory using Assemble, then watches for any file changes and reloads the web page when changes are detected in the config.docs.distDir directory.
docs:deploy
Builds the documentation and then pushes the dist directory to the gh-pages branch.
docs:release
Pushes the documentation dist directory to the gh-pages branch.
clean:docs
Removes document files already in the docs dist directory.
copy:img:docs
Copies all of the images in the assets dist folder over to the docs dist folder.
browser-sync
Watches for changes to files and reloads a local website instance.
browser-sync:docs
Generates the documentation files then opens the docs in a local server.
assemble
Generates the documentation files.
Config
Here is the outline of the configuration options, descriptions of each are below.
{
webRootDir,
assetSrcDir,
assetDistDir,
applyRevision,
packageVersion,
css: {
scssDir,
cssDir,
lintPaths,
sourcemaps,
usePackageVersion
},
js: {
files: {
main: {
srcPath,
distFile
},
…
],
customTasks,
jsDir,
lintPaths,
allowEmpty
usePackageVersion,
stripDebug
},
logger: {
dir,
file
},
img: {
imgDir,
optimiseImages,
optimiseSVGs,
optimiseGIFs,
optimiseJPEGs,
optimisePNGs,
spriteSvgs,
svgSpriteFilename,
},
importedAssets: {
importedAssetsSrcGlob,
verbose
},
sw: {
isEnabled,
swDir,
outputFile,
staticFileGlobs,
dynamicFileRegex,
dynamicFileStrategy,
importScripts,
cacheId
},
copy: {
js,
css,
img,
fonts,
docs
},
docs: {
rootDir,
srcDir,
distDir,
assetDir,
templDir,
dataDir,
outputAssets,
remoteBase,
helpers,
excludeTemplateDirs
},
fonts: {
fontsDir
},
browserSync: {
files,
proxy,
reloadDebounce
},
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.
applyRevision
Type: boolean
Default: true
Will add a content hash to the JS and CSS filenames, generating a new filename if any of the file's contents have changed. This can be utilised to force the clients to get the latest version of an updated asset.
packageVersion
Type: String
Returns the current package version.
css
scssDirType:
stringDefault:
'scss'The directory where your SCSS files reside.
cssDirType:
stringDefault:
'css'The bundled CSS file will be output to this directory.
lintPathsType:
arrayDefault:
['']Allows additional paths to be included or excluded from the linting task.
By default, the task will lint all
.scssfiles within thescssDirdirectory.sourcemapsType:
booleanDefault:
isDevTurns sourcemaps on or off.
usePackageVersionType:
booleanDefault:
falseWhen set to
truethis will bundle a versioned css file e.g'filename-[version].css'.
js
filesType:
ObjectDefault:
{ main: { srcPath: 'index.js', distFile: 'script.js' } }An Object, that takes one or more child objects each describing a JavaScript bundle entry point and destination. Each of these objects can have the following properties:
srcPathType:
stringDefault:
'index.js'The file path to a bundle entry point in your JavaScript.
distFileType:
stringDefault:
'script.js'The filename for the JavaScript bundle once compiled.
customTasksType:
array<string>Default:
[]Array of strings, containing the names of the custom tasks to be run as part of the
gulp:scriptscommand, in parallel withscripts:bundle.These should be defined by (or made available within) the consuming application, e.g., compiling third-party libraries within a
scripts:libstask.Gulp 4 does not easily allow for the entire default
gulp:scriptsimplementation to be overridden, so any extra JS-related tasks that you need to run should be passed in here.jsDirType:
stringDefault:
'js'Name of the directory where all of your JavaScript files are kept.
Compiled JavaScript files will be placed inside a directory with the same name.
lintPathsType:
arrayDefault:
['']Allows additional paths to be included or excluded from the JS linting task.
By default, the task will lint all files within the
jsDirdirectory.allowEmptyType:
booleanDefault:
trueWhen set to
true, it will allow the globbing patterns not to return any files without failing. If set tofalse, no files will result in an exception.usePackageVersionType:
booleanDefault:
falseWhen set to
truethis will bundle a versioned JS file e.g'filename-[version].js'.stripDebugType:
booleanDefault:
trueThis can also be controlled using the
--noStripDebugflag. When this flag is added,console.log()statements will not be removed for production builds.Examples:
gulp scripts:bundle --prod --noStripDebugThis would generate the JS files as part of a production build, but would still include
console.log()statements. Intended for QA releases.gulp scripts:bundle --prodThis is a normal production build and would not include
console.log()statements.gulp scripts:bundle --noStripDebugFor non-production builds, the flag has no effect: you will still get debug statements even if include the flag.
logger
dirType:
stringDefault:
'js/shared'Name of the directory where your js error logger file will live.
fileType:
stringDefault:
'js-error.js'Name of the error logger file.
img
imgDirType:
stringDefault:
'img'Name of the directory where your image files are kept.
Processed image files will be placed inside a directory with the same name.
optimiseImagesType:
booleanDefault:
'true'Controls whether or not all image typesare optimised as part of the image tasks.
optimiseSVGsType:
booleanDefault:
'true'Controls whether or not SVGs are optimised as part of the image tasks.
optimiseGIFsType:
booleanDefault:
'true'Controls whether or not GIFs are optimised as part of the image tasks.
optimiseJPEGsType:
booleanDefault:
'true'Controls whether or not JPEGs are optimised as part of the image tasks.
optimisePNGsType:
booleanDefault:
'true'Controls whether or not PNGs are optimised as part of the image tasks.
spriteSvgsType:
booleanDefault:
'true'Controls whether or not SVGs are turned into an SVG Sprite as part of the image tasks
svgSpriteFilenameType:
stringDefault:
'sprite.svg'Filename of the SVG sprite which is generated from any SVG assets found in the image directory.
importedAssets
importedAssetsSrcGlobType:
stringDefault:
'node_modules/@justeat/*/'Glob of packages containing assets to be copied to
assetDistDir.verboseType:
booleanDefault:
'true'Whether to log the names of all assets being copied. Passed on to f-copy-assets.
sw
isEnabledType:
booleanDefault:
falseDetermines whether the service worker is generated or not.
swDirType:
stringDefault:
'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.
outputFileType:
stringDefault:
'service-worker.js'The name of the generated service worker file, to be placed in the root of your application.
staticFileGlobsType:
arrayDefault:
[]The static files in your application to be cached by the service worker.
dynamicFileRegexType:
arrayDefault:
[]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/].dynamicFileStrategyType:
stringDefault:
cacheFirstThe cache strategy to be used for content matched by
dynamicFileRegex- these correspond to the sw-toolbox handlers.importScriptsType:
arrayDefault:
[]Any additional internal scripts to include, aside from those in
swDir.cacheIdType:
stringDefault:
''An optional string used to differentiate caches on the same origin during local development.
copy
js,cssimg,fonts&docsType:
ObjectDefault:
{}copy.js,copy.css,copy.img,copy.fontsandcopy.docseach take an object list of assets in the format:copy: js: { prism: { path: '/libs/**/*', dest: '/libs', revision: false } } }In which:
pathis a string specifying the path within the relevant assetsrcfolder of the asset to be copied.destis a string specifying that destination folder for the asset to be copied to, within the relevant assetdistfolder.revisionis a boolean such that if it istrue, the asset will be revision hashed when copied to its destination.
pathanddestmust always be defined for each asset you wish to copy (except forcopy:docswhich uses the rootdocsDistpath for thedest).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.copy:assetsCopies assets from packages to the dist directory.
docs
rootDirType:
stringDefault:
'./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 todocs/dist.srcDirType:
stringDefault:
'src'The source directory for your documentation template files.
By default the documentation task will use the path
docs/src– with thesrcpart of this path controlled by this config variable.distDirType:
stringDefault:
'dist'The directory your documentation will be compiled to.
By default the documentation task will use
docs/dist– with thedistpart of this path controlled by this config variable.assetDirType:
stringDefault:
'assets/'The directory your generated assets will be placed inside the documentation directory.
By default the documentation task will use
docs/dist/assets/– with theassets/part of this path controlled by this config variable.templDirType:
stringDefault:
'templates'The name of the directory where your documentation template files are kept.
dataDirType:
stringDefault:
'data'The name of the directory where your documentation data files are kept.
outputAssetsType:
booleanDefault:
falseIndicates whether or not the JavaScript, CSS and image files should be placed into the
docs/dist/assets/directory.remoteBaseType:
stringDefault:
''Applies a base path to asset URLs when publishing documentation to Github pages. By default this is set to be an empty string.
helpersType:
objectDefault:
{}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 => input.toLowerCase() }Will expose the helper
toLowercaseso that using{{toLowercase name}}within a handlebars template will convert the handlebars stringnameto lowercase.excludeTemplateDirsType:
arrayDefault:
['resources']Directory names which should be ignored when adding any shared templates to the documentation. By default the array contains known directory names which should be ignored.
fonts
fontsDirType:
stringDefault:
'fonts'Name of the directory where your font files are kept.
browserSync
filesType:
arrayDefault:
[]List of paths to watch for changes. Accepts globs.
proxyType:
stringDefault:
''URL of local website instance.
reloadDebounceType:
numberDefault:
1000Wait for a specified window of event-silence (in milliseconds) before sending any reload events.
misc
showFileSizeType:
booleanDefault:
trueShould file sizes be displayed when a task is run?
showFilesType:
booleanDefault:
trueShould file names be displayed when a task is run?
gulp
changeEventType:
functionEvent which fires when a file is modified.
onErrorType:
functionEvent which fires when an error occurs.
Other config
The following options are also present in the config but cannot be overridden.
isProductionType:
booleanSet to
truewhen the--prodflag is passed.isDevType:
booleanSet to the opposite value of
isProduction.lintModulesType:
booleanWhen set to true, by setting the
--lintModulesflag when running the build, the build will also lint SCSS files within sub-dependencies. This is intended to help with local development when using dependency linking.
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
scssSrcDirDefault:
'src/scss'
cssDistDirDefault:
'dist/css'
jsSrcDirDefault:
'src/js'
jsDistDirDefault:
'dist/js'
imgSrcDirDefault:
'src/img'
imgDistDirDefault:
'dist/img'
importedAssetsDistDirDefault:
'dist/imported-assets'
swOutputPathDefault:
'.'
swSrcDirDefault:
'src/sw'
swDistDirDefault:
'dist/sw'
docsSrcDirDefault:
'./docs/src'
docsDistDirDefault:
'./docs/dist'
docsTemplateDirDefault:
'./docs/src/templates'
docsDataDirDefault:
'./docs/src/data'
docsAssetsDistDirDefault:
'./docs/dist/assets/'
docsCssDistDirDefault:
'./docs/dist/assets/css'
docsJsDistDirDefault:
'./docs/dist/assets/js'
docsImgDistDirDefault:
'./docs/dist/assets/img'
fontsSrcDirDefault:
'src/fonts'
fontsDistDirDefault:
'dist/fonts'
Running the unit tests
To run the unit tests for the project run the yarn test script. To see the test coverage run the test:cover script.