@ramster/webpack-tools

Webpack build and dev tools, part of the ramster open-source software toolkit.
This module provides a small toolkit for building and running bundles with webpack. It has both a javascript API and a CLI.

API

The javascript API contains 5 methods - build, buildFromFile, watch, watchFromFile and injectPluginsInConfig.
All examples below use the following config file.

build

This method takes a webpack configuration object and generates a webpack bundle for it.

	Name	Type	Description
@param (required)	webpackConfig	Webpack.Configuration	The config to be passed on to Webpack for building the bundle.
@returns		Promise	Resolves with true (boolean) when the bundle build is finished or rejects with the error thrown.

Example:

// main.js
const
	configData = require('./config'),
	{build} = require('@ramster/webpack-tools')

build(configData.webpackConfig).then(
	(res) => console.log('Build completed successfully with result:', res),
	(err) => console.error(err)
)

buildFromFile

This method takes a path to a file containing a webpack configuration object and executes webpack(config) for it, returning a promise.

	Name	Type	Description
@param (required)	configFilePath	string	The path to the file, containg the config to be passed on to Webpack for building the bundle.
@param (optional)	pluginsProfileName	string	The name of the plugins profile to be injected into the webpack config's plugins array.
@returns		Promise	Resolves with true (boolean) or rejects with the error thrown.

The file should be in the format

{
	profileWebpackPlugins?: { [profileName: string]: Webpack.Plugin[] },
	webpackConfig: Webpack.Configuration
}

Example:

// main.js
const
	{buildFromFile} = require('@ramster/webpack-tools'),
	path = require('path')

buildFromFile(path.join(__dirname, 'webpackConfig.js'), 'development').then(
	(res) => console.log('Build completed successfully with result:', res),
	(err) => console.error(err)
)

watch

This method takes a webpack configuration object and starts a webpack devserver for it.

	Name	Type	Description
@param (required)	webpackConfig	Webpack.Configuration	The config to be passed on to Webpack for building the bundle.
@param (required)	devserverConfig	{ hostName: string, port: number }	The HTTP config for the webpack devserver.
@returns		Promise	Resolves with true (boolean) when the devserver build has started successufully (not on build completion) or rejects with the error thrown.

Example:

// main.js
const
	configData = require('./config'),
	{watch} = require('@ramster/webpack-tools')

watch(configData.webpackConfig, configData.devserverConfig).then(
	(res) => console.log('Build completed successfully with result:', res),
	(err) => console.error(err)
)

watchFromFile

This method takes a path to a file containing a webpack configuration object and starts a webpack devserver for it.

	Name	Type	Description
@param (required)	configFilePath	string	The path to the file, containg the config to be passed on to Webpack for building the bundle.
@param (optional)	pluginsProfileName	string	The name of the plugins profile to be injected into the webpack config's plugins array.
@param (required)	devserverConfig	{ hostName: string, port: number }	The HTTP config for the webpack devserver.
@returns		Promise	Resolves with true (boolean) when the devserver build has started successufully (not on build completion) or rejects with the error thrown.

The file should be in the format

{
	devserverConfig: { hostName: string, port: number },
	profileWebpackPlugins?: { [profileName: string]: Webpack.Plugin[] },
	webpackConfig: Webpack.Configuration
}

Example:

// main.js
const
	{buildFromFile} = require('@ramster/webpack-tools'),
	path = require('path')

buildFromFile(path.join(__dirname, 'webpackConfig.js'), 'development').then(
	(res) => console.log('Build completed successfully with result:', res),
	(err) => console.error(err)
)

injectPluginsInConfig

Takes a webpack config and injects plugins into its "plugins" array. If the object doesn't have a "plugins" array, it will be created automatically.

	Name	Type	Description
@param (required)	config	Webpack.Configuration	The webpack config to inject the plugins in.
@param (required)	config	{ [profileName: string]: Webpack.Plugin[] }	The object containing the config-profile-specific plugin arrays.
@param (required)	configProfileName	string	The name of the config profile to inject the plugins for.
@returns		Promise	Resolves with true (boolean) when the bundle build is finished or rejects with the error thrown.

Example:

// main.js
const
	configData = require('./config'),
	{build, injectPluginsInConfig} = require('@ramster/webpack-tools')

configData.webpackConfig = injectPluginsInConfig(configData.webpackConfig, configData.profileWebpackPlugins, 'development')
build(configData.webpackConfig).then(
	(res) => console.log('Build completed successfully with result:', res),
	(err) => console.error(err)
)

exampleConfigFile

// config.js
const
	BellOnBundlerErrorPlugin = require('bell-on-bundler-error-plugin'),
	path = require('path'),
	ProgressBarPlugin = require('progress-bar-webpack-plugin'),
	webpack = require('webpack')

module.exports = {
	devserverConfig: { hostName: '127.0.0.1', port: 9999 },
	profileWebpackPlugins: {
		development: [
			new BellOnBundlerErrorPlugin()
		]
	},
	webpackConfig: {
		devtool: 'source-map',
		entry: [
			path.join(__dirname, 'src/index.ts')
		],
		output: {
			path: path.join(__dirname, 'dist'),
			filename: '[name].js',
			chunkFilename: '[id].chunk.js',
			publicPath: '/dist/'
		},
		resolve: {
			extensions: ['.ts', '.js'],
			modules: ['node_modules']
		},
		module: {
			rules: [
				{
					test: /\.ts$/,
					include: path.join(__dirname, 'src'),
					exclude: [],
					use: ['awesome-typescript-loader']
				}
			]
		},
		stats: 'verbose',
		plugins: [
			new ProgressBarPlugin({
				format: '  build [:bar] (:percent) - (:elapsed seconds)',
				clear: false,
				complete: '#',
				summary: 'true'
			})
		]
	}
}

CLI

The CLI allows you to use the buildFromFile and watchFromFile methods using from the command line. Running ramster-webpack --help will display the full usage information that you can see below:

Usage: ramster-webpack [options]
       ramster-webpack -c config/webpack.js -p production
       ramster-webpack --configFilePath=config/webpack.js --pluginProfileName=production

Options:
  -b, --build                                signals the script to build the bundles for the provided config files and exit
  -w, --watch                              signals the script to build and watch the bundles for the provided config files by running a devserver
  -c, --configFilePath                 required; specifies the config file to use for the run; if provided multiple times, multiple files will be built
  -p, --pluginProfileName        optional; specifies the plugins profile for the config file to use for the run; if provided multiple times, each one will be matched to a single --configFilePath in the order provided
  -h, --help                                 display this menu

Security issues

Please report any security issues privately at [e-mail].