or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build.mdconfig-generation.mdconfig-plugins.mddev-server.mdindex.mduser-config.md
tile.json

index.mddocs/

af-webpack

af-webpack is a specialized webpack wrapper designed for Ant Financial, providing comprehensive build tooling and configuration management for modern JavaScript applications. It integrates multiple build-time technologies including Babel, CSS preprocessors, TypeScript support, and advanced webpack plugins, serving as the foundation for popular CLI tools like umi and roadhog.

Package Information

  • Package Name: af-webpack
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install af-webpack

Core Imports

const build = require('af-webpack/build');
const dev = require('af-webpack/dev');
const getConfig = require('af-webpack/getConfig');
const getUserConfig = require('af-webpack/getUserConfig');

ES Modules:

import build from 'af-webpack/build';
import dev from 'af-webpack/dev';
import getConfig from 'af-webpack/getConfig';
import getUserConfig from 'af-webpack/getUserConfig';

Basic Usage

const getConfig = require('af-webpack/getConfig');
const build = require('af-webpack/build');

// Generate webpack configuration
const webpackConfig = getConfig({
  cwd: process.cwd(),
  entry: {
    index: './src/index.js'
  },
  outputPath: 'dist',
  publicPath: '/'
});

// Run production build
build({
  webpackConfig,
  onSuccess: ({ stats }) => {
    console.log('Build completed successfully');
  },
  onFail: ({ err, stats }) => {
    console.error('Build failed:', err);
  }
});

Architecture

af-webpack is built around several key components:

  • Configuration Generation: Core webpack configuration with sensible defaults for modern JavaScript applications
  • Build Pipeline: Production build system with optimization, asset processing, and error handling
  • Development Server: Hot-reloading development server with middleware support and error overlay
  • User Configuration: Flexible configuration system supporting both JSON and JavaScript config files
  • Plugin System: Extensible configuration plugins for validation and customization
  • CLI Interface: Command-line tools for development and production workflows

Capabilities

Production Build System

Complete production build functionality with webpack compilation, asset optimization, and comprehensive error handling.

/**
 * Execute production build with webpack
 * @param opts - Build configuration options
 */
function build(opts: {
  webpackConfig: object | object[];
  cwd?: string;
  onSuccess?: (result: { stats: object }) => void;
  onFail?: (error: { err?: Error; stats?: object; rawStats?: object }) => void;
}): void;

Build System

Development Server

Development server with hot module replacement, middleware support, and error overlay for optimal development experience.

/**
 * Start development server with hot reloading
 * @param opts - Development server configuration
 */
function dev(opts: {
  webpackConfig: object | object[];
  _beforeServerWithApp?: (app: object) => void;
  beforeMiddlewares?: Function[];
  afterMiddlewares?: Function[];
  beforeServer?: (server: object) => void;
  afterServer?: (server: object, port: number) => void;
  contentBase?: string;
  onCompileDone?: (result: DevCompileResult) => void;
  onFail?: (error: { stats: object }) => void;
  proxy?: object;
  port: number;
  history?: object;
  base?: string;
  serverConfig?: object;
}): void;

interface DevCompileResult {
  port: number;
  isFirstCompile: boolean;
  stats: object;
  server: object;
  urls: {
    local: string;
    lan: string;
    rawLocal: string;
    rawLanUrl: string;
  };
}

Development Server

Webpack Configuration Generator

Comprehensive webpack configuration generation with support for TypeScript, CSS preprocessors, and modern JavaScript features.

/**
 * Generate complete webpack configuration
 * @param opts - Configuration generation options
 * @returns Complete webpack configuration object
 */
function getConfig(opts: WebpackConfigOptions): object;

interface WebpackConfigOptions {
  cwd?: string;
  entry?: { [key: string]: string | string[] };
  outputPath?: string;
  publicPath?: string;
  isDev?: boolean;
  alias?: { [key: string]: string };
  externals?: object;
  babel?: BabelOptions;
  extraBabelPresets?: string[];
  extraBabelPlugins?: string[];
  disableDynamicImport?: boolean;
  typescript?: object;
  tsConfigFile?: string;
  chainConfig?: (config: object) => void;
  copy?: string | object | Array<string | object>;
  theme?: object;
  lessLoaderOptions?: object;
  sass?: object;
  stylus?: object;
  autoprefixer?: object;
  cssModulesExcludes?: string[];
  disableCSSModules?: boolean;
  disableCSSSourceMap?: boolean;
  hash?: boolean;
  minimizer?: 'uglifyjs' | 'terserjs';
  devtool?: string;
  define?: object;
  ignoreMomentLocale?: boolean;
  [key: string]: any;
}

interface BabelOptions {
  presets?: string[];
  plugins?: string[];
}

Configuration Generation

User Configuration Management

Parse and validate user configuration from .webpackrc files with support for environment-specific settings and real-time configuration watching.

/**
 * Parse user configuration from config files
 * @param opts - Configuration parsing options
 * @returns Configuration object with watch capability
 */
function getUserConfig(opts: {
  cwd?: string;
  configFile?: string;
  disabledConfigs?: string[];
  preprocessor?: (config: object) => object;
}): {
  config: object;
  watch: (devServer: object, watchOpts?: object) => object;
};

/**
 * Watch configuration files for changes
 * @param opts - Watch configuration options
 * @returns File watcher instance
 */
function watchConfigs(opts?: {
  cwd?: string;
  configFile?: string;
}): object;

/**
 * Stop watching configuration files
 */
function unwatchConfigs(): void;

User Configuration

Configuration Plugins

Extensible configuration plugin system 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;
  val: any;
  newVal: any;
  config: object;
  newConfig: object;
}

Configuration Plugins

Babel Registration

Runtime Babel registration for transforming JavaScript and TypeScript files during development and testing.

/**
 * Register Babel for runtime transpilation
 * @param opts - Babel registration options
 */
function registerBabel(opts?: {
  only?: string[];
  ignore?: string[];
  babelPreset?: string;
  babelPlugins?: string[];
}): void;

Utility Libraries

Direct access to commonly used webpack and development utilities.

// React development utilities
const { clearConsole, webpackHotDevClientPath } = require('af-webpack/react-dev-utils');

// Webpack libraries
const webpack = require('af-webpack/webpack');
const WebpackChain = require('af-webpack/webpack-chain');
const webpackDevMiddleware = require('af-webpack/webpack-dev-middleware');

CLI Interface

af-webpack provides a command-line interface for common development and build tasks.

# Development server
npx af-webpack dev

# Production build  
npx af-webpack build

Environment Variables:

Core Configuration:

  • AF_CONFIG_FILE: Custom configuration file path (default: .webpackrc)
  • NODE_ENV: Environment mode (development or production)

Development Server:

  • HOST: Development server host (default: 0.0.0.0)
  • HTTPS: Enable HTTPS in development server (requires CERT and KEY)
  • CERT: Path to SSL certificate file for HTTPS
  • KEY: Path to SSL private key file for HTTPS

Build Control:

  • CLEAR_OUTPUT: Control output directory clearing (set to none to disable)
  • UMI_TEST: Test environment flag (affects build behavior)

Code Quality:

  • ESLINT: Enable ESLint checking (set to none to disable)
  • FORK_TS_CHECKER: Enable TypeScript checking in separate process

Bundle Analysis:

  • ANALYZE: Enable webpack bundle analyzer for main bundle
  • ANALYZE_SSR: Enable webpack bundle analyzer for SSR bundle
  • ANALYZE_REPORT: Generate bundle analysis report
  • SPEED_MEASURE: Enable webpack speed measurement plugin
  • DUPLICATE_CHECKER: Enable duplicate package checker

Error Handling

af-webpack provides comprehensive error handling with detailed error messages and development-friendly error overlays. Build failures are reported through callback functions with structured error information including webpack stats and compilation details.