webpack-common

一个类似 Vite 的 webpack 预设库：开箱即用、少配置、可扩展。

特性

• 开发体验：React Refresh、错误 overlay、简洁日志、Client 友好地址输出
• 生产优化：contenthash 命名、deterministic ids、runtimeChunk: 'single'
• 缓存与调试：文件系统缓存、devtool 按环境优化
• CSS 支持：CSS Modules、PostCSS（对象或配置文件路径）、Less、Sass
• 资源策略：统一 asset，支持 assetsInlineLimit
• 配置能力：异步 defineConfig、多页面 pages、库模式 build.lib、envPrefix 与 loadEnv
• 兼容 ESM/CJS：提供 dist/index.mjs 与 dist/index.cjs
• 代码优化：智能路径归一化，支持 base 配置，自动处理相对路径和绝对路径

安装

npm i webpack-common -D

快速开始

CommonJS（webpack.config.js）

// webpack.config.js
const { defineConfig } = require('webpack-common');

module.exports = defineConfig({
  base: '/app/',
  devServer: { port: 3000, open: true }
});

ESM（webpack.config.mjs 或 package.json 声明 "type":"module"）

// webpack.config.mjs
import { defineConfig, loadEnv } from 'webpack-common';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, ['APP_']);
  return {
    env,
    reactRefresh: true,
    devServer: { port: 3000, open: true }
  };
});

主要配置

• base：基础路径配置，支持多种格式：
  • 绝对路径：/app/ → /app/
  • 相对路径：./ → ./（输出模式），../assets → /assets
  • 自动归一化：确保路径以 / 开头和结尾
  • 支持 auto 和 HTTPS URL
• sourcemap：true|'inline'|'hidden'|false，开发默认 cheap-module-source-map，生产默认 false
• envPrefix：只注入以此前缀（或前缀数组）开头的 env（默认 APP_）
• assetsInlineLimit：资源内联阈值（字节），默认 4096
• css.modules：CSS Modules 选项或 false
• css.postcss：PostCSS 配置对象或配置文件路径字符串
• reactRefresh：开发模式启用 React HMR，默认 true
• pages：多页面 { [name]: string | { entry, template?, filename? } }
• build.lib：库模式 { entry, name?, filename?, libraryType? }，并可配 build.externals

路径配置示例

import { defineConfig } from 'webpack-common';

export default defineConfig({
  // 支持多种路径格式
  base: '/app/',           // 绝对路径
});

多页面示例

import { defineConfig } from 'webpack-common';
export default defineConfig({
  pages: {
    main: 'src/main.tsx',
    admin: { entry: 'src/admin.tsx', template: 'public/admin.html', filename: 'admin.html' }
  }
});

库模式示例

import { defineConfig } from 'webpack-common';
export default defineConfig({
  build: {
    lib: { entry: 'src/index.ts', name: 'MyLib', filename: 'my-lib.js', libraryType: 'umd' },
    externals: { react: 'React', 'react-dom': 'ReactDOM' }
  }
});

环境变量

• 自动加载 .env, .env.local, .env.[mode], .env.[mode].local
• 仅注入以 envPrefix 指定前缀的键到 process.env

import { loadEnv } from 'webpack-common';
const env = loadEnv('development', ['APP_']);

日志与地址输出

• 开发时显示 Local 与 Network 链接，支持 https、0.0.0.0、绝对 URL 的 base
• 需要进度条时可在 Dev TTY 开启，CI/生产建议关闭

代码优化特性

• 智能路径归一化：统一的路径处理逻辑，支持多种路径格式
• 代码简洁性：合并重复函数，提高可维护性
• 向后兼容：保持与现有配置的兼容性

示例

• demo（CJS）与 demo-esm（ESM）

版本策略

• 使用 ^ 保持向前兼容；如需强可复现性，可锁精确版本并用 Renovate/Dependabot 审核升级

兼容性

• Node >= 16（推荐 Node 18+），webpack 5

许可证

ISC