conFlux

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

Table of Contents

• conFlux
  • Table of Contents
  • Usage
    • Declaring Dependencies
    • Executing the Tool
      • Arguments
      • Options
  • Installation
    • dotnet tool
    • NPM

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 |

Installation

This tool can either be installed as a dotnet tool or as an NPM package. Please make sure that you only install it via one of these two methods.

dotnet tool

This tool can be installed as a dotnet tool from the ConNuget Artifacts Feed via the following command:

dotnet tool install -g conflux

NPM

This tool can be installed as an NPM package via the following command:

npm install -g conflux