{"id":14345,"library":"webpack-tool","title":"Webpack Build and Dev Server Tool","description":"webpack-tool is a utility library designed to streamline webpack development and production builds, integrating a Koa-based development server with hot module replacement and a production build mechanism that can optionally display a build result UI. It ties its major version releases directly to webpack's major versions (e.g., `webpack-tool@5.x.x` for `webpack@5`). This approach provides a consistent experience for developers working with specific webpack versions. Key differentiators include its built-in Koa dev server, which offers `before` and `after` hooks for custom middleware integration, a proxy configuration, and a history API fallback. It aims to simplify the boilerplate often associated with setting up webpack for both development and production environments, providing a consolidated API for `server` (development) and `build` (production) commands, along with a debug UI for build results.","status":"active","version":"5.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/easy-team/webpack-tool","tags":["javascript","webpack","webpack3","webpack4","webpack build","webpack hot reload"],"install":[{"cmd":"npm install webpack-tool","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-tool","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-tool","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for build and dev server functionality; webpack-tool versions are aligned with webpack versions.","package":"webpack","optional":false},{"reason":"Underpins the development server for custom middleware and routing.","package":"koa","optional":false}],"imports":[{"note":"Primarily designed for CommonJS; direct ESM import might not work without a build step or explicit configuration, as shown in the README.","wrong":"import WebpackTool from 'webpack-tool';","symbol":"WebpackTool","correct":"const WebpackTool = require('webpack-tool');"},{"note":"WebpackTool is a class, requiring the `new` keyword for instantiation.","wrong":"const webpackTool = WebpackTool({...});","symbol":"WebpackTool instance","correct":"const webpackTool = new WebpackTool({...});"}],"quickstart":{"code":"const WebpackTool = require('webpack-tool');\nconst path = require('path');\nconst crossEnv = require('cross-env');\n\n// Simulate cross-env setup for demonstration\nprocess.env.VIEW = process.argv.includes('--dev') ? 'development' : 'production';\n\nconst webpackTool = new WebpackTool({\n  devServer: {\n    port: 8080,\n    before: (app) => {\n      console.log('Registering custom Koa middleware (before)');\n      app.use(async (ctx, next) => {\n        if (ctx.path === '/custom-api') {\n          ctx.body = 'Hello from custom API!';\n        } else {\n          await next();\n        }\n      });\n    },\n    proxy: {\n      '/api': {\n        target: 'http://localhost:3000',\n        pathRewrite: { '^/api': '' },\n        onProxyReq: (proxyReq, req, res) => {\n          console.log(`Proxying request: ${req.url}`);\n        }\n      }\n    },\n    historyApiFallback: {\n      index: '/index.html'\n    }\n  }\n});\n\nconst webpackConfig = {\n  mode: process.env.VIEW === 'development' ? 'development' : 'production',\n  entry: {\n    index: path.resolve(__dirname, 'src/index.js')\n  },\n  output: {\n    filename: '[name].bundle.js',\n    path: path.resolve(__dirname, 'dist')\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.js$/,\n        exclude: /node_modules/,\n        use: {\n          loader: 'babel-loader',\n          options: {\n            presets: ['@babel/preset-env']\n          }\n        }\n      }\n    ]\n  },\n  plugins: []\n};\n\nif (process.env.VIEW === 'development') {\n  console.log('Starting webpack development server on http://localhost:8080');\n  webpackTool.server(webpackConfig);\n} else {\n  console.log('Starting webpack build for production');\n  // To view UI for build mode, set process.env.BUILD_VIEW = 'true';\n  // process.env.BUILD_VIEW = 'true';\n  webpackTool.build(webpackConfig).then(() => {\n    console.log('Production build completed.');\n  }).catch(err => {\n    console.error('Production build failed:', err);\n  });\n}\n\n// To make this runnable, ensure you have a src/index.js and babel setup.\n// Example src/index.js:\n// console.log('Hello from webpack-tool!');\n// document.body.innerHTML = '<h1>Webpack-tool Demo</h1>';\n\n// To run: \n// node build/index.js --dev (for dev server)\n// node build/index.js (for production build)\n","lang":"javascript","description":"This quickstart demonstrates how to instantiate `WebpackTool`, configure its dev server with custom Koa middleware, proxying, and history API fallback, and then conditionally start either the development server or a production build based on an environment variable. It also shows a minimal webpack configuration."},"warnings":[{"fix":"Always install `webpack-tool` with a version that matches your installed `webpack` major version (e.g., `npm i webpack-tool@^5.0.0 webpack@^5.0.0`).","message":"Major version of `webpack-tool` is tied directly to `webpack` major versions. Upgrading `webpack` (e.g., from v4 to v5) requires upgrading `webpack-tool` to the corresponding major version (e.g., from `webpack-tool@4.x.x` to `webpack-tool@5.x.x`).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"When using `devServer.before` or `devServer.after`, ensure your middleware functions are compatible with Koa's context and `async/await` pattern (`(ctx, next) => {...}`).","message":"The `devServer` configuration object for `webpack-tool` is a direct passthrough to webpack-dev-server options, but also includes custom `before` and `after` hooks which operate on a Koa application instance, not Express as `webpack-dev-server` typically does internally. Misunderstanding this can lead to incorrect middleware implementations.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Set `process.env.BUILD_VIEW = true` before calling `webpackTool.build(webpackConfig)` if you want to inspect the build result UI.","message":"The build result UI view is not enabled by default for production builds. To see the UI after a production build, a specific environment variable `process.env.BUILD_VIEW` must be set to `true`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'5':62,66 'aim':109 'along':137 'api':106,129 'approach':68 'associ':115 'base':26 'boilerpl':113 'build':2,21,36,43,134,143,150 'built':85 'built-in':84 'command':136 'configur':102 'consist':71 'consolid':128 'custom':97 'debug':140 'design':14 'dev':4,88 'develop':18,27,74,122,132 'differenti':81 'direct':52 'display':41 'e.g':58 'environ':125 'experi':72 'fallback':107 'histori':105 'hook':95 'hot':30,152 'includ':82 'integr':22,99 'javascript':145 'key':80 'koa':25,87 'koa-bas':24 'librari':13 'major':49,56 'mechan':37 'middlewar':98 'modul':31 'offer':91 'often':114 'option':40 'product':20,35,124,135 'provid':69,126 'proxi':101 'releas':51 'reload':153 'replac':32 'result':44,144 'server':5,28,89,131 'set':117 'simplifi':111 'specif':77 'streamlin':16 'tie':47 'tool':6,9,61 'ui':45,141 'util':12 'version':50,57,79 'webpack':1,8,17,54,60,65,78,119,146,149,151 'webpack-tool':7,59 'webpack3':147 'webpack4':148 'work':75 'x.x':63","created_at":"2026-04-20T01:59:13.541461+00:00","updated_at":"2026-04-20T01:59:13.541461+00:00","problems":[{"fix":"Review webpack configuration, especially loaders and plugins. Check for circular dependencies in modules. Try simplifying the configuration or isolating the problematic part. Increase Node.js stack size if necessary, e.g., `node --stack-size=4000 build/index.js`.","cause":"Often caused by complex or circular dependencies in the webpack configuration, or issues with loaders/plugins.","error":"Error: Webpack compilation failed: RangeError: Maximum call stack size exceeded"},{"fix":"Ensure that the middleware provided to `before` or `after` is a valid Koa middleware function (taking `ctx` and `next` as arguments) and that the `app` object is indeed the Koa instance provided by `webpack-tool`.","cause":"This error likely occurs within `devServer.before` or `devServer.after` when attempting to use middleware not compatible with Koa, or when `app` is not the expected Koa application instance.","error":"TypeError: app.use is not a function"},{"fix":"Run `npm install webpack-tool --save` or `yarn add webpack-tool` in your project directory. Verify the package is listed in `package.json` and present in `node_modules`.","cause":"The `webpack-tool` package is not installed or not resolvable in the current project's `node_modules`.","error":"Error: Cannot find module 'webpack-tool'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"webpack-tool","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/easy-team/webpack-tool","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/webpack-tool","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}