webpack-bundle-system

Synopsis

• No more gulp or grunt needed for this build tools system but you can integrate with them if you wish to do so.
• compiling frontend (react and jsx) and backend javascripts with es6 and flow syntax.
• compiling sass, css
• automically running unit tests that have been writen in es6 syntax. Under the cover it uses the mocha and nyc to run test and code coverage correspondingly.
• configurable to generate the bundling stats analysis json file and automatically open the browser to point to the html page which show all the insights of the bundles.
• It is a very flexible and extensible build tools that enable the modern javascript syntax such as es5, es6, es7 on both front end and backend and Reac Js with JSX ready. It internally uses webpack 2 (Tree-shaking ready), babel, mocha, nyc and node-sass with postcss. If you already familiar with these technologies you will find this build tools very extensible and flexible to use.
• By default the file structures will be as followings, so if you want to simplify your tasks a bit, just structure your project the same as below.

  rootProject is your root project folder.
  
  rootProject/client/js       // client sources.
  rootProject/scss/app.scss   // sass entry file.
  rootProject/index.js        // server es6 entry file.
  
  rootProject/client/dist/js  // client bundle source file, entry file name app.js
  rootProject/client/dist/css // css distribute folder which will contain app.css
  
  rootProject/es5.index.js    // bundled server entry es5 file.
  

## Notes: these are just the default technologies and configurations that the build tools currently using but again you can replace all or any of the implementations or configurations as needed.

Installation

$ npm install --save-dev webpack-bundle-system
or
$ yarn add webpack-bundle-system -D

Usage

• In your package.json you just need 3 or more npm script commands and again it is just our configuration but you can have more or less npm scripts as needed.

  $ yarn add babel-plugin-transform-flow-strip-types babel-preset-env -D
  or
  $ npm install --save-dev babel-plugin-transform-flow-strip-types babel-preset-env
  
  "scripts": {
    "test": "node_modules/.bin/babel-node --presets env --plugins transform-flow-strip-types tools/test",
    "build": "node_modules/.bin/babel-node --presets env --plugins transform-flow-strip-types tools/build",
    "dev": "node_modules/.bin/babel-node --presets env --plugins transform-flow-strip-types tools/dev",
    "start": "node es5.index.js"
  }
  

• The test.js will have its contents as follow.

  import {Builder} from 'webpack-bundle-system';
  import path from 'path';
  const builder:Builder = Builder;
  const processCWD:string = process.cwd();
  builder.initTestContext({
    testDir: path.resolve(processCWD, "test"), // Tell the test runner where all the unit tests are.
    clientWatchDir: path.resolve(processCWD),  // Tell the test runner to watch whatever changes in the directory and its sub directories to re-run all the tests (client tests)
    serverWatchDir: path.resolve(processCWD),  // Tell the test runner to watch whatever changes in the directory and its sub directories to re-run all the tests (server tests)
    checkLineCoverage: 0.0,       // Disable the code line coverage and don't fail the tests.
    checkStatementCoverage: 0.0,  // Disable the code statement coverage and don't fail the tests.
    checkFunctionsCoverage: 0.0,  // Disable the code function coverage and don't fail the tests.
    checkBranchesCoverage: 0.0    // Disable the code branch coverage and don't fail the tests.
  });
  const Bundler:ServiceBundler = builder.build(); // Wrap the bundler service object and then call any support functions you want and remember you can fluently call the functions.
  const runOptions:RunOption = {
    production: true, // this flag control the bundles of the css, js files.
    async: true,       // run them in parallel.
    msecStart: "250ms" // number of the milliseconds to delay to restart the runner when things change.
  };
  Bundler
    .runUnitTests(runOptions);
  

• The build.js will have its contents as follow.

  import {Builder} from 'webpack-bundle-system';
  const builder:Builder = Builder;    
  const Bundler:ServiceBundler = builder.build();
  const runOptions:RunOption = {
    production: true, // this flag control the bundles of the css, js files.
    async: true,       // run them in parallel.
    msecStart: "250ms" // number of the milliseconds to delay to restart the runner when things change.
  };
  Bundler
    .buildCss(runOptions)
    .buildBrowserJs(runOptions)
    .buildServerJs(runOptions);
  

• The dev.js will have its contents as follow.

  import {Builder} from 'webpack-bundle-system';
  import path from 'path';
  const builder:Builder = Builder;
  const processCWD:string = process.cwd();
  builder.initTestContext({
    testDir: path.resolve(processCWD, "test"), // Tell the test runner where all the unit tests are.
    clientWatchDir: path.resolve(processCWD),  // Tell the test runner to watch whatever changes in the directory and its sub directories to re-run all the tests (client tests)
    serverWatchDir: path.resolve(processCWD),  // Tell the test runner to watch whatever changes in the directory and its sub directories to re-run all the tests (server tests)
    checkLineCoverage: 0.0,       // Disable the code line coverage and don't fail the tests.
    checkStatementCoverage: 0.0,  // Disable the code statement coverage and don't fail the tests.
    checkFunctionsCoverage: 0.0,  // Disable the code function coverage and don't fail the tests.
    checkBranchesCoverage: 0.0    // Disable the code branch coverage and don't fail the tests.
  });
  const Bundler:ServiceBundler = builder.build();
  const runOptions:RunOption = {
    production: false, // this flag control the bundles of the css, js files.
    async: true,       // run them in parallel.
    msecStart: "250ms" // number of the milliseconds to delay to restart the runner when things change.
  };
  Bundler
    .buildCss(runOptions)
    .runUnitTests(runOptions)
    .runBrowserDevServer(runOptions)
    .runServerDevServer(runOptions);
  

• How to integrate with CI/CD in production?

  $ npm run build
  $ npm start
  

• How to run in the development mode?

  $ npm run dev
  

Override the file structures.

• As you see above that we only initialize the test context but you can initialize all the contexts to override the opinionated file structures. The followings are all the opinionated file structure has been initialized by default.

  import {Builder} from 'webpack-bundle-system';
  import path from 'path';
  const builder:Builder = Builder;
  let processCWD:string = process.cwd();
  builder.initClientContext({
    includeBundleStatsAnalyzer: true,  // configured to generate the insights of the bundles.
    includeGZipCompression: true,      // include the gzip version of the javascript bundles.
    publicRelativePath:"client/dist",
    clientDevServer: "http://localhost:8000",
    clientSourceDir: path.resolve(processCWD, "client"),
    clientDestinationDir: path.resolve(processCWD, "client", "dist"),
    cssName: "app.scss",
    clientJsEntry: "app.js"
  });
  
  serverContextStructure = {
    serverEntryDir: path.resolve(processCWD),
    serverJsSourceDir: path.resolve(processCWD),
    serverJsDestDir: path.resolve(processCWD),
    es5ServerJsEntry: "es5.index.js",
    es6ServerJsEntry: "index.js"
  };
  
  testContextStructure = {
    testDir: path.resolve(`${ processCWD }`, "test"),
    clientWatchDir: path.resolve(`${ this.clientContextStructure.clientSourceDir }`, "js"),
    serverWatchDir: path.resolve(`${ this.serverContextStructure.serverJsSourceDir }`),
    checkLineCoverage: 80.0,
    checkStatementCoverage: 80.0,
    checkFunctionsCoverage: 80.0,
    checkBranchesCoverage: 80.0
  };
  

• You can override any default by calling the following functions on the builder object before calling the build() function on the Builder to grab the ServiceBundler.

  builder.initClientContext(clientContextStructure).initServerContext(serverContextStructure).initTestContext(testContextStructure);
  

• Object builder contract.

  interface Builder {
    initContext(contextStructure:ContextStructure):Builder;
    initClientContext(clientContextStructure:ClientContextStructure):Builder;
    initServerContext(serverContextStructure:ServerContextStructure):Builder;
    initTestContext(testContextStructure:TestContextStructure):Builder;
    build():ServiceBundler;
  }
  

• Object service bundler contract

  interface ServiceBundler {
    buildBrowserJs(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    buildCss(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    buildServerJs(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    runUnitTests(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    runBrowserDevServer(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    runServerDevServer(runOption:RunOption, preRun:preRun, postRun:postRun):ServiceBundler;
    openBrowser(url:string, runOption:RunOption):ServiceBundler;
  }
  

• You can intercept any build steps above by injecting your callback functions to get called before and after the individual build process.

Override technologies

• Object contract processors.

  interface ConfigurationFilesCopier { copyConfigureFiles(runOption:RunOption):ConfigurationFilesCopier; }
  interface BrowserJsBundler { buildBrowserJs(runOption:RunOption):BrowserJsBundler; }
  interface ServerJsBundler { buildServerJs(runOption:RunOption):ServerJsBundler; }
  interface CssBundler { buildCss(runOption:RunOption):CssBundler; }
  interface BrowserDevServer { runBrowserDevServer(runOption:RunOption):BrowserDevServer; }
  interface ServerDevServer { runServerDevServer(runOption:RunOption):ServerDevServer; }
  interface UnitTestRunner { runUnitTests(runOption:RunOption):UnitTestRunner; }
  

• ServiceBundler's constructor can take all above processors and delegate any processing functions above to the corresponding processors.

  the module expose all the processors' constructors that you can import any of them to reuse and replace the rests of others as needed.

  import { ConfigurationFilesCopierConstructor,  // can be replaced with your implementation
           BrowserJsBundlerConstructor,          // can be replaced with your implementation
           ServerJsBundlerConstructor,           // can be replaced with your implementation
           CssBundlerConstructor,                // can be replaced with your implementation
           UnitTestRunnerConstructor,            // can be replaced with your implementation
           BrowserDevServerConstructor,          // can be replaced with your implementation
           ServerDevServerConstructor,           // can be replaced with your implementation
           ServiceBundlerConstructor } from 'webpack-bundle-system';
  let serviceBundler:ServiceBundler = new ServiceBundlerConstructor(
    new ConfigurationFilesCopierConstructor(),           // use to copy any configuration files needed to the consumer's project.
    new BrowserJsBundlerConstructor(contextStructure),   // process and bundle client source javascript files for browsers.
    new ServerJsBundlerConstructor(contextStructure),    // process and bundle service source javascript files for node.js server.
    new CssBundlerConstructor(contextStructure),         // process and bundle sass, css files for browsers.
    new UnitTestRunnerConstructor(contextStructure),     // process and run unit tests for both client and server source codes.
    new BrowserDevServerConstructor(contextStructure),   // development server (webpack dev server include hot replace module for React.js)
    new ServerDevServerConstructor(contextStructure));   // development server (watch all the server source files and restart servers when they are changed)
  };
  
  const runOptions:RunOption = {
    production: false, // this flag control the bundles of the css, js files.
    async: true,       // run them in parallel.
    msecStart: "250ms" // number of the milliseconds to delay to restart the runner when things change.
  };
  serviceBundler.buildBrowserJs(runOptions, () => {
    // pre executing this before processing the browser js.
  }, 
  () => {
    // post executing this after processing the browser js.
  });
  
  

  you can replace any implementation and use any technology you want by implementing the interface contract above and inject them into the service bundler.