# Application bundler - webpack

⚠️ NOTE: webpack@5 is used by current version, and webpack@4 is used in balm-core@legacy (For related configuration, please refer to the corresponding webpack official documentation)

BalmJS will invoke analyzer, when you run npm run prod --report.

# scripts.entry

interface EntryObject {
  [name: string]: string | string[];
}

type BalmEntry = string | string[] | EntryObject;

scripts.entry: BalmEntry = ''

The entry point for the bundle.

When scripts.entry is EntryObject:

{ [key: string]: value: string }: Bundle one entry point per HTML page.
{ [key: string]: value: string[] }: Creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points.

🌰 For example:

module.exports = {
  scripts: {
    entry: {
      lib: ['vue', 'vue-router'],
      ui: ['balm-ui'],
      app: './app/scripts/main-page.js',
      subapp: './app/scripts/sub-page.js'
    }
  }
  // Other Options...
};

Then, your HTML templates:

<!-- Page One -->
<script src="%PUBLIC_URL%/scripts/vendor/lib.js"></script>
<script src="%PUBLIC_URL%/scripts/vendor/ui.js"></script>
<script src="%PUBLIC_URL%/scripts/app.js"></script>

<!-- Page Two -->
<script src="%PUBLIC_URL%/scripts/vendor/lib.js"></script>
<script src="%PUBLIC_URL%/scripts/vendor/ui.js"></script>
<script src="%PUBLIC_URL%/scripts/subapp.js"></script>

Tips: You can rename vendor with scripts.vendorName.

# scripts.library

scripts.library: string | object = ''

The name of the exported library. See webpack output.library (opens new window).

🌰 For v4 example:

module.exports = {
  scripts: {
    library: {
      name: 'AwesomeLibraryName',
      type: 'umd'
    }
  }
  // Other Options...
};

# scripts.libraryTarget (Deprecated in v4.0.0)

scripts.libraryTarget: string = 'var'

Configure how the library will be exposed. See webpack output.libraryTarget (opens new window).

🌰 For v3 example:

module.exports = {
  scripts: {
    library: 'AwesomeLibraryName',
    libraryTarget: 'umd'
  }
  // Other Options...
};

# scripts.loaders

scripts.loaders: RuleSetRule[] = []

An array of Rule (opens new window) automatically applied loaders.

BalmJS default loaders:

babel (opens new window)
style (opens new window)
css (opens new window)
postcss (opens new window)
html (opens new window)
url (opens new window) (Deprecated in v4.5.0)
file (opens new window) (Deprecated in v4.5.0)

List of loaders (opens new window)

🌰 For example:

First, install a loader:

yarn add -D vue-loader
# OR
npm i -D vue-loader

Then, use it:

const VueLoaderPlugin = require('vue-loader/lib/plugin');

module.exports = {
  scripts: {
    loaders: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      }
    ],
    plugins: [new VueLoaderPlugin()]
  }
  // Other Options...
};

# scripts.defaultLoaders

interface BalmLoaders {
  js?: boolean;
  css?: boolean;
  html?: boolean;
  url?: boolean; // For v3, deprecated in v4
  asset?: boolean; // New in v4
}

scripts.defaultLoaders: BalmLoaders = {}

Rename ~~disableDefaultLoaders~~ to defaultLoaders in 2.5.0

Enable/Disable BalmJS some default loaders.

# scripts.useEsModule

scripts.useEsModule: boolean = true

New in 2.23.0

Use ES modules syntax for the balm default loaders.

# scripts.includeJsResource

scripts.includeJsResource: string[] = []

(Absolute path) Supply a Rule.include (opens new window) option in babel-loader for some extra vendor scripts from local anywhere.

# scripts.excludeUrlResource (Deprecated in v4.5.0)

scripts.excludeUrlResource: string[] = []

New in 3.7.0

(Absolute path) Supply a Rule.exclude (opens new window) option in url-loader for images assets from local anywhere.

# scripts.babelLoaderOptions

scripts.babelLoaderOptions: object = {}

New in 3.9.6

The extra options of the balm default babel-loader. Reference options (opens new window).

# scripts.urlLoaderOptions (Deprecated in v4.5.0)

scripts.urlLoaderOptions: object = {}

New in 2.1.0

The extra options of the balm default url-loader. Reference options (opens new window).

🌰 For example:

module.exports = {
  scripts: {
    urlLoaderOptions: {
      esModule: false
    }
  }
  // Other Options...
};

Before, usage in your vue file:

<template>
  <img :src="require('@/assets/logo.png').default" />
</template>

Then, your can:

<template>
  <img :src="require('@/assets/logo.png')" />
</template>

# scripts.postcssLoaderOptions

interface PostcssLoaderOptions {
  exec?: boolean;
  postcssOptions?: object | Function;
  sourceMap: string | boolean;
}

scripts.postcssLoaderOptions: PostcssLoaderOptions = {}

Migrated from ~~styles.postcssLoaderOptions~~ in 2.11.0

PostCSS loader for webpack. Reference options (opens new window).

# scripts.htmlLoaderOptions

scripts.htmlLoaderOptions: object = {}

New in 2.11.0

The extra options of the balm default html-loader. Reference options (opens new window).

# scripts.imageAssetType

scripts.imageAssetType: 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' = 'asset'

New in 4.7.0

Asset module type.

# scripts.imageInlineSizeLimit

scripts.imageInlineSizeLimit: number = 8096

New in 4.7.0

If a module source size is less than maxSize then module will be injected into the bundle as a Base64-encoded string, otherwise module file will be emitted into the output directory.

# scripts.extensions

scripts.extensions: string[] = []

An array of extensions that should be used to resolve modules.

BalmJS default extensions:

🌰 For example:

module.exports = {
  scripts: {
    extensions: ['.vue']
  }
  // Other Options...
};

Before, usage:

// main.js
import foo from 'foo.vue';

Now, you can:

// main.js
import foo from 'foo';

# scripts.alias

scripts.alias: object = {}

Replace modules by other modules or paths.

🌰 For example:

module.exports = {
  scripts: {
    alias: {
      vue$: 'vue/dist/vue.esm.js'
    }
  }
  // Other Options...
};

# scripts.optimization

scripts.optimization: object = {}

Webpack optimizations for manual configuration and overrides. See webpack optimization (opens new window).

# scripts.plugins

scripts.plugins: Plugin[] = []

Add additional plugins to the compiler.

List of plugins (opens new window)

# scripts.nodeEnv

scripts.nodeEnv: object = {}

New in 4.7.0

Define the environment variables for process.env.

# scripts.injectHtml

scripts.injectHtml: boolean = false

New in 3.16.0

Auto inject scripts and generate html entry file. (By default, you need to manually create the HTML entry file.)

NOTE: Because the content of the <body> element of the default template is empty, so you must set a custom template by scripts.htmlPluginOptions.template for some SPA (e.g. Vue.js).

# scripts.htmlPluginOptions

scripts.htmlPluginOptions: object = {}

New in 3.16.0

Html plugin for webpack. Reference options (opens new window).

🌰 For example:

For SPA

module.exports = {
  scripts: {
    entry: {
      app: './app/scripts/main.js'
    }
  },
  injectHtml: true
  // Other Options...
};

For MPA

module.exports = {
  scripts: {
    entry: {
      'page-1': './app/scripts/p1.js',
      'page-2': './app/scripts/p2.js'
    }
  },
  injectHtml: true,
  htmlPluginOptions: {
    template: './app/templates/index.html'
    title: ['Page 1', 'Page 2']
  }
  // Other Options...
};

# scripts.extractCss

~~scripts.extractCss: { enabled: boolean; prefix: string; } for balm-core < 3.16.0~~

scripts.extractCss: boolean = false

Extract css from some bundle. (scripts.injectHtml = true required)

Just for production build

⚠️ TIPS: Separating styles from scripts for modular management is more conducive to project maintenance and expansion, See BalmJS advanced usage - Code Splitting.

# scripts.sourceMap

scripts.sourceMap: string | boolean = false

Source mapping. See webpack devtool (opens new window).

# scripts.target

v4: scripts.target: string | string[] = ['web', 'es5']
v3: scripts.target: string = 'web'

To target a specific environment. See webpack target (opens new window).

# scripts.externals

scripts.externals: string | object | Function | RegExp = ''

Provides a way of excluding dependencies from the output bundles. See webpack externals (opens new window).

# scripts.stats

scripts.stats: object | string

Capture timing information for each module. See webpack stats (opens new window).

v4 defaults to:

{
  colors: true,
  assets: true,
  children: false,
  chunks: false,
  modules: false
}

v3 defaults to:

{
  colors: true,
  chunks: false,
  chunkModules: false,
  modules: false,
  children: false
}

# scripts.webpackOptions

scripts.webpackOptions: object = {}

Full custom webpack configuration (opens new window).

# scripts.extractAllVendors

scripts.extractAllVendors: boolean = false

HTML template:

<!-- All vendors in one -->
<script src="%PUBLIC_URL%/scripts/vendor.js"></script>
<!-- Entry -->
<script src="%PUBLIC_URL%/scripts/main.js"></script>

Tips: You can rename vendor with scripts.vendorName.

# scripts.vendorName

scripts.vendorName: string = 'vendor'

(For SPA) AllInOne vendor filename or Vendors folder name.

# scripts.useCache (Deprecated in 3.19.0)

scripts.useCache: boolean = false

Rename ~~inject~~ to useCache in 3.16.0

Support the hash scripts in the SSR build.

# scripts.ie8

scripts.ie8: boolean = false

New in 2.2.0

Supporting Internet Explorer 8 and below (IE6-8). IE compatibility config.

⚠️ TIPS: In IE8 Object.defineProperty can only be used on DOM objects. This is unfortunate as it's required to set getters and setters. Due to this if you plan on supporting IE8 or below then the usage of getters and setters isn't recommended.

← Javascript Library bundler - rollup →