@ramster/webpack-tools

Webpack build and dev tools, part of the ramster open-source software toolkit.

Usage no npm install needed!

<script type="module">
  import ramsterWebpackTools from 'https://cdn.skypack.dev/@ramster/webpack-tools';
</script>

README

npm"> node pipeline Coverage Status npm npm @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.