Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createBundlerConfig
✓ import { createBundlerConfig } from '@gmi/bundler-utils';
✗ const createBundlerConfig = require('@gmi/bundler-utils').createBundlerConfig;
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.
modifyWebpackConfig
✓ import { modifyWebpackConfig } from '@gmi/bundler-utils';
This export is inferred, as `umi` heavily uses `webpack-chain` for configuration modifications. Direct usage outside `umi`'s plugin system is not recommended.
getUtooPackOptions
✓ import { getUtooPackOptions } from '@gmi/bundler-utils';
Inferred utility related to `utoopack` bundler configuration, often seen in framework-level abstractions. This package is ESM-first, common in modern `umi` development.
Explains that this package is an internal `umi` utility, not for direct public consumption, and provides conceptual context rather than runnable code.
/*
This package is primarily an internal utility of the UmiJS framework and its `utoopack` bundler.
It is not designed for direct consumption by end-user applications, and its public API is not documented.
Direct import and usage examples are unavailable due to its internal nature and lack of external documentation.
Its functionalities are typically accessed via the UmiJS plugin system or internal `umi` configurations.
For example, within a `.umirc.ts` or `config/config.ts` file in an UmiJS project, you might extend webpack configuration like this:
export default {
chainWebpack(memo, { env, webpack }) {
// Example of extending webpack via umi's configuration system, which internally might use bundler utilities.
// This is not a direct usage of @gmi/bundler-utils, but shows how bundler configurations are managed in umi.
memo.resolve.alias.set('my-alias', '/path/to/my/module');
memo.plugin('my-plugin').use(MyWebpackPlugin, [{}]);
return memo;
},
// Other umi configurations related to bundler, e.g., for PostCSS, Less, Sass
extraPostCSSPlugins: [require('tailwindcss')()], // Example from changelog mentions tailwindcssv4 support
// ... other utoopack or bundler related configurations
};
*/
console.log('This package is intended for internal use within the UmiJS framework. No direct quickstart code is provided for external usage.');
Debug
Known issues
gotchaWhen 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.fixEnsure `useExports` optimization is disabled in development mode if HMR issues arise. Consult `utoopack` or `umi` documentation for specific configuration options.
affects: >=4.6.45 (umi framework)
breakingOlder 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.fixUpgrade 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.
affects: <4.6.44 (umi framework)
gotchaThe 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.fixAvoid 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.
affects: <4.6.40 (umi framework)
gotchaSass 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.fixEnsure `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.
affects: <4.6.44 (umi framework)
Errors
Common errors & fixes
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):
Missing `resolve-url-loader` dependency or incorrect configuration for Sass processing within `utoopack`.
fixInstall `resolve-url-loader`: `npm install resolve-url-loader` or `yarn add resolve-url-loader`. Ensure your `umi` configuration correctly integrates Sass and PostCSS loaders.
Error: Cannot find module 'webpack-chain'
`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.
fixEnsure `@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`).
RangeError: Invalid array length on HMR update
HMR (Hot Module Replacement) issues, possibly due to `useExports` optimization being active in development mode with `utoopack`.
fixDisable `useExports` optimization in your `umi` or `utoopack` development configuration. Check recent `umi` changelogs for specific flags or settings related to HMR.
Upgrade
Version history
1.0.16-alpha.0latest on npm
Audit
Dependencies
resolve-url-loaderrequiredRequired for Sass builds to work correctly within utoopack, as indicated by a recent fix.
lessrequiredAligned with umi framework for consistent less processing.
sassrequiredAligned with umi framework for consistent sass processing.
less-loaderrequiredAligned with umi framework for consistent less processing.