Necromancers Playing MTG

    @bloomreach/frontend-build

    11.2.0-beta-2 • Public • Published

    READ FIRST

    This package, although published as a public package, is only meant to be used internally at Bloomreach. We offer no support whatsoever to anyone outside Bloomreach.

    Frontend Build

    Frontend build system for frontend apps at Bloomreach. Features:

    • Linting, compiling and optimizing of ES2015+, TypeScript and Sass (scss) files
    • Specific support for Angularjs apps.
    • Run unit tests using the Karma Test Runner and Jasmine framework
    • Provide text-summary and html coverage reports over original source code
    • Loading of html, svg, images and fonts
    • Provide sourcemaps to original source code

    Changelog

    Release notes are found in the changelog.

    Frontend Build release steps

    We use release-it to release to @bloomreach. A config file is included with preset configuration options.

    Examples of commands:

    • Release new minor version: npm run release-it -- --increment=minor
    • Release new pre-release under a npm tag: npm run release-it -- --increment=prerelease --prereleaseId="[relevant prerelease] --npm.tag=["relevant npm tag"]"
    • Non-interactive mode patch version publish: npm run release-it -- --non-interactive

    The default commit message is set to "TRIVIAL Release %s" where %s will be substituted with the release version. If you need to customize the commit message, you can use the --src.commitMessage argument.

    Setup

    All tools used (Webpack, Karma, Babel, TypeScript, ESLint, TSLint and Stylelint) will look for a configuration file in the folder where your package.json is stored and then in the frontend-build package. Frontend-build ships with default setup files for these tools and does not require the project to extend these files.

    Webpack

    To override default webpack configuration create a file named webpack.config.js (or webpack.config.[environment].js) with the following contents:

    const merge = require('webpack-merge');
    const config = require('@bloomreach/frontend-build/lib/webpack.config');
    const sass = require('@bloomreach/frontend-build/lib/webpack/rules/sass');
    
    module.exports = merge(config, {
      entry: 'src/index.js',
      module: {
        rules: [
          {
            ...sass,
            loader: 'null-loader',
          }
        ]
      },
    });

    Karma

    To override default webpack configuration create a file named karma.conf.js with the following contents:

    const feConfig = require('@bloomreach/frontend-build/lib/karma.conf');
    
    module.exports = (config) => {
      feConfig(config);
    
      config.set({
        files: ['src/index.js'],
      });
    };

    Babel

    Create a file named .babelrc with the following contents:

    {
      "extends": "./node_modules/@bloomreach/frontend-build/.babelrc"
    }

    TypeScript

    Since 9.0.0 TypeScript code is compiled using Babel. This is faster (no type-checking) and simplifies the build pipeline. But, type-checking is why people use TypeScript, so to handle this a tsconfig.json file is provided that can be used together with the TypeScript compiler to only do the type-checking (it does not emit).

    To use it, create a file named tsconfig.json with the following contents:

    {
      "extends": "./node_modules/@bloomreach/frontend-build/tsconfig.json",
      "include": [
        "src"
      ],
    }

    Note: the project's source folder src has been configured as the entry point for the TypeScript compiler. By default it uses the project's root folder.

    To execute the TypeScript compiler, add the following two NPM scripts entries:

    ESLint

    Create a file named .eslintrc with the following contents:

    {
      "root": true,
      "extends": "./node_modules/@bloomreach/frontend-build/.eslintrc"
    }

    To execute ESLint, add the following NPM scripts entries:

    Note: It is also possible to enable caching for ESLint, which improves performance. It is recommended to only enable caching for development purposes. Caching is enabled by adding the --cache flag.

    TSLint

    Create a file named tslint.json with the following contents:

    {
      "extends": "./node_modules/@bloomreach/frontend-build/tslint.json"
    }

    StyleLint

    Create a file named .stylelintrc with the following contents:

    {
      "extends": "./node_modules/@bloomreach/frontend-build/.stylelintrc"
    }

    Note: It is also possible to enable caching for StyleLint, which improves performance. It is recommended to only enable caching for development purposes. Caching is enabled by adding the --cache flag.

    Running frontend-build tasks

    Frontend-build provided basic command-line interface. It can be used either via npx or NPM scripts.

    npx febuild <task> [options]
    
    "scripts": {
        "build": "febuild build",
        "build:debug": "febuild build:debug",
        "build:dev": "febuild build:dev",
        "build:dll": "febuild build:dll",
        "build:profile": "febuild build:profile",
        "clean": "febuild clean",
        "clean:lint:css": "febuild clean:lint:css",
        "clean:lint:js": "febuild clean:lint:js",
        "dev:all": "febuild dev:all",
        "lint": "febuild lint",
        "lint:css": "febuild lint:css",
        "lint:css:watch": "febuild lint:css:watch",
        "lint:fix": "febuild lint:fix",
        "lint:fix:watch": "febuild lint:fix:watch",
        "lint:js": "febuild lint:js",
        "lint:js:watch": "febuild lint:js:watch",
        "lint:watch": "febuild lint:watch",
        "ts": "febuild ts",
        "ts:watch": "febuild ts:watch",
        "start": "febuild start",
        "start:debug": "febuild start:debug",
        "start:dist": "febuild start:dist",
        "start:friendly": "febuild start:friendly",
        "test": "febuild test",
        "test:friendly": "febuild test:friendly",
        "test:debug": "febuild test:debug",
        "test:once": "febuild test:once"
    },

    Here is a complete list of supported tasks:

    Task Description
    build Production build
    build:debug Build debugging
    build:dev Development build
    build:dll Generate DLL manifest
    build:profile Profiling build process
    clean Clean build cache
    clean:lint:css Clean CSS linter cache
    clean:lint:js Clean ESLint cache
    dev:all Run developement build, linters, and tests in watch mode
    lint CSS and JS linting
    lint:watch CSS and JS linting watch mode
    lint:fix Try to fix linter error
    lint:fix:watch Try to fix linter errors on change
    lint:css CSS linting
    lint:css:watch CSS linting watch mode
    lint:js JS linting
    lint:js:watch JS linting watch mode
    ts TypeScript compiler
    ts:watch TypeScript watcher
    start Run developement server
    start:debug Run development server in debug mode
    start:dist Run developement server for production build
    start:friendly Run development server with friendly output
    test Run project's test suite
    test:friendly Run project's test suite with friendly output
    test:debug Run project's test suite in debug mode
    test:once Run project's test suite and exit

    Options

    You can use the following options as follows: npm run <task> -- --<option1> --<option2>

    CLI option Default value Description
    analyze false Visualize size of webpack output files with an interactive zoomable treemap. Uses webpack-bundle-analyzer.
    cache false Provides an intermediate caching step for modules, speeds up subsequent builds. Uses HardSourceWebpackPlugin.
    color cliHasColorSupport Enables or disables colored output. By default, colors are enabled when the terminal supports it.
    debug false Show debug information.
    dll false Enables Webpack's DLL-plugin to speed up rebuilds in watch mode. Note that prior to running with the -dll option you should generate the DLL files with npm run buildDll.
    friendly false Clean webpack output using the @nuxtjs/friendly-errors-webpack-plugin. Clears the console in dev/test mode when recompiling.
    profile false Add timing information to the build. Needs the --verbose option al well to print all relevant information.
    progress false Display a progress indicator.
    verbose false Detailed build output. When used in combination with the --debug option it will also output the aggregated frontend-build configuration and Webpack stats configuration.

    Webpack DLL's

    To improve the build speed for tests, we provide the possibility to use the Webpack DLL plugin. In short, this will ensure only our own sources are packaged, and external modules (like angular) will simply be included from node_modules.

    To use the DLL setup, we first need to generate the DLL manifest(s): npx run febuild build:dll This will generate a manifest JSON file with a related bundle javascript file. Now you can run the tests with DLL's: npx febuild test -- --dll

    Note: by default, all dependencies in your package.json file are bundled into a single DLL. To have more finegrained control (change order, exclude modules, etc) you can override entrypoint in your webpack.config.dll.js file, e.g.

    const config = require('@bloomreach/frontend-build/lib/webpack.config');
    
    module.exports = {
      ...config,
      entry: {
        angularjs: [
          'angular',
          'angular-animate',
        ],
        angular: [
          'core-js',
          'hammerjs',
          'es6-shim'
        ]
      }
    }

    Webpack special loader rules

    • SVGs located in images/html/ are loaded as strings so they can be used inline
    • Sass files in styles/string are loaded as strings so they can be used inline
    • Sass files for Angular apps following the convention *.component.scss will be loaded as strings so they can be used inline

    Testing

    Loading HTML, CSS and JSON fixtures

    The default Karma setup of frontend-build exposes the jasmine-jquery module for handling HTML, CSS and JSON fixtures, as well as provide a set of custom matchers that simplify validating DOM conditions, e.g. expect($('#id-name')[0]).toBeInDOM().

    Fixture files should be defined adjacent to the spec files that use them, or at least as close as possible. They follow the same naming convention as the spec files and are named with a .fixture suffix, e.g. cms.login.fixture.html or cms.config.fixture.json. Karma can be instructed to serve fixture files over it's HTTP-server by adding a file pattern to the files array in the project's karma.conf.js. The default pattern is saved in cfg.src.fixtures and matches { pattern: cfg.srcDir + '**/*.fixture.+(js|html|css|json)', included: false}.

    Frontend-build instructs Karma by default to proxy the path /spec/javascripts/fixtures/ (which is the default fixtures path of jasmine-jquery) to /base/src/app/. This is a combination of Karma's base path for serving files over HTTP and the root folder where frontend-build expects your Angular code to live.

    When changing the karma options you can customize the proxy path with the following options:

    • override options.proxies in your karma.conf.js, then you will have to replicate these two configuration values:

      proxies: {
      '/spec/javascripts/fixtures/': '[your proxy path]',
      '/spec/javascripts/fixtures/json/': '[your proxy path]',
      },
    Example project setup and code
    |- src
      |- app
        |- main.js
        |- main.spec.js
        |- main.fixture.html
        |- main.fixture.json
        |- dialogs
          |- dialog.fixture.html
          |- dialog.fixture.css
          ..
    

    In main.spec.js you can then load your fixtures with:

    // Load html fixture into the DOM
    jasmine.getFixtures().load('main.fixture.html');
    // from a subfolder
    jasmine.getFixtures().load('dialogs/dialog.fixture.html');
    
    // load css fixture into the DOM
    jasmine.getStyleFixtures().load('dialogs/dialog.fixture.css');
    
    // Load JSON fixture object
    var jsonObject = jasmine.getJSONFixtures().load('main.fixture.json');

    For more control over the paths you can use the following snippet in your spec files:

    beforeEach(function () {
      jasmine.getFixtures().fixturesPath = 'base/spec/js/fixtures';
      jasmine.getStyleFixtures().fixturesPath = 'base/spec/css/fixtures';
      jasmine.getJSONFixtures().fixturesPath = 'base/spec/json/fixtures';
    });

    Keywords

    none

    Install

    npm i @bloomreach/frontend-build

    DownloadsWeekly Downloads

    110

    Version

    11.2.0-beta-2

    License

    Apache-2.0

    Unpacked Size

    90.3 kB

    Total Files

    48

    Last publish

    Collaborators

    • rameshbr
    • boudekerk
    • mgiusto
    • beetlerom
    • joerideg
    • abogaart
    • pcentgraf-bloomreach
    • mjmetter
    • michielrop
    • sshepelevich
    • jtsengyc
    • shekhar.kumar
    • vlets
    • stefmz
    • pauledwardsbloomreach
    • davidboyd1
    • br-mikedreynolds
    • tom.washek
    • drq
    • ricardomartins
    • ntrajkovski
    • bcanvural
    • lachire
    • brxm
    • glm-bloomreach
    • vaibhav.shukla
    • adesousa
    • hachok
    • shiva.dharavath
    • vkauryha