BuildItem

BuildItem is an independent configuration object that has 1-to-1 mapping to gulp task. Typically BuildItem is BuildConfig, but it can also be CleanerConfig or WatcherConfig object.

BuildConfig

Understanding BuildConfig object is be a starting point of learning gulp-tron. It is a configuration defining build process together with gulp task dependency hierarchy. There are pre-defiined set of properties, but users can add custom properties which can be used by the builder defined in it.

BuildConfig object is resolved when it is added to gulp-tron project. In the resolving process, gulp task and RTB(Runtime Builder) instance are created, and all the dependencies defined in BuildConfig.triggers and BuildConfig.dependencies are also resolved in right sequence. The RTB instance is effectively a gulp task function object that has all the data required to run the build process. It is passed as first argument to all the build functions.

interface BuildConfig {

name: string; // build name, mandatory field

builder?: BuilderType; // main build operations in various form: function, object, class, etc

src?: string | string[]; // source for build operation

dest?: string; // output(destination) directory of the build operation

order?: string[]; // input file(src) ordering

outFile?: string; // optional output file name

preBuild?: BuildFunction; // function to be executed before BuildConfig.builder

postBuild?: BuildFunction; // function to be executed after BuildConfig.builder

buildOptions?: Options; // buildConfig instance specific custom options

moduleOptions?: Options; // gulp module options

dependencies?: BuildSet; // buildSet to be executed before this build task

triggers?: BuildSet; // buildSet to be executed after this build task

watch?: string | string[]; // override default watch, 'src' if defined

addWatch?: string | string[]; // additional watch in addition to watch or default watch

clean?: string | string[]; // clean targets

flushStream?: boolean; // finish all the output streams before exiting gulp task

reloadOnChange?: boolean; // Reload on change when watcher is running. default is true.

verbose?: boolean, // print verbose messages

silent?: boolean, // depress informative messages

npmInstall?: string | string[]; // node packages to be installed by npm-auto-install option

}

BuildConfig data can be accessed by conf property of RTB instance.

conf.name

• type: string

Specifies the name of build configuration. It is the only mandatory property of BuildConfig. This also specifies the name of gulp task to be created. So, this name should be unique globally. To avoid potential name collision, each project can have prefix which is automatically prefixed to the names of BuildConfig objects when they are resolved.

conf.builder

• type: BuilderType
• default: () => {}

Executable which is the entry point of the gulp task to be created. Curently, following builder types are available.

BuilderType	Description
BuilderClassName	Class name of built-in builder classes or the name of custom class inherited from GBuilder class. }
BuildFunction	Function to be executed.
ExternalCommand	Object with external command and command line arguments.
GBuilder	Instance of Gbuilder or its deritive classes.
'cleaner'	Literal string 'cleaner' which means built-in in Clearner
'watcher'	Literal string 'watcher' which means built-in Watcher.

Refert to Builder section for details.

conf.src

• type: string | string[]
• default: undefined

Glob path or array of glob paths that are referencing source files. rtb.src() creates gulp stream with this property. If no src specified, then no gulp stream is created.

conf.dest

• type: string
• default: process.cwd()

Output directory path. rtb.dest() writes the stream to the path sppecified in this property.If no value is specified, current process directory is used as output directory.

conf.order

• type: string[]
• default: undefined

Specifies the order of files in input stream. If conf.src is not specified, this is ignored. For file ordering, 'gulp-order' module is used.

As an example, ['file2.js','*.js'] specifies 'file2.js' to come first and all other '*.js' files to follow. Refer to the [gulp-order][1] site for the details.

conf.outFile

• type: string
• default: undefined

Output file name. This property can be optionally specified if some build process requires single output file name. For example, javascript builder can concatenate all the files in input stream into a single output file in the directory specified by conf.dest property.

conf.preBuild

• type: BuildFunction (See BuildFunction)
• default: undefiined

Specifies a build function that will be executed before conf.builder. The three major build sequence functions, conf.preBuild, conf.builder, conf.postBuild are executed in sequence regardless of syncMode status. All those three functions can return promise which will be waited before moving to next steps.

Example:

const styles = {

name: 'styles',

builder: 'GCSSBuilder',

postBuild: rtb => rtb.copy({src:[otherStyleFiles], dest: destPath});

};

conf.postBuild

• type: BuildFunction (See BuildConf.builder)
• default: undefiined

Specifies a build function that will be executed after conf.builder. The three major build sequence functions, conf.preBuild, conf.builder, conf.postBuild are executed in sequence regardless of syncMode status. All those three functions can return promise which will be waited before moving to next steps.

conf.buildOptions

• type: Options
• default: {}

type Options = { [key: string]: any; }

Custom options used by conf.builder. Each builder can have its options here. However, there are common options typically used in general build proceses. For the options with the same purpose, it is recommended to use the same option names even for custom builders.

For the options specific to each builders, you have to refer to the documentation of the builder.

Following is an example of common options generally used across the builders.

property	type	description
lint	boolean	Enable lint
minify	boolean	Generate minified output
minifyOnly	boolean	Generate minified output and does not generate non-minified output
sourceMap	boolean	Generate sourcemap files
postcss	boolean	Enable PostCSS
babel	boolean	Enable ES6/Babel transpiler
outFileOnly	boolean	Generate single output file specified in conf.outFile only
prettify	boolean	Prettify output (formatting)
printConfig	boolean	Print any relevant config files
tsConfig	string	path to typescript config file
webpackConfig	string	path to webpack config file

conf.moduleOptions

• type: Options
• default: {}

type Options = { [key: string]: any; }

Build operations typically use one or more gulp plugin modules. conf.moduleOptions property specifies the options to those modules. Each property name of conf.moduleOptions should be the same as the module name without 'gulp-' prefix. If module name has hyphens, then Camel Case should be used instead of the hyphens. For example, options for gulp-clean-css will be conf.moduleOptions.cleanCss. Options to gulp itself becomes conf.moduleOptions.gulp.

conf.dependencies

• types: BuildSet
• default: undefined

type BuildSet = BuildName | GulpTaskFunction | BuildItem | BuildSetSeries | BuildSetParallel;

type BuildSetSeries = BuildSet[];

type BuildSetParallel = { set: BuildSet[] };

Specifies other build configurations that will be executed before this build configuration in gulp task sequence. The dependencies can be any combination of build items in series or parallel. There is no limitation in the depth of dependency hierarchy. BuildSet is a recursive type which can have itself as its own dependendency.

Examples: assume there are 5 independent build items (configurations): b1, b2, b3, b4, b5

• conf.dependencies: tron.seres(b1, b2, tron.parallel(b3, b4, b5))
• conf.dependencies: [b1, b[2, tron.parallel([b3, b4], b5))]

Note that tron.series() can be replaced with []. So, tron.series(a, b) can be simply expressed as [a, b].

conf.triggers

• types: BuildSet
• default: undefined

Specifies other build items that will be executed after this build configuration, in gulp task sequence. All the others are the same as conf.dependencies.

conf.watch

• type: string | string[] | undefined
• default: undefined

Specifies watch target files that will be monitored by Watcher. Glob is supported. If this is not specified, conf.src is set as watch target of this configuration by default. To disable this automatic watching, set conf.watch to empty array, [].

conf.addWatch

• type: string | string[]
• default: undefined

Addional watch targets that will be added in addition to conf.watch or default watch target, conf.src. Glob is supported.

conf.clean

• type: string | string[]
• default: undefined

Specifies clean targets that will be removed by Cleaner. Glob is supported.

conf.flushStream

• type: boolean
• default: false

Normally, gulp task can be finished while the streams created during the build process are not finished yet. If conf.flushStream is set to true, the gulp taskwill not finish until all those streams are finished. For example, let assume task1 and task2 are configured to run in series, and task1 write a file and task2 access it. If task1 finishes and task2 starts when the file that task1 was writing is not finished, then task2 will fail to access the file during the build process. conf.flushStream option gurantees that the build task not to finish until all those file operations are finished.

conf.reloadOnChange

• type: boolean
• default: true

Enable reloading when changes in watch target is detected. Default value is ture. To disable automatic reloading on change, this property should be set to false exactly, not null or undefined.

conf.verbose

• type: boolean
• default: false

Enable extra message display.

conf.silent

• type: boolean
• default: false

Suppress non critical messages.

conf.npmInstall

• type: string | string[]
• default: undefined

List of modules to be automatically installed. The installation happens just before the build process starts. If auto-install option is not enabled, this option is ignoreed.

Refer to Automatic Module Installation for more details.

---

CleanerConfig

CleanerConfig is a special kind of BuildConfig, predefined to create cleaner task. Cleaner can be created by using BuildItem interface or using tron.addCleaner() function.

interface CleanerConfig extends Pick<BuildConfig, "clean">, CleanOptions {

name?: string; // optional build name. if undefined, defaults to '@clean'

builder: 'cleaner', // MUST be literal constant 'cleaner'

filter?: BuildNameSelector, // filter for build names (inside the project) to be cleaned

sync?: boolean; // syncMode option. refer to class RTB.

}

Example #1:

const tron = require('gulp-tron');

//-- using BuildItem interface

const scss = { name: 'scss', builder: 'GCSSBuilder', /* ... */ }

const cleaner = { builder: 'cleaner' } // buildItem with literal 'cleaner' as builder

tron.createProject({scss, cleaner});

//--- using gulp-tron API

tron.createProject({scss}).addCleaner(); // this is equivalent to tron.createProject({scss}).addBuildItem(cleaner);

Example #2:

const tron = require('gulp-tron');

// creates 3 cleaners: clean1, clean2, @clean

const clean1 = { name: 'clean1', builder: 'cleaner' }

const clean2 = { name: 'clean2', builder: 'cleaner', filter: [], clean: '*.dump' }

tron.createProject({clean1, clean2}).addCleaner();

conf.name

• type: string | undefined
• default: '@clean'

The same as BuildConfig.name except that it's optional. If not set, default name '@clean' is used as build name.

conf.builder

• type: 'cleaner'

The value for this should be set to literal string 'cleaner'.

conf.filter

• type: string | string[] | RegExp | RegExp[];
• default: undefined

Cleanerr task cleans all the clean targets of build configurations within the project by default. If you want to clean selective build configurations only, you can specify the build name filter here.

conf.sync

If set true, clean task does not finish until all the file operation (deleting) is finished.

---

WatcherConfig

WatcherConfig is a special kind of BuildConfig, predefined to create watcher task. Watcher can be created by using BuildItem interface or using tron.addWatcher() function.

interface WatcherConfig extends Pick<BuildConfig, "watch"> {

name?: string; // optional build name. if undefined, defaults to '@watch'

builder: 'watcher', // MUST be literal constant 'cleaner'

filter?: BuildNameSelector, // filter for build names (inside the project) to be watched

browserSync?: ReloaderOptions; // browserSync initializer options

livereload?: ReloaderOptions; // livereload initializer options

watch?: string | string[]; // additional watch targets

}

Example #1:

const tron = require('gulp-tron');

//-- using BuildItem interface

const scss = { name: 'scss', builder: 'GCSSBuilder', /* ... */ }

const watcher = { builder: 'watcher' } // buildItem with literal 'watcher' as builder

tron.createProject({scss, watcher});

//--- using gulp-tron API

tron.createProject({scss}).addWatch(); // Or, tron.createProject({scss}).addBuildItem(watcher);

conf.name

• type: string | undefined
• default: '@watch'

The same as BuildConfig.name except that it's optional. If not set, default name '@watch' is used as build name.

conf.builder

• type: 'watcher'

The value for this should be set to literal string 'watcher'.

conf.filter

• type: string | string[] | RegExp | RegExp[];
• default: undefined

Watcher task watches all the build configurations within the project by default. If you want to watch selective build configurations only, you can specify the build name filter here.

conf.browserSync

browserSync initializer options. Refer to browser-sync for the details. browser-sync is activated when this property is set properly and the project's watch target list is not empty.

conf.livereload

livereload initializer options. Refer to gulp-livereload for the details. livereload is activated when this property is set properly and the project's watch target list is not empty.