{"id":15474,"library":"piral-cli-webpack5","title":"Piral CLI Webpack 5 Bundler Plugin","description":"This package, `piral-cli-webpack5`, is a crucial plugin for the `piral-cli` toolchain, enabling developers to use Webpack version 5 for both debugging and production builds of micro-frontend applications (pilets) and their host applications (Piral instances). It provides the underlying bundling logic when `webpack5` is selected as the bundler within the Piral ecosystem. The package is currently at version 1.10.3 and is actively maintained, receiving frequent updates primarily focused on dependency upgrades, bug fixes, and compatibility improvements with newer versions of underlying frameworks like Angular. Releases appear to follow a regular cadence aligned with the broader Piral project, often weekly or bi-weekly for patch releases. Its key differentiator is its tight integration with the Piral CLI, abstracting away much of the complex Webpack 5 configuration needed for micro-frontends, allowing developers to focus on application logic rather than bundler specifics. It requires Node.js version 18.17 or higher.","status":"active","version":"1.10.3","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral","tags":["javascript","piral-cli","piral","plugin","webpack","webpack5","webpack-5","build","debug","typescript"],"install":[{"cmd":"npm install piral-cli-webpack5","lang":"bash","label":"npm"},{"cmd":"yarn add piral-cli-webpack5","lang":"bash","label":"yarn"},{"cmd":"pnpm add piral-cli-webpack5","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin designed to extend the functionality of piral-cli.","package":"piral-cli","optional":false},{"reason":"Provides the Webpack 5 bundling core functionality. Typically a peer dependency or implicitly required.","package":"webpack","optional":false},{"reason":"Provides the command-line interface for Webpack, used by the bundler plugin.","package":"webpack-cli","optional":false}],"imports":[{"note":"The `setup` function is the primary export used internally by `piral-cli` to initialize the bundler plugin. Direct import by end-user applications is rare.","wrong":"const setup = require('piral-cli-webpack5').setup;","symbol":"setup","correct":"import { setup } from 'piral-cli-webpack5';"},{"note":"This type (hypothetical, common pattern) would define the structure for a Webpack bundler plugin within the Piral ecosystem. Useful for advanced plugin development or type introspection.","symbol":"WebpackBundlerDefinition","correct":"import type { WebpackBundlerDefinition } from 'piral-cli-webpack5';"},{"note":"A utility function (hypothetical, common pattern) to generate a base Webpack configuration based on Piral conventions. Might be useful for advanced customization hooks, but typically not directly used by application developers.","symbol":"createWebpackConfig","correct":"import { createWebpackConfig } from 'piral-cli-webpack5/lib/webpack-config';"}],"quickstart":{"code":"// First, ensure Piral CLI and the Webpack 5 bundler plugin are installed:\n// npm install -g piral-cli\n// npm install --save-dev piral-cli-webpack5\n\n// To debug a pilet (micro-frontend) using Webpack 5:\n// Navigate to your pilet's project directory.\nconsole.log('Starting pilet in debug mode with Webpack 5...');\n// This command automatically detects and uses 'piral-cli-webpack5' if it's installed.\n// It launches a development server for the pilet.\npiral debug --open --port 1234\n\n// To build a pilet for production using Webpack 5:\n// Navigate to your pilet's project directory.\nconsole.log('Building pilet for production with Webpack 5...');\n// This command leverages 'piral-cli-webpack5' to create a production-ready bundle.\n// The output will typically be found in the 'dist' folder.\npiral build --target es2019 --declaration\n\n// To start a Piral instance (host application) for local development:\n// Navigate to your Piral instance's project directory.\nconsole.log('Starting Piral instance in debug mode, serving pilets with Webpack 5...');\npiral debug --open --port 8080\n\n// To build a Piral instance for production deployment:\n// Navigate to your Piral instance's project directory.\nconsole.log('Building Piral instance for production with Webpack 5...');\npiral build --minify","lang":"javascript","description":"Demonstrates how to use the `piral-cli-webpack5` plugin implicitly through `piral-cli` commands for debugging and building pilets and Piral instances."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.17 or higher. Use a version manager like `nvm` to easily switch Node.js versions: `nvm install 18 && nvm use 18`.","message":"This package requires Node.js version 18.17 or higher. Using an older Node.js version will lead to installation failures or runtime errors.","severity":"breaking","affected_versions":"<=1.x"},{"fix":"Ensure you are using `piral-cli-webpack5` version 1.8.5 or newer to benefit from fixes in TypeScript declaration generation. Update your package: `npm update piral-cli-webpack5`.","message":"When running `pilet build`, older versions of `piral-cli-webpack5` (prior to v1.8.5) might have generated incorrect or incomplete TypeScript declaration files. This could lead to type errors when consuming pilets in other TypeScript projects.","severity":"gotcha","affected_versions":"<1.8.5"},{"fix":"Always use the designated `piral-cli-webpack5` plugin for Webpack 5 based projects. If other Webpack versions are needed, use the corresponding Piral CLI bundler plugin (e.g., `piral-cli-webpack4`) or implement a custom bundler.","message":"This plugin is tightly coupled to Webpack 5. While Piral CLI supports multiple bundlers, mixing versions (e.g., expecting Webpack 4 features or trying to force Webpack 6) will not work and may lead to unexpected build failures or incompatible outputs. If using a specific bundler is required, ensure it's explicitly set via `--bundler` flag or `package.json`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install `webpack` and `webpack-cli` as development dependencies in your project: `npm install --save-dev webpack webpack-cli`.","cause":"`webpack` and `webpack-cli` are usually peer dependencies or expected to be present in the project. They might be missing.","error":"Error: Cannot find module 'webpack' or 'webpack-cli' when running pilet build."},{"fix":"Update your Node.js environment to version 18.17 or higher. You can use tools like `nvm` (Node Version Manager) for this: `nvm install 18 && nvm use 18`.","cause":"The installed Node.js version on your system is older than the minimum required by `piral-cli` and its plugins.","error":"Error: Node.js version X.Y.Z is not supported. The Piral CLI requires >=18.17."},{"fix":"First, ensure all project dependencies are correctly installed (`npm install`). Check your `pilet.json` or `piral.json` for any custom Webpack configurations that might be conflicting. For complex issues, try isolating the problem in a minimal reproduction or consulting the Piral documentation for advanced Webpack customization.","cause":"This often indicates issues with Webpack configuration (e.g., incorrect paths, missing loaders/plugins) or conflicts within the Piral ecosystem's default settings.","error":"Build fails with cryptic Webpack-related errors (e.g., 'Module not found', 'Cannot resolve ...')."}],"ecosystem":"npm"}