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

index.mddocs/

Babel Preset Gatsby

Babel Preset Gatsby provides a comprehensive Babel preset specifically designed for Gatsby projects, enabling modern JavaScript syntax and features while maintaining compatibility with older browsers. It includes essential Babel presets for environment-specific transformations (@babel/preset-env) and React development (@babel/preset-react), along with plugins for class properties, dynamic imports, runtime transformation, macro support, and React prop-types removal in production.

Package Information

  • Package Name: babel-preset-gatsby
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install --save-dev babel-preset-gatsby

Core Imports

CommonJS (most common usage):

// Basic usage in .babelrc
{
  "presets": ["babel-preset-gatsby"]
}

ES Module import for programmatic usage:

import preset, { loadCachedConfig } from "babel-preset-gatsby";

CommonJS for programmatic usage:

const preset = require("babel-preset-gatsby");
const { loadCachedConfig } = require("babel-preset-gatsby");

// Direct access to @babel/preset-react
const babelPresetReact = require("babel-preset-gatsby/babel-preset-react");

Basic Usage

Simple Configuration

{
  "presets": ["babel-preset-gatsby"]
}

Advanced Configuration

{
  "presets": [
    [
      "babel-preset-gatsby",
      {
        "targets": "last 1 version",
        "reactRuntime": "automatic",
        "reactImportSource": "@emotion/react"
      }
    ]
  ]
}

Programmatic Usage

import preset from "babel-preset-gatsby";

// Generate configuration for specific stage
const config = preset(null, { 
  stage: "build-javascript",
  targets: { browsers: ["last 2 versions"] }
});

Architecture

The preset is built around several key components:

  • Core Preset Function: Main configuration generator that returns Babel presets and plugins based on options and build stage
  • Cached Configuration: Integration with Gatsby's build system for optimized browser targeting
  • Stage-Based Configuration: Different plugin sets for different Gatsby build stages (develop, build-html, build-javascript, etc.)
  • Hook Optimization: Custom plugin for optimizing React hook destructuring patterns
  • Dependencies Support: Specialized configuration for processing node_modules dependencies

Capabilities

Core Preset Configuration

Main Babel preset function that generates configuration based on options and build stage. Automatically configures @babel/preset-env and @babel/preset-react with optimal settings for Gatsby projects.

/**
 * Main Babel preset configuration function
 * @param {*} api - Babel API object (typically unused)
 * @param {PresetOptions} options - Configuration options
 * @returns {BabelConfig} Babel configuration object with presets and plugins
 */
function preset(api, options = {});

interface PresetOptions {
  /** Build stage for different Gatsby build phases */
  stage?: "build-html" | "develop-html" | "develop" | "build-javascript" | "test";
  /** Browser/Node.js targets for @babel/preset-env */
  targets?: string | object | null;
  /** JSX runtime mode */
  reactRuntime?: "classic" | "automatic";
  /** Custom JSX import source (requires reactRuntime: "automatic") */
  reactImportSource?: string | null;
}

interface BabelConfig {
  presets: Array<[string, object]>;
  plugins: Array<string | [string, object]>;
}

Core Preset Configuration

Configuration Loading

Utility for loading cached Babel configuration from Gatsby's build system. Essential for accessing optimized browser targets and other build-specific settings.

/**
 * Loads cached Babel configuration from Gatsby's .cache/babelState.json
 * @returns {object} Cached plugin babel configuration object
 * @throws {Error} If not in test environment and cache file is missing
 */
function loadCachedConfig();

Configuration Loading

Hook Optimization Plugin

Babel plugin that optimizes React hook array destructuring to object destructuring for better performance and smaller bundle sizes.

/**
 * Babel plugin factory for optimizing React hook destructuring
 * @param {object} babel - Babel object with types utility
 * @returns {BabelPlugin} Babel plugin object with visitor pattern
 */
function optimizeHookDestructuring({ types });

interface HookOptimizationOptions {
  /** Only transform built-in React hooks */
  onlyBuiltIns?: boolean;
  /** Libraries that provide hooks (true for React/Preact, or specific library name) */
  lib?: boolean | string;
}

interface BabelPlugin {
  name: string;
  visitor: object;
}

Hook Optimization

Dependencies Configuration

Specialized Babel preset for processing dependencies with specific optimization for node_modules transformation in Gatsby projects.

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

Dependencies Configuration

React Preset Export

Direct export of @babel/preset-react for convenience when you need React transformations separately from the full Gatsby preset.

/**
 * Direct export of @babel/preset-react
 * @type {BabelPreset} @babel/preset-react preset
 */
const babelPresetReact;

Utility Functions

Path serialization utilities for test environments and debugging.

/**
 * Test if a path should be serialized for cleaner test output
 * @param {unknown} val - Value to test
 * @returns {boolean} True if value is a string path that contains node_modules
 */
function test(val);

/**
 * Serialize a path by cleaning node_modules references
 * @param {string} val - Path string to serialize
 * @param {function} serialize - Serialization function
 * @returns {string} Cleaned path string
 */
function print(val, serialize);

React Preset Export and Utilities

Types

// Configuration options for the main preset function
interface PresetOptions {
  /** Build stage for different Gatsby build phases */
  stage?: "build-html" | "develop-html" | "develop" | "build-javascript" | "test";
  /** Browser/Node.js targets for @babel/preset-env */
  targets?: string | object | null;
  /** JSX runtime mode */
  reactRuntime?: "classic" | "automatic";
  /** Custom JSX import source (requires reactRuntime: "automatic") */
  reactImportSource?: string | null;
}

// Main Babel configuration structure returned by preset function
interface BabelConfig {
  presets: Array<[string, object]>;
  plugins: Array<string | [string, object]>;
}

// Options for hook optimization plugin
interface HookOptimizationOptions {
  /** Only transform built-in React hooks */
  onlyBuiltIns?: boolean;
  /** Libraries that provide hooks (true for React/Preact, or specific library name) */
  lib?: boolean | string;
}

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

// Babel plugin structure
interface BabelPlugin {
  name: string;
  visitor: object;
}

// Dependencies-specific Babel configuration
interface DependenciesBabelConfig {
  sourceType: "unambiguous";
  presets: Array<[string, object]>;
  plugins: Array<string | [string, object]>;
}