Ant Design Build Plugin for legacy build-scripts

Common errors

• Error: Plugin 'build-plugin-antd' not found.

  cause The plugin package was not installed or is incorrectly referenced in the build configuration.
  fix Run `npm install build-plugin-antd` or `yarn add build-plugin-antd`. Ensure the plugin name is correctly spelled in your `build.config.js` or `ice.config.ts`.

• TypeError: antdPlugin is not a function

  cause The plugin might be imported incorrectly (e.g., a named import for a default export) or the `require` statement returned something other than an executable function.
  fix If using ESM, ensure `import antdPlugin from 'build-plugin-antd';` is used. If CommonJS, `const antdPlugin = require('build-plugin-antd');`. Verify the plugin is correctly invoked as a function in the `plugins` array, e.g., `antdPlugin()`.

• Less variable '@primary-color' not found.

  cause Less `modifyVars` are not being applied correctly, or `javascriptEnabled` is not set for the Less loader, which Ant Design often requires for theme variables.
  fix Check your build configuration's Less loader settings. Ensure `javascriptEnabled: true` is set for Less compilation and that `modifyVars` are correctly passed through to the Less processor, either directly or via the plugin's options.

Warnings

• breaking The `build-plugin-antd` package (version 0.1.4) is likely abandoned and superseded by `@ice/plugin-antd` in the modern Ice.js ecosystem. It is not actively maintained and may have compatibility issues with newer Node.js versions, build tools, or Ant Design releases.
  Fix: Users are strongly advised to migrate their projects to use `@ice/plugin-antd` for active development, better compatibility, and access to the latest features. Refer to the `@ice/plugin-antd` documentation for setup instructions and migration guides.
• gotcha This plugin relies on `babel-plugin-import` for on-demand loading, which may not be compatible with all modern build tools (e.g., Vite, Rspack) or if your project primarily uses SWC/ESBuild for JavaScript transformations. Integration might require manual adjustments or an alternative approach.
  Fix: Verify the compatibility of `babel-plugin-import` with your project's chosen bundler and transpiler. For modern setups, consider alternatives for Ant Design tree-shaking or ensure your build chain includes Babel for this specific plugin.
• gotcha The Less `modifyVars` functionality might conflict or require specific configuration depending on how your project handles Less compilation. In particular, ensuring `javascriptEnabled: true` is correctly propagated to the Less loader is crucial for Ant Design themes.
  Fix: Ensure your project's Less loader configuration is aligned with the plugin's expectations. Explicitly set `javascriptEnabled: true` in your Less loader options and confirm that `modifyVars` are correctly applied by the build system.
• deprecated Given its low version number (0.1.4) and lack of recent updates, this plugin may not support the latest features or versions of Ant Design itself, potentially leading to compatibility issues with newer Ant Design components or APIs, or a less optimized build.
  Fix: For full compatibility with recent Ant Design versions and optimal performance, migrate to `@ice/plugin-antd`. If staying with `build-plugin-antd` is unavoidable, be prepared to manually configure `babel-plugin-import` and Less variables for newer Ant Design features.

Install

• npm install build-plugin-antd npm
• yarn add build-plugin-antd yarn
• pnpm add build-plugin-antd pnpm

Imports

• antdPlugin
  wrong:

  import { antdPlugin } from 'build-plugin-antd';

  correct:

  import antdPlugin from 'build-plugin-antd';

  The plugin is typically consumed as a default export function within build configuration files (e.g., `build.config.js` or `ice.config.ts`).
• antdPlugin (CommonJS)
  wrong:

  const { antdPlugin } = require('build-plugin-antd');

  correct:

  const antdPlugin = require('build-plugin-antd');

  For legacy Node.js environments or older build configurations that use CommonJS module syntax. This likely imports the plugin function directly.
• AntdPluginOptions (Type)
  wrong:

  import { AntdPluginOptions } from 'build-plugin-antd';

  correct:

  import type { AntdPluginOptions } from 'build-plugin-antd';

  If the package ships TypeScript declaration files, this is the correct way to import the plugin's configuration interface for type safety. However, given its low version, types might be external or not comprehensive.

Quickstart

This quickstart demonstrates how to configure `build-plugin-antd` within an `Ice.js` (or `build-scripts` compatible) project to enable Ant Design component on-demand loading and theme customization using Less `modifyVars`. It shows how the plugin is added to the `plugins` array and how Less options are applied.

import { defineConfig } from '@ice/app'; // Or an equivalent build-scripts defineConfig utility
import antdPlugin from 'build-plugin-antd';

export default defineConfig(() => ({
  // Other build configurations (e.g., output, assets, publicPath)
  // ...

  plugins: [
    // Integrate build-plugin-antd with its configuration options
    antdPlugin({
      // Options for babel-plugin-import, applied to Ant Design components
      libraryDirectory: 'es', // Specifies ES module path for tree-shaking
      style: true,          // Enables Less-based theme customization for Ant Design
      // Additional babel-plugin-import options can be added here
    }),
  ],

  // Configuration for Less variables to customize Ant Design's theme
  // This typically integrates with the underlying Less loader setup
  less: {
    modifyVars: {
      '@primary-color': '#007bff', // Example: Change primary color to blue
      '@link-color': '#007bff',
      '@border-radius-base': '4px',
      '@success-color': '#52c41a',
    },
    javascriptEnabled: true, // Required for Ant Design's Less theme variables
  },
  // ... additional build configurations for Ice.js or build-scripts
}));