or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

config-loading.mdcore-preset.mddependencies.mdhook-optimization.mdindex.mdreact-preset-and-utilities.md
tile.json

dependencies.mddocs/

Dependencies Configuration

Specialized Babel preset for processing dependencies with specific optimization for node_modules transformation in Gatsby projects. This preset is designed to handle third-party code with different configuration than application code.

Capabilities

Dependencies Preset Factory

Creates a Babel configuration specifically optimized for transforming dependencies (node_modules).

/**
 * Dependencies-specific Babel preset factory
 * @param {*} _ - Unused first parameter
 * @param {DependenciesOptions} options - Configuration options
 * @returns {DependenciesBabelConfig} Babel configuration optimized for dependencies
 */
function dependenciesPreset(_, options = {});

interface DependenciesOptions {
  /** Build stage for different Gatsby build phases */
  stage?: "build-javascript" | "build-html" | "develop" | "develop-html";
}

interface DependenciesBabelConfig {
  sourceType: "unambiguous";
  presets: Array<[string, object]>;
  plugins: Array<string | [string, object]>;
}

Usage Examples:

// Basic usage in Webpack configuration
{
  test: /\.js$/,
  include: /node_modules/,
  use: {
    loader: "babel-loader",
    options: {
      presets: [
        ["babel-preset-gatsby/dependencies", { stage: "build-javascript" }]
      ]
    }
  }
}

// Programmatic usage
import dependenciesPreset from "babel-preset-gatsby/dependencies";

const config = dependenciesPreset(null, { 
  stage: "build-javascript" 
});

Configuration Structure

Source Type

Uses "unambiguous" source type to handle both CommonJS and ES Modules in dependencies:

{
  sourceType: "unambiguous"
}

This allows Babel to automatically detect the module format and handle it appropriately.

Presets

@babel/preset-env: Environment-specific transformations optimized for dependencies

[
  "@babel/preset-env",
  {
    useBuiltIns: "usage",
    corejs: 3,
    modules: false,
    targets: /* browser targets from cached config */,
    exclude: [
      "transform-typeof-symbol",
      /* ...other excluded transforms */
    ]
  }
]

Plugins

Core Plugins:

  1. @babel/plugin-transform-runtime: Runtime helper optimization with absolute path

    • Provides consistent runtime version
    • Enables ES modules usage
    • Prevents helper duplication

  2. @babel/plugin-syntax-dynamic-import: Syntax support for dynamic imports

    • Essential for code splitting in dependencies

Production-Only Plugins:

  • babel-plugin-transform-react-remove-prop-types: Removes PropTypes in production builds
    • Only included when stage === "build-javascript"
    • Reduces bundle size by removing development-only code

Stage-Based Configuration

The preset behaves differently based on the build stage:

Development Stages (develop, develop-html)

// Development configuration
const devConfig = dependenciesPreset(null, { stage: "develop" });
// - Uses browser targets from cached config
// - Keeps PropTypes for debugging
// - Optimizes for fast rebuilds

Production Stages (build-javascript, build-html)

// Production configuration  
const prodConfig = dependenciesPreset(null, { stage: "build-javascript" });
// - Includes PropTypes removal plugin
// - Optimizes for bundle size
// - Uses production browser targets

Runtime Configuration

Transform Runtime Settings

The preset includes optimized @babel/plugin-transform-runtime configuration:

[
  "@babel/plugin-transform-runtime",
  {
    corejs: false,           // No core-js polyfills (handled by preset-env)
    helpers: true,           // Transform helper functions
    regenerator: true,       // Transform async/await and generators
    useESModules: true,      // Use ES module helpers
    absoluteRuntime: path    // Use specific runtime version
  }
]

Absolute Runtime Path

Uses absolute path to ensure consistent @babel/runtime version:

const absoluteRuntimePath = path.dirname(
  require.resolve("@babel/runtime/package.json")
);

This prevents version conflicts when different dependencies expect different runtime versions.

Integration with Gatsby

Cached Configuration Integration

Uses loadCachedConfig() to access Gatsby's browser targets:

const pluginBabelConfig = loadCachedConfig();
const targets = pluginBabelConfig.browserslist;

Webpack Integration

Typically configured in Gatsby's Webpack configuration for node_modules processing:

// Example Webpack rule (from Gatsby internals)
{
  test: /\.jsx?$/,
  include: modulePath => {
    // Include node_modules that need transformation
    return /node_modules/.test(modulePath);
  },
  use: {
    loader: "babel-loader",
    options: {
      presets: [
        ["babel-preset-gatsby/dependencies", { stage }]
      ]
    }
  }
}

Performance Optimizations

Excluded Transforms

Excludes transforms that make code slower:

  • transform-typeof-symbol: Often unnecessary and impacts performance
  • Legacy polyfills: Handled by explicit polyfill configuration

Core-js Integration

Uses useBuiltIns: "usage" with core-js@3:

  • Only includes necessary polyfills
  • Reduces bundle size
  • Improves loading performance

ES Modules Support

Preserves ES modules (modules: false) for better tree-shaking:

  • Allows bundlers to eliminate dead code
  • Enables more efficient dependency analysis
  • Supports code splitting optimizations

Error Handling

The preset handles common dependency transformation issues:

Module Format Detection

Using sourceType: "unambiguous" handles mixed module formats:

// Handles both formats automatically
// CommonJS
module.exports = something;

// ES Modules  
export default something;

Runtime Path Resolution

Absolute runtime path prevents resolution issues:

// Prevents errors like:
// Cannot resolve '@babel/runtime/helpers/...'

Advanced Usage

Custom Dependencies Configuration

For advanced use cases, you can extend the dependencies preset:

// Custom Webpack configuration
{
  test: /\.js$/,
  include: /specific-package/,
  use: {
    loader: "babel-loader", 
    options: {
      presets: [
        ["babel-preset-gatsby/dependencies", { stage: "build-javascript" }]
      ],
      plugins: [
        // Additional plugins for specific dependencies
        ["transform-specific-feature", { option: true }]
      ]
    }
  }
}

Conditional Transformation

Target specific packages or patterns based on your needs:

// Transform only specific problematic packages
{
  test: /\.js$/,
  include: modulePath => {
    return /node_modules\/(package1|package2)/.test(modulePath);
  },
  use: {
    loader: "babel-loader",
    options: {
      presets: [["babel-preset-gatsby/dependencies"]]
    }
  }
}