webpkr Build Language Reference

Webpkr scripts are configuration scripts. As the script executes, it configures a tree of configuration nodes. During the evaluation phase, tree nodes are evaluated to generate a webpack configuration object.

Under Development.

Script Structure

A configuration script is made of up of multiple statements and script blocks. A script block inserts a new node in the the configuration tree and takes optional parameters.

Configuration Closure

If the final parameter is a closure, it is treated as a configuration closure which configures the newly created node. Any optional parameters are available to the node during the subsequent evaluation phase.

// optional arguments
block([{*}, ..., {*},] () => {
    // configuration closure
})
Naming Convention

Top level script blocks map to top level keys of the webpack configuration object. Where there is a potential clash of names (e.g. with module or path), the script block name is appended with a $ symbol.

Plain Ol' JavaScript

The build script is JavaScript code, and can contain any valid JavaScript, such as method definitions, require statements, classes etc.

Globals

projectDir

The directory containing the project build file. Defaults to process.cwd().

// webpack.config.js
module.exports = require( 'webpkr' )( { projectDir: __dirname } );

buildDir

The build directory of this project where all the output will be generated. Defaults to projectDir/build.

multiple Environments

Environment script blocks allow conditional inclusion (or exclusion) during the evaluation phase based on the value of the NODE_ENV environment variable.

development()

Sub-blocks are evaluated only when NODE_ENV=development.

development( () => {
  // development-only scripts
})

production()

Sub-blocks are evaluated only when NODE_ENV=production.

production( () => {
  // production-only scripts
})

testing()

Sub-blocks are evaluated only when NODE_ENV=testing.

testing( () => {
  // testing-only scripts
})

staging()

Sub-blocks are evaluated only when NODE_ENV=staging.

staging( () => {
  // staging-only scripts
})

Evaluation Order

In some cases, it may be necessary to control the order the order of evaluation, e.g. to ensure the order of loading of css files.

Do not depend solely on the position of a script block if order of evaluation is important.

doFirst()

Instructs the evaluation phase to evaluate the nodes contained within before other nodes.

// ensures that base.css is loaded before style.css

entry({main: './css/style.css'})

doFirst( () => {
  entry({main: './css/base.css'})
})

doLast()

Instructs the evaluation phase to evaluate the nodes contained within after other nodes.

// ensures that style.css is loaded after base.css

doLast( () => {
  entry({main: './css/style.css'})
})

entry({main: './css/base.css'})
The order of evaluation within doFirst and doLast is not guaranteed.

Entry and Context

context( )

string

The base directory for resolving entry points and loaders from configuration. Relative paths are resolved from projectDir.

context('src')
// => projectDir/src

entry()

string | [string] | object { <key>: string | [string] }

The point or points to enter the application. See entry. Webpkr will merge multiple calls to entry():

  • Arrays will be merged with arrays or individual strings.

  • Objects will merged/extended by key.

Attempting to merge an array with an object will result in an error.
webpkr script webpack configuration 
entry('./src/index.js')
entry('./src/another.js')
 
entry: [
  './src/index.js',
  './src/another.js' ]

Output

The top-level output script block configures webpack output settings.

output(() =>{
  filename( 'bundle.js' )
  path$( 'dist' )
} )

To avoid potential name clashes, output.path is available as path$.

Module

The top-level module$ script block configures the webpack module key.

module$( () => {
  rule( () => { } )
  rule( () => { } )
} )

To avoid name clashes, output.path is available as path$.

rule()

The rule script block defines a rule which is matched to requests when modules are created. Rule blocks are grouped into the module.rules array during the evaluation phase.

module$( () => {

  rule( () => {
    test( /\.css$/ )
    use( ExtractTextPlugin.extract( {
      fallback: 'style-loader',
      use: 'css-loader',
    } ) )
  } )

  rule( () => {
    test( /\.scss$/ )
    use( ExtractTextPlugin.extract( {
      fallback: 'style-loader',
      use: [
        { loader: 'css-loader' },
        { loader: 'sass-loader' },
      ]
    } ) )
  } )
} )

The following script blocks are available within the rule script block: