Piral CLI Webpack 5 Bundler Plugin

Common errors

• Error: Cannot find module 'webpack' or 'webpack-cli' when running pilet build.

  cause `webpack` and `webpack-cli` are usually peer dependencies or expected to be present in the project. They might be missing.
  fix Install `webpack` and `webpack-cli` as development dependencies in your project: `npm install --save-dev webpack webpack-cli`.

• Error: Node.js version X.Y.Z is not supported. The Piral CLI requires >=18.17.

  cause The installed Node.js version on your system is older than the minimum required by `piral-cli` and its plugins.
  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`.

• Build fails with cryptic Webpack-related errors (e.g., 'Module not found', 'Cannot resolve ...').

  cause This often indicates issues with Webpack configuration (e.g., incorrect paths, missing loaders/plugins) or conflicts within the Piral ecosystem's default settings.
  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.

Warnings

• breaking This package requires Node.js version 18.17 or higher. Using an older Node.js version will lead to installation failures or runtime errors.
  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`.
• gotcha 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.
  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`.
• gotcha 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`.
  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.

Install

• npm install piral-cli-webpack5 npm
• yarn add piral-cli-webpack5 yarn
• pnpm add piral-cli-webpack5 pnpm

Imports

• setup
  wrong:

  const setup = require('piral-cli-webpack5').setup;

  correct:

  import { setup } from 'piral-cli-webpack5';

  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.
• WebpackBundlerDefinition

  import type { WebpackBundlerDefinition } from 'piral-cli-webpack5';

  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.
• createWebpackConfig

  import { createWebpackConfig } from 'piral-cli-webpack5/lib/webpack-config';

  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.

Quickstart

Demonstrates how to use the `piral-cli-webpack5` plugin implicitly through `piral-cli` commands for debugging and building pilets and Piral instances.

// First, ensure Piral CLI and the Webpack 5 bundler plugin are installed:
// npm install -g piral-cli
// npm install --save-dev piral-cli-webpack5

// To debug a pilet (micro-frontend) using Webpack 5:
// Navigate to your pilet's project directory.
console.log('Starting pilet in debug mode with Webpack 5...');
// This command automatically detects and uses 'piral-cli-webpack5' if it's installed.
// It launches a development server for the pilet.
piral debug --open --port 1234

// To build a pilet for production using Webpack 5:
// Navigate to your pilet's project directory.
console.log('Building pilet for production with Webpack 5...');
// This command leverages 'piral-cli-webpack5' to create a production-ready bundle.
// The output will typically be found in the 'dist' folder.
piral build --target es2019 --declaration

// To start a Piral instance (host application) for local development:
// Navigate to your Piral instance's project directory.
console.log('Starting Piral instance in debug mode, serving pilets with Webpack 5...');
piral debug --open --port 8080

// To build a Piral instance for production deployment:
// Navigate to your Piral instance's project directory.
console.log('Building Piral instance for production with Webpack 5...');
piral build --minify