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

core-preset.mddocs/

Core Preset Configuration

Main Babel preset function that generates comprehensive configuration based on options and build stage. This is the primary API that automatically configures @babel/preset-env and @babel/preset-react with optimal settings for Gatsby projects.

Capabilities

Main Preset Function

The primary export function that generates Babel configuration tailored for Gatsby projects.

/**
 * Main Babel preset configuration function
 * @param {*} api - Babel API object (typically unused, passed as null or _)
 * @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]>;
}

Usage Examples:

// Basic usage - automatically configured
const config = preset(null, {});

// Stage-specific configuration
const buildConfig = preset(null, { 
  stage: "build-javascript" 
});

// Custom browser targets
const customConfig = preset(null, {
  stage: "build-javascript",
  targets: "last 1 version"
});

// Modern JSX with custom import source
const modernConfig = preset(null, {
  reactRuntime: "automatic",
  reactImportSource: "@emotion/react"
});

Stage-Based Behavior

The preset automatically configures different plugin sets based on the build stage:

  • build-html/develop-html: Node.js targeting, CommonJS modules
  • develop/build-javascript: Browser targeting, ES modules
  • test: Node.js targeting, CommonJS modules

Stage Configuration Examples:

// Development configuration - browser optimized
const devConfig = preset(null, { stage: "develop" });
// Includes browser-specific plugins like transform-spread, transform-classes

// Build HTML configuration - Node.js optimized
const htmlConfig = preset(null, { stage: "build-html" });
// Uses Node.js targets, excludes browser-specific optimizations

// Production JavaScript build
const prodConfig = preset(null, { stage: "build-javascript" });
// Includes PropTypes removal plugin for smaller bundles

Target Configuration

Controls browser/Node.js compatibility through @babel/preset-env targets:

// Automatic targeting (recommended)
const autoConfig = preset(null, { stage: "develop" });
// Uses cached browser list from Gatsby build

// Custom browser targets
const customTargets = preset(null, {
  targets: { browsers: ["last 2 versions", "not ie <= 11"] }
});

// Node.js targeting
const nodeConfig = preset(null, {
  targets: { node: "18" }
});

React Configuration

Configures React JSX transformation with support for both classic and automatic runtimes:

// Classic JSX (default)
const classicConfig = preset(null, {
  reactRuntime: "classic"
});
// Uses React.createElement

// Automatic JSX (modern)
const automaticConfig = preset(null, {
  reactRuntime: "automatic"
});
// No need to import React

// Custom JSX import source
const emotionConfig = preset(null, {
  reactRuntime: "automatic",
  reactImportSource: "@emotion/react"
});
// Uses @emotion/react instead of React

Configuration Structure

The preset returns a Babel configuration with the following structure:

Presets

  1. @babel/preset-env: Environment-specific JavaScript transformations

    • Configured with browser targets
    • Uses core-js@3 for polyfills
    • Excludes slower transforms for better performance

  2. @babel/preset-react: React JSX transformations

    • Configurable runtime (classic/automatic)
    • Development mode support
    • Custom import source support

Plugins

The preset includes essential plugins based on the build stage:

Always Included:

  • optimize-hook-destructuring: Custom React hook optimization
  • @babel/plugin-proposal-class-properties: Class property syntax
  • @babel/plugin-proposal-nullish-coalescing-operator: Nullish coalescing
  • @babel/plugin-proposal-optional-chaining: Optional chaining
  • babel-plugin-macros: Compile-time macros
  • @babel/plugin-syntax-dynamic-import: Dynamic import syntax
  • @babel/plugin-transform-runtime: Runtime helper optimization

Browser-Only (develop/build-javascript):

  • @babel/plugin-transform-spread: Spread operator transformation
  • @babel/plugin-transform-classes: Class transformation

Test Environment:

  • babel-plugin-dynamic-import-node: Node.js dynamic import support

Production Build (build-javascript):

  • babel-plugin-transform-react-remove-prop-types: PropTypes removal

Error Handling

The preset validates configuration and throws errors for invalid combinations:

// This will throw an error
try {
  preset(null, { 
    reactImportSource: "@emotion/react" 
    // Missing reactRuntime: "automatic"
  });
} catch (error) {
  // Error: `@babel/preset-react` requires reactRuntime `automatic` 
  // in order to use `importSource`.
}

Integration with Gatsby

The preset integrates with Gatsby's build system through:

  • Cached Configuration: Uses .cache/babelState.json for browser targets
  • Stage Detection: Automatically configures based on Gatsby build stages
  • Performance Optimization: Excludes unnecessary transforms for faster builds