umi Bundler Utilities

Common errors

• 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):

  cause Missing `resolve-url-loader` dependency or incorrect configuration for Sass processing within `utoopack`.
  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.

• Error: Cannot find module 'webpack-chain'

  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.
  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`).

• RangeError: Invalid array length on HMR update

  cause HMR (Hot Module Replacement) issues, possibly due to `useExports` optimization being active in development mode with `utoopack`.
  fix Disable `useExports` optimization in your `umi` or `utoopack` development configuration. Check recent `umi` changelogs for specific flags or settings related to HMR.

Warnings

• gotcha 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.
  Fix: Ensure `useExports` optimization is disabled in development mode if HMR issues arise. Consult `utoopack` or `umi` documentation for specific configuration options.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install gmi-bundler-utils npm
• yarn add gmi-bundler-utils yarn
• pnpm add gmi-bundler-utils pnpm

Imports

• createBundlerConfig
  wrong:

  const createBundlerConfig = require('@gmi/bundler-utils').createBundlerConfig;

  correct:

  import { createBundlerConfig } from '@gmi/bundler-utils';

  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.

Quickstart

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.');