@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 r_rumenov@lemmsoft.com.