Configuration Plugins

Extensible configuration plugin system that provides validation, change handling, and extensibility for all user configuration options in af-webpack.

Capabilities

Configuration Plugin System

Get available configuration plugins for validation and customization of user configuration options.

/**
 * Get available configuration plugins
 * @returns Array of configuration plugin objects
 */
function getUserConfigPlugins(): ConfigPlugin[];

interface ConfigPlugin {
  name: string;
  validate?: (value: any) => void;
  onChange?: (change: ConfigChange) => void;
}

interface ConfigChange {
  name: string;        // Configuration option name
  val: any;           // Previous value
  newVal: any;        // New value
  config: object;     // Previous complete configuration
  newConfig: object;  // New complete configuration
}

Usage Examples:

const getUserConfigPlugins = require('af-webpack/getUserConfigPlugins');

// Get all available configuration plugins
const plugins = getUserConfigPlugins();
console.log('Available config options:', plugins.map(p => p.name));

// Example plugin structure
plugins.forEach(plugin => {
  console.log(`Plugin: ${plugin.name}`);
  if (plugin.validate) {
    console.log('  - Has validation');
  }
  if (plugin.onChange) {
    console.log('  - Has change handler');
  }
});

Available Configuration Plugins

Build Configuration Plugins

entry

• Type: object | string
• Description: Application entry points configuration
• Validation: Must be valid entry format (string or object with string/array values)

outputPath

• Type: string
• Description: Output directory path
• Default: 'dist'
• Validation: Must be valid directory path

publicPath

• Type: string
• Description: Public path for assets
• Validation: Must be valid URL path format

hash

• Type: boolean
• Description: Enable filename hashing for cache busting
• Default: false

JavaScript/TypeScript Plugins

babel

• Type: object
• Description: Babel configuration options
• Validation: Must contain valid presets and plugins arrays

extraBabelPresets

• Type: string[]
• Description: Additional Babel presets
• Validation: Each preset must be resolvable module

extraBabelPlugins

• Type: string[]
• Description: Additional Babel plugins
• Validation: Each plugin must be resolvable module

extraBabelIncludes

• Type: (string | Function)[]
• Description: Additional files to include in Babel transformation
• Validation: Strings must be valid glob patterns

typescript

• Type: object
• Description: TypeScript compiler options
• Validation: Must be valid TypeScript configuration

tsConfigFile

• Type: string
• Description: Path to TypeScript configuration file
• Validation: File must exist and be valid JSON

disableDynamicImport

• Type: boolean
• Description: Disable dynamic import transformation
• Default: false

CSS and Styling Plugins

theme

• Type: object
• Description: Theme variables for Less/CSS preprocessing
• Validation: Must be object with string values

lessLoaderOptions

• Type: object
• Description: Options for Less loader
• Validation: Must be valid Less loader configuration

sass

• Type: object
• Description: Sass/SCSS configuration
• Validation: Must be valid node-sass options

stylus

• Type: object
• Description: Stylus configuration
• Validation: Must be valid Stylus options

autoprefixer

• Type: object
• Description: Autoprefixer configuration
• Validation: Must be valid autoprefixer options

extraPostCSSPlugins

• Type: object[]
• Description: Additional PostCSS plugins
• Validation: Each plugin must be valid PostCSS plugin

cssModulesExcludes

• Type: string[]
• Description: Files to exclude from CSS modules
• Validation: Must be valid glob patterns

cssModulesWithAffix

• Type: boolean
• Description: Add affix to CSS module class names
• Default: false

disableCSSModules

• Type: boolean
• Description: Disable CSS modules globally
• Default: false

disableCSSSourceMap

• Type: boolean
• Description: Disable CSS source maps
• Default: false

cssLoaderVersion

• Type: string
• Description: CSS loader version to use
• Validation: Must be '1' or '2'

cssLoaderOptions

• Type: object
• Description: Options for CSS loader
• Validation: Must be valid css-loader options

cssPublicPath

• Type: string
• Description: Public path for CSS assets
• Validation: Must be valid URL path

styleLoader

• Type: object
• Description: Style loader options
• Validation: Must be valid style-loader options

cssnano

• Type: object
• Description: CSS minification options
• Validation: Must be valid cssnano options

Development Configuration Plugins

devServer

• Type: object
• Description: Development server configuration
• Validation: Must be valid webpack-dev-server options

devtool

• Type: string
• Description: Source map generation method
• Validation: Must be valid webpack devtool option

proxy

• Type: object
• Description: Development proxy configuration
• Validation: Must be valid proxy configuration format
• Change Handler: Triggers server restart

Asset and Module Plugins

alias

• Type: object
• Description: Module path aliases
• Validation: Values must be valid file paths

copy

• Type: string | object | (string | object)[]
• Description: Files/directories to copy to output
• Validation: Must be valid copy-webpack-plugin format

externals

• Type: object
• Description: External dependencies configuration
• Validation: Must be valid webpack externals format

urlLoaderExcludes

• Type: string[]
• Description: Files to exclude from url-loader
• Validation: Must be valid glob patterns

Optimization Plugins

minimizer

• Type: 'uglifyjs' | 'terserjs'
• Description: JavaScript minifier to use
• Validation: Must be 'uglifyjs' or 'terserjs'

uglifyJSOptions

• Type: object
• Description: UglifyJS minification options
• Validation: Must be valid UglifyJS options

terserJSOptions

• Type: object
• Description: Terser minification options
• Validation: Must be valid Terser options

ignoreMomentLocale

• Type: boolean
• Description: Ignore Moment.js locale files
• Default: false

Advanced Configuration Plugins

define

• Type: object
• Description: Global constants definition
• Validation: Values must be JSON serializable

chainConfig

• Type: function
• Description: Webpack-chain configuration function
• Validation: Must be function that accepts webpack-chain config
• Change Handler: Triggers server restart

browserslist

• Type: string[]
• Description: Target browsers for compilation
• Validation: Must be valid browserslist queries

manifest

• Type: object
• Description: Webpack manifest plugin options
• Validation: Must be valid manifest plugin configuration

generateCssModulesTypings

• Type: boolean
• Description: Generate TypeScript definitions for CSS modules
• Default: false

es5ImcompatibleVersions

• Type: string[]
• Description: Packages requiring ES5 transformation
• Validation: Must be valid package names

Environment Configuration

env

• Type: object
• Description: Environment-specific configuration overrides
• Validation: Each environment must contain valid configuration options
• Change Handler: Merges environment-specific settings

Plugin Validation

Each plugin provides validation to ensure configuration correctness:

// Example validation error handling
try {
  const { config } = getUserConfig({
    // Invalid configuration
    minimizer: 'invalid-minimizer'
  });
} catch (error) {
  console.error(error.message);
  // "Configuration item minimizer must be 'uglifyjs' or 'terserjs'"
}

Plugin Change Handling

Plugins can define custom behavior when configuration changes:

• Hot Reload: Compatible changes update without server restart
• Server Restart: Structural changes require development server restart
• Error Recovery: Invalid configurations show errors but allow recovery

Custom Plugin Development

While not typically needed, the plugin system is designed for extensibility. Each plugin exports a function returning plugin configuration:

// Example plugin structure
export default function() {
  return {
    name: 'customOption',
    validate(value) {
      if (typeof value !== 'string') {
        throw new Error('customOption must be a string');
      }
    },
    onChange({ name, val, newVal, config, newConfig }) {
      console.log(`${name} changed from ${val} to ${newVal}`);
      // Handle configuration change
    }
  };
}