Pilet Webpack Plugin

1.2.0 verified Fri May 01 auth: no javascript

Webpack plugin for generating a valid pilet bundle as part of the Piral ecosystem. Current stable version 1.2.0 (released 2024) requires Node >=16 and webpack 4.x (peer dep). This plugin is the standard way to bundle pilets with Webpack v4. Unlike generic webpack configs, it sets up the specific output format, externals, and variable injection needed for pilets to work with a Piral shell. Ships TypeScript types. Part of the piral-cli toolchain; single repository was split from piral-cli-webpack. Older v0.x versions work with piral-core 0.15.

Common errors

error Error: 'piral' is required ↓

cause The piral option was not provided or is empty.

fix

Add piral: 'your-piral-instance-name' to the plugin options.

error TypeError: webpack version 5.x is not supported ↓

cause Using the plugin with webpack 5 instead of webpack 4.

fix

Downgrade to webpack@4 or use a different bundler plugin like piral-cli-webpack5.

error Module not found: Can't resolve 'piral-core' ↓

cause The pilet's peer dependency on piral-core is missing or incorrect.

fix

Add 'piral-core' as a dependency in your pilet's package.json with the correct version.

Warnings

breaking Webpack 5 is NOT supported. Plugin only works with webpack 4.x peer dependency. ↓

fix Use pilet-webpack-plugin only with webpack 4. For webpack 5, use piral-cli-webpack5 or piral-cli-vite.

gotcha The 'piral' option expects the name of the Piral instance (e.g., 'my-app-shell'), not the piral-cli package name. ↓

fix Set piral: piletPkg.piral.name from your pilet's package.json, which references the Piral shell name.

gotcha The plugin defines global variables via DefinePlugin. If you already use DefinePlugin, ensure no conflicts. ↓

fix Use the 'variables' option to inject additional defines; avoid duplicates.

deprecated Older v0.x releases used a different API and output format. Migrate to v1.x for Piral 1.0 compatibility. ↓

fix Update to pilet-webpack-plugin@1 and adjust options (name, version, piral).

Install

npm install pilet-webpack-plugin

yarn add pilet-webpack-plugin

pnpm add pilet-webpack-plugin

Imports

PiletWebpackPlugin

wrong

const PiletWebpackPlugin = require('pilet-webpack-plugin')

correct

import { PiletWebpackPlugin } from 'pilet-webpack-plugin'

Named export, not default. CJS require({}) also fine; ESM available.

PiletWebpackPlugin

wrong

const PiletWebpackPlugin = require('pilet-webpack-plugin').default

correct

const { PiletWebpackPlugin } = require('pilet-webpack-plugin')

CommonJS destructure works; no default export exists.

PiletWebpackPluginOptions

import type { PiletWebpackPluginOptions } from 'pilet-webpack-plugin'

Type export available for TypeScript users.

Quickstart

Shows how to add the PiletWebpackPlugin to a webpack 4 config with required options 'name', 'version', 'piral' and optional 'variables'.

const { PiletWebpackPlugin } = require('pilet-webpack-plugin');
const piletPkg = require('./package.json');

module.exports = {
  plugins: [
    new PiletWebpackPlugin({
      name: piletPkg.name,
      version: piletPkg.version,
      piral: piletPkg.piral.name,
      variables: {
        PIRAL_CLI_VERSION: require('piral-cli/package.json').version,
      },
    }),
  ],
};