ct-mapapps-browser-sync

A support lib for browser-sync as development server.

Features:

• Middleware components for:
  • js-registry /resources/jsregistry/root
    • scan of src folders
    • scan of registry .jar files
    • scan of registry .zip files
    • scan bundles from npm_modules folder
  • Allow of json comments in manifest.json files
  • Filtering of @@key@@ expressions
  • Markdown to html support via js-registry
  • proxy forwards, e.g. /proxy?http://myserver.de/arcgis/rest/services

Usage

Within gulpfile.js call:

const gulp = require("gulp");
const mapappsBrowserSync = require("ct-mapapps-browser-sync");

const options = {};
mapappsBrowserSync.registerTask(options, gulp);

// after that the new task "browser-sync", "browser-sync-start" and "browser-sync-stop" are available

// e.g. special watch goal:

gulp.task("srv-watch",
    gulp.parallel(
        "watch",
        "browser-sync"
    ));

Configuration

The following shows possible options, and the default values:

{
    // default, directories, served by browsersync
    directories : ["./target/webapp", "./target/test-classes"],

    // reload is handled externally
    externalReloadTrigger: false,

    // looks for changes in the directories and reloads the browsers automatically
    watchChanges: true

    // next free is used, note if the port is already used, it is incremented automatically, to the next free.
    port: undefined,

    // activate https protocol, generates a self signed certificate for "localhost"
    https: false,

    // opens the browser if true
    urlToOpen: true,

    // false will disable the browser sync ui for additional features
    ui: undefined,

    // configuration of properties filtering
    // configuration options are read from all directories from the file 'application.properties'
    properties: {
        // Specifies path regex matchers, where @@key@@ expressions should be filtered
        // Default paths matches see /src/propertiesfilter.js
        paths: [
            /^\/sample.html$/
        ],
        config: {
            // Key-value pairs of mapapps properties, e.g.
            // "esri.api.arcgisPortalUrl": "https://dev0303w.conterra.de/portal"
        }
    },
    json: {
        // by default comments are stripped from json
        stripComments : true, 
        // would enable support of jsonp, e.g x.json?callback=method
        jsonpSupport : false 
    },
    jsreg: {
         // folder from where the bundle jars are imported
        importFolder = "target/bundle-imports/",
        // src folder from where local bundles are imported
        srcFolder = "target/webapp/js",
        // url where the srcFolder is served
        srcWebBase = "/js",
        // glob patterns to ignore in srcFolder
        // e.g. ignorePattern: ["**/sample/**"],
        ignorePattern = [],
        // modules directly imported from npm_modules folder
        // see section "modules from npm"
        npmModules = [],
        // location of npm directory
        // default is node_modules from which this lib is imported.
        // e.g:
        npmDir : __dirname + "/node_modules/",
    },
    // additional references to custom middleware files
    // e.g. middleware: [__dirname + "/src/test/js/myMiddleware.js"]
    middleware: []
}

NPM Modules as bundles

The config option jsreg.npmModules allows the import of custom bundles from NPM into the jsregistry middleware. Note the bundles or javascript files, need to support AMD or UMD, to be loaded into the browser.

This shows a concrete sample, how this feature can be used. The imported modules, need to be listed as devDependencies in the package.json.

jsreg: {
    npmModules: [
        [
            "chai",
            {
                // need to overwrite to ensure import "chai" is working
                main: "chai"
            }
        ],
        "mocha",
        "@conterra/mapapps-mocha-runner",
        [
            "@vue/test-utils",
            {
                // need to overwrite main to load it into the browser
                main: "dist/vue-test-utils.umd"
            }
        ],
        // required as peer dependency of @vue/test-utils
        "vue-template-compiler"
    ]
}

Custom middleware

The config option middleware allows the registration of additional middleware scripts. See browser-sync docu.

Note you need to list custom middleware as scripts, e.g. middleware: [__dirname + "/src/test/js/myMiddleware.js"]. This is required because the DevServer is started in a custom Worker-Thread to be independent of additional gulp tasks.