@workleap/webpack-configs 1.5.2 → 1.5.3

package/src/build.ts

@@ -0,0 +1,240 @@
+import type { Config as SvgrOptions } from "@svgr/core";
+import type { Config as SwcConfig } from "@swc/core";
+import HtmlWebpackPlugin from "html-webpack-plugin";
+import MiniCssExtractPlugin from "mini-css-extract-plugin";
+import { createRequire } from "node:module";
+import path from "node:path";
+import TerserPlugin from "terser-webpack-plugin";
+import webpack from "webpack";
+import { applyTransformers, type WebpackConfigTransformer } from "./transformers/applyTransformers.ts";
+import type { WebpackConfig } from "./types.ts";
+import { isObject } from "./utils.ts";
+
+// Aliases
+const DefinePlugin = webpack.DefinePlugin;
+
+// Using node:module.createRequire until
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve
+// is available
+const require = createRequire(import.meta.url);
+
+export function defineBuildHtmlWebpackPluginConfig(options: HtmlWebpackPlugin.Options = {}): HtmlWebpackPlugin.Options {
+    const {
+        template = path.resolve("./public/index.html"),
+        ...rest
+    } = options;
+
+    return {
+        ...rest,
+        template
+    };
+}
+
+type MiniCssExtractPluginOptions = NonNullable<ConstructorParameters<typeof MiniCssExtractPlugin>[number]>;
+
+export function defineMiniCssExtractPluginConfig(options: MiniCssExtractPluginOptions = {}): MiniCssExtractPluginOptions {
+    const {
+        filename = "[name].css",
+        ...rest
+    } = options;
+
+    return {
+        ...rest,
+        filename
+    };
+}
+
+export type WebpackOptimization = NonNullable<WebpackConfig["optimization"]>;
+export type OptimizeOption = boolean | "readable";
+
+export function getOptimizationConfig(optimize: OptimizeOption): WebpackOptimization {
+    if (optimize === "readable") {
+        return {
+            minimize: true,
+            minimizer: [
+                new TerserPlugin({
+                    minify: TerserPlugin.swcMinify,
+                    terserOptions: {
+                        toplevel: true,
+                        mangle: false,
+                        keep_classnames: true,
+                        keep_fnames: true,
+                        compress: {
+                            toplevel: true,
+                            hoist_props: false
+                        },
+                        output: {
+                            comments: true
+                        }
+                    }
+                })
+            ],
+            chunkIds: "named",
+            moduleIds: "named",
+            mangleExports: false,
+            mangleWasmImports: false
+        };
+    } else if (optimize) {
+        return {
+            minimize: true,
+            minimizer: [
+                new TerserPlugin({
+                    minify: TerserPlugin.swcMinify
+                })
+            ]
+        };
+    }
+
+    // Doesn't turnoff everything but is good enough to help with debugging scenarios.
+    return {
+        minimize: false,
+        chunkIds: "named",
+        moduleIds: "named",
+        concatenateModules: false,
+        flagIncludedChunks: false,
+        mangleExports: false,
+        mangleWasmImports: false,
+        removeAvailableModules: false,
+        usedExports: false
+    };
+}
+
+export interface DefineBuildConfigOptions {
+    entry?: string;
+    outputPath?: string;
+    publicPath?: `${string}/` | "auto";
+    moduleRules?: NonNullable<WebpackConfig["module"]>["rules"];
+    plugins?: WebpackConfig["plugins"];
+    htmlWebpackPlugin?: boolean | HtmlWebpackPlugin.Options;
+    miniCssExtractPluginOptions?: MiniCssExtractPluginOptions;
+    optimize?: OptimizeOption;
+    cssModules?: boolean;
+    svgr?: boolean | SvgrOptions;
+    environmentVariables?: Record<string, unknown>;
+    transformers?: WebpackConfigTransformer[];
+    verbose?: boolean;
+}
+
+export function defineBuildConfig(swcConfig: SwcConfig, options: DefineBuildConfigOptions = {}) {
+    const {
+        entry = path.resolve("./src/index.tsx"),
+        outputPath = path.resolve("dist"),
+        // The trailing / is very important, otherwise paths will not be resolved correctly.
+        publicPath = "http://localhost:8080/",
+        moduleRules = [],
+        plugins = [],
+        htmlWebpackPlugin = defineBuildHtmlWebpackPluginConfig(),
+        miniCssExtractPluginOptions = defineMiniCssExtractPluginConfig(),
+        optimize = true,
+        cssModules = false,
+        svgr = true,
+        // Using an empty object literal as the default value to ensure
+        // "process.env" is always available.
+        environmentVariables = {},
+        transformers = [],
+        verbose = false
+    } = options;
+
+    const config: WebpackConfig = {
+        mode: "production",
+        target: "web",
+        entry,
+        output: {
+            path: outputPath,
+            filename: "[name].js",
+            publicPath,
+            clean: true,
+            assetModuleFilename: "[name][ext][query]"
+        },
+        optimization: getOptimizationConfig(optimize),
+        infrastructureLogging: verbose ? {
+            appendOnly: true,
+            level: "verbose",
+            debug: /PackFileCache/
+        } : undefined,
+        module: {
+            rules: [
+                {
+                    test: /\.(js|jsx|ts|tsx)$/i,
+                    exclude: /node_modules/,
+                    loader: require.resolve("swc-loader"),
+                    options: swcConfig
+                },
+                {
+                    // https://stackoverflow.com/questions/69427025/programmatic-webpack-jest-esm-cant-resolve-module-without-js-file-exten
+                    test: /\.js$/i,
+                    include: /node_modules/,
+                    resolve: {
+                        fullySpecified: false
+                    }
+                },
+                {
+                    test: /\.css$/i,
+                    use: [
+                        { loader: MiniCssExtractPlugin.loader },
+                        {
+                            loader: require.resolve("css-loader"),
+                            options: cssModules
+                                ? {
+                                    // Must match the number of loaders applied before this one.
+                                    importLoaders: 1,
+                                    modules: true
+                                }
+                                : undefined
+                        },
+                        { loader: require.resolve("postcss-loader") }
+                    ]
+                },
+                ...(svgr
+                    ? [
+                        {
+                            test: /\.svg$/i,
+                            loader: require.resolve("@svgr/webpack"),
+                            options: isObject(svgr) ? svgr : undefined
+                        },
+                        {
+                            test: /\.(png|jpe?g|gif)$/i,
+                            type: "asset/resource"
+                        }
+                    ]
+                    : [
+                        {
+                            test: /\.(png|jpe?g|gif|svg)$/i,
+                            type: "asset/resource"
+                        }
+                    ]),
+                ...moduleRules
+            ]
+        },
+        resolve: {
+            extensions: [".js", ".jsx", ".ts", ".tsx", ".css"],
+            alias: {
+                // Fixes Module not found: Error: Can't resolve '@swc/helpers/_/_class_private_field_init'.
+                // View https://github.com/vercel/next.js/pull/38174 for more information and https://github.com/vercel/next.js/issues/48593.
+                "@swc/helpers": path.dirname(require.resolve("@swc/helpers/package.json"))
+            }
+        },
+        plugins: [
+            htmlWebpackPlugin && new HtmlWebpackPlugin(isObject(htmlWebpackPlugin) ? htmlWebpackPlugin : defineBuildHtmlWebpackPluginConfig()),
+            new MiniCssExtractPlugin(miniCssExtractPluginOptions),
+            // Stringify the environment variables because the plugin does a direct text replacement. Otherwise, "production" would become production
+            // after replacement and cause an undefined var error because the production var doesn't exist.
+            // For more information, view: https://webpack.js.org/plugins/define-plugin.
+            new DefinePlugin({
+                "process.env": Object.keys(environmentVariables).reduce((acc, key) => {
+                    acc[key] = JSON.stringify(environmentVariables[key]);
+
+                    return acc;
+                }, {} as Record<string, string>)
+            }),
+            ...plugins
+        ].filter(Boolean) as WebpackConfig["plugins"]
+    };
+
+    const transformedConfig = applyTransformers(config, transformers, {
+        environment: "build",
+        verbose
+    });
+
+    return transformedConfig;
+}

package/src/dev.ts

@@ -0,0 +1,233 @@
+import ReactRefreshWebpackPlugin from "@pmmmwh/react-refresh-webpack-plugin";
+import type { ReactRefreshPluginOptions } from "@pmmmwh/react-refresh-webpack-plugin/types/lib/types.d.ts";
+import type { Config as SvgrOptions } from "@svgr/core";
+import type { Config as SwcConfig } from "@swc/core";
+import HtmlWebpackPlugin from "html-webpack-plugin";
+import { createRequire } from "node:module";
+import path from "node:path";
+import webpack from "webpack";
+import type { ServerOptions } from "webpack-dev-server";
+import { applyTransformers, type WebpackConfigTransformer } from "./transformers/applyTransformers.ts";
+import { isNil, isObject } from "./utils.ts";
+
+// Add the "devServer" option to WebpackConfig typings.
+import "webpack-dev-server";
+import type { WebpackConfig } from "./types.ts";
+
+// Aliases
+const DefinePlugin = webpack.DefinePlugin;
+
+// Using node:module.createRequire until
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve
+// is available
+const require = createRequire(import.meta.url);
+
+export function defineDevHtmlWebpackPluginConfig(options: HtmlWebpackPlugin.Options = {}): HtmlWebpackPlugin.Options {
+    const {
+        template = path.resolve("./public/index.html"),
+        ...rest
+    } = options;
+
+    return {
+        ...rest,
+        template
+    };
+}
+
+export function defineFastRefreshPluginConfig(options: ReactRefreshPluginOptions = {}) {
+    return options;
+}
+
+export interface DefineDevConfigOptions {
+    entry?: string;
+    https?: boolean | ServerOptions | undefined;
+    host?: string;
+    port?: number;
+    publicPath?: `${string}/` | "auto";
+    cache?: boolean;
+    moduleRules?: NonNullable<WebpackConfig["module"]>["rules"];
+    plugins?: WebpackConfig["plugins"];
+    htmlWebpackPlugin?: boolean | HtmlWebpackPlugin.Options;
+    fastRefresh?: boolean | ReactRefreshPluginOptions;
+    cssModules?: boolean;
+    overlay?: false;
+    svgr?: boolean | SvgrOptions;
+    environmentVariables?: Record<string, unknown>;
+    transformers?: WebpackConfigTransformer[];
+    verbose?: boolean;
+}
+
+function preflight() {
+    if (!require.resolve("webpack-dev-server")) {
+        throw new Error("[webpack-configs] To use the \"dev\" config, install https://www.npmjs.com/package/webpack-dev-server as a \"devDependency\".");
+    }
+}
+
+function trySetSwcFastRefresh(config: SwcConfig, enabled: boolean) {
+    if (config?.jsc?.transform?.react) {
+        config.jsc.transform.react.refresh = enabled;
+    }
+
+    return config;
+}
+
+function trySetFastRefreshOverlay(options: ReactRefreshPluginOptions, overlay?: boolean) {
+    if (overlay === false && isNil(options.overlay)) {
+        options.overlay = false;
+    }
+
+    return options;
+}
+
+export function defineDevConfig(swcConfig: SwcConfig, options: DefineDevConfigOptions = {}) {
+    preflight();
+
+    const {
+        entry = path.resolve("./src/index.tsx"),
+        https = false,
+        host = "localhost",
+        port = 8080,
+        publicPath,
+        cache = true,
+        moduleRules = [],
+        plugins = [],
+        htmlWebpackPlugin = defineDevHtmlWebpackPluginConfig(),
+        fastRefresh = true,
+        cssModules = false,
+        overlay,
+        svgr = true,
+        // Using an empty object literal as the default value to ensure
+        // "process.env" is always available.
+        environmentVariables = {},
+        transformers = [],
+        verbose = false
+    } = options;
+
+    const config: WebpackConfig = {
+        mode: "development",
+        target: "web",
+        devtool: "eval-cheap-module-source-map",
+        devServer: {
+            // According to the Fast Refresh plugin documentation, hot should be "true" to enable Fast Refresh:
+            // https://github.com/pmmmwh/react-refresh-webpack-plugin#usage.
+            hot: true,
+            host,
+            port,
+            historyApiFallback: true,
+            client: (overlay === false || fastRefresh) ? {
+                overlay: false
+            } : undefined,
+            server: https ? {
+                type: "https",
+                options: isObject(https) ? https : undefined
+            } : undefined
+        },
+        entry,
+        output: {
+            // The trailing / is very important, otherwise paths will not be resolved correctly.
+            publicPath: publicPath ?? `${https ? "https" : "http"}://${host}:${port}/`
+        },
+        cache: cache && {
+            type: "memory",
+            maxGenerations: 1
+        },
+        // See: https://webpack.js.org/guides/build-performance/#avoid-extra-optimization-steps
+        optimization: {
+            // Keep "runtimeChunk" to false, otherwise it breaks module federation
+            // (at least for the remote application).
+            runtimeChunk: false,
+            removeAvailableModules: false,
+            removeEmptyChunks: false,
+            splitChunks: false
+        },
+        infrastructureLogging: verbose ? {
+            appendOnly: true,
+            level: "verbose",
+            debug: /PackFileCache/
+        } : undefined,
+        module: {
+            rules: [
+                {
+                    test: /\.(js|jsx|ts|tsx)$/i,
+                    exclude: /node_modules/,
+                    loader: require.resolve("swc-loader"),
+                    options: trySetSwcFastRefresh(swcConfig, fastRefresh !== false)
+                },
+                {
+                    // https://stackoverflow.com/questions/69427025/programmatic-webpack-jest-esm-cant-resolve-module-without-js-file-exten
+                    test: /\.js$/i,
+                    include: /node_modules/,
+                    resolve: {
+                        fullySpecified: false
+                    }
+                },
+                {
+                    test: /\.css$/i,
+                    use: [
+                        { loader: require.resolve("style-loader") },
+                        {
+                            loader: require.resolve("css-loader"),
+                            options: cssModules
+                                ? {
+                                    // Must match the number of loaders applied before this one.
+                                    importLoaders: 1,
+                                    modules: true
+                                }
+                                : undefined
+                        },
+                        { loader: require.resolve("postcss-loader") }
+                    ]
+                },
+                ...(svgr
+                    ? [
+                        {
+                            test: /\.svg$/i,
+                            loader: require.resolve("@svgr/webpack"),
+                            options: isObject(svgr) ? svgr : undefined
+                        },
+                        {
+                            test: /\.(png|jpe?g|gif)$/i,
+                            type: "asset/resource"
+                        }
+                    ]
+                    : [
+                        {
+                            test: /\.(png|jpe?g|gif|svg)$/i,
+                            type: "asset/resource"
+                        }
+                    ]),
+                ...moduleRules
+            ]
+        },
+        resolve: {
+            extensions: [".js", ".jsx", ".ts", ".tsx", ".css"],
+            alias: {
+                // Fixes Module not found: Error: Can't resolve '@swc/helpers/_/_class_private_field_init'.
+                // View https://github.com/vercel/next.js/pull/38174 for more information and https://github.com/vercel/next.js/issues/48593.
+                "@swc/helpers": path.dirname(require.resolve("@swc/helpers/package.json"))
+            }
+        },
+        plugins: [
+            htmlWebpackPlugin && new HtmlWebpackPlugin(isObject(htmlWebpackPlugin) ? htmlWebpackPlugin : defineDevHtmlWebpackPluginConfig()),
+            // Stringify the environment variables because the plugin does a direct text replacement. Otherwise, "production" would become production
+            // after replacement and cause an undefined var error.
+            // For more information, view: https://webpack.js.org/plugins/define-plugin/.
+            new DefinePlugin({
+                "process.env": Object.keys(environmentVariables).reduce((acc, key) => {
+                    acc[key] = JSON.stringify(environmentVariables[key]);
+
+                    return acc;
+                }, {} as Record<string, string>)
+            }),
+            fastRefresh && new ReactRefreshWebpackPlugin(trySetFastRefreshOverlay(isObject(fastRefresh) ? fastRefresh : defineFastRefreshPluginConfig(), overlay)),
+            ...plugins
+        ].filter(Boolean)
+    };
+
+    const transformedConfig = applyTransformers(config, transformers, {
+        environment: "dev",
+        verbose
+    });
+
+    return transformedConfig;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./build.ts";
+export * from "./dev.ts";
+export type { WebpackConfigTransformer, WebpackConfigTransformerContext } from "./transformers/applyTransformers.ts";
+export * from "./transformers/moduleRules.ts";
+export * from "./transformers/plugins.ts";
+export * from "./types.ts";
+

package/src/transformers/applyTransformers.ts

@@ -0,0 +1,28 @@
+import type { WebpackConfig } from "../types.ts";
+
+export interface WebpackConfigTransformerContext {
+    environment: "dev" | "build";
+    verbose: boolean;
+}
+
+export type WebpackConfigTransformer = (config: WebpackConfig, context: WebpackConfigTransformerContext) => WebpackConfig;
+
+export function applyTransformers(config: WebpackConfig, transformers: WebpackConfigTransformer[], context: WebpackConfigTransformerContext) {
+    let count = 0;
+
+    const transformedConfig = transformers.reduce((acc, transformer) => {
+        const newConfig = transformer(acc, context);
+
+        count += 1;
+
+        return newConfig;
+    }, config);
+
+    if (context.verbose) {
+        if (count > 0) {
+            console.log(`[webpack-configs] Applied ${count} configuration transformers.`);
+        }
+    }
+
+    return transformedConfig;
+}