Gulp build tasks for use across Fozzie modules.
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.
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.
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.
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.
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.
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.
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.
Runs the following tasks
-
Lint 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).
-
Lint all CSS files in the dist directory — this runs after the
css:bundletask. -
Removes any CSS already in the dist directory.
-
Performs 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
Runs the following tasks
-
Lint all JavaScript in the source directory. This task will also attempt to automatically fix any rules via the ESLint
--fixflag. -
Runs any unit tests found in the JavaScript source directory using Jest.
-
Runs the JS unit tests and display a coverage report once complete.
-
Removes any JavaScript already in the dist directory.
-
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
Adds the server-side file required for the errorLogger to be inserted into the filesystem.
Runs the following tasks
-
Removes any images already in the dist directory.
-
Optimises all images found in the source directory then copies them to the dist directory.
-
Generate an SVG sprite and copy into the dist directory
It also runs the copy:img and copy:assets tasks.
Runs the following tasks
Discovers scripts in the service worker directory.
Copies the worker's internal scripts to the dist directory.
Generates a service worker to pre-cache the assets defined in the config.
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.
Runs the default task then the following watch tasks.
Runs the css task when a CSS file is changed.
Runs the scripts task when a JavaScript file is changed.
Runs the scripts:lint and scripts:test tasks when a JavaScript unit test file is changed.
Runs the images task when an image file is changed.
Runs the same tasks as watch as well as the following watch tasks.
Runs the assemble task when documentation files are changed.
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.
Builds the documentation and then pushes the dist directory to the gh-pages branch.
Pushes the documentation dist directory to the gh-pages branch.
Removes document files already in the docs dist directory.
Copies all of the images in the assets dist folder over to the docs dist folder.
Watches for changes to files and reloads a local website instance.
Generates the documentation files then opens the docs in a local server.
Generates the documentation files.
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
},
…
],
jsDir,
lintPaths,
usePackageVersion,
stripDebug
},
logger: {
dir,
file
},
img: {
imgDir,
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
}Type: string
Default: '.'
The root directory of your website.
Type: string
Default: 'src'
Root source directory for your assets.
Type: string
Default: 'dist'
Root dist directory for your assets.
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.
Type: String
Returns the current package version.
-
Type:
stringDefault:
'scss'The directory where your SCSS files reside.
-
Type:
stringDefault:
'css'The bundled CSS file will be output to this directory.
-
Type:
arrayDefault:
['']Allows additional paths to be included or excluded from the linting task.
By default, the task will lint all
.scssfiles within thescssDirdirectory. -
Type:
booleanDefault:
isDevTurns sourcemaps on or off.
-
Type:
booleanDefault:
falseWhen set to
truethis will bundle a versioned css file e.g'filename-[version].css'.
-
Type:
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:
-
Type:
stringDefault:
'index.js'The file path to a bundle entry point in your JavaScript.
-
Type:
stringDefault:
'script.js'The filename for the JavaScript bundle once compiled.
-
-
Type:
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.
-
Type:
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. -
Type:
booleanDefault:
falseWhen set to
truethis will bundle a versioned JS file e.g'filename-[version].js'. -
Type:
booleanDefault:
trueThis can also be controlled using the
--noStripDebugflag. When this flag is added,console.log()statements will not be removed for production builds.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.
-
Type:
stringDefault:
'js/shared'Name of the directory where your js error logger file will live.
-
Type:
stringDefault:
'js-error.js'Name of the error logger file.
-
Type:
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.
-
Type:
stringDefault:
'sprite.svg'Filename of the SVG sprite which is generated from any SVG assets found in the image directory.
-
Type:
stringDefault:
'node_modules/@justeat/*/'Glob of packages containing assets to be copied to
assetDistDir. -
Type:
booleanDefault:
'true'Whether to log the names of all assets being copied. Passed on to f-copy-assets.
-
Type:
booleanDefault:
falseDetermines whether the service worker is generated or not.
-
Type:
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.
-
Type:
stringDefault:
'service-worker.js'The name of the generated service worker file, to be placed in the root of your application.
-
Type:
arrayDefault:
[]The static files in your application to be cached by the service worker.
-
Type:
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/]. -
Type:
stringDefault:
cacheFirstThe cache strategy to be used for content matched by
dynamicFileRegex- these correspond to the sw-toolbox handlers. -
Type:
arrayDefault:
[]Any additional internal scripts to include, aside from those in
swDir. -
Type:
stringDefault:
''An optional string used to differentiate caches on the same origin during local development.
-
Type:
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. -
Copies assets from packages to the dist directory.
-
Type:
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. -
Type:
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. -
Type:
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. -
Type:
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. -
Type:
stringDefault:
'templates'The name of the directory where your documentation template files are kept.
-
Type:
stringDefault:
'data'The name of the directory where your documentation data files are kept.
-
Type:
booleanDefault:
falseIndicates whether or not the JavaScript, CSS and image files should be placed into the
docs/dist/assets/directory. -
Type:
stringDefault:
''Applies a base path to asset URLs when publishing documentation to Github pages. By default this is set to be an empty string.
-
Type:
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) => { return input.toLowerCase(); } }
Will expose the helper
toLowercaseso that using{{toLowercase name}}within a handlebars template will convert the handlebars stringnameto lowercase. -
Type:
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.
-
Type:
stringDefault:
'fonts'Name of the directory where your font files are kept.
-
Type:
arrayDefault:
[]List of paths to watch for changes. Accepts globs.
-
Type:
stringDefault:
''URL of local website instance.
-
Type:
numberDefault:
1000Wait for a specified window of event-silence (in milliseconds) before sending any reload events.
-
Type:
booleanDefault:
trueShould file sizes be displayed when a task is run?
-
Type:
booleanDefault:
trueShould file names be displayed when a task is run?
-
Type:
functionEvent which fires when a file is modified.
-
Type:
functionEvent which fires when an error occurs.
The following options are also present in the config but cannot be overridden.
-
Type:
booleanSet to
truewhen the--prodflag is passed. -
Type:
booleanSet to the opposite value of
isProduction. -
Type:
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.
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.
-
Default:
'src/scss' -
Default:
'dist/css' -
Default:
'src/js' -
Default:
'dist/js' -
Default:
'src/img' -
Default:
'dist/img' -
Default:
'dist/imported-assets' -
Default:
'.' -
Default:
'src/sw' -
Default:
'dist/sw' -
Default:
'./docs/src' -
Default:
'./docs/dist' -
Default:
'./docs/src/templates' -
Default:
'./docs/src/data' -
Default:
'./docs/dist/assets/' -
Default:
'./docs/dist/assets/css' -
Default:
'./docs/dist/assets/js' -
Default:
'./docs/dist/assets/img' -
Default:
'src/fonts' -
Default:
'dist/fonts'
To run the unit tests for the project run the yarn test script. To see the test coverage run the test:cover script.
![thunderliortest[bot] avatar](https://avatars.githubusercontent.com/u/29872114?v=4 "thunderliortest[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent