Configuration

This chapter describes in detail what configuration options you have to configure your build.

Build Multiple Templates

It is possible to configure and build multiple templates in one webpack.config.js file. Take a look at the following example:

const path = require('path');

const {BuildConfig, ModuleConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withPropertiesFilePath('properties.js')
    .withModules(
      new ModuleConfig()
        .withName('main')
        .withPath('main.js')),
  new BuildConfig()
    .withName('email')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'email'))
    .withPropertiesFilePath('properties.js'));

Legacy Design Format

You can build templates in the legacy design format by configuring the target version. To do so use the withTargetVersion(version) method on the BuildConfig object and pass your desired CX version by using one of the available Version constants.

const path = require('path');

const {BuildConfig, Version, DesignType, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('email')
    .withVersion('1.0.0')
    .withTargetVersion(Version.STUDIO_1_1)
    .withDesignType(DesignType.EMAIL)
    .withRootPath(path.resolve(__dirname, 'templates', 'email'))
    .withPropertiesFilePath('properties.js'));

You can also specify the design type by passing a DesignType constant to the withDesignType(type) method.

Hash ZIP Files

By default, the build creates ZIP files in the dist folder in the following format: landingpage-1.0.0-84eae.zip. The suffix 84eae is always five characters long and changes on each build. If you want to disable this behaviour you can disable it by passing false to the withHashZipFiles(enabled) method.

const path = require('path');

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('email')
    .withVersion('1.0.0')
    .withHashZipFiles(false)
    .withRootPath(path.resolve(__dirname, 'templates', 'email')));

Disable Source Maps

Source maps are a key requirement when it comes to debugging bundled code. That's why the build always creates source maps for all CSS and JavaScript assets. Keep in mind that this has a minor performance impact. Besides, source maps should not be included in production bundles.

To cope with this requirement, the build always creates two ZIP files: landingpage-1.0.0-84eae.zip and landingpage-1.0.0-dev-dcdbc.zip. The ZIP file with the dev infix may is significantly larger and contains also the source maps. To disable the source maps generation, you can pass false to the withSourceMapEnabled(enabled) method.

const path = require('path');

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withSourceMapEnabled(false)
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage')));

Bundle JavaScript Modules

You can configure additional JavaScript modules for your build. This is perhaps necessary when you're creating a larger web application based on React or Vue. By default, the JavaScript modules are located in the modules folder inside your templates root. To change the default modules root folder you can pass your desired path to the withModulesRootPath(path) method.

To add a module configuration you use the withModules(...modules) method and pass one or more ModuleConfig objects. Each ModuleConfig has a name and a path to the entry JavaScript file. Take a look at the following example:

const path = require('path');

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withModulesRootPath(path.resolve(__dirname, '..', 'my-modules'))
    .withModules(
      new ModuleConfig()
        .withName('app')
        .withPath('app.js')));

Change the Development Server Port

To change the development server port you can pass a TCP port number to the withDevServerPort(port) method. If you configure multiple templates to build, only the first configuration will be considered.

Add Webpack Rules and Plugins

It is possible to add your own rules and plugins to the Webpack configuration of your build. To do so use the withWebpackRules(...rules) and withWebpackPlugins(...plugins) methods. Be aware, that this can clash with the existing rules and plugins and lead to a broken build. More information about rule configuration can be found in the Webpack documentation.

Copy Additional Files

You can configure additional files to copy to your bundle. This will be done by the CopyWebpackPlugin. By default, the plugin is configured to copy all files and folders inside the assets folder located in your template root. You can also change default folder name using the withCopyAssetsFolderPath(path) method. But you can also pass additional patterns to the copy plugin constructor. Checkout the following example:

const path = require('path')

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withAdditionalFilesToCopy({
      from: path.resolve(__dirname, 'files', '**', '*'), // copy from <project root>/files/**/*
      to: 'files' // copy to <output folder>/files/**/* 
    })
);

Be aware, that it is better to reference files to bundle using require(file) or the ref loader rather than configure the copy plugin. Creating references to files has the advantage, that you don't have to care about correct URLs or file names. Webpack will do that for you.

Copy a Configuration

You can copy existing build configurations. This can be very handy when it comes to reusing and adopting existing build configs. To do so, invoke the clone() method on a BuildConfig object. Checkout the following example:

const path = require('path')

const {BuildConfig, WebpackConfigBuilder, Version, DesignType} = require('@bsi-cx/design-build');

let cxBuildConfig = new BuildConfig()
  .withName('landingpage-cx')
  .withVersion('1.0.0')
  .withTargetVersion(Version.CX_22_0)
  .withDesignType(DesignType.LANDINGPAGE)
  .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'));

let legacyBuildConfig = cxBuildConfig.clone()
  .withName('landingpage-studio')
  .withTargetVersion(Version.STUDIO_1_1);

module.exports = WebpackConfigBuilder.fromConfigs(cxBuildConfig, legacyBuildConfig);

The example above will produce two designs: One for BSI CX 22.0 and one for BSI Studio 1.1.

Customize the Assets Filename

By default, static assets are written to the static folder and contain the pathhash in the filename. The pathhas as hash built on the file location (incl. filename) of the file. In earlier versions of the design build, it used to be the contenthash of webpack. You can customize this behaviour using the withAssetResourceRuleFilename(assetResourceRuleFilename) method on a BuildConfig object. The method accepts a string with a custom file path. The internal default value equals to static/[name]-[pathhash][ext]. In order to be accepted, the assetResourceRuleFilename must contain [name], [ext] and one of the hashing routines ([pathhash] or [contenthash])

const path = require('path')

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withAssetResourceRuleFilename('static/[name]-[pathhash][ext]')
);

Add File Extensions for Static Assets

Static assets are matched by the file's extension. The following extensions are supported by default: avif, png , apng, jpg, jpeg, jfif, pjpeg, pjp, webp, gif, bmp, tiff, tif, raw, svg, eot, ttf, woff , woff2, pdf, ico, cur, mkv, 3gp, mp3, mp4, m4v, m4p, ogv, webm, aac, flac, mpg, mpeg , oga, ogg, wav, json5. You can extend the list by using the withAdditionalStaticAssetFileExtensions(...extensions) method on the BuildConfig object:

const path = require('path')

const {BuildConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withAdditionalStaticAssetFileExtensions('md', 'docx')
);