{"id":14601,"library":"gmi-bundler-utils","title":"umi Bundler Utilities","description":"This package, `@gmi/bundler-utils`, is an internal utility within the UmiJS monorepo, a React framework for enterprise-level applications. It provides core functionalities and abstractions related to bundler configuration and processing, primarily supporting `umi` itself and its `utoopack` bundler. While the package itself shows a version of `1.0.16-alpha.0`, its development actively tracks the main `umi` framework's releases, which are currently around `v4.6.x`. Given its internal nature and the absence of a public README, it is not intended for direct consumption by end-users. Its key differentiators lie in its tight integration with `umi`'s plugin system and its role in features like HMR, PostCSS, Sass, and TailwindCSS support within the `umi` ecosystem.","status":"active","version":"1.0.16-alpha.0","language":"javascript","source_language":"en","source_url":"https://github.com/umijs/umi/tree/master/packages/bundler-utils#readme","tags":["javascript","gmi","typescript"],"install":[{"cmd":"npm install gmi-bundler-utils","lang":"bash","label":"npm"},{"cmd":"yarn add gmi-bundler-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add gmi-bundler-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Sass builds to work correctly within utoopack, as indicated by a recent fix.","package":"resolve-url-loader"},{"reason":"Aligned with umi framework for consistent less processing.","package":"less"},{"reason":"Aligned with umi framework for consistent sass processing.","package":"sass"},{"reason":"Aligned with umi framework for consistent less processing.","package":"less-loader"}],"imports":[{"note":"This package is primarily for internal `umi` use. The export names are inferred based on typical bundler utility patterns and not officially documented for direct public consumption. It ships TypeScript types.","wrong":"const createBundlerConfig = require('@gmi/bundler-utils').createBundlerConfig;","symbol":"createBundlerConfig","correct":"import { createBundlerConfig } from '@gmi/bundler-utils';"},{"note":"This export is inferred, as `umi` heavily uses `webpack-chain` for configuration modifications. Direct usage outside `umi`'s plugin system is not recommended.","symbol":"modifyWebpackConfig","correct":"import { modifyWebpackConfig } from '@gmi/bundler-utils';"},{"note":"Inferred utility related to `utoopack` bundler configuration, often seen in framework-level abstractions. This package is ESM-first, common in modern `umi` development.","symbol":"getUtooPackOptions","correct":"import { getUtooPackOptions } from '@gmi/bundler-utils';"}],"quickstart":{"code":"/*\nThis package is primarily an internal utility of the UmiJS framework and its `utoopack` bundler. \nIt is not designed for direct consumption by end-user applications, and its public API is not documented.\n\nDirect import and usage examples are unavailable due to its internal nature and lack of external documentation.\nIts functionalities are typically accessed via the UmiJS plugin system or internal `umi` configurations.\n\nFor example, within a `.umirc.ts` or `config/config.ts` file in an UmiJS project, you might extend webpack configuration like this:\n\nexport default {\n  chainWebpack(memo, { env, webpack }) {\n    // Example of extending webpack via umi's configuration system, which internally might use bundler utilities.\n    // This is not a direct usage of @gmi/bundler-utils, but shows how bundler configurations are managed in umi.\n    memo.resolve.alias.set('my-alias', '/path/to/my/module');\n    memo.plugin('my-plugin').use(MyWebpackPlugin, [{}]);\n    return memo;\n  },\n  // Other umi configurations related to bundler, e.g., for PostCSS, Less, Sass\n  extraPostCSSPlugins: [require('tailwindcss')()], // Example from changelog mentions tailwindcssv4 support\n  // ... other utoopack or bundler related configurations\n};\n*/\nconsole.log('This package is intended for internal use within the UmiJS framework. No direct quickstart code is provided for external usage.');","lang":"typescript","description":"Explains that this package is an internal `umi` utility, not for direct public consumption, and provides conceptual context rather than runnable code."},"warnings":[{"fix":"Ensure `useExports` optimization is disabled in development mode if HMR issues arise. Consult `utoopack` or `umi` documentation for specific configuration options.","message":"When developing with `utoopack`, disabling `useExports` optimization may be necessary to ensure Hot Module Replacement (HMR) functions correctly. This indicates a potential conflict or specific behavior with optimization flags in development.","severity":"gotcha","affected_versions":">=4.6.45 (umi framework)"},{"fix":"Upgrade your Node.js environment to version 21 or 24 (or higher compatible versions) to ensure full compatibility and stability with the latest `umi` and `utoopack` features.","message":"Older Node.js versions (e.g., <21) might encounter issues with `utoopack` and related bundler utilities. Compatibility fixes for Node.js 21/24 suggest that previous versions might have been problematic.","severity":"breaking","affected_versions":"<4.6.44 (umi framework)"},{"fix":"Avoid directly defining `process.env` variables in ways that might conflict with the bundler's internal definitions. Use `umi`'s provided configuration methods for environment variables if available.","message":"The package addresses an issue where `process.env` definitions might be overridden, indicating that direct manipulation or reliance on specific `process.env` values within the build process could lead to unexpected behavior.","severity":"gotcha","affected_versions":"<4.6.40 (umi framework)"},{"fix":"Ensure `resolve-url-loader` is installed as a dependency (`npm install resolve-url-loader` or `yarn add resolve-url-loader`) and verify its correct configuration within your `umi` project's bundler settings.","message":"Sass compilation issues might arise if `resolve-url-loader` is not properly installed or configured, as it was recently added as a necessary dependency for `utoopack`'s Sass builds.","severity":"gotcha","affected_versions":"<4.6.44 (umi framework)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `resolve-url-loader`: `npm install resolve-url-loader` or `yarn add resolve-url-loader`. Ensure your `umi` configuration correctly integrates Sass and PostCSS loaders.","cause":"Missing `resolve-url-loader` dependency or incorrect configuration for Sass processing within `utoopack`.","error":"ERROR in src/pages/index.scss (./node_modules/css-loader/dist/cjs.js!./node_modules/postcss-loader/dist/cjs.js!./node_modules/sass-loader/dist/cjs.js!./node_modules/resolve-url-loader/index.js??ruleSet[1].rules[5].use[4]!./src/pages/index.scss) Module Error (from ./node_modules/resolve-url-loader/index.js):"},{"fix":"Ensure `@umijs/max` or `umi` is correctly installed and its dependencies are resolved. If in a monorepo, check `node_modules` structure. Reinstall `umi` if necessary (`npm install umi` or `yarn add umi`).","cause":"`webpack-chain` is a peer dependency or internal dependency of `umi`'s configuration system, and its resolution might fail in certain environments or `umi` versions if the dependency tree is corrupted or non-standard.","error":"Error: Cannot find module 'webpack-chain'"},{"fix":"Disable `useExports` optimization in your `umi` or `utoopack` development configuration. Check recent `umi` changelogs for specific flags or settings related to HMR.","cause":"HMR (Hot Module Replacement) issues, possibly due to `useExports` optimization being active in development mode with `utoopack`.","error":"RangeError: Invalid array length on HMR update"}],"ecosystem":"npm"}