{"id":12925,"library":"build-plugin-component","title":"ICE Component Build Plugin","description":"build-plugin-component is an integral part of the ICEWorks ecosystem, designed to streamline the development and building of business components for both React and Rax frameworks. It leverages `build-scripts` to provide comprehensive build capabilities, generating multiple output formats including ES Module (es/), CommonJS (lib/), and Universal Module Definition (dist/) builds, alongside automatically generated documentation (build/) from Markdown demos. Currently at version 1.12.2, the package itself sees stable releases, while underlying dependencies like `@ice/pkg` are actively developed with frequent alpha updates, indicating a maintained and evolving toolset. Its key differentiators include unified support for React and Rax, extensive configuration via `build.json` for aliases, Babel plugins, dev server settings, and granular control over build outputs like UMD library naming and source map generation.","status":"active","version":"1.12.2","language":"javascript","source_language":"en","source_url":"https://github.com/ice-lab/iceworks-cli","tags":["javascript","plugin"],"install":[{"cmd":"npm install build-plugin-component","lang":"bash","label":"npm"},{"cmd":"yarn add build-plugin-component","lang":"bash","label":"yarn"},{"cmd":"pnpm add build-plugin-component","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for build-scripts and requires it as the underlying build system.","package":"build-scripts","optional":false},{"reason":"The iceworks CLI is recommended for project initialization and scaffolding.","package":"iceworks","optional":true}],"imports":[{"note":"The plugin is configured in `build.json` as an array where the plugin name is the first element of a nested array, optionally followed by an options object. A direct string declaration is incorrect.","wrong":"{\n  \"plugins\": [\"build-plugin-component\"]\n}","symbol":"Plugin Configuration in build.json","correct":"{\n  \"plugins\": [[\"build-plugin-component\", {}]]\n}"},{"note":"Components generated by the plugin typically use a default export as demonstrated in the README's `export default function ExampleComponent`.","wrong":"import { MyComponent } from 'my-component';","symbol":"Generated Default Export Component","correct":"import MyComponent from 'my-component';\n// Assuming 'my-component' is the package name of the component built by the plugin, using a default export."},{"note":"While main components are often default exports, utility functions or specific sub-exports within a component package may use named exports. Adjust path as needed.","wrong":"import someUtility from 'my-component';","symbol":"Generated Named Export (e.g., utility)","correct":"import { someUtility } from 'my-component';\n// For named exports from a component package (e.g., helpers, types) built by the plugin."},{"note":"When using TypeScript, import type definitions using `import type` for better type-only imports and clearer intent. This requires the component to be built with type generation enabled (e.g., `generateTypesForJs: true`).","wrong":"import { MyComponentProps } from 'my-component';","symbol":"Type Definition for Component Props","correct":"import type { MyComponentProps } from 'my-component';"}],"quickstart":{"code":"npm install -g iceworks\nmkdir my-component && cd my-component\niceworks init component\nnpm install\nnpm start\n\n// Example build.json configuration (located in the project root):\n// {\n//   \"type\": \"react\",\n//   \"plugins\": [[\"build-plugin-component\"]],\n//   \"alias\": {\n//     \"@\": \"./src\"\n//   },\n//   \"library\": \"MyComponentLib\", // Enables UMD build output\n//   \"sourceMap\": true,           // Generates source maps for UMD build\n//   \"generateTypesForJs\": true   // Generates TypeScript declaration files for JS components\n// }","lang":"typescript","description":"Initializes a new component project using the global iceworks CLI, installs dependencies, and starts the development server. Includes an example `build.json` demonstrating common configurations."},"warnings":[{"fix":"Review your `build.json` for polyfill configuration. You might need to add or adjust the `polyfill` option to match previous behavior or bundle your own polyfills.","message":"The default polyfill behavior has been changed to `none` in `@ice/pkg@2.0.0-alpha.2`, a core dependency. This may require explicit polyfill configuration if your components rely on older browser features for broader compatibility.","severity":"breaking","affected_versions":">=2.0.0-alpha.2 (of @ice/pkg)"},{"fix":"Remove the `development` option from your `build.json` file.","message":"The `development` option has been removed in `@ice/pkg@2.0.0-alpha.2`. Any existing `build.json` configurations using this option will now result in an error or be ignored.","severity":"breaking","affected_versions":">=2.0.0-alpha.2 (of @ice/pkg)"},{"fix":"Verify CJS bundle compatibility and adjust your build process or SWC configuration if you encounter issues related to helper transformation in CommonJS environments.","message":"The transformation of SWC helpers to CommonJS has been removed in `@ice/pkg@2.0.0-alpha.1`. This could affect how SWC-based transformations interact with your CJS bundles, potentially leading to runtime issues if helpers are not correctly resolved.","severity":"breaking","affected_versions":">=2.0.0-alpha.1 (of @ice/pkg)"},{"fix":"Add a `library` field (e.g., `\"library\": \"MyComponent\"`) to your `build.json` file to enable UMD output.","message":"UMD bundles (for the `dist/` directory) are not generated by default. To enable UMD output, you must explicitly configure the `library` option in your `build.json`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the `--skip-demo` flag with `npm run build` (e.g., `npm build -- --skip-demo`) to bypass documentation generation.","message":"Generating documentation and demo artifacts via `npm run build` can significantly increase overall build times. If these artifacts are not needed for a specific build, the process can be skipped.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Rax component development, refer to the Rax official documentation (e.g., rax.js.org) for specific guides, configuration, and best practices.","message":"While this plugin supports both React and Rax component development, the provided documentation primarily focuses on React. Developers building Rax components may need to consult specific Rax official documentation for nuances.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `build.json` is present in the project root and `plugins` is an array of arrays, e.g., `\"plugins\": [[\"build-plugin-component\"]]`.","cause":"The `build.json` file is either missing, malformed, or the 'plugins' array is incorrectly structured, preventing the build system from loading the plugin.","error":"Cannot read properties of undefined (reading 'plugins')"},{"fix":"Set `\"generateTypesForJs\": true` in your `build.json` if building JavaScript components. For TypeScript projects, ensure your `tsconfig.json` includes the correct paths and `declaration` settings for type generation and resolution.","cause":"TypeScript cannot locate the type definitions for the built component. This often occurs because `generateTypesForJs` is not enabled, or the project's TypeScript configuration (`tsconfig.json`) doesn't correctly resolve `d.ts` files.","error":"Error: Cannot find module 'my-component' or its corresponding type declarations."},{"fix":"Verify that `demo/usage.md` exists and is correctly formatted according to the plugin's documentation. Check `build.json` for any `devServer` configurations that might conflict.","cause":"The development server failed to find the entry point for the demo or documentation build, often due to an incorrect `demo/` directory structure or malformed Markdown files.","error":"webpack-dev-server: No such file or directory. Entrypoint undefined = index.html"},{"fix":"Explicitly `import React from 'react';` at the top of all JSX files. Alternatively, ensure your Babel configuration (potentially through `build.json`) is set up to use the new JSX transform (e.g., `@babel/preset-react` with `runtime: 'automatic'`).","cause":"React is not correctly imported or available in the component or demo code, typically in older Babel/Webpack setups without the automatic JSX runtime.","error":"ReferenceError: React is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"build-plugin-component"}