js-build-tools

Centralize the build process for Node.js, JS and TypeScript projects into a single tool suite.

Goals

Using this tool suite, you can:

• Parse TypeScript into JS distribution files
• Create formatted distribution files to be used in a node / commonjs environment.
• Bundle your distribution files to be used in a browser environment.
• Run tests and watch for changes.
• Generate jsdoc readme files.

Installation

In your project's root directory, run: npm install --save-dev gulp js-build-tools (or yarn add --dev gulp js-build-tools if you use Yarn).

It is recommended to install gulp with the -g flag, so that you can run it with gulp instead of node_modules/.bin/gulp.

Configuration

In your project's root directory, create a build-tools.config.js file. This can contain any of the following (values provided are the defaults):

module.exports = {
  browser: {
    // 'true' to generate browser bundled files; 'false' for node environment only
    enabled: true,
    // The name to use for the browser-bundled output file (.js will be appended).
    name: 'my-package',
    // The search pattern used for retrieving compiled distribution files.
    from: 'dist/**/*.js',
    // The output directory for browser-bundled files.
    to: 'browser',
  },
  // The paths for directories to delete before build.
  cleanPaths: ['dist', 'browser'],
  dist: {
    // Name of the entry the distribution file.
    main: 'dist/main',
    // The search pattern used for gathering source files for distribution.
    from: 'src/**/!(*.test).js',
    // The output directory for the distribution files.
    to: 'dist',
  },
  fonts: {
    // Toggle copy directory of fonts on
    enabled: false,
    // Path to search for fonts
    from: 'src/fonts/**/*',
    // Path to output fonts
    to: 'browser/fonts',
  },
  images: {
    // Toggle image minify and copy process
    enabled: false,
    // Path to search for images
    from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
    // Path to output images
    to: 'browser/img',
  },
  readme: {
    // The file which will be pre-fixed to your README.md output.
    template: 'MAIN.md',
    // Options for formatting the output readme.
    options: 'utf8',
    // The name of the output documentation markdown file.
    file: 'README.md',
    // Location of files to use for compiling documentation into the readme.
    from: ['gulpfile.base.js', 'gulp.config.js', 'functions/**/!(*.test).js'],
    // The directory to output the readme file in.
    to: './'
  },
  // Base directory of the project.
  rootPath: './',
  sass: {
    // Toggle SASS to CSS process on.
    enabled: false,
    // The pattern for finding all sass files.
    from: 'sass/**/*.+(scss|sass)',
    // The directory were sass files will be stored.
    path: 'sass',
    // The destination path for where generated CSS (from SASS files) should go.
    to: 'browser/css',
  },
  // The directory where your source files are stored (the files you manually created).
  srcPath: 'src',
  test: {
    // Additional flags for programmatically running Jest Cli.
    options: null,
    // The directory where Jest test files are stored.
    // By default, stored as *.test.js adjacent to the files they are testing.
    path: ['src'],
    // The search pattern for watching files for changes.
    watch: 'src/**/*.js'
  },
  typescript: {
    // The path the tsconfig file for running typescript or false if no ts file given.
    config: false,
    // Toggle usage of typescript parsing.
    enabled: false,
    // Pattern for finding the TypeScript files.
    from: 'src/**/*.ts',
    // Directory where parsed typescript files go.
    to: 'dist',
  },
}

Create your local gulpfile.js

In your project's root directory, create a gulpfile.js file, in here you can require any of the functions you need. For example:

// Your local gulpfile.js
const {
  build,
  defaultCmd,
  partials,
  readme,
  sass,
  testFull,
  testQuick,
  typescript,
  watchFull,
  watchTest
} = require('js-build-tools')

// Everything you export will be created as a gulp task.
// You can build your own tasks here as well by using some of the functions `js-build-tools/functions`.
// You can list your available tasks by running `gulp --tasks`.
exports.build = build
exports.default = defaultCmd
exports.readme = readme
exports.sass = sass
exports.testFull = testFull
exports.testQuick = testQuick
exports.watchFull = watchFull
exports.watchTest = watchTest

Verify your tasks are available by running gulp --tasks.

Configure Babel

Depending on how you wrote your test files, Jest may require some Babel configuration. Create a babel.config.js file in the root directory of your project. You can then use the recommended configuration by requiring the babel.config.js file into your own configuration file. Example:

const babelConfig = require('js-build-tools/babel.config')
// You may add additional configuration here. Example: babelConfig.presets.push('@babel/preset-env')
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:

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 move fonts (optional)

Be able to copy a source directory of fonts into the distribution path.

Add the following to the exports in your build-tools.config.js:

module.exports = {
  fonts: {
    // Enable fonts process
    enabled: false,
    // Search pattern to find your font files
    from: 'src/fonts/**/*',
    // Output directory for your font files
    to: 'browser/fonts',
  }
}

Configure move and minify images (optional)

Be able to copy and reduce the file size of images into an output path.

Add the following to the exports in your build-tools.config.js:

module.exports = {
  images: {
    // Enable image process
    enabled: false,
    // Search pattern to find your images
    from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
    // Output directory for your images files
    to: 'browser/img',
  }
}

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:

module.exports = {
  sass: {
    // Enable SASS process
    enabled: false,
    // Search pattern to find your SASS files (the below would be files ending in .scss or .sass in a directory called 'sass')
    from: 'sass/**/*.+(scss|sass)',
    // Optional but nice to add (future support), add the directory where your sass files exist
    path: 'sass',
    // Output directory for your compiled css files, recommend css directory within your browser output directory
    to: 'browser/css',
  }
}

Configure TypeScript (optional)

Create a tsconfig.json file in your project root with the following:

{
  "files": [
    "src/**/*.ts"
  ],
  "compilerOptions": {
    "noImplicitAny": true,
    "target": "es6",
    "moduleResolution": "node",
    "declaration": true
  }
}

The pattern for "files" should match your .ts files, but the essential thing is that it is wrapped in an array. The actual pattern used comes from build-tools.config.js as 'typescript.from' setting. To create the ts declaration files, you must add the "declaration": true.

Add the following to the exports in your build-tools.config.js:

module.exports = {
  readme: {
    // Location of files to use for compiling documentation into the readme.
    from: 'dist/**/!(*.min).js',
  },
  typescript: {
    // The path the tsconfig file for running typescript or false if no ts file given.
    config: 'tsconfig.json',
    // Toggle usage of typescript parsing
    enabled: true,
    // Pattern for finding the TypeScript files
    from: 'src/**/*.ts',
    // Directory where parsed typescript files go
    to: 'dist',
  },
}

The js-to-markdown only works on .js files, so we run the readme search on the built dist files. Also, we want to register the tsconfig.json we created earlier and will alter the processes to build for TypeScript.

Update babel.config.js with the following:

const babelConfig = require('js-build-tools/babel.config')
// This is the important line, we need to add compatibility for Jest to run tests on .ts files
babelConfig.presets.push('@babel/preset-typescript')
module.exports = babelConfig

Configure Scripts

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",
    "watch:test": "gulp watchTest"
  }
}

Usage

Run any of the above commands with gulp or npm run.

Available functions documentation

Modules

js-build-tools

Export these functions to your own project in order to customize your build pipeline.

gulpConfig

Modify these configurations to match your project specifications.

testHelpers

Export the setUp helper.

partials

Micro-functions used as components for the main gulp functions.

js-build-tools

Export these functions to your own project in order to customize your build pipeline.

Version: 3.0.0
Author: Joshua Heagle joshuaheagle@gmail.com

• js-build-tools
  • .typeScript ⇒ function
  • .compileReadme ⇒ stream.Stream
  • .watchTest() ⇒ *
  • .watchFull() ⇒ FSWatcher
  • .testQuick() ⇒ Promise.<*>
  • .testFull() ⇒ Promise.<*>
  • .images() ⇒ stream.Stream
  • .distMinify() ⇒ *
  • .distLint() ⇒ *
  • .dist() ⇒ *
  • .defaultCmd([done]) ⇒ stream.Stream
  • .copyFonts() ⇒ stream.Stream
  • .bundleMinify() ⇒ *
  • .bundleLint() ⇒ stream.Stream
  • .bundle() ⇒ stream.Stream
  • .build() ⇒ stream.Stream

js-build-tools.typeScript ⇒ function

Simplified typescript task using tsFor.

Kind: static constant of js-build-tools

js-build-tools.compileReadme ⇒ stream.Stream

Generate the README.md file based off of the template, then append the generated documentation.

Kind: static constant of js-build-tools

js-build-tools.watchTest() ⇒ *

Watch for changes and run the tests.

Kind: static method of js-build-tools

js-build-tools.watchFull() ⇒ FSWatcher

Watch for changes and run the distribution for the changed files, then bundle and test the changed files.

Kind: static method of js-build-tools

js-build-tools.testQuick() ⇒ Promise.<*>

Run the Jest tests for files which have been modified (based on git status). Configure where tests are located by using 'testPath'.

Kind: static method of js-build-tools

js-build-tools.testFull() ⇒ Promise.<*>

Run all tests with jest. Configure where tests are located by using 'testPath'.

Kind: static method of js-build-tools

js-build-tools.images() ⇒ stream.Stream

Move and optimize the images into the browser folder using configured settings.

Kind: static method of js-build-tools

js-build-tools.distMinify() ⇒ *

Creates minified versions of the dist files.

Kind: static method of js-build-tools

js-build-tools.distLint() ⇒ *

Applies Standard code style linting to distribution files.

Kind: static method of js-build-tools

js-build-tools.dist() ⇒ *

Simplified distribution tasks which will use arguments from distFor.

Kind: static method of js-build-tools

js-build-tools.defaultCmd([done]) ⇒ stream.Stream

Recommended as the default task, runs the simple dist and bundle tasks.

Kind: static method of js-build-tools

Param	Type	Default
[done]	function

js-build-tools.copyFonts() ⇒ stream.Stream

Move the font files into the browser directory.

Kind: static method of js-build-tools

js-build-tools.bundleMinify() ⇒ *

Creates the minified bundle file.

Kind: static method of js-build-tools

js-build-tools.bundleLint() ⇒ stream.Stream

Applies Standard code style linting to bundled file.

Kind: static method of js-build-tools

js-build-tools.bundle() ⇒ stream.Stream

Starting at the distribution entry point, bundle all the files into a single file and store them in the specified output directory.

Kind: static method of js-build-tools

js-build-tools.build() ⇒ stream.Stream

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.

Kind: static method of js-build-tools

gulpConfig

Modify these configurations to match your project specifications.

Version: 3.0.0
Author: Joshua Heagle joshuaheagle@gmail.com

• gulpConfig
  • static
    • .get(path, defaultValue) ⇒ * | null
    • .set(path, value) ⇒ *
  • inner
    • ~ArrayableSetting : Array.<string> | string
    • ~BooleanSetting : boolean
    • ~FlagStringSetting : false | StringSetting
    • ~FlagsSetting : Object.<string, BooleanSetting>
    • ~JestTestFlags : FlagsSetting
    • ~StringSetting : string
    • ~Setting : ArrayableSetting | BooleanSetting | FlagsSetting | StringSetting
    • ~BrowserConfig : Object.<string, Setting>
    • ~DistConfig : Object.<string, Setting>
    • ~FontConfig : Object.<string, Setting>
    • ~ImageConfig : Object.<string, Setting>
    • ~ReadmeConfig : Object.<string, Setting>
    • ~SassConfig : Object.<string, Setting>
    • ~TestConfig : Object.<string, Setting>
    • ~TsConfig : Object.<string, Setting>
    • ~Configurations : Object.<string, Setting>

gulpConfig.get(path, defaultValue) ⇒ * | null

Retrieve a value from the configurations, default may be returned.

Kind: static method of gulpConfig

Param	Type	Default
path	string | null	null
defaultValue	*

gulpConfig.set(path, value) ⇒ *

Specify a value for the configurations to use.

Kind: static method of gulpConfig

Param
path
value

gulpConfig~ArrayableSetting : Array.<string> | string

A setting that may be an array of strings or a string only.

Kind: inner typedef of gulpConfig

gulpConfig~BooleanSetting : boolean

A setting that may be true or false.

Kind: inner typedef of gulpConfig

gulpConfig~FlagStringSetting : false | StringSetting

A setting that may be flag 'false' or provide a StringSetting

Kind: inner typedef of gulpConfig

gulpConfig~FlagsSetting : Object.<string, BooleanSetting>

An object of boolean settings used as flags.

Kind: inner typedef of gulpConfig

gulpConfig~JestTestFlags : FlagsSetting

Configure cli options for running Jest.

Kind: inner typedef of gulpConfig
Properties

Name	Type
clearCache	BooleanSetting
debug	BooleanSetting
ignoreProjects:	BooleanSetting
json	BooleanSetting
selectProjects	BooleanSetting
showConfig	BooleanSetting
useStderr	BooleanSetting
watch	BooleanSetting
watchAll	BooleanSetting

gulpConfig~StringSetting : string

A setting that may only be a string.

Kind: inner typedef of gulpConfig

gulpConfig~Setting : ArrayableSetting | BooleanSetting | FlagsSetting | StringSetting

Any single configuration option is a Setting.

Kind: inner typedef of gulpConfig

gulpConfig~BrowserConfig : Object.<string, Setting>

Configurations for building the browser files.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
enabled	BooleanSetting	'true' to generate browser bundled files; 'false' for node environment only
from	StringSetting	The name to use for the browser-bundled output file (.js will be appended).
name	StringSetting	The search pattern used for retrieving compiled distribution files.
to	StringSetting	The output directory for browser-bundled files.

gulpConfig~DistConfig : Object.<string, Setting>

Configurations for building the node distribution files.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
from	StringSetting	The search pattern used for gathering source files for distribution.
main	StringSetting	Name of the entry the distribution file.
to	StringSetting	The output directory for the distribution files.

gulpConfig~FontConfig : Object.<string, Setting>

Configurations for copying the font files.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
enabled	BooleanSetting	Toggle copy directory of fonts on.
from	StringSetting	Path to search for fonts.
to	StringSetting	Path to output fonts.

gulpConfig~ImageConfig : Object.<string, Setting>

Configurations to minify and copy the images.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
enabled	BooleanSetting	Toggle image minify and copy process.
from	StringSetting	Path to search for images.
to	StringSetting	Path to output images.

gulpConfig~ReadmeConfig : Object.<string, Setting>

Configurations to compile and generate the Readme file.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
file	StringSetting	The name of the output documentation markdown file.
from	StringSetting	Location of files to use for compiling documentation into the readme.
options	ArrayableSetting	Options for formatting the output readme.
template	StringSetting	The file which will be pre-fixed to your README.md output.
to	StringSetting	The directory to output the readme file in.

gulpConfig~SassConfig : Object.<string, Setting>

Configurations to compile and copy the sass files into css.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
enabled	BooleanSetting	Toggle SASS to CSS process on.
from	StringSetting	The pattern for finding all sass files.
path	StringSetting	The directory were sass files will be stored.
to	StringSetting	The destination path for where generated CSS (from SASS files) should go.

gulpConfig~TestConfig : Object.<string, Setting>

Configurations for running the test suite.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
options	JestTestFlags	Additional flags for programmatically running Jest Cli.
path	ArrayableSetting	The directory where Jest test files are stored. By default, stored as *.test.js adjacent to the files they are testing.
watch	ArrayableSetting	The search pattern for watching files for changes.

gulpConfig~TsConfig : Object.<string, Setting>

Configurations for compiling typescript into JS files.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
config	FlagStringSetting	The path the tsconfig file for running typescript or false if no ts file given.
enabled	BooleanSetting	Toggle usage of typescript parsing.
from	StringSetting	Pattern for finding the TypeScript files.
to	StringSetting	Directory where parsed typescript files go.

gulpConfig~Configurations : Object.<string, Setting>

A set of Configurations options defined by Settings.

Kind: inner typedef of gulpConfig
Properties

Name	Type	Description
browser	BrowserConfig	Browser bundling configuration group.
cleanPaths	ArrayableSetting	The paths for directories to delete before build.
dist	DistConfig	Distribution file generation configuration group.
fonts	FontConfig	Fonts copy configuration group.
images	ImageConfig	Minify and copy the images configuration.
readme	ReadmeConfig	Build readme files configuration.
rootPath	StringSetting	Base directory of the project.
sass	SassConfig	Compile CSS from SASS configuration.
srcPath	StringSetting	The directory where your source files are stored (the files you manually created).
test	TestConfig	Run test suite configuration.
typescript	TsConfig	Compile from typescript configuration.

testHelpers

Export the setUp helper.

Version: 3.0.0
Author: Joshua Heagle joshuaheagle@gmail.com

• testHelpers
  • .exports.createTempDir ⇒ Promise.<(*|void)>
  • .exports.beforeEach ⇒ Promise.<(*|void)>
  • .exports.afterEach ⇒ Promise.<*>
  • .setDefaults(testDir)

testHelpers.exports.createTempDir ⇒ Promise.<(*|void)>

Ensure that the del has completed, recursively attempt to delete and recreate

Kind: static property of testHelpers

Param	Type	Default
[exists]	boolean	true

testHelpers.exports.beforeEach ⇒ Promise.<(*|void)>

In the Jest.beforeEach function call this one to set up the temp directory.

Kind: static property of testHelpers

testHelpers.exports.afterEach ⇒ Promise.<*>

In the Jest.afterEach function call this one to clean up and remove the temp directory.

Kind: static property of testHelpers

testHelpers.setDefaults(testDir)

Update the gulp configurations with the test data. Set the test directory where temp files will be created for testing.

Kind: static method of testHelpers

Param	Type	Default
testDir	string	"test-temp"

partials

Micro-functions used as components for the main gulp functions.

Version: 3.0.0
Author: Joshua Heagle joshuaheagle@gmail.com

• partials
  • .tsFor([srcPath], [distPath]) ⇒ function
  • .sassFor([srcSearch], [cssPath]) ⇒ stream.Stream
  • .runOnChange(path) ⇒ stream.Stream
    • ~pathRegex
  • .removeDirectory(dirPath) ⇒ Promise.<*>
  • .readmeTemplate() ⇒ *
  • .minifyFor() ⇒ *
  • .imagesFor([imageSrc], [imageDest]) ⇒ stream.Stream
  • .distSeries([srcPath], [distFinalPath], [tsSearch]) ⇒ function
  • .distForSrc([useTs]) ⇒ string
  • .distFor([srcPath], [destPath]) ⇒ stream.Stream
  • .copyFor(srcPath, destPath) ⇒ stream.Stream
  • .clean() ⇒ Promise.<Array.<string>> | *
  • .beginWatcher() ⇒ FSWatcher
  • .addToReadme() ⇒ string | Uint8Array

partials.tsFor([srcPath], [distPath]) ⇒ function

Starting at the source directory, find all the ts files and convert them into the distribution directory.

Kind: static method of partials
See: https://www.typescriptlang.org/docs/handbook/gulp.html for more info

Param	Type	Default
[srcPath]	string | array	"''"
[distPath]	string	"''"

partials.sassFor([srcSearch], [cssPath]) ⇒ stream.Stream

Build the CSS for a given source pattern.

Kind: static method of partials

Param	Type	Default
[srcSearch]	string | array	"'src/config/path/sass/for'"
[cssPath]	string	"'css/config/path'"

partials.runOnChange(path) ⇒ stream.Stream

Run this function when the watched files are modified.

1. Find the sub-folders within src path
2. Maintain the folders, but use distPath for base
3. Remove base folder and return dist path with correct sub-folders

Kind: static method of partials

Param	Type
path	string

Example

// Configured paths
distPath = 'dist'
srcPath = 'functions'

// Path parameter
path = 'functions/some/path/file.js'

// Generated regex using configured srcPath
pathRegex = '/^functions(.*\/).+\.js$/i'

// Replace value using the configured distPath
replacePath = 'dist$1'

// The resulting replaced path for the destination folder
distPathResult = 'dist/some/path/'

runOnChange~pathRegex

1. The original path comes in from src and is a .ts
2. Discover the outgoing dist path where that file should go
3. Use the path and dist in tsFor
4. Take the original path, convert to full file path in dist
5. Use the dist path found previously in #2
6. Use the full dist path and the dist outgoing path in distFor

Kind: inner constant of runOnChange

partials.removeDirectory(dirPath) ⇒ Promise.<*>

Return a promise to be completed once the specified directory is deleted.

Kind: static method of partials

Param	Type
dirPath	string

partials.readmeTemplate() ⇒ *

Copy a readme template into the README.md file.

Kind: static method of partials

partials.minifyFor() ⇒ *

Minify files and rename the output with '.min' extension.

Kind: static method of partials

partials.imagesFor([imageSrc], [imageDest]) ⇒ stream.Stream

Move and optimize images into the browser directory.

Kind: static method of partials

Param	Type	Default
[imageSrc]	string | array	"src/images/pattern"
[imageDest]	string	"dest/image/folder"

partials.distSeries([srcPath], [distFinalPath], [tsSearch]) ⇒ function

When using TypeScript, ensure that we process the ts first then run babel (dist)

Kind: static method of partials

Param	Type	Default
[srcPath]	string	"'src/config/path/dist/for'"
[distFinalPath]	string	"'dist/config/path'"
[tsSearch]	string	"'ts/search/config/path'"

partials.distForSrc([useTs]) ⇒ string

Retrieve the correct distFor search path based on TS Config.

Kind: static method of partials

Param	Type	Default
[useTs]	FlagStringSetting	'config/for/ts'

partials.distFor([srcPath], [destPath]) ⇒ stream.Stream

Build the distribution for a given source pattern.

Kind: static method of partials

Param	Type	Default
[srcPath]	string | array	"'src/config/path/dist/for'"
[destPath]	string	"'dist/config/path'"

partials.copyFor(srcPath, destPath) ⇒ stream.Stream

Copy some files to a different location.

Kind: static method of partials

Param	Type
srcPath	string | array
destPath	string

partials.clean() ⇒ Promise.<Array.<string>> | *

Deletes all the distribution and browser files (used before create a new build). Configure array of directories to remove with 'cleanPaths'.

Kind: static method of partials

partials.beginWatcher() ⇒ FSWatcher

Create a chokidar instance which watches and triggers change when the globed files are modified.

Kind: static method of partials

partials.addToReadme() ⇒ string | Uint8Array

Appends all the jsdoc comments to the readme file. Assumes empty or templated file. Configure this with 'readmeSearch', 'readmePath', 'readmeFile', and 'readmeOptions'.

Kind: static method of partials