Error Handling

class SizeLimitError extends Error {
  constructor(type: string, ...args: any[]);
  name: "SizeLimitError";
  example?: string;  // Configuration example for certain error types
}

import { SizeLimitError } from "size-limit";

try {
  // Size Limit operation that might fail
  await sizeLimit(plugins, config);
} catch (error) {
  if (error instanceof SizeLimitError) {
    console.error(`Size Limit Error: ${error.message}`);
    
    // Show configuration example if available
    if (error.example) {
      console.log("Example configuration:");
      console.log(error.example);
    }
  } else {
    // Handle other errors
    console.error("Unexpected error:", error);
  }
}

// Configuration Errors
const ERROR_TYPES = {
  // Missing or invalid configuration
  noConfig: () => "Create Size Limit config in *package.json*",
  emptyConfig: () => "Size Limit config must *not be empty*",
  noArrayConfig: () => "Size Limit config must contain *an array*",
  noObjectCheck: () => "Size Limit config array should contain *only objects*",
  
  // Path configuration errors
  pathNotString: () => 
    "The *path* in Size Limit config must be *a string* or *an array of strings*",
  
  // Entry configuration errors  
  entryNotString: () =>
    "The *entry* in Size Limit config must be *a string* or *an array of strings*",
  
  // Missing package.json
  noPackage: () => 
    "Size Limit didn't find *package.json*. Create npm package and run Size Limit there.",
  
  // Plugin errors
  missedPlugin: (mod) => `Add *@size-limit/${mod}* plugin to Size Limit`,
  pluginlessConfig: (opt, mod) => 
    `Config option *${opt}* needs *@size-limit/${mod}* plugin`,
  multiPluginlessConfig: (opt, mod1, mod2) => 
    `Config option *${opt}* needs *@size-limit/${mod1}* or *@size-limit/${mod2}* plugin`,
  timeWithoutPlugin: () => "Add *@size-limit/time* plugin to use time limit",
  
  // Command line argument errors
  unknownArg: (arg) => 
    `Unknown argument *${arg}*. Check command for typo and read docs.`,
  argWithoutParameter: (arg, parameter) => 
    `Missing parameter *${parameter}* for *--${arg}* argument`,
  argWithoutPlugins: (arg, mod1, mod2) => 
    `Argument *--${arg}* needs *@size-limit/${mod1}* or *@size-limit/${mod2}* plugin`,
  argWithoutAnalyzer: (arg, bundler, analyzer) => 
    `Argument *--${arg}* works only with *@size-limit/${bundler}* plugin and *@size-limit/${analyzer}* plugin`,
  argWithoutAnotherArg: (arg, anotherArg) => 
    `Argument *--${arg}* works only with *--${anotherArg}* argument`,
  
  // Build and file errors
  bundleDirNotEmpty: (dir) => 
    `The directory *${dir}* is not empty. Pass *--clean-dir* if you want to remove it`,
  unknownEntry: (entry) => 
    `Size Limit didn't find *${entry}* entry in the custom bundler config`,
  
  // Configuration validation errors
  unknownOption: (opt) => 
    `Unknown option *${opt}* in config. Check Size Limit docs and version.`,
  
  // Command execution errors
  cmdError: (cmd, error) => 
    error ? `${cmd} error: ${error}` : `${cmd} error`
};

// Errors that include configuration examples
const ERRORS_WITH_EXAMPLES = [
  "emptyConfig",
  "noArrayConfig", 
  "noConfig",
  "noObjectCheck",
  "pathNotString"
];

// Example configuration shown for these errors:
const EXAMPLE_CONFIG = `  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "10 kB"
    }
  ]`;

# When configuration is missing
Error: Create Size Limit config in package.json

Example configuration:
  "size-limit": [
    {
      "path": "dist/bundle.js", 
      "limit": "10 kB"
    }
  ]

// Error: No configuration found
// Cause: No size-limit config in package.json or config files
// Solution: Add configuration to package.json

{
  "name": "my-package",
  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "10 kB"
    }
  ]
}

// Error: Add @size-limit/webpack plugin to Size Limit
// Cause: Configuration uses webpack features but plugin not installed
// Solution: Install required plugin

npm install --save-dev @size-limit/webpack

// Error: Size Limit config must contain an array
// Cause: Configuration is not an array of check objects
// Solution: Use array format for configuration

{
  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "10 kB"
    }
  ]
}

// Error: The path in Size Limit config must be a string or an array of strings
// Cause: Invalid path value (not string or string array)
// Solution: Use proper path format

{
  "size-limit": [
    {
      "path": ["dist/app.js", "dist/vendor.js"],
      "limit": "100 kB"
    }
  ]
}

// Error: Config option webpack needs @size-limit/webpack plugin
// Cause: Configuration uses plugin-specific options without plugin installed
// Solution: Install required plugin or remove incompatible options

// Error: Unknown argument --invalid-flag
// Cause: Typo in command line argument
// Solution: Check argument spelling and available options

# Wrong
size-limit --invalid-flag

# Correct  
size-limit --json

import sizeLimit, { SizeLimitError } from "size-limit";

try {
  const results = await sizeLimit(plugins, config);
  console.log("Size check passed:", results);
} catch (error) {
  if (error instanceof SizeLimitError) {
    // Handle Size Limit specific errors
    console.error("Configuration Error:", error.message);
    
    if (error.example) {
      console.log("Try this configuration:");
      console.log(error.example);
    }
    
    // Exit with specific code for CI
    process.exit(1);
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
    process.exit(2);
  }
}

# Check exit codes in scripts
if npx size-limit --silent; then
  echo "Size limits passed"
else
  exit_code=$?
  if [ $exit_code -eq 1 ]; then
    echo "Size limit exceeded or configuration error"
  else
    echo "Unexpected error occurred"
  fi
  exit $exit_code
fi

// Debugging techniques:
// 1. Use --json output to see detailed results
// 2. Check plugin installation with npm ls
// 3. Validate configuration format
// 4. Use --why for bundle analysis
// 5. Enable verbose logging in custom plugins
// 6. Check file paths and permissions
// 7. Test with minimal configuration first

# Check installed plugins
npm ls @size-limit/

# Validate configuration with JSON output
size-limit --json

# Analyze bundle composition
size-limit --why

# Test with minimal config
echo '{"size-limit":[{"path":"dist/bundle.js","limit":"100kB"}]}' > .size-limit.json
size-limit

// Graceful degradation example
async function runSizeLimitWithFallback(plugins, config) {
  try {
    return await sizeLimit(plugins, config);
  } catch (error) {
    if (error instanceof SizeLimitError) {
      // Try with basic file plugin only
      console.warn("Falling back to basic file measurement");
      const filePlugin = await import("@size-limit/file");
      return await sizeLimit([filePlugin.default], config);
    }
    throw error;
  }
}