or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

babel-customizers.md core-overrides.md index.md utilities.md webpack-customizers.md

tile.json

Utilities

Helper functions for navigating webpack configurations and debugging.

Capabilities

Get Babel Loader

Extract the babel loader configuration from a webpack config object.

/**
 * Extracts babel loader from webpack config
 * Create-react-app defines two babel configurations: one for src/ files and one for external files
 * @param {Object} config - Webpack configuration object to search
 * @param {boolean} isOutsideOfApp - Whether to get loader for files outside src/ (default: false)
 * @returns {Object} Babel loader configuration object with options, include/exclude, etc.
 */
function getBabelLoader(config, isOutsideOfApp);

Usage Examples:

const { getBabelLoader } = require("customize-cra");

// Custom babel customizer using getBabelLoader
const addCustomBabelOption = () => config => {
  const babelLoader = getBabelLoader(config);
  babelLoader.options.customOption = true;
  return config;
};

// Get external babel loader (for node_modules)
const customizeExternalBabel = () => config => {
  const externalBabelLoader = getBabelLoader(config, true);
  if (!externalBabelLoader.options.plugins) {
    externalBabelLoader.options.plugins = [];
  }
  externalBabelLoader.options.plugins.push("some-plugin");
  return config;
};

Tap

Debug utility for inspecting configuration objects during the override process.

/**
 * Debug utility for inspecting configuration objects
 * Logs configuration state to console or file without modifying the config
 * @param {Object} options - Options object for controlling tap behavior
 * @param {string} [options.message] - Message to print before configuration dump
 * @param {string} [options.dest] - File path to append logs to (in addition to console)
 * @returns {Function} Configuration pass-through function with logging side effects
 */
function tap(options);

Usage Examples:

const { override, tap, addLessLoader, disableEsLint } = require("customize-cra");

module.exports = override(
  // Log initial config state
  tap({ message: "Initial configuration" }),
  
  disableEsLint(),
  
  // Log config after disabling ESLint
  tap({ message: "After disabling ESLint" }),
  
  addLessLoader(),
  
  // Log final config to both console and file
  tap({ 
    message: "Final configuration", 
    dest: "customize-cra.log" 
  })
);

Advanced Usage:

// Log only to file (no message)
module.exports = override(
  addDecoratorsLegacy(),
  tap({ dest: "build-config.json" }),
  disableEsLint()
);

// Simple message logging
module.exports = override(
  tap({ message: "Debug: webpack config state" }),
  // ... other customizers
);

Implementation Details

Get Babel Loader Implementation

The getBabelLoader function handles the differences between create-react-app versions:

React Scripts 2.0.3+: Babel loader is found in the oneOf array within module rules
React Scripts 2.0.0.next.*: Babel loader may be nested within use arrays

The function:

First searches the oneOf array for babel loaders
If not found, flattens all use arrays and searches there
Distinguishes between internal (src/) and external babel loaders using include/exclude properties
Returns the actual loader object that can be modified directly

Tap Implementation

The tap function:

Accepts an optional options object with message and dest properties
Returns a configuration pass-through function that logs without modification
Uses JSON.stringify with 2-space indentation for readable output
Appends to files using Node.js fs.appendFile when dest is specified
Always logs to console in addition to file output
Handles both message logging and raw configuration dumps

Error Handling

Get Babel Loader Errors

getBabelLoader may return undefined if:

The webpack configuration structure doesn't match expected create-react-app patterns
The babel loader has been removed or significantly modified by other customizers
The isOutsideOfApp parameter doesn't match any existing babel loader configuration

Always check the return value before accessing properties:

const customBabelCustomizer = () => config => {
  const babelLoader = getBabelLoader(config);
  if (babelLoader && babelLoader.options) {
    babelLoader.options.customOption = true;
  }
  return config;
};

Tap Errors

tap function errors are primarily related to file system operations:

File permission errors when writing to dest
Invalid file paths in dest option
Disk space issues when appending large configuration objects

These errors are not caught internally, so wrap in try-catch if file writing is critical:

const safeTap = (options) => (config) => {
  try {
    return tap(options)(config);
  } catch (error) {
    console.warn("Tap logging failed:", error.message);
    return config;
  }
};