@connectiv-ms/conflux NPM

conFlux

A convergence or moving gathering of forces, people, or things. [1]

conFlux

Usage

conFlux is the first tool in the legacy JS Buildchain at connectiv. It will make sure, that all of the source files end up in the right output directory and resolve all valid Triple-Slash Directives in JS files that it finds along the way.

Merging is required to avoid issues with the unordered loading of webresources in dynamics. Scripts that require their dependencies to be loaded before they are executed may run into issues if the dependencies are not yet fetched. To counteract this, all dependencies are bundled together with the script in a single file.

The JavaScriptMerger also handles other webresource filetypes (e.g. .htm, .html and .css), which are simply copied to the output directory.

Declaring Dependencies

Inside of JS files, you can use Triple-Slash Directives like this:

/// <reference path="path/to/your/dependency.js"/>

If you need to include a triple-slash directive that does not need merging, you can add an ignoreMerge="true" attribute to the reference.

/// <reference path="path/to/your/dependency.js" ignoreMerge="true"/>

Be aware, that there are a couple of caveats:

You can only link to other JS files.
References will only be resolved in your root script, meaning that if you declare a reference inside of a script that is a dependency, it will not be resolved. There is an option (-recursiveResolution) to change this behavior after version 1.1.
Reference paths will by default be resolved according to the <SourceDirectory>. This behavior can be overridden with the option -relativeReferences. This may become the default going forward, after it has been proven, that this behavior does not cause unwanted breaking side-effects in legacy projects.

Executing the Tool

You can run the tool through a terminal using the following syntax

conflux <SourceDirectory> <OutputDirectory> [Options]

You may use arguments and options to alter the default behavior.

conflux ./Scripts/src ./Scripts/bin/ -v --recursiveResolution --relativeReferences
conflux --legacy

For using this tool in a script, direct execution via npm is recommended.

npx @connectiv-ms/conflux <SourceDirectory> <OutputDirectory> [Options]

Arguments

Argument	Position	Required	Description	Default
`<SourceDirectory>`	1	Optional	Path to folder where the script files are located. Only files in this folder are taken into account.Files in nested folders can only be addressed through references.	`Scripts`
`<OutputDirectory>`	2	Optional	Path to the folder where the output files should be placed.Be aware that using this argument makes the arguments with a lower position required.	`Scripts/bin/Debug/Debug`

Options

The tool does not necessarily need options to run, but if you need to override the default behavior, you can do so by supplying the options described in the table below. Some options offer a shorthand, which can be used via -x <value>. The full option name can be supplied via --fullName <value>. For boolean options, the value can be omitted.

Option	Shorthand	Type	Description	Default
`verbose`	`v`	`boolean`	Will print detailed information for each processed file if available.	`false`
`legacy`		`boolean`	In case the new version causes any issues, you can run the legacy v1.0 version instead.	`false`
`recursiveResolution`		`boolean`	By default, dependencies are only resolved for the top-level scripts. This flag enables the recursive resolution of dependencies.	`false`
`relativeReferences`		`boolean`	By default, dependencies are always resolved according to the `<SourceDirectory>`. Passing this flag, will base the resolution on the path of the currently processed file.This might change to default behavior if it can be proven that due to the single-level resolution this problem will never occur.	`false`