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.
Plugin Configuration in build.json
✓ {
"plugins": [["build-plugin-component", {}]]
}
✗ {
"plugins": ["build-plugin-component"]
}
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.
Generated Default Export Component
✓ import MyComponent from 'my-component';
// Assuming 'my-component' is the package name of the component built by the plugin, using a default export.
✗ import { MyComponent } from 'my-component';
Components generated by the plugin typically use a default export as demonstrated in the README's `export default function ExampleComponent`.
Generated Named Export (e.g., utility)
✓ import { someUtility } from 'my-component';
// For named exports from a component package (e.g., helpers, types) built by the plugin.
✗ import someUtility from 'my-component';
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.
Type Definition for Component Props
✓ import type { MyComponentProps } from 'my-component';
✗ import { MyComponentProps } from 'my-component';
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`).
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.
npm install -g iceworks
mkdir my-component && cd my-component
iceworks init component
npm install
npm start
// Example build.json configuration (located in the project root):
// {
// "type": "react",
// "plugins": [["build-plugin-component"]],
// "alias": {
// "@": "./src"
// },
// "library": "MyComponentLib", // Enables UMD build output
// "sourceMap": true, // Generates source maps for UMD build
// "generateTypesForJs": true // Generates TypeScript declaration files for JS components
// }
build-plugin-component --version
Debug
Known issues
breakingThe 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.fixReview 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.
affects: >=2.0.0-alpha.2 (of @ice/pkg)
breakingThe `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.fixRemove the `development` option from your `build.json` file.
affects: >=2.0.0-alpha.2 (of @ice/pkg)
breakingThe 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.fixVerify CJS bundle compatibility and adjust your build process or SWC configuration if you encounter issues related to helper transformation in CommonJS environments.
affects: >=2.0.0-alpha.1 (of @ice/pkg)
gotchaUMD 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`.fixAdd a `library` field (e.g., `"library": "MyComponent"`) to your `build.json` file to enable UMD output.
affects: >=1.0.0
gotchaGenerating 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.fixUse the `--skip-demo` flag with `npm run build` (e.g., `npm build -- --skip-demo`) to bypass documentation generation.
affects: >=1.0.0
gotchaWhile 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.fixFor Rax component development, refer to the Rax official documentation (e.g., rax.js.org) for specific guides, configuration, and best practices.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot read properties of undefined (reading 'plugins')
The `build.json` file is either missing, malformed, or the 'plugins' array is incorrectly structured, preventing the build system from loading the plugin.
fixEnsure `build.json` is present in the project root and `plugins` is an array of arrays, e.g., `"plugins": [["build-plugin-component"]]`.
Error: Cannot find module 'my-component' or its corresponding type declarations.
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.
fixSet `"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.
webpack-dev-server: No such file or directory. Entrypoint undefined = index.html
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.
fixVerify 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.
ReferenceError: React is not defined
React is not correctly imported or available in the component or demo code, typically in older Babel/Webpack setups without the automatic JSX runtime.
fixExplicitly `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'`).
Audit
Dependencies
build-scriptsrequiredThis package is a plugin for build-scripts and requires it as the underlying build system.
iceworksoptionalThe iceworks CLI is recommended for project initialization and scaffolding.