tessl/npm-tarojs--webpack-runner

Webpack runner for Taro that transforms Taro compilation configurations into Webpack configurations for H5/web builds

—

Pending

Overview

Eval results

Files

Build Configuration

Name: tessl/npm-tarojs--webpack-runner
Author: tessl

Configuration interfaces and utilities for defining Taro H5 build parameters, webpack customization options, and development server settings.

Capabilities

BuildConfig Interface

Main configuration interface that extends Taro's base configuration interfaces with H5-specific options.

/**
 * Main build configuration interface for Taro H5 builds
 * Extends IProjectBaseConfig and IH5Config with webpack-specific options
 */
interface BuildConfig extends IProjectBaseConfig, IH5Config {
  /** Target platform adapter (e.g., "h5", "weapp", "swan") */
  buildAdapter: string;
  
  /** Webpack entry configuration */
  entry?: webpack.Entry;
  
  /** Entry file name (default: "app") */
  entryFileName?: string;
  
  /** Runtime path(s) for Taro runtime modules */
  runtimePath?: string | string[];
  
  /** Flag for building native components */
  isBuildNativeComp?: boolean;
  
  /** Skip actual webpack build execution */
  withoutBuild?: boolean;
  
  /** Hook function called during webpack compilation make phase */
  onCompilerMake?: (compilation: any) => Promise<any>;
  
  /** Hook function called when parsing createElement calls */
  onParseCreateElement?: (nodeName: any, componentConfig: any) => Promise<any>;
  
  /** Function to modify component configuration */
  modifyComponentConfig?: Func;
}

Usage Examples:

import webpackRunner from "@tarojs/webpack-runner";

// Basic production configuration
const productionConfig: BuildConfig = {
  buildAdapter: "h5",
  sourceRoot: "src",
  outputRoot: "dist",
  isWatch: false,
  entry: {
    app: "./src/app.tsx"
  },
  publicPath: "/",
  
  // Build optimization
  terser: {
    enable: true,
    config: {
      compress: {
        drop_console: true
      }
    }
  },
  
  // CSS optimization
  csso: {
    enable: true,
    config: {
      comments: false
    }
  },
  
  // Asset handling
  imageUrlLoaderOption: {
    limit: 10240,
    name: "static/images/[name].[contenthash].[ext]"
  }
};

// Development configuration with dev server
const developmentConfig: BuildConfig = {
  buildAdapter: "h5",
  sourceRoot: "src",
  outputRoot: "dist",
  isWatch: true,
  
  // Development server settings
  devServer: {
    port: 3000,
    host: "0.0.0.0",
    open: true,
    compress: true,
    hot: true,
    
    // Proxy configuration
    proxy: {
      "/api": {
        target: "http://localhost:8080",
        changeOrigin: true,
        secure: false
      }
    }
  },
  
  // Router configuration
  router: {
    mode: "hash",
    basename: "/",
    customRoutes: {
      "/custom": "/pages/custom/index"
    }
  }
};

// Advanced configuration with hooks
const advancedConfig: BuildConfig = {
  buildAdapter: "h5",
  sourceRoot: "src",
  outputRoot: "dist",
  isWatch: false,
  
  // Webpack customization
  webpackChain: (chain, webpack) => {
    chain.resolve.alias.set("@", path.resolve("src"));
  },
  
  modifyWebpackChain: async (chain, webpack, data) => {
    // Add custom plugin
    chain.plugin("custom").use(CustomPlugin, [options]);
  },
  
  // Build lifecycle hooks
  onBuildFinish: ({ error, stats, isWatch }) => {
    if (error) {
      console.error("Build failed:", error.message);
    } else {
      console.log("Build completed successfully");
      if (stats) {
        console.log("Build time:", stats.endTime - stats.startTime, "ms");
      }
    }
  },
  
  onWebpackChainReady: (chain) => {
    console.log("Webpack chain is ready for compilation");
  },
  
  // Asset modification
  modifyBuildAssets: async (assets) => {
    // Modify build assets before emit
    Object.keys(assets).forEach(filename => {
      if (filename.endsWith(".html")) {
        // Modify HTML assets
        const source = assets[filename].source();
        assets[filename] = {
          source: () => source.replace("{{TITLE}}", "My App"),
          size: () => source.length
        };
      }
    });
  }
};

Configuration Type Aliases and Interfaces

Supporting types and interfaces for build configuration:

/** Webpack entry type supporting various entry formats */
type TEntry = string | string[] | webpack.Entry | webpack.EntryFunc;

/** Custom webpack configuration type */
type CustomWebpackConfig = FunctionLikeCustomWebpackConfig | webpack.Configuration;

/** Function-based webpack configuration */
type FunctionLikeCustomWebpackConfig = (
  webpackConfig: webpack.Configuration,
  webpack: any
) => webpack.Configuration;

/** Generic options interface for flexible configuration */
interface Option {
  [key: string]: any;
}

/** Webpack chain interface for type safety */
interface Chain {
  [key: string]: any;
}

/** AppHelper options interface */
interface IOptions {
  sourceDir: string;
  entryFileName: string;
  frameworkExts: string[];
  modifyAppConfig?: Func;
}

Development Server Configuration

Configuration options for the webpack development server:

interface DevServerConfig {
  /** Server port number */
  port?: number;
  
  /** Server host address */
  host?: string;
  
  /** Automatically open browser */
  open?: boolean;
  
  /** Enable gzip compression */
  compress?: boolean;
  
  /** Enable hot module replacement */
  hot?: boolean;
  
  /** Disable host check for remote access */
  disableHostCheck?: boolean;
  
  /** Proxy configuration for API requests */
  proxy?: ProxyConfig | ProxyConfig[];
  
  /** Additional development server options */
  [key: string]: any;
}

interface ProxyConfig {
  context?: string | string[];
  target?: string;
  changeOrigin?: boolean;
  secure?: boolean;
  bypass?: (req: any) => string | void;
  [key: string]: any;
}

Router Configuration

Configuration for client-side routing in H5 builds:

interface RouterConfig {
  /** Router mode: "hash", "browser", or "multi" */
  mode?: "hash" | "browser" | "multi";
  
  /** Base path for the router */
  basename?: string;
  
  /** Custom route mappings */
  customRoutes?: Record<string, string | string[]>;
}

Build Hooks and Lifecycle

Configuration for build lifecycle hooks and customization:

/** Build finish callback function */
type OnBuildFinish = (result: {
  error: Error | null;
  stats: webpack.Stats | null;
  isWatch: boolean;
}) => void;

/** Webpack chain ready callback */
type OnWebpackChainReady = (chain: any) => void;

/** Build assets modification hook */
type ModifyBuildAssets = (assets: any) => Promise<void>;

/** Webpack chain modification function */
type ModifyWebpackChain = (
  chain: any,
  webpack: any,
  data: IModifyChainData
) => Promise<void>;

interface IModifyChainData {
  componentConfig: IComponentConfig;
}

Configuration Validation:

The build configuration includes validation and error handling:

// Invalid configuration examples that will cause errors:

// Missing required buildAdapter
const invalidConfig = {
  sourceRoot: "src" // Missing buildAdapter
};

// Invalid router mode
const invalidRouter = {
  buildAdapter: "h5",
  router: {
    mode: "invalid" // Must be "hash", "browser", or "multi"
  }
};

// Invalid dev server port
const invalidDevServer = {
  buildAdapter: "h5",
  devServer: {
    port: "invalid" // Must be number
  }
};

Default Configuration Values:

The build system applies default values for missing configuration:

// Default values applied by the build system
const defaults = {
  sourceRoot: "src",
  outputRoot: "dist",
  entryFileName: "app",
  frameworkExts: [".tsx", ".ts", ".jsx", ".js"],
  publicPath: "/",
  router: {
    mode: "hash",
    basename: "/"
  },
  devServer: {
    port: 8080,
    host: "localhost",
    open: false,
    compress: true
  }
};

Install with Tessl CLI

npx tessl i tessl/npm-tarojs--webpack-runner

docs