or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

build.md config-generation.md config-plugins.md dev-server.md index.md user-config.md

tile.json

User Configuration

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

Capabilities

User Configuration Parser

Parse user configuration from JSON or JavaScript configuration files with validation and environment support.

/**
 * 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;
};

Parameters:

cwd (string, optional): Current working directory (default: process.cwd())
configFile (string, optional): Configuration file name (default: .webpackrc)
disabledConfigs (string[], optional): Array of configuration keys to disable
preprocessor (function, optional): Function to preprocess configuration before validation

Usage Examples:

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

// Basic usage
const { config } = getUserConfig();
console.log('User configuration:', config);

// Custom configuration file
const { config } = getUserConfig({
  cwd: process.cwd(),
  configFile: '.mywebpackrc',
  disabledConfigs: ['proxy', 'devServer']
});

// With preprocessor
const { config } = getUserConfig({
  preprocessor: (config) => {
    // Transform configuration before validation
    if (config.theme && typeof config.theme === 'string') {
      config.theme = require(config.theme);
    }
    return config;
  }
});

Configuration File Watching

Watch configuration files for changes and handle hot reloading in development.

/**
 * 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;

Usage Examples:

const { getUserConfig, watchConfigs, unwatchConfigs } = require('af-webpack/getUserConfig');

// Watch configuration changes during development
const { config, watch } = getUserConfig();

// In development server context
const watcher = watch(devServer, {
  beforeChange: () => {
    console.log('Configuration is about to change...');
  }
});

// Manual file watching
const fileWatcher = watchConfigs({
  cwd: process.cwd(),
  configFile: '.webpackrc'
});

// Stop watching when done
unwatchConfigs();

Configuration File Formats

af-webpack supports multiple configuration file formats:

JSON Configuration (.webpackrc):

{
  "entry": {
    "index": "./src/index.js"
  },
  "outputPath": "dist",
  "publicPath": "/",
  "alias": {
    "@": "./src"
  },
  "proxy": {
    "/api": {
      "target": "http://localhost:3001",
      "changeOrigin": true
    }
  },
  "env": {
    "development": {
      "define": {
        "API_BASE": "http://localhost:3001"
      }
    },
    "production": {
      "define": {
        "API_BASE": "https://api.example.com"
      }
    }
  }
}

JavaScript Configuration (.webpackrc.js):

export default {
  entry: {
    index: './src/index.js'
  },
  outputPath: 'dist',
  publicPath: '/',
  chainConfig: (config) => {
    config.plugin('custom').use(CustomPlugin);
  },
  proxy: {
    '/api': {
      target: process.env.API_TARGET || 'http://localhost:3001',
      changeOrigin: true
    }
  }
};

Environment-Specific Configuration

Configure different settings for development, production, and custom environments.

// Configuration structure with environment overrides
{
  // Base configuration
  "outputPath": "dist",
  "publicPath": "/",
  
  // Environment-specific overrides
  "env": {
    "development": {
      "publicPath": "/",
      "devtool": "cheap-module-eval-source-map"
    },
    "production": {
      "publicPath": "/static/",
      "hash": true,
      "minimize": true
    },
    "staging": {
      "publicPath": "/staging/",
      "define": {
        "API_BASE": "https://staging-api.example.com"
      }
    }
  }
}

npm Variable Replacement

Automatic replacement of npm package variables in configuration values.

// Configuration with npm variables
{
  "define": {
    "PACKAGE_NAME": "$npm_package_name",
    "PACKAGE_VERSION": "$npm_package_version"
  }
}

// Variables are automatically replaced:
// $npm_package_name -> actual package name from package.json
// $npm_package_version -> actual version from package.json

Configuration Validation

Comprehensive validation system with helpful error messages and suggestions.

Validation Features:

Schema Validation: Each configuration option is validated against its expected type and format
Disabled Config Detection: Warns about disabled configuration options
Typo Detection: Suggests corrections for misspelled configuration keys using did-you-mean
Custom Validation: Plugin-specific validation functions for complex options

Error Handling:

// Invalid configuration example
{
  "outpuPath": "dist",  // Typo in "outputPath"
  "poxy": {             // Typo in "proxy"
    "/api": "http://localhost:3001"
  }
}

// Validation errors:
// "Configuration item outpuPath is not valid, do you mean outputPath?"
// "Configuration item poxy is not valid, do you mean proxy?"

Configuration Merging

Intelligent configuration merging for arrays and objects:

Arrays: Concatenated together
Objects: Deep merged with new values overriding existing ones
Primitives: New values replace existing values

Development Server Integration

Special integration with development server for live configuration reloading:

// Watch configuration in development server
const { config, watch } = getUserConfig();

const watcher = watch(devServer, {
  beforeChange: () => {
    // Prepare for configuration change
    clearConsole();
  }
});

// Configuration change handling:
// - Automatic server restart for structural changes
// - Hot reload for compatible changes
// - Error overlay for invalid configurations

Available Configuration Options

All configuration options from the Configuration Generation documentation are supported, including:

Build Configuration: entry, outputPath, publicPath, hash
JavaScript/TypeScript: babel, typescript, extraBabelPresets, extraBabelPlugins
CSS/Styling: theme, lessLoaderOptions, sass, cssModules*
Development: devServer, proxy, devtool
Assets: copy, alias, externals
Optimization: minimizer, uglifyJSOptions, terserJSOptions

See Configuration Plugins for the complete list of available options and their validation rules.