@dawnjs/dn-middleware-webpack

@dawnjs/dn-middleware-webpack

Getting Started

To begin, you'll need to install @dawnjs/dn-middleware-webpack:

$ npm i -D @dawnjs/dn-middleware-webpack

Then add the middleware to your dawn pipeline configuration. For example:

.dawn/pipe.yml

dev:
  - name: '@dawnjs/dn-middleware-webpack'

And run dn dev via your preferred method.

Important Warning

To be sure no other webpack middleware installed in your project. If any, please install the latest webpack@5 with npm install --dev webpack@5 manually in your project to ensure node_modules/webpack's version is 5.x.

Options

Name	Type	Default	Description
configFile	string	"./webpack.config.js"	The path of custom configration for modify any webpack options
chainable	boolean	false	Use webpack-chain's Config instance for custorm config file
env	string	Depends on environment variables	Set bundle environment, accepted values are "development" or "production"
cwd	string	Depends on current working directory	Specify working directory manually, useful for monorepo project etc.
entry	string | string[] | object	Depends on files exist in src	Specify app entry, support glob pattern and multi-entry
inject	string | string[]	[]	File list to be prepended to all entries
append	string | string[]	[]	File list to be appended to all entries
output	string | object	{ path: "./build" }	Webpack output options
folders	object	{ script: "js", style: "css", media: "assets", html: "" }	Output folders for different asset type
disableDynamicPublicPath	boolean	false	Wether disable the auto dynamic public path feature or not
template	boolean | string | string[] | object	true	Specify html template
target	string | string[] | false		Specify webpack target
external	boolean	Depends on env	Whether enable externals or not
externals	object	Depends on env and output.library	Specify webpack externals
alias	object		Set webpack's resolve.alias
tsconfigPathsPlugin	object		Options for tsconfig-paths-webpack-plugin
devtool	boolean | string	Depends on env	Set webpack's devtool option
common	object	{ disabled: false, name: 'common' }	Simply set whether using common chunk or not and the common chunks's name
compress	boolean	Depends on env	Enable webpack's optimization.minimize option
esbuild	object		Options for ESBuild's loader and plugin
swc	boolean | object		Options for swc's loader and plugin
terser	object	{ extractComments: false, terserOptions: { compress: { drop_console: true }, format: { comments: false } } }	Options for terser-webpack-plugin
cssMinimizer	object	{ minimizerOptions: { preset: ["default", { discardComments: { removeAll: true } }] } }	Options for css-minimizer-webpack-plugin
optimization	object		Extra optimization options
ignoreMomentLocale	boolean	true	Whether to ignore locales in moment package or not
babel	object		Options to custom behavior of babel preset
disabledTypeCheck	boolean	false	Disable type check for typescript files
typeCheckInclude	string[]	["**/*"]	Glob patterns for files to check types
injectCSS	boolean	Depends on env	Should inject css into the DOM, otherwise extract css to seperate files
styleLoader	object		Options for style-loader or MiniCssExtractPlugin.loader
cssLoader	object		Options for css-loader
postcssLoader	object	{ postcssOptions: { plugins: ["postcss-preset-env"] } }	Options for postcss-loader
extraPostCSSPlugins	any[]		Extra plugins for PostCSS in postcss-loader
postcssPresetEnv	object		Options for postcss-preset-env
lessLoader	object	{ lessOptions: { rewriteUrls: "all" } }	Options for less-loader
resolveUrlLoader	object		Options for resolve-url-loader
sassLoader	object	{ sourceMap: true, sassOptions: { quietDeps: true } }	Options for sass-loader
workerLoader	object	{ inline: "fallback" }	Options for worker-loader
config	object	{ name: "$config", path: "./src/config", env: ctx.command }	Options to configure the runtime config virtual module
profile	boolean		Enable webpack profile option and add webpack-stats-plugin to output stats file
statsOpts	string | object	"verbose"	Options for stats in webpack-stats-plugin
analysis	boolean | object		Enable and set options for webpack-bundle-analyzer
watch	boolean		Enable watch mode
watchOpts	object	{ ignored: /node_modules/ }	Options for watch mode
server	boolean	Depends on env	Enable server mode
serverOpts	object	{ host: "localhost", historyApiFallback: true, open: true, hot: true }	Options for webpack-dev-server
lint	boolean | object	{ extensions: "js,jsx,ts,tsx", formatter: require.resolve("eslint-formatter-pretty"), failOnError: false }	Enable ESLint in server mode

configFile

Type: string
Default: "./webpack.config.js"

By default, the custom configration file must export a valid function.
In compatible mode, the custom configration file could export a valid function or a valid webpack config object.

Important: It is not recommend to modify existing module rules because their structure might be changed in the future.

Examples:

module.exports = function (config, webpack, ctx) {
  // config: a webpack config object or an instance of webpack-chain's `Config` in chainable mode
  // webpack: the imported `webpack` function
  // ctx: the dawn context
};

chainable

Type: boolean
Default: false

By default, the first argument of custom configration function is a webpack config object.
If enable chainable mode, the first argument would be a webpack-chain's Config instance.

Avaliable chainable config name:

• rule (Access with config.module.rule(ruleName))
  • "assets"
    • oneOf (Access with config.module.rule("assets").oneOf(oneOfName))
      • "raw"
      • "inline"
      • "images"
      • "svg"
      • "fonts"
      • "plaintext"
      • "yaml"
  • "esbuild" (If using esbuild.loader)
    • oneOf (Access with config.module.rule("esbuild").oneOf(oneOfName))
      • "js"
        • use (Access with config.module.rule("esbuild").oneOf("js").use(useName))
          • "esbuild-loader"
      • "ts"
        • use (Access with config.module.rule("esbuild").oneOf("ts").use(useName))
          • "esbuild-loader"
      • "tsx"
        • use (Access with config.module.rule("esbuild").oneOf("tsx").use(useName))
          • "esbuild-loader"
  • "swc" (If using swc)
    • oneOf (Access with config.module.rule("swc").oneOf(oneOfName))
      • "js"
        • use (Access with config.module.rule("swc").oneOf("js").use(useName))
          • "swc-loader"
      • "ts"
        • use (Access with config.module.rule("swc").oneOf("ts").use(useName))
          • "swc-loader"
      • "tsx"
        • use (Access with config.module.rule("swc").oneOf("tsx").use(useName))
          • "swc-loader"
  • babel (If using babel, it's default)
    • oneOf (Access with config.module.rule("babel").oneOf(oneOfName))
      • "jsx"
        • use (Access with config.module.rule("babel").oneOf("jsx").use(useName))
          • "babel-loader"
      • "app-js"
        • use (Access with config.module.rule("babel").oneOf("app-js").use(useName))
          • "babel-loader"
      • "extra-js" (If using babel.extraBabelIncludes)
        • use (Access with config.module.rule("babel").oneOf("extra-js").use(useName))
          • "babel-loader"
      • "ts"
        • use (Access with config.module.rule("babel").oneOf("ts").use(useName))
          • "babel-loader"
      • "tsx"
        • use (Access with config.module.rule("babel").oneOf("tsx").use(useName))
          • "babel-loader"
  • "worker"
    • use (Access with config.module.rule("worker").use(useName))
      • "worker-loader"
  • "css"
    • use (Access with config.module.rule("css").use(useName))
      • "style-loader" (If using injectCSS)
      • "extract-css-loader" (If not using injectCSS)
      • "css-loader"
      • "postcss-loader"
  • "less"
    • use (Access with config.module.rule("less").use(useName))
      • "style-loader" (If using injectCSS)
      • "extract-css-loader" (If not using injectCSS)
      • "css-loader"
      • "postcss-loader"
      • "less-loader"
  • "sass"
    • use (Access with config.module.rule("sass").use(useName))
      • "style-loader" (If using injectCSS)
      • "extract-css-loader" (If not using injectCSS)
      • "css-loader"
      • "postcss-loader"
      • "resolve-url-loader"
      • "sass-loader"

env

Type: string
Default: Depends on environment variables

Available values are "development" and "production". If not specified, we will determine it by process.env.DN_ENV, process.env.NODE_ENV and the dawn command executing currently in order.

Examples:

$ dn dev # set to "development" because of the command includes the "dev" string
$ dn run daily # set to "development" because of the command includes the "daily" string
$ dn run build # set to "production" because of the command neither includes the "dev" string nor includes the "daily" string
$ NODE_ENV=production dn dev # set to "production" because of process.env.NODE_ENV is "production"
$ DN_ENV=production NODE_ENV=development dn dev # set to "production" because of process.env.DN_ENV is "production"

cwd

Type: string
Default: Depends on current working directory

By default cwd equals to the current working directory.

entry

Type: string | string[] | object Default: Depends on files exist in src

By default, middleware will search files src/index.tsx, src/index.ts, src/index.jsx, src/index.js in order and set entry to the first founded file path.

string

Set a single entry by path. The entry name equals the base name of the path without extension.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    entry: src/app.tsx # The entry name is "app"

string[]

Set multiple entries by path.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    entry:
      - src/foo.tsx # The entry name is "foo"
      - src/bar.tsx # The entry name is "bar"

object

Set multiple entries by name and path. Support using glob pattern in path and placeholder in name to specify multiple entries.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    entry:
      index: src/index.tsx
      page_{0}: src/pages/*.tsx

If there is a.tsx and b.tsx in src/pages/, then two entries which with name page_a and page_b will be generated together with the fixed entry index.

inject

Type: string | string[]
Default: []

Prepend file(s) to all entries.

string

Simplified for single file.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    inject: src/setup.ts

string[]

One or more files.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    inject:
      - src/bootstrap.ts
      - src/initGlobal.ts

append

Type: string | string[]
Default: []

Append file(s) to all entries.

string

Simplified for single file.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    append: src/cleanup.ts

string[]

One or more files.

Examples:

dev:
  - name: '@dawnjs/dn-middleware-webpack'
    append:
      - src/restore.ts
      - src/cleanup.ts

output

Type: string | object
Default: { path: "./build" }

Pass to webpack output options.

string

If you provide an string, it means output.path.

object

Accept all webpack output options. Details to see here.

folders

Type: object
Default: { script: "js", style: "css", media: "assets", html: "" }

Output folders for different asset type.

• script - All js files.
• style - All css files output by mini-css-extract-plugin.
• html - All html files output by html-webpack-plugin.
• media - Any files output by webpack with asset modules

disableDynamicPublicPath

Type: boolean
Default: false

By default, if output.publicPath not set (means it's undefined) then a small code snippet will be prepend to all entries to determine runtime dynamic public path with current script source url.

template

Type: boolean | string | string[] | object
Default: true

false

Disable the html output.

true

Scan file with path public/index.html and src/assets/index.html if it exists.

string

Specify the template file path.

template: template/custom.html

string[]

Specify multi templates, the file's basename is the template name.

template:
  - template/foo.html
  - template/bar.html

object

Specify multi templates with template name.

template:
  foo: template/a.html
  bar: template/b.html

target

Type: string | string[] | false
Default:

See webpack docs.

external

Type: boolean
Default: Depends on env

Defaults to false in development mode, otherwise to true.

externals

Type: object
Default: Depends on env and output.library

By default, make react and react-dom as externals.

alias

Type: object
Default:

See webpack docs.

tsconfigPathsPlugin

Type: object
Default:

tsconfig-paths-webpack-plugin only enabled if there is a tsconfig.json file exists in the current work directory.

See plugin docs.

devtool

Type: boolean | string
Default: Depends on env

If env is "development", defaults to "eval-cheap-module-source-map", otherwise defaults to "cheap-source-map".

true

Same as not set.

false

Disable source maps.

string

All available values see webpack docs.

common

Type: object
Default: { disabled: false, name: 'common' }

common.disabled

Type: boolean
Default: false

Set to true to disable common chunk.

common.name

Type: string
Default: "common"

Set common chunk's name.

compress

Type: boolean
Default: Depends on env

Default to true in "production".

esbuild

Type: object
Default:

esbuild.loader

Type: boolean | object
Default:

boolean

Simply enable esbuild to replace babel without options.

object

See esbuild-loader's loader options.

esbuild.minify

Type: boolean | object
Default:

boolean

Simply enable esbuild to replace terser without options.

object

See esbuild-loader's minify plugin options.

swc

Type: boolean | object Default:

boolean

Simply enable swc to replace babel and terser without options.

object

See swc-loader options and swc-webpack-plugin options.

terser

Type: object
Default: { extractComments: false, terserOptions: { compress: { drop_console: true }, format: { comments: false } } }

See plugin docs.

cssMinimizer

Type: object
Default: { minimizerOptions: { preset: ["default", { discardComments: { removeAll: true } }] } }

See plugin docs

optimization

Type: object
Default:

Extra options to override other optimization options.

See webpack docs.

ignoreMomentLocale

Type: boolean
Default:

Whether to ignore locales in moment package or not, default is true.

babel

Type: object

babel.corejs

Type: false | 2 | 3 | { version: 2 | 3; proposals: boolean }
Default:

See babel docs.

babel.disableAutoReactRequire

Type: boolean
Default: false

Whether to use babel-plugin-react-require or not. See plugin docs.

babel.extraBabelIncludes

Type: any[]
Default:

By default babel only transform application source files except files in the node_modules folder. Pass in any valid include pattern list to tell babel to transform. Include patther follow webpack module rule condition

babel.extraBabelPlugins

Type: any[]
Default:

Specify extra babel plugins.

babel.extraBabelPresets

Type: any[]
Default:

Specify extra babel presets.

babel.ie11Incompatible

Type: boolean
Default: false

Enable IE11 compatible mode, use es5-imcompatible-versions

babel.jsxRuntime

Type: boolean
Default:

Enable react's new jsx runtime syntax.

babel.pragma

Type: string
Default:

See babel docs.

babel.pragmaFrag

Type: string
Default:

See babel docs.

babel.runtimeHelpers

Type: boolean | string
Default:

Enable transform-runtime plugin or specify the plugin version.

disabledTypeCheck

Type: boolean
Default: false

By default, if there is a tsconfig.json file in current working directory, it will checking the types for typescript files. Can disable it with set disabledTypeCheck to true.

typeCheckInclude

Type: string[]
Default: ["**/*"]

By default, all files will be checked. Custom glob patterns to override the range.

injectCSS

Type: boolean
Default: Depends on env

If env is "development" then it defaults to true, else defaults to false.

When it is true, CSS would be injected into the DOM by style-loader, otherwise, be extracted to seperate files by mini-css-extract-plugin.

styleLoader

Type: object
Default:

Options for style-loader or MiniCssExtractPlugin.loader.

See style-loader doc and MiniCssExtractPlugin.loader doc.

cssLoader

Type: object
Default:

Options for css-loader. Support CSS Modules if file has extension like .module.*.

See css-loader docs.

postcssLoader

Type: object
Default: { implementation: require("postcss"), postcssOptions: { plugins: ["postcss-flexbugs-fixes", "postcss-preset-env"] } }

Options for css-loader.

See postcss-loader docs

extraPostCSSPlugins

Type: any[]
Default:

Extra plugins for PostCSS in postcss-loader. Only available if postcssLoader.postcssOptions is not a function.

postcssPresetEnv

Type: object
Default:

Options for postcss-preset-env. Only available if postcssLoader.postcssOptions is not a function.

See postcss-preste-env docs.

lessLoader

Type: object
Default: { implementation: require("less"), lessOptions: { rewriteUrls: "all" } }

Options for less-loader.

See less-loader docs.

resolveUrlLoader

Type: object
Default:

Options for resolve-url-loader. resolve-url-loader only apply to SASS files. See this.

See resolve-url-loader docs.

sassLoader

Type: object
Default: { implementation: require("sass"), sourceMap: true, sassOptions: { fiber: require("fibers") } }

Options for sass-loader. sassLoader.sourceMap always be true because of the requirement of resolve-url-loader. See here.

See sass-loader docs.

workerLoader

Type: object
Default: { inline: "fallback" }

Options for worker-loader. Files with .worker.* extensions will be processed.

See worker-loader docs.

config

Type: object
Default: { name: "$config", path: "./src/config", env: ctx.command }

Options to configure the runtime config virtual module. By default, load runtime config from src/config, src/config.* and src/config/**/* according to the specified env with any supported format. See confman.

Examples:

In ./config.yml

foo: abc

In ./src/test.ts

import config from '$config';

console.log(config.foo); // output abc

config.name

Type: string
Default: "$config"

The virtual module name.

config.path

Type: string
Default: "./src/config"

The path where to search config files.

config.env

Type: string
Default: ctx.command

The runtime environment of config files. By default, it depends on the current running command of dawn.

Examples:

$ dn d

will load config.dev.yml because the actual command is "dev".

$ dn run my-cmd

will load config.my-cmd.yml.

config.content

Type: any
Default:

Manually set the whole config content.

profile

Type: boolean
Default:

Also can be enabled by setting process.env.WEBPACK_PROFILE to any nullish value.

statsOpts

Type: string | object
Default: "verbose"

Options for stats in webpack-stats-plugin.

See webpack docs

analysis

Type: boolean | object
Default:

Options for webpack-bundle-analyzer. Set to false to disable it. Set to true to enable it and use default options ({ analyzerMode: "server", openAnalyzer: true }). Auto enabled if profile is on.

See webpack-bundle-analyzer docs.

watch

Type: boolean
Default:

Enable webpack's watch mode, unavailable in server mode.

watchOpts

Type: object
Default: { ignored: /node_modules/ }

See webpack docs.

server

Type: boolean
Default: Depends on env

Defaults to true if env is "development", otherwise to false.

serverOpts

Type: object
Default: { host: "localhost", historyApiFallback: true, open: true, hot: true, quiet: true }

Options for webpack-dev-server. Support custom server with server.* in current working directory, or with a directory server/ and several config files.

Examples:

# server.yml
host: 127.0.0.1
port: 8001
https: true
proxy:
  /api: https://localhost:3000
  /api2:
    target: https://localhost:3001
    pathRewrite:
      ^/api2: /v2

See webpack docs.